From 5da193f4a6f60ecf8ff4c5f748fa74c872ef361e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Mon, 3 Dec 2018 20:59:59 +0100 Subject: Update user guide --- guide/deps.html | 27 +++++++++++++++++++++++++-- guide/index.html | 2 +- guide/plugins_usage.html | 4 +++- guide/relx.html | 9 ++++++++- 4 files changed, 37 insertions(+), 5 deletions(-) (limited to 'guide') diff --git a/guide/deps.html b/guide/deps.html index 0fc548b..0cfe95a 100644 --- a/guide/deps.html +++ b/guide/deps.html @@ -70,7 +70,14 @@ It has TEST_DEPS for dependencies used only for tes dep_ct_helper = git https://github.com/ninenines/ct_helper master

DOC_DEPS for dependencies used only when building documentation:

DOC_DEPS = edown

REL_DEPS for dependencies required to build the release, or to include extra applications in the release:

REL_DEPS = recon

And SHELL_DEPS for dependencies to make available when running the make shell command:

SHELL_DEPS = tddreloader

All these will be documented in more details in their respective -chapters.

7.2.1. Modifying the dependency source or version

By default, Erlang.mk will look into its package index to +chapters.

Note that these additional types of dependencies will only +be fetched after normal dependencies by default. You can +force a dependency to be downloaded first by extending the +target deps:: before including erlang.mk, for example:

+deps +
+$(CURDIR)/deps/triq +

7.2.1. Modifying the dependency source or version

By default, Erlang.mk will look into its package index to find the project you are looking for, if you only provide its name. This is this case:

DEPS = cowboy

If you need a different version, you need to define another variable. There are two ways to do this, each being useful @@ -134,7 +141,23 @@ those from C.

Similarly, if project A depends on projects B, C and D, regardless of the order, and A, B and C depend on a different version of D, it will always be A’s version that wins, because we fetch all dependencies of A before -fetching those from B or C.

7.4. Fetching and listing dependencies only

You can fetch all dependencies recursively without building anything, +fetching those from B or C.

Once a dependency is built, it will not be built again by +default. Typically dependencies do not need to be recompiled +and this speeds up building immensely. There are a few ways +to force recompiling a dependency however:

  • +The dependency directory is a symbolic link; the dependency + will always be recompiled. +
  • +The dependency is built directly, for example with a command + like make -C deps/cowlib, or make in the dependency’s + directory. +
  • +The variable FULL is set, for example make FULL=1. This + will force building of all dependencies. This can be added + to your Makefile before including erlang.mk. +
  • +The file ebin/dep_built in the dependency is removed. +

7.4. Fetching and listing dependencies only

You can fetch all dependencies recursively without building anything, with the make fetch-deps command. It follows the same rules described in the section above.

You can list all dependencies recursively, again without building anything, with the make list-deps command. It will obviously need diff --git a/guide/index.html b/guide/index.html index ec5b1a6..ac7ea7e 100644 --- a/guide/index.html +++ b/guide/index.html @@ -33,7 +33,7 @@ div.navfooter{margin-bottom:1em}

-
   Next

Erlang.mk User Guide

Loïc Hoguin

Table of Contents

1. Installation
1.1. On Unix
1.2. On Windows
2. Getting started
2.1. Creating a folder for your project
2.2. Downloading Erlang.mk
2.3. Getting started with OTP applications
2.4. Getting started with OTP libraries
2.5. Getting started with OTP releases
2.6. Getting started from scratch
2.7. Using spaces instead of tabs
2.8. Using templates
2.9. Hiding Erlang.mk from git
2.10. Getting help
3. Overview
3.1. Building your project
3.2. Exploring the package index
3.3. Generating documentation
3.4. Running tests
3.5. Need more?
4. Updating Erlang.mk
4.1. Initial bootstrap
4.2. Updating
4.3. Customizing the build
5. Limitations
5.1. Erlang must be available
5.2. Spaces in path
5.3. Dependency tracking and modification times
I. Code
6. Building
6.1. How to build
6.2. What to build
6.3. Application resource file
6.4. Automatic application resource file values
6.5. File formats
6.6. Compilation options
6.7. Cold and hot builds
6.8. Dependency tracking
6.9. Generating Erlang source
6.10. Cleaning
7. Packages and dependencies
7.1. Searching packages
7.2. Adding dependencies to your project
7.3. How deps are fetched and built
7.4. Fetching and listing dependencies only
7.5. Ignoring unwanted dependencies
7.6. Dependencies directory
7.7. Many applications in one repository
7.8. Repositories with no application at the root level
7.9. Autopatch
7.10. Dealing with duplicate modules
7.11. Skipping deps
8. NIFs and port drivers
8.1. C source code location and Erlang environment
8.2. Using a custom Makefile
8.3. Using Erlang.mk directly
8.4. Propagating compile and linker flags to sub-Makefiles
9. Releases
9.1. Setup
9.2. Configuration
9.3. Generating the release
9.4. Running the release
9.5. Upgrading a release
9.6. Getting Relx semver value
10. Self-extracting releases
10.1. Generating the self-extracting archive
10.2. Running the release
11. Escripts
11.1. Requirements
11.2. Generating an escript
11.3. Configuration
11.4. Extra files
11.5. Optimizing for size
12. OTP version management
12.1. Erlang versions
12.2. OTP version pinning
12.3. Continuous integration
12.4. Configuring Kerl
13. Compatibility with other build tools
13.1. Rebar projects as Erlang.mk dependencies
13.2. Erlang.mk projects as Rebar dependencies
II. Documentation
14. AsciiDoc documentation
14.1. Requirements
14.2. Writing AsciiDoc documentation
14.3. Configuration
14.4. Usage
15. EDoc comments
15.1. Writing EDoc comments
15.2. Configuration
15.3. Usage
15.4. Running EDoc on all applications
16. Sphinx documentation
16.1. Writing Sphinx documentation
16.2. Basic setup
16.3. Erlang.mk configuration
16.4. Generating man pages
III. Tests
17. Erlang shell
17.1. Configuration
17.2. Usage
18. EUnit
18.1. Writing tests
18.2. Configuration
18.3. Usage
19. Common Test
19.1. Writing tests
19.2. Configuration
19.3. Usage
20. Triq
21. Code coverage
22. Continuous integration
22.1. Configuring Erlang/OTP versions to test
22.2. Running tests across all configured versions
22.3. Extending the CI targets
23. Dialyzer
23.1. How it works
23.2. Configuration
23.3. Usage
24. Xref
IV. Third-party plugins
25. External plugins
25.1. Loading all plugins from a dependency
25.2. Loading one plugin from a dependency
25.3. Writing external plugins
25.4. Early-stage plugins
25.5. Loading plugins local to the application
26. List of plugins
26.1. efene.mk
26.2. elixir.mk
26.3. elvis.mk
26.4. geas
26.5. hexer.mk
26.6. hexpm.mk
26.7. jorel
26.8. lfe.mk
26.9. mix.mk
26.10. reload.mk
26.11. rust.mk
V. About Erlang.mk
27. Why Erlang.mk
27.1. Erlang.mk is fast
27.2. Erlang.mk gives you the full power of Unix
27.3. Erlang.mk is a text file
27.4. Erlang.mk can manage Erlang itself
27.5. Erlang.mk can do more than Erlang
27.6. Erlang.mk integrates nicely in Make and Automake projects
28. Short history
28.1. Before Erlang.mk
28.2. Lifetime of the project
29. Contributing
29.1. Priorities
29.2. Bugs
29.3. Code
29.4. Packages
29.5. Documentation
29.6. Feature requests
   Next
+
   Next

Erlang.mk User Guide

Loïc Hoguin

Table of Contents

1. Installation
1.1. On Unix
1.2. On Windows
2. Getting started
2.1. Creating a folder for your project
2.2. Downloading Erlang.mk
2.3. Getting started with OTP applications
2.4. Getting started with OTP libraries
2.5. Getting started with OTP releases
2.6. Getting started from scratch
2.7. Using spaces instead of tabs
2.8. Using templates
2.9. Hiding Erlang.mk from git
2.10. Getting help
3. Overview
3.1. Building your project
3.2. Exploring the package index
3.3. Generating documentation
3.4. Running tests
3.5. Need more?
4. Updating Erlang.mk
4.1. Initial bootstrap
4.2. Updating
4.3. Customizing the build
5. Limitations
5.1. Erlang must be available
5.2. Spaces in path
5.3. Dependency tracking and modification times
I. Code
6. Building
6.1. How to build
6.2. What to build
6.3. Application resource file
6.4. Automatic application resource file values
6.5. File formats
6.6. Compilation options
6.7. Cold and hot builds
6.8. Dependency tracking
6.9. Generating Erlang source
6.10. Cleaning
7. Packages and dependencies
7.1. Searching packages
7.2. Adding dependencies to your project
7.3. How deps are fetched and built
7.4. Fetching and listing dependencies only
7.5. Ignoring unwanted dependencies
7.6. Dependencies directory
7.7. Many applications in one repository
7.8. Repositories with no application at the root level
7.9. Autopatch
7.10. Dealing with duplicate modules
7.11. Skipping deps
8. NIFs and port drivers
8.1. C source code location and Erlang environment
8.2. Using a custom Makefile
8.3. Using Erlang.mk directly
8.4. Propagating compile and linker flags to sub-Makefiles
9. Releases
9.1. Setup
9.2. Configuration
9.3. Generating the release
9.4. Running the release
9.5. Upgrading a release
9.6. Getting Relx semver value
10. Self-extracting releases
10.1. Generating the self-extracting archive
10.2. Running the release
11. Escripts
11.1. Requirements
11.2. Generating an escript
11.3. Configuration
11.4. Extra files
11.5. Optimizing for size
12. OTP version management
12.1. Erlang versions
12.2. OTP version pinning
12.3. Continuous integration
12.4. Configuring Kerl
13. Compatibility with other build tools
13.1. Rebar projects as Erlang.mk dependencies
13.2. Erlang.mk projects as Rebar dependencies
II. Documentation
14. AsciiDoc documentation
14.1. Requirements
14.2. Writing AsciiDoc documentation
14.3. Configuration
14.4. Usage
15. EDoc comments
15.1. Writing EDoc comments
15.2. Configuration
15.3. Usage
15.4. Running EDoc on all applications
16. Sphinx documentation
16.1. Writing Sphinx documentation
16.2. Basic setup
16.3. Erlang.mk configuration
16.4. Generating man pages
III. Tests
17. Erlang shell
17.1. Configuration
17.2. Usage
18. EUnit
18.1. Writing tests
18.2. Configuration
18.3. Usage
19. Common Test
19.1. Writing tests
19.2. Configuration
19.3. Usage
20. Triq
21. Code coverage
22. Continuous integration
22.1. Configuring Erlang/OTP versions to test
22.2. Running tests across all configured versions
22.3. Extending the CI targets
23. Dialyzer
23.1. How it works
23.2. Configuration
23.3. Usage
24. Xref
IV. Third-party plugins
25. External plugins
25.1. Loading all plugins from a dependency
25.2. Loading one plugin from a dependency
25.3. Writing external plugins
25.4. Early-stage plugins
25.5. Loading plugins local to the application
26. List of plugins
26.1. efene.mk
26.2. elixir.mk
26.3. elvis.mk
26.4. geas
26.5. hexer.mk
26.6. hexpm.mk
26.7. jorel
26.8. lfe.mk
26.9. mix.mk
26.10. reload.mk
26.11. rust.mk
V. About Erlang.mk
27. Why Erlang.mk
27.1. Erlang.mk is fast
27.2. Erlang.mk gives you the full power of Unix
27.3. Erlang.mk is a text file
27.4. Erlang.mk can manage Erlang itself
27.5. Erlang.mk can do more than Erlang
27.6. Erlang.mk integrates nicely in Make and Automake projects
28. Short history
28.1. Before Erlang.mk
28.2. Lifetime of the project
29. Contributing
29.1. Priorities
29.2. Bugs
29.3. Code
29.4. Packages
29.5. Documentation
29.6. Feature requests
   Next
diff --git a/guide/plugins_usage.html b/guide/plugins_usage.html index c78e48b..a2f01a3 100644 --- a/guide/plugins_usage.html +++ b/guide/plugins_usage.html @@ -65,7 +65,9 @@ file:

THIS := $(dir $(realpath $(lastword $(MAKEF
 include $(THIS)/mk/dist.mk
 include $(THIS)/mk/templates.mk

The THIS variable is required to relatively include files.

This allows users to not only be able to select individual plugins, but also select all plugins from the dependency -in one go if they wish to do so.

25.4. Early-stage plugins

Plugins declared in DEP_PLUGINS are loaded near the end of Erlang.mk. +in one go if they wish to do so.

Plugins can include some help text by extending the target +help-plugins:

help-plugins::
+    $(verbose) printf "%s\n" "" "Run benchmark: $(MAKE) perfs"

25.4. Early-stage plugins

Plugins declared in DEP_PLUGINS are loaded near the end of Erlang.mk. That’s why you have access to all previously initialized variables. However, if you want your plugin to add common dependencies to your applications, a regular is loaded too late in the process. diff --git a/guide/relx.html b/guide/relx.html index 9d23106..88fc617 100644 --- a/guide/relx.html +++ b/guide/relx.html @@ -38,7 +38,14 @@ chapter covers the Erlang.mk-specific bits. Consult the Relx website for more information.

9.1. Setup

Erlang.mk will create a release if it detects a Relx configuration file in the $(RELX_CONFIG) location. This defaults to $(CURDIR)/relx.config. You can override it by defining -the variable before including Erlang.mk:

RELX_CONFIG = $(CURDIR)/webchat.config

Relx does not need to be installed. Erlang.mk will download +the variable before including Erlang.mk:

RELX_CONFIG = $(CURDIR)/webchat.config

It is also possible to have multiple relx.config files. +For example you might have one for development and one for +production. You can use conditionals to decide which one +should be used:

ifdef PROD
+RELX_CONFIG = $(CURDIR)/relx.prod.config
+else
+RELX_CONFIG = $(CURDIR)/relx.dev.config
+endif

Relx does not need to be installed. Erlang.mk will download and build it automatically.

The Relx executable will be saved in the $(RELX) file. This location defaults to $(CURDIR)/relx and can be overriden.

9.2. Configuration

You can specify additional Relx options using the RELX_OPTS variable. For example, to enable dev_mode:

RELX_OPTS = -d true

While you can specify the output directory for the release -- cgit v1.2.3