From fbc67e34a3521d5e67a1c1c66988dbcbad1df97f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Thu, 22 Oct 2015 03:17:18 +0200 Subject: Update user guide --- guide/ch01.html | 2 +- guide/ch02.html | 2 +- guide/ch03.html | 2 +- guide/ch04.html | 2 +- guide/ch05.html | 2 +- guide/ch06.html | 9 ++++--- guide/ch07.html | 2 +- guide/ch08.html | 45 ++------------------------------ guide/ch09.html | 36 ++------------------------ guide/ch10.html | 37 ++------------------------- guide/ch11.html | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ guide/ch12.html | 37 +++++++++++++++++++++++++++ guide/ch13.html | 37 +++++++++++++++++++++++++++ guide/ch14.html | 37 +++++++++++++++++++++++++++ guide/ch15.html | 37 +++++++++++++++++++++++++++ guide/ch16.html | 37 +++++++++++++++++++++++++++ guide/ch17.html | 37 +++++++++++++++++++++++++++ guide/ch18.html | 37 +++++++++++++++++++++++++++ guide/ch19.html | 37 +++++++++++++++++++++++++++ guide/ch20.html | 37 +++++++++++++++++++++++++++ guide/ch21.html | 37 +++++++++++++++++++++++++++ guide/ch22.html | 69 +++++++++++++++++++++++++++++++++++++++++++++++++ guide/ch23.html | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++ guide/ch24.html | 37 +++++++++++++++++++++++++++ guide/ch25.html | 37 +++++++++++++++++++++++++++ guide/ch26.html | 37 +++++++++++++++++++++++++++ guide/index.html | 4 +-- guide/pt01.html | 2 +- guide/pt02.html | 4 +-- guide/pt03.html | 4 +-- guide/pt04.html | 37 +++++++++++++++++++++++++++ guide/pt05.html | 37 +++++++++++++++++++++++++++ 32 files changed, 796 insertions(+), 129 deletions(-) create mode 100644 guide/ch11.html create mode 100644 guide/ch12.html create mode 100644 guide/ch13.html create mode 100644 guide/ch14.html create mode 100644 guide/ch15.html create mode 100644 guide/ch16.html create mode 100644 guide/ch17.html create mode 100644 guide/ch18.html create mode 100644 guide/ch19.html create mode 100644 guide/ch20.html create mode 100644 guide/ch21.html create mode 100644 guide/ch22.html create mode 100644 guide/ch23.html create mode 100644 guide/ch24.html create mode 100644 guide/ch25.html create mode 100644 guide/ch26.html create mode 100644 guide/pt04.html create mode 100644 guide/pt05.html diff --git a/guide/ch01.html b/guide/ch01.html index f816946..8815cd6 100644 --- a/guide/ch01.html +++ b/guide/ch01.html @@ -2,7 +2,7 @@ -Erlang.mk +Erlang.mk User Guide + + +
+ + + +
+
+ +
Prev   Next

Chapter 11. Compatibility with other build tools

Erlang.mk tries its best to be compatible with the other Erlang +build tools. It can use dependencies written with other build +tools in mind, and can also make your projects usable by those +build tools as well. Erlang.mk is like the cool kid that gets +along with everybody.

In this chapter I will use the term Rebar project to refer +to a project built using Rebar 2, Rebar 3 or Mad. These three +build tools are very similar and share the same configuration +file.

11.1. Rebar projects as Erlang.mk dependencies

Erlang.mk comes with a feature called Autoload which will +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 +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, +and the application resource file, found either at +ebin/$(PROJECT).app or at src/$(PROJECT).app.src.

11.2.1. Rebar configuration

Erlang.mk comes with a target that generates a rebar.config +file when invoked:

$ make rebar.config

Careful! This will build the file even if it already existed +before.

To build this file, Erlang.mk uses information it finds in +the DEPS and ERLC_OPTS variables, among others. This +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 +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. +It could also be that we forgot to handle something! Sorry. +We are of course interested to hear about any compatibility +problems you may have, just open a ticket!

11.2.2. Application resource file

Erlang.mk has two ways to generate an application resource +file: from the information found in the Makefile, or from +the information found in the src/$(PROJECT).app.src file. +Needless to say, if you have this file in your repository, +then you don’t need to worry about compatibility with other +build tools.

If you don’t, however, it’s not much harder. Every time +Erlang.mk will compile your application, it will produce +a new ebin/$(PROJECT).app file. Simply commit this file +when it changes. It will only change when you modify the +configuration, add or remove modules.

Prev Up Next
 Home 
+
+ + diff --git a/guide/ch12.html b/guide/ch12.html new file mode 100644 index 0000000..9b19e69 --- /dev/null +++ b/guide/ch12.html @@ -0,0 +1,37 @@ + + + + +Erlang.mk User Guide + + + +
+ + + +
+
+ +
Prev   Next

Chapter 12. Asciidoc documentation

Placeholder chapter.

Prev Up Next
 Home 
+
+ + diff --git a/guide/ch13.html b/guide/ch13.html new file mode 100644 index 0000000..7188967 --- /dev/null +++ b/guide/ch13.html @@ -0,0 +1,37 @@ + + + + +Erlang.mk User Guide + + + +
+ + + +
+
+ +
Prev   Next

Chapter 13. EDoc comments

Placeholder chapter.

Prev Up Next
 Home 
+
+ + diff --git a/guide/ch14.html b/guide/ch14.html new file mode 100644 index 0000000..7160d01 --- /dev/null +++ b/guide/ch14.html @@ -0,0 +1,37 @@ + + + + +Erlang.mk User Guide + + + +
+ + + +
+
+ +
Prev   Next

Chapter 14. Erlang shell

Placeholder chapter.

Prev Up Next
 Home 
+
+ + diff --git a/guide/ch15.html b/guide/ch15.html new file mode 100644 index 0000000..3f23d71 --- /dev/null +++ b/guide/ch15.html @@ -0,0 +1,37 @@ + + + + +Erlang.mk User Guide + + + +
+ + + +
+
+ +
Prev   Next

Chapter 15. EUnit

Placeholder chapter.

Prev Up Next
 Home 
+
+ + diff --git a/guide/ch16.html b/guide/ch16.html new file mode 100644 index 0000000..2c71c11 --- /dev/null +++ b/guide/ch16.html @@ -0,0 +1,37 @@ + + + + +Erlang.mk User Guide + + + +
+ + + +
+
+ +
Prev   Next

Chapter 16. Common Test

Placeholder chapter.

Prev Up Next
 Home 
+
+ + diff --git a/guide/ch17.html b/guide/ch17.html new file mode 100644 index 0000000..edf141e --- /dev/null +++ b/guide/ch17.html @@ -0,0 +1,37 @@ + + + + +Erlang.mk User Guide + + + +
+ + + +
+
+ +
Prev   Next

Chapter 17. Property based testing

Placeholder chapter.

Prev Up Next
 Home 
+
+ + diff --git a/guide/ch18.html b/guide/ch18.html new file mode 100644 index 0000000..f882401 --- /dev/null +++ b/guide/ch18.html @@ -0,0 +1,37 @@ + + + + +Erlang.mk User Guide + + + +
+ + + +
+
+ +
Prev   Next

Chapter 18. Code coverage

Placeholder chapter.

Prev Up Next
 Home 
+
+ + diff --git a/guide/ch19.html b/guide/ch19.html new file mode 100644 index 0000000..2ae3d8e --- /dev/null +++ b/guide/ch19.html @@ -0,0 +1,37 @@ + + + + +Erlang.mk User Guide + + + +
+ + + +
+
+ +
Prev   Next

Chapter 19. Continuous integration

Placeholder chapter.

Prev Up Next
 Home 
+
+ + diff --git a/guide/ch20.html b/guide/ch20.html new file mode 100644 index 0000000..7fe395e --- /dev/null +++ b/guide/ch20.html @@ -0,0 +1,37 @@ + + + + +Erlang.mk User Guide + + + +
+ + + +
+
+ +
Prev   Next

Chapter 20. Dialyzer

Placeholder chapter.

Prev Up Next
 Home 
+
+ + diff --git a/guide/ch21.html b/guide/ch21.html new file mode 100644 index 0000000..32dab50 --- /dev/null +++ b/guide/ch21.html @@ -0,0 +1,37 @@ + + + + +Erlang.mk User Guide + + + +
+ + + +
+
+ +
Prev   Next

Chapter 21. Xref

Placeholder chapter.

Prev Up Next
 Home 
+
+ + diff --git a/guide/ch22.html b/guide/ch22.html new file mode 100644 index 0000000..82a9782 --- /dev/null +++ b/guide/ch22.html @@ -0,0 +1,69 @@ + + + + +Erlang.mk User Guide + + + +
+ + + +
+
+ +
Prev   Next

Chapter 22. External plugins

It is often convenient to be able to keep the build files +used by all your projects in one place. Those files could +be Makefiles, configuration files, templates and more.

Erlang.mk allows you to automatically load plugins from +dependencies. Plugins can do anything, including defining +new variables, defining file templates, hooking themselves +inside the normal Erlang.mk processing or even adding new +rules.

You can load plugins using one of two methods. You can +either load all plugins from a dependency, or just one. +We will also cover conventions about writing external +plugins.

22.1. Loading all plugins from a dependency

To load plugins from a dependency, all you need to do is add +the dependency name to DEP_PLUGINS in addition to the list +of dependencies.

For example, if you have cowboy in DEPS, add cowboy in +DEP_PLUGINS also:

DEPS = cowboy
+DEP_PLUGINS = cowboy

This will load the file plugins.mk in the root folder of +the Cowboy repository.

22.2. Loading one plugin from a dependency

Now that we know how to load all plugins, let’s take a look +at how to load one specific plugin from a dependency.

To do this, instead of writing only the name of the dependency, +we will write its name and the path to the plugin file. This +means that writing DEP_PLUGINS = cowboy is equivalent to +writing DEP_PLUGINS = cowboy/plugins.mk.

Knowing this, if we were to load the plugin mk/dist.mk +from Cowboy and no other, we would write the following in +our Makefile:

DEPS = cowboy
+DEP_PLUGINS = cowboy/mk/dist.mk

22.3. Writing external plugins

The plugins.mk file is a convention. It is meant to load +all the plugins from the dependency. The code for the plugin +can be written directly in plugins.mk or be separate.

If you are providing more than one plugin with your repository, +the recommended way is to create one file per plugin in the +mk/ folder in your repository, and then include those +individual plugins in plugins.mk.

For eaxmple, if you have two plugins mk/dist.mk and +mk/templates.mk, you could write the following plugins.mk +file:

THIS := $(dir $(realpath $(lastword $(MAKEFILE_LIST))))
+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.

Prev Up Next
 Home 
+
+ + diff --git a/guide/ch23.html b/guide/ch23.html new file mode 100644 index 0000000..fa71745 --- /dev/null +++ b/guide/ch23.html @@ -0,0 +1,70 @@ + + + + +Erlang.mk User Guide + + + +
+ + + +
+
+ +
Prev   Next

Chapter 23. Why Erlang.mk

Why would you choose Erlang.mk, if not for its +many features? 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 +solution that works for most people, and gives additional +options for projects that run into edge cases, often in the +form of extra variables or rules to be defined.

23.2. Erlang.mk gives you the full power of Unix

Erlang.mk is a Makefile.

You could use Erlang.mk directly without configuring anything +and it would just work. But you can also extend it greatly +either through configuration or hooks, and you can of course +add your own rules to the Makefile.

In all cases: for configuration, hooks or custom rules, you +have all the power of Unix at your disposal, and can call +any utility or even any language interpreter you want, +every time you need to. Erlang.mk also allows you to write +scripts in this small language called Erlang directly inside +your Makefile if you ever need to…

23.3. Erlang.mk is a text file

Erlang.mk is a Makefile.

Which means Erlang.mk is a simple text file. You can edit a +text file. Nothing stops you. If you run into any bug, or +behavior that does not suit you, you can just open the +erlang.mk file in your favorite editor, fix and/or comment +a few lines, save, and try again. It’s as simple as it gets.

Currently using a binary build tool? Good luck with that.

23.4. Erlang.mk can manage Erlang itself

Erlang.mk isn’t written in Erlang.

That’s not a good thing, you say? Well, here’s one thing +that Erlang.mk and Makefiles can do for you that Erlang +build tool can’t easily: choose what version of Erlang is +to be used for compiling the project.

This really is a one-liner in Erlang.mk (a few more lines +if you also let it download and build Erlang directly) +and allows for even greater things, like testing your +project across all supported Erlang versions in one small +command: make -k ci.

23.5. Erlang.mk can do more than Erlang

Erlang.mk doesn’t care what your dependencies are written in.

Erlang.mk will happily compile any dependency, as long as +they come with a Makefile. The dependency can be written +in C, C++ or even Javascript… Who cares, really? If you +need Erlang.mk to fetch it, then Erlang.mk will fetch it +and compile it as needed.

23.6. Erlang.mk integrates nicely in Make and Automake projects

If you are planning to put your project in the middle of +a Make or Automake-based build environment, then the most +logical thing to do is to use a Makefile.

Erlang.mk will happily sit in such an environment and behave +as you expect it to.

Prev Up Next
 Home 
+
+ + diff --git a/guide/ch24.html b/guide/ch24.html new file mode 100644 index 0000000..c6b95c7 --- /dev/null +++ b/guide/ch24.html @@ -0,0 +1,37 @@ + + + + +Erlang.mk User Guide + + + +
+ + + +
+
+ +
Prev   Next

Chapter 24. Short history

Placeholder chapter.

Prev Up Next
 Home 
+
+ + diff --git a/guide/ch25.html b/guide/ch25.html new file mode 100644 index 0000000..5031178 --- /dev/null +++ b/guide/ch25.html @@ -0,0 +1,37 @@ + + + + +Erlang.mk User Guide + + + +
+ + + +
+
+ +
Prev   Next

Chapter 25. Architecture

Placeholder chapter.

Prev Up Next
 Home 
+
+ + diff --git a/guide/ch26.html b/guide/ch26.html new file mode 100644 index 0000000..d5b423b --- /dev/null +++ b/guide/ch26.html @@ -0,0 +1,37 @@ + + + + +Erlang.mk User Guide + + + +
+ + + +
+
+ +
Prev   

Chapter 26. Contributing

Placeholder chapter.

Prev Up 
 Home 
+
+ + diff --git a/guide/index.html b/guide/index.html index 094621f..8f0a30f 100644 --- a/guide/index.html +++ b/guide/index.html @@ -2,7 +2,7 @@ -Erlang.mk +Erlang.mk User Guide + + +
+ + + +
+
+ +
Prev   Next

Part IV. Third-party plugins

Prev   Next
 Home 
+
+ + diff --git a/guide/pt05.html b/guide/pt05.html new file mode 100644 index 0000000..b3b80a4 --- /dev/null +++ b/guide/pt05.html @@ -0,0 +1,37 @@ + + + + +Erlang.mk User Guide + + + +
+ + + +
+
+ +
Prev   Next

Part V. About Erlang.mk

Prev   Next
 Home 
+
+ + -- cgit v1.2.3