From 0ebdf9c62523e516c081ec6eaf6124d5cba76150 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Sat, 9 Jan 2016 15:49:51 +0100 Subject: Update user guide --- guide/asciidoc.html | 21 ++++++++++++++++++++- guide/ct.html | 4 ++-- guide/dialyzer.html | 4 ++-- guide/edoc.html | 4 ++-- guide/eunit.html | 4 ++-- guide/index.html | 2 +- guide/overview.html | 4 ++-- guide/shell.html | 4 ++-- 8 files changed, 33 insertions(+), 14 deletions(-) (limited to 'guide') diff --git a/guide/asciidoc.html b/guide/asciidoc.html index 8903668..ed4222b 100644 --- a/guide/asciidoc.html +++ b/guide/asciidoc.html @@ -33,7 +33,26 @@ div.navfooter{margin-bottom:1em}
-
Prev   Next

Chapter 12. Asciidoc documentation

Placeholder chapter.

Prev Up Next
 Home 
+
Prev   Next

Chapter 12. AsciiDoc documentation

Erlang.mk provides rules for generating documentation from +AsciiDoc files. It can automatically build a user guide PDF, +chunked HTML documentation and Unix manual pages.

12.1. Writing AsciiDoc documentation

AsciiDoc is a text document format for +writing notes, documentation, articles, books, ebooks, slideshows, +web pages, man pages and blogs. AsciiDoc files can be translated +to many formats including HTML, PDF, EPUB, man page.

The AsciiDoc user guide +describes the AsciiDoc syntax.

The Erlang.mk user guide +is written in AsciiDoc and can be used as an example. The entry +file is book.asciidoc.

Erlang.mk expects you to put your documentation in a specific +location. This 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.

12.2. Configuration

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

12.3. 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 +/usr/local/share/man. The MAN_SECTIONS variable defines +which manual sections are to be installed. It defaults to 3 7.

To install man pages to a custom location:

$ make install-docs MAN_INSTALL_PATH=/opt/share/man

Note that you may need to run the install commands using +sudo or equivalent if the location is not writeable by +your user.

Prev Up Next
 Home 
diff --git a/guide/ct.html b/guide/ct.html index 97c8f36..b1672f8 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/.

16.2. Configuration

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

16.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 @@ -47,7 +47,7 @@ Common Test suites Erlang.mk will be aware of. It does not normally need to be set as Erlang.mk will find the test suites automatically.

The name of the suite is the part before _SUITE.erl. If the file is named http_SUITE.erl, the test suite -is http:

CT_SUITES = http ws

16.3. Usage

To run all tests (including Common Test):

$ make tests

To run all tests and static checks (including Common Test):

$ make check

You can also run Common Test separately:

$ make ct

Erlang.mk will create targets for all test suites it finds. +is http:

CT_SUITES = http ws

16.3. Usage

To run all tests (including Common Test):

$ make tests

To run all tests and static checks (including Common Test):

$ make check

You can also run Common Test separately:

$ make ct

Erlang.mk will create targets for all test suites it finds. If you have a file named test/http_SUITE.erl, then the target ct-http will run that specific test suite:

$ make ct-http

Erlang.mk provides a convenient way to run a specific group or a specific test case within a specific group, diff --git a/guide/dialyzer.html b/guide/dialyzer.html index 0c9f537..6d995bd 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 @@ -59,7 +59,7 @@ The former one defines which directories should be part of the analysis. The latter defines what extra warnings Dialyzer should report.

Note that Erlang.mk enables the race condition warnings by default. As it can take considerably large resources -to run, you may want to disable it on larger projects.

20.3. Usage

To perform an analysis, run the following command:

$ make dialyze

This will create the PLT file if it doesn’t exist.

The analysis will also be performed when you run the +to run, you may want to disable it on larger projects.

20.3. Usage

To perform an analysis, run the following command:

$ make dialyze

This will create the PLT file if it doesn’t exist.

The analysis will also be performed when you run the following command, alongside tests:

$ make check

You can use the plt target to create the PLT file if it doesn’t exist. This is normally not necessary as Dialyzer creates it automatically.

The PLT file will be removed when you run make distclean.

Prev Up Next
 Home 
diff --git a/guide/edoc.html b/guide/edoc.html index e24967c..40ebdde 100644 --- a/guide/edoc.html +++ b/guide/edoc.html @@ -35,11 +35,11 @@ div.navfooter{margin-bottom:1em}
Prev   Next

Chapter 13. EDoc comments

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

13.1. Writing EDoc comments

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

13.2. Configuration

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

13.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
-EDOC_OPTS = {doclet, edown_doclet}

13.3. Usage

To build all documentation, you would typically use:

$ make docs

Do note, however, that EDoc comments will only be generated +EDOC_OPTS = {doclet, edown_doclet}

13.3. Usage

To build all documentation, you would typically use:

$ make docs

Do note, however, that EDoc comments will only be generated automatically if the doc/overview.edoc file exists. If you do not want that file and still want to generate doc comments, two solutions are available.

You can generate EDoc documentation directly:

$ make edoc

You can enable automatic generation on make docs by adding diff --git a/guide/eunit.html b/guide/eunit.html index 422003c..2162fee 100644 --- a/guide/eunit.html +++ b/guide/eunit.html @@ -58,12 +58,12 @@ 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.

15.2. Configuration

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

15.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 to be passed to erl when running EUnit tests. For example, -you can load the vm.args and sys.config files:

EUNIT_ERL_OPTS = -args_file rel/vm.args -config rel/sys.config

15.3. Usage

To run all tests (including EUnit):

$ make tests

To run all tests and static checks (including EUnit):

$ make check

You can also run EUnit separately:

$ make eunit

EUnit will be quiet by default, only outputting errors. +you can load the vm.args and sys.config files:

EUNIT_ERL_OPTS = -args_file rel/vm.args -config rel/sys.config

15.3. Usage

To run all tests (including EUnit):

$ make tests

To run all tests and static checks (including EUnit):

$ make check

You can also run EUnit separately:

$ make eunit

EUnit will be quiet by default, only outputting errors. You can easily make it verbose for a single invocation:

$ make eunit EUNIT_OPTS=verbose

Erlang.mk allows you to run all tests from a specific module, or a specific test case from that module, using the variable t.

For example, to run all tests from the cow_http_hd diff --git a/guide/index.html b/guide/index.html index a442678..ab968ca 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. Using spaces instead of tabs
2.7. Using templates
2.8. 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. Ignoring unwanted dependencies
7.5. Dependencies directory
7.6. Dependencies local to the repository
7.7. Repositories with no application at the root level
7.8. Autopatch
7.9. 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
10. Escripts
11. Compatibility with other build tools
11.1. Rebar projects as Erlang.mk dependencies
11.2. Erlang.mk projects as Rebar dependencies
II. Documentation
12. Asciidoc documentation
13. EDoc comments
13.1. Writing EDoc comments
13.2. Configuration
13.3. Usage
III. Tests
14. Erlang shell
14.1. Configuration
14.2. Usage
15. EUnit
15.1. Writing tests
15.2. Configuration
15.3. Usage
16. Common Test
16.1. Writing tests
16.2. Configuration
16.3. Usage
17. Property based testing
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. lfe.mk
23.7. reload.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. Using spaces instead of tabs
2.7. Using templates
2.8. 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. Ignoring unwanted dependencies
7.5. Dependencies directory
7.6. Dependencies local to the repository
7.7. Repositories with no application at the root level
7.8. Autopatch
7.9. 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
10. Escripts
11. Compatibility with other build tools
11.1. Rebar projects as Erlang.mk dependencies
11.2. Erlang.mk projects as Rebar dependencies
II. Documentation
12. AsciiDoc documentation
12.1. Writing AsciiDoc documentation
12.2. Configuration
12.3. Usage
13. EDoc comments
13.1. Writing EDoc comments
13.2. Configuration
13.3. Usage
III. Tests
14. Erlang shell
14.1. Configuration
14.2. Usage
15. EUnit
15.1. Writing tests
15.2. Configuration
15.3. Usage
16. Common Test
16.1. Writing tests
16.2. Configuration
16.3. Usage
17. Property based testing
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. lfe.mk
23.7. reload.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/overview.html b/guide/overview.html index fb5ac33..120b33c 100644 --- a/guide/overview.html +++ b/guide/overview.html @@ -57,8 +57,8 @@ example to find all packages related to Cowboy:

$
 Chapter 13, EDoc comments generates HTML documentation directly from
 your source code.
While it is convenient, ask yourself: if all the documentation is
 inside the source code, why not just open the source code directly?
-That’s where Asciidoc comes in.
The Asciidoc
-Chapter 12, Asciidoc documentation plugin expects all documentation
+That’s where Asciidoc comes in.
The Asciidoc
+Chapter 12, AsciiDoc documentation plugin expects all documentation
 to be separate from source. It will generate HTML, PDF, man pages and
 more from the documentation you write in the doc/src/ folder in
 your repository.

3.4. Running tests

Erlang.mk supports a lot of different testing and static diff --git a/guide/shell.html b/guide/shell.html index ca0a70e..89e1d0c 100644 --- a/guide/shell.html +++ b/guide/shell.html @@ -34,14 +34,14 @@ div.navfooter{margin-bottom:1em}

Prev   Next

Chapter 14. Erlang shell

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

14.1. Configuration

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

14.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. To continue with our example, if you want to use kjell as your shell, you also need to change SHELL_ERL and point it to the kjell executable:

SHELL_ERL = $(DEPS_DIR)/kjell/bin/kjell

You can specify additional options to be used when starting the -shell using the SHELL_OPTS variable:

SHELL_OPTS = -setcookie chocolate

Any of the usual erl options can be used, including -eval:

SHELL_OPTS = -eval 'my_app:run()'

14.2. Usage

To start the shell, all you need is the following command:

$ make shell

The shell can be stopped as usual with a double Ctrl+C or the +shell using the SHELL_OPTS variable:

SHELL_OPTS = -setcookie chocolate

Any of the usual erl options can be used, including -eval:

SHELL_OPTS = -eval 'my_app:run()'

14.2. Usage

To start the shell, all you need is the following command:

$ make shell

The shell can be stopped as usual with a double Ctrl+C or the command q()..

Prev Up Next
 Home 
-- cgit v1.2.3