From ace1e250489c858abc33989df4fbed46627975c7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Sun, 30 Oct 2016 16:59:51 +0200 Subject: Update user guide --- guide/asciidoc.html | 2 +- guide/ct.html | 2 +- guide/dialyzer.html | 2 +- guide/edoc.html | 2 +- guide/escript.html | 27 ++++++++++++++++++++++++++- guide/eunit.html | 2 +- guide/index.html | 2 +- guide/shell.html | 2 +- 8 files changed, 33 insertions(+), 8 deletions(-) diff --git a/guide/asciidoc.html b/guide/asciidoc.html index 0fcb434..ab8d579 100644 --- a/guide/asciidoc.html +++ b/guide/asciidoc.html @@ -48,7 +48,7 @@ file is doc/src/guide/ for the user guide, and doc/src/manual/ for the function reference. In the case of the user guide, the entry point is always doc/src/guide/book.asciidoc.

For manual pages, it is good practice to use section 3 for -modules, and section 7 for the application itself.

13.3. Configuration

All of the AsciiDoc related configuration can be done directly +modules, and section 7 for the application itself.

13.3. Configuration

All of the AsciiDoc related configuration can be done directly inside the files themselves.

13.4. Usage

To build all documentation:

$ make docs

To build only the AsciiDoc documentation:

$ make asciidoc

To build only the user guide:

$ make asciidoc-guide

To build only the manual:

$ make asciidoc-manual

To install man pages on Unix:

$ make install-docs

Erlang.mk allows customizing the installation path and sections of the man pages to be installed. The MAN_INSTALL_PATH variable defines where man pages will be installed. It defaults to diff --git a/guide/ct.html b/guide/ct.html index ad63374..c8f8f5f 100644 --- a/guide/ct.html +++ b/guide/ct.html @@ -39,7 +39,7 @@ Test suites.

_SUITE.erl and that the files be located in the $(TEST_DIR) directory. -This defaults to test/.

17.2. Configuration

The CT_OPTS variable allows you to set extra Common Test +This defaults to test/.

17.2. Configuration

The CT_OPTS variable allows you to set extra Common Test options. Options are documented in the Common Test user guide. You can use it to set Common Test hooks, for example:

CT_OPTS = -ct_hooks cowboy_ct_hook

The CT_SUITES variable can be used to override what diff --git a/guide/dialyzer.html b/guide/dialyzer.html index 6d995bd..8b5efc5 100644 --- a/guide/dialyzer.html +++ b/guide/dialyzer.html @@ -44,7 +44,7 @@ dependencies of the application or applications you are currently working on, including standard applications in Erlang/OTP itself.

Dialyzer can generate this PLT file. Erlang.mk includes rules to automatically generate the PLT file when it is missing.

Once the PLT file is generated, Dialyzer can perform the -analysis in record time.

20.2. Configuration

In a typical usage scenario, no variable needs to be set. +analysis in record time.

20.2. Configuration

In a typical usage scenario, no variable needs to be set. The defaults should be enough. Do note however that the dependencies need to be set properly using the DEPS and LOCAL_DEPS variables.

The DIALYZER_PLT file indicates where the PLT file will diff --git a/guide/edoc.html b/guide/edoc.html index bfb4425..5203a39 100644 --- a/guide/edoc.html +++ b/guide/edoc.html @@ -35,7 +35,7 @@ div.navfooter{margin-bottom:1em}

Prev   Next

Chapter 14. EDoc comments

Erlang.mk provides a thin wrapper on top of EDoc, an application that generates documentation based on comments found in modules.

14.1. Writing EDoc comments

The EDoc user guide -explains everything you need to know about EDoc comments.

14.2. Configuration

The EDOC_OPTS variable allows you to specify additional +explains everything you need to know about EDoc comments.

14.2. Configuration

The EDOC_OPTS variable allows you to specify additional EDoc options. Options are documented in the EDoc manual.

A common use for this variable is to enable Markdown in doc comments, using the edown application:

DOC_DEPS = edown
diff --git a/guide/escript.html b/guide/escript.html
index e874663..b8056e5 100644
--- a/guide/escript.html
+++ b/guide/escript.html
@@ -33,7 +33,32 @@ div.navfooter{margin-bottom:1em}
 
 

 
-
Prev   Next
Chapter 11. Escripts
Placeholder chapter.
Prev Up Next
 Home 

+
Prev   Next
Chapter 11. Escripts
Escripts are an alternative to release. They are meant to be
+used for small command line executables written in Erlang.
They are not self-contained, unlike releases
+Chapter 9, Releases.
+Erlang must be installed for them to run. This however means
+that they are fairly small compared to releases.
For self-contained executables, check self-extracting releases
+Chapter 10, Self-extracting releases.
Erlang.mk uses p7zip by default to generate the escript
+archive. Make sure it is installed.
11.1. Generating an escript
Run the following command to generate an escript:
$ make escript
This will by default create an escript with the same name as
+the project, in the project’s directory. If the project is
+called relx then the escript will be in ./relx.
You can run the escript as you would any executable:
$ ./relx
11.2. Configuration
You can change the name of the escript by setting ESCRIPT_NAME.
+The name determines both the default output file name and the
+entry module containing the function main/1.
ESCRIPT_FILE can be set if you need a different file name
+or location.
The escript header can be entirely customized. The first line
+is the shebang, set by ESCRIPT_SHEBANG. The second line is
+a comment, set by ESCRIPT_COMMENT. The third line is the
+arguments the VM will use when running the escript, set by
+ESCRIPT_EMU_ARGS.
Finally, ESCRIPT_ZIP can be set to customize the command used
+to create the zip file. Read on for more information.
11.3. Extra files
Generating an escript is a two-part process. First, a zip file
+is created with the contents of the escript. Then a header is
+added to this file to create the escript.
It is possible to add commands that will be executed between
+the two steps. You can for example add extra files to the zip
+archive:
escript-zip::
+    $(verbose) $(ESCRIPT_ZIP) $(ESCRIPT_ZIP_FILE) priv/templates/*
The ESCRIPT_ZIP variable contains the command to run to add
+files to the zip archive ESCRIPT_ZIP_FILE.
11.4. Optimizing for size
Erlang.mk will by default compile BEAM files with debug
+information. You may want to disable this behavior to obtain
+smaller escript files. Simply set ERLC_OPTS to a value that
+does not include +debug_info.
Prev Up Next
 Home 

 

 
 
diff --git a/guide/eunit.html b/guide/eunit.html
index 1a5bb22..d211887 100644
--- a/guide/eunit.html
+++ b/guide/eunit.html
@@ -58,7 +58,7 @@ compiled.
-ifdef(TEST).
 %% Insert tests here.
 
 -endif.
Erlang.mk will automatically recompile your code when you
-perform a normal build after running tests, and vice versa.

16.2. Configuration

The EUNIT_OPTS variable allows you to specify additional +perform a normal build after running tests, and vice versa.

16.2. Configuration

The EUNIT_OPTS variable allows you to specify additional EUnit options. Options are documented in the EUnit manual. At the time of writing, the only available option is verbose:

EUNIT_OPTS = verbose

The EUNIT_ERL_OPTS variable allows you to specify options diff --git a/guide/index.html b/guide/index.html index dbf92b2..07038cc 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. 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
9. Releases
9.1. Setup
9.2. Configuration
9.3. Generating the release
9.4. Running the release
9.5. Upgrading a release
10. Self-extracting releases
10.1. Generating the self-extracting archive
10.2. Running the release
11. Escripts
12. Compatibility with other build tools
12.1. Rebar projects as Erlang.mk dependencies
12.2. Erlang.mk projects as Rebar dependencies
II. Documentation
13. AsciiDoc documentation
13.1. Requirements
13.2. Writing AsciiDoc documentation
13.3. Configuration
13.4. Usage
14. EDoc comments
14.1. Writing EDoc comments
14.2. Configuration
14.3. Usage
III. Tests
15. Erlang shell
15.1. Configuration
15.2. Usage
16. EUnit
16.1. Writing tests
16.2. Configuration
16.3. Usage
17. Common Test
17.1. Writing tests
17.2. Configuration
17.3. Usage
18. Code coverage
19. Continuous integration
20. Dialyzer
20.1. How it works
20.2. Configuration
20.3. Usage
21. Xref
IV. Third-party plugins
22. External plugins
22.1. Loading all plugins from a dependency
22.2. Loading one plugin from a dependency
22.3. Writing external plugins
23. List of plugins
23.1. efene.mk
23.2. elixir.mk
23.3. elvis.mk
23.4. geas
23.5. hexer.mk
23.6. hexpm.mk
23.7. jorel
23.8. lfe.mk
23.9. mix.mk
23.10. reload.mk
23.11. rust.mk
V. About Erlang.mk
24. Why Erlang.mk
24.1. Erlang.mk is fast
24.2. Erlang.mk gives you the full power of Unix
24.3. Erlang.mk is a text file
24.4. Erlang.mk can manage Erlang itself
24.5. Erlang.mk can do more than Erlang
24.6. Erlang.mk integrates nicely in Make and Automake projects
25. Short history
25.1. Before Erlang.mk
25.2. Lifetime of the project
26. Contributing
26.1. Priorities
26.2. Bugs
26.3. Code
26.4. Packages
26.5. Documentation
26.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. 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
9. Releases
9.1. Setup
9.2. Configuration
9.3. Generating the release
9.4. Running the release
9.5. Upgrading a release
10. Self-extracting releases
10.1. Generating the self-extracting archive
10.2. Running the release
11. Escripts
11.1. Generating an escript
11.2. Configuration
11.3. Extra files
11.4. Optimizing for size
12. Compatibility with other build tools
12.1. Rebar projects as Erlang.mk dependencies
12.2. Erlang.mk projects as Rebar dependencies
II. Documentation
13. AsciiDoc documentation
13.1. Requirements
13.2. Writing AsciiDoc documentation
13.3. Configuration
13.4. Usage
14. EDoc comments
14.1. Writing EDoc comments
14.2. Configuration
14.3. Usage
III. Tests
15. Erlang shell
15.1. Configuration
15.2. Usage
16. EUnit
16.1. Writing tests
16.2. Configuration
16.3. Usage
17. Common Test
17.1. Writing tests
17.2. Configuration
17.3. Usage
18. Code coverage
19. Continuous integration
20. Dialyzer
20.1. How it works
20.2. Configuration
20.3. Usage
21. Xref
IV. Third-party plugins
22. External plugins
22.1. Loading all plugins from a dependency
22.2. Loading one plugin from a dependency
22.3. Writing external plugins
23. List of plugins
23.1. efene.mk
23.2. elixir.mk
23.3. elvis.mk
23.4. geas
23.5. hexer.mk
23.6. hexpm.mk
23.7. jorel
23.8. lfe.mk
23.9. mix.mk
23.10. reload.mk
23.11. rust.mk
V. About Erlang.mk
24. Why Erlang.mk
24.1. Erlang.mk is fast
24.2. Erlang.mk gives you the full power of Unix
24.3. Erlang.mk is a text file
24.4. Erlang.mk can manage Erlang itself
24.5. Erlang.mk can do more than Erlang
24.6. Erlang.mk integrates nicely in Make and Automake projects
25. Short history
25.1. Before Erlang.mk
25.2. Lifetime of the project
26. Contributing
26.1. Priorities
26.2. Bugs
26.3. Code
26.4. Packages
26.5. Documentation
26.6. Feature requests
   Next
diff --git a/guide/shell.html b/guide/shell.html index 60ccac5..60bd187 100644 --- a/guide/shell.html +++ b/guide/shell.html @@ -34,7 +34,7 @@ div.navfooter{margin-bottom:1em}
Prev   Next

Chapter 15. Erlang shell

Erlang.mk provides a convenient target for starting a shell -with all the paths set properly to experiment with your code.

15.1. Configuration

The SHELL_DEPS variable can be used to define dependencies +with all the paths set properly to experiment with your code.

15.1. Configuration

The SHELL_DEPS variable can be used to define dependencies that are only to be used when the make shell command is called. For example, if you want to use kjell as your shell:

SHELL_DEPS = kjell

Dependencies are downloaded and compiled the first time you run the make shell command.

You can customize the executable used to start the Erlang shell. -- cgit v1.2.3