From a932f220ca62d1f4f6a0d9bfb6ee206fdef7fe59 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Wed, 30 Dec 2015 01:58:35 +0100 Subject: Update user guide --- guide/building.html | 12 +++++++---- guide/compat.html | 7 ++++--- guide/ct.html | 3 ++- guide/deps.html | 3 ++- guide/eunit.html | 3 ++- guide/getting_started.html | 9 ++++++--- guide/index.html | 2 +- guide/overview.html | 50 +++++++++++++++++++++++++++++++--------------- guide/why.html | 3 ++- 9 files changed, 61 insertions(+), 31 deletions(-) diff --git a/guide/building.html b/guide/building.html index b0482c7..4893be3 100644 --- a/guide/building.html +++ b/guide/building.html @@ -59,13 +59,15 @@ and develop on a machine with slow file access, like the Raspberry Pi and many other embedded devices.

Note that this command may fail if a required dependency is missing.

6.2.2. Dependencies

You can build all dependencies, and nothing else, by running the following command:

$ make deps

This will fetch and compile all dependencies and their -dependencies, recursively.

Packages and dependencies are covered +dependencies, recursively.

Packages and dependencies +Chapter 7, Packages and dependencies are covered in the next chapter.

6.2.3. Release

It is not possible to build the release without at least building the application itself, unless of course if there’s no application to begin with.

To generate the release, make will generally suffice with a normal Erlang.mk. A separate target is however available, and will take care of building the release, after building -the application and all dependencies:

$ make rel

Consult the Releases chapter for more +the application and all dependencies:

$ make rel

Consult the Releases +Chapter 9, Releases chapter for more information about what releases are and how they are generated.

6.3. Application resource file

When building your application, Erlang.mk will generate the application resource file. This file is mandatory for all Erlang applications and is @@ -111,7 +113,8 @@ PROJECT_VERSION = 2.0.0-pre.2 PROJECT_REGISTERED = cowboy_clock LOCAL_DEPS = crypto -DEPS = cowlib ranch

Any space before and after the value is dropped.

Dependencies are covered in details in +DEPS = cowlib ranch

Any space before and after the value is dropped.

Dependencies +Chapter 7, Packages and dependencies are covered in details in the next chapter.

6.3.2. Legacy method

The src/$(PROJECT).app.src file is a legacy method of building Erlang applications. It was introduced by the original rebar build tool, of which Erlang.mk owes a great deal as it @@ -140,7 +143,8 @@ The following formats are supported natively:

In addition, Erlang.mk keeps track of header files (.hrl) as described at the end of this chapter. It can also compile -C code, as described in the NIFs and port drivers +C code, as described in the NIFs and port drivers +Chapter 8, NIFs and port drivers chapter.

Erlang.mk also comes with plugins for the following formats:

Extension Location Description Output

.dtl

templates/

Django templates

ebin/*.beam

.proto

src/

Protocol buffers

ebin/*.beam

6.6. Compilation options

Erlang.mk provides a few variables that you can use to customize the build process and the resulting files.

6.6.1. ERLC_OPTS

ERLC_OPTS can be used to pass some options to erlc, the Erlang compiler. Erlang.mk does not restrict any option. Please refer to diff --git a/guide/compat.html b/guide/compat.html index def4498..005b305 100644 --- a/guide/compat.html +++ b/guide/compat.html @@ -44,7 +44,8 @@ use Rebar 2 to patch any Rebar project and make it compatible with Erlang.mk. This feature essentially patches Rebar out and adds a Makefile to the project that Erlang.mk can then use for building:

Autoload is documented in more details in the -Packages and dependencies chapter.

11.2. Erlang.mk projects as Rebar dependencies

Erlang.mk projects can be made compatible with the Rebar family +Packages and dependencies +Chapter 7, Packages and dependencies chapter.

11.2. Erlang.mk projects as Rebar dependencies

Erlang.mk projects can be made compatible with the Rebar family of build tools pretty easily, as Erlang.mk will generate all the files they require for building.

The Rebar family requires two files: a rebar.config file containing compilation options and the list of dependencies, @@ -57,8 +58,8 @@ means that the Rebar family builds your project much the same way as Erlang.mk.

Careful though! Different build tools have different fetching strategies. If some applications provide differing dependencies, they might be fetched differently by other build tools. Check -the Sanity check chapter to find -out how to detect such issues.

You can automatically generate this file when you build +the upcoming Sanity check chapter to find out how to detect such +issues.

You can automatically generate this file when you build your application, by making it a dependency of the app target:

app:: rebar.config

Don’t forget to commit the file when it changes!

If you run into other issues, it’s probably because you use a feature specific to Erlang.mk, like the cp fetch method. diff --git a/guide/ct.html b/guide/ct.html index 14c1637..f1c21d5 100644 --- a/guide/ct.html +++ b/guide/ct.html @@ -54,7 +54,8 @@ using the variable t. Note that this only applies t suite-specific targets, like the ct-http example above.

To run all tests from the http_compress group in the http_SUITE test suite, write:

$ make ct-http t=http_compress

Similarly, to run a specific test case in that group:

$ make ct-http t=http_compress:headers_dupe

To do the same against a multi-application repository, you can use the -C option:

$ make -C apps/my_app ct-http t=my_group:my_case

Note that this also applies to dependencies. When using Cowboy -as a dependency, you can run the following directly:

$ make -C deps/cowboy ct-http t=http_compress

Finally, code coverage is available, +as a dependency, you can run the following directly:

$ make -C deps/cowboy ct-http t=http_compress

Finally, code coverage +Chapter 18, Code coverage is available, but covered in its own chapter.

Prev Up Next
 Home 
diff --git a/guide/deps.html b/guide/deps.html index cbece74..1b424d1 100644 --- a/guide/deps.html +++ b/guide/deps.html @@ -58,7 +58,8 @@ building a NIF:

BUILD_DEPS = leveldb
 dep_leveldb = git https://github.com/basho/leveldb 2.1.3

This dependency will be built before your application, so you could easily copy the resulting shared file into your priv/ directory as part of the build process. More information -about that in the NIFs and port drivers +about that in the NIFs and port drivers +Chapter 8, NIFs and port drivers chapter.

Another variable, LOCAL_DEPS, allows specifying runtime dependencies which are part of Erlang/OTP itself, but also dependencies that are included in the repository. Since they diff --git a/guide/eunit.html b/guide/eunit.html index 686b23d..4af6bf8 100644 --- a/guide/eunit.html +++ b/guide/eunit.html @@ -69,7 +69,8 @@ the variable t.

For example, to run all tests module (instead of all tests from the entire project), one could write:

$ make eunit t=cow_http_hd

Similarly, to run a specific test case:

$ make eunit t=cow_http_hd:parse_accept_test_

To do the same against a multi-application repository, you can use the -C option:

$ make -C apps/my_app eunit t=my_module:hello_test

Note that this also applies to dependencies. From Cowboy, -you can run the following directly:

$ make -C deps/cowlib eunit t=cow_http_hd

Finally, code coverage is available, +you can run the following directly:

$ make -C deps/cowlib eunit t=cow_http_hd

Finally, code coverage +Chapter 18, Code coverage is available, but covered in its own chapter.

Prev Up Next
 Home 
diff --git a/guide/getting_started.html b/guide/getting_started.html index b3a9d7f..edf340c 100644 --- a/guide/getting_started.html +++ b/guide/getting_started.html @@ -61,7 +61,8 @@ cp .erlang.mk.build/erlang.mk ./erlang.mk rm -rf .erlang.mk.build

This is Erlang.mk bootstrapping itself. Indeed, the file you initially downloaded contains nothing more than the code needed to bootstrap. This operation is done only once. Consult the -Updating Erlang.mk chapter for more +Updating Erlang.mk +Chapter 4, Updating Erlang.mk chapter for more information.

Of course, the generated project can now be compiled:

$ make

Cheers!

2.4. Getting started with OTP libraries

An OTP library is an Erlang application that has no supervision tree. In other words, it is nothing but modules.

This kind of project can also be generated by Erlang.mk, using the bootstrap-lib target:

$ make -f erlang.mk bootstrap-lib

Erlang.mk will once again bootstrap itself and generate all @@ -73,7 +74,8 @@ You can use the bootstrap-rel target for this purpo create a project that will build a release:

$ make -f erlang.mk bootstrap-lib bootstrap-rel

It is often very useful to keep the top-level project for commands useful during operations, and put the components of the system in separate applications that you will then -depend on. Consult the Packages and dependencies +depend on. Consult the Packages and dependencies +Chapter 7, Packages and dependencies chapter for more information.

When you run make from now on, Erlang.mk will compile your project and build the release:

$ make
  APP    hello_joe.app.src
@@ -89,7 +91,8 @@ project and build the release:
$ make
 ===> release successfully created!
The first time you run this command, Erlang.mk will download
 relx, the release building tool. So don’t worry if you see
 more output than above.
If building the release is slow, no need to upgrade your
-hardware just yet. Just consult the Releases
+hardware just yet. Just consult the Releases
+Chapter 9, Releases
 chapter for various tips to speed up build time during
 development.
You can start the release using the ./_rel/hello_joe_release/bin/hello_joe_release
 script, or simply run make run. The latter will also compile
diff --git a/guide/index.html b/guide/index.html
index 769cf67..724a2ed 100644
--- a/guide/index.html
+++ b/guide/index.html
@@ -32,7 +32,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
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
V. About Erlang.mk
23. Why Erlang.mk
23.1. Erlang.mk is fast
23.2. Erlang.mk gives you the full power of Unix
23.3. Erlang.mk is a text file
23.4. Erlang.mk can manage Erlang itself
23.5. Erlang.mk can do more than Erlang
23.6. Erlang.mk integrates nicely in Make and Automake projects
24. Short history
24.1. Before Erlang.mk
24.2. Lifetime of the project
25. Contributing
25.1. Priorities
25.2. Bugs
25.3. Code
25.4. Packages
25.5. Documentation
25.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
13. EDoc comments
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
V. About Erlang.mk
23. Why Erlang.mk
23.1. Erlang.mk is fast
23.2. Erlang.mk gives you the full power of Unix
23.3. Erlang.mk is a text file
23.4. Erlang.mk can manage Erlang itself
23.5. Erlang.mk can do more than Erlang
23.6. Erlang.mk integrates nicely in Make and Automake projects
24. Short history
24.1. Before Erlang.mk
24.2. Lifetime of the project
25. Contributing
25.1. Priorities
25.2. Bugs
25.3. Code
25.4. Packages
25.5. Documentation
25.6. Feature requests
   Next

 

 
 
diff --git a/guide/overview.html b/guide/overview.html
index cf35ede..0c5da11 100644
--- a/guide/overview.html
+++ b/guide/overview.html
@@ -35,37 +35,55 @@ div.navfooter{margin-bottom:1em}
 
Prev   Next
Chapter 3. Overview
Now that you know how to get started, let’s take a look at
 what Erlang.mk can do for you.
3.1. Building your project
Erlang.mk is first and foremost a build tool. It is especially
 tailored for Erlang developers and follows widely accepted
-practices in the Erlang community.
Erlang.mk will happily build all Erlang-specific files
+practices in the Erlang community.
Erlang.mk will happily build all Erlang-specific files
+Chapter 6, Building
 you throw at it. Other kinds of files too, like C or C++ code
-when you are working on a NIF or a port driver.
Erlang.mk embraces the concept of source dependencies.
+when you are working on a NIF or a port driver
+Chapter 8, NIFs and port drivers.
Erlang.mk embraces the concept of source dependencies
+Chapter 7, Packages and dependencies.
 It can fetch dependency source code using a variety of mechanisms,
-including fetching from Git, Mercurial or SVN.
Erlang.mk will automatically generate releases
-when applicable. It can also generate escripts.
3.2. Exploring the package index
Erlang.mk comes with a built-in package index.
+including fetching from Git, Mercurial or SVN.
Erlang.mk will automatically generate releases
+Chapter 9, Releases
+when applicable. It can also generate escripts
+Chapter 10, Escripts.
3.2. Exploring the package index
Erlang.mk comes with a built-in package index
+Chapter 7, Packages and dependencies.
 It is built as an extension of the dependency system and is
 meant to be used for discovery purposes.
No package is ever installed, they are only used as dependencies
 and are always project-specific. They can be thought of as a
 shortcut over plain dependencies.
You can get a list of all packages known to Erlang.mk by using
 the search target:
$ make search
You can also use this target to search across all packages, for
-example to find all packages related to Cowboy:
$ make search q=cowboy
3.3. Generating documentation
Erlang.mk supports EDoc and Asciidoc.
EDoc generates HTML documentation directly from
+example to find all packages related to Cowboy:
$ make search q=cowboy
3.3. Generating documentation
Erlang.mk supports EDoc and Asciidoc.
EDoc
+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 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
-analysis tools.
The make shell command allows you
+analysis tools.
The make shell
+Chapter 14, Erlang shell command allows you
 to test your project manually. You can automate these
-unit tests with EUnit and test
-your entire system with Common Test.
-Property based testing
+unit tests with EUnit
+Chapter 15, EUnit and test
+your entire system with Common Test
+Chapter 16, Common Test.
+Property based testing
+Chapter 17, Property based testing
 with Triq is a strong alternative to writing unit tests
-manually. Code coverage can of course
+manually. Code coverage
+Chapter 18, Code coverage can of course
 be enabled during tests.
Erlang.mk comes with features to make your life easier when
-setting up and using Continuous integration.
On the static analysis side of things, Erlang.mk comes with
-support for Dialyzer, Xref
-and Elvis, performing success typing
-analysis, cross reference and style reviewing.
3.5. Need more?
Not convinced yet? You can read about why you should use Erlang.mk
-and its history. And if you’re still not
+setting up and using Continuous integration
+Chapter 19, Continuous integration.
On the static analysis side of things, Erlang.mk comes with
+support for Dialyzer
+Chapter 20, Dialyzer and Xref
+Chapter 21, Xref,
+to perform success typing analysis and cross referencing
+of the code.
3.5. Need more?
Not convinced yet? You can read about why you should use Erlang.mk
+Chapter 23, Why Erlang.mk
+and its history
+Chapter 24, Short history. And if you’re still not
 convinced after that, it’s OK! The world would be boring if
 everyone agreed on everything all the time.
Prev   Next
 Home 

 
diff --git a/guide/why.html b/guide/why.html
index ad3dc79..3e8da98 100644
--- a/guide/why.html
+++ b/guide/why.html
@@ -33,7 +33,8 @@ div.navfooter{margin-bottom:1em}
 

 
 
Prev   Next
Chapter 23. Why Erlang.mk
Why would you choose Erlang.mk, if not for its
-many features? This chapter will
+many features
+Chapter 3, Overview? This chapter will
 attempt to answer that.
23.1. Erlang.mk is fast
Erlang.mk is as fast as it gets.
Erlang.mk will group the compilation of files so as to avoid
 running the BEAM more than necessary. This saves many seconds
 compared to traditional Makefiles, even on small projects.
Erlang.mk will not try to be too smart. It provides a simple
-- 
cgit v1.2.3