diff options
Diffstat (limited to 'doc/src/guide/app.asciidoc')
-rw-r--r-- | doc/src/guide/app.asciidoc | 146 |
1 files changed, 138 insertions, 8 deletions
diff --git a/doc/src/guide/app.asciidoc b/doc/src/guide/app.asciidoc index a04c5a9..5c097f6 100644 --- a/doc/src/guide/app.asciidoc +++ b/doc/src/guide/app.asciidoc @@ -165,6 +165,36 @@ key from dependencies automatically, which means you need to add them to Erlang.mk and to the '.app.src' at the same time, duplicating the work. +If you really can't live without the legacy method, for one +reason or another, worry not; Erlang.mk will support it. And +if you need to create a new project that uses this method, you +just have to say so when bootstrapping: + +[source,bash] +$ make -f erlang.mk bootstrap-lib LEGACY=1 + +=== Automatic application resource file values + +When building the application resource file, Erlang.mk may +automatically add an `id` key with information about the +Git commit (if using Git), or an empty string otherwise. +It will only do this under specific conditions: + +* The application was built as a dependency of another, or +* The legacy method was used, and the '.app.src' file contained `{id, "git"}` + +This value is most useful when you need to help your users, +as it allows you to know which version they run exactly by +asking them to look in the file, or by running a simple +command on their production server: + +[source,erlang] +---- +1> application:get_all_key(cowboy). +{ok,[{description,"Small, fast, modular HTTP server."}, + {id,"2.0.0-pre.2-25-g0ffde50-dirty"}, +---- + === File formats Erlang.mk supports a variety of different source file formats. @@ -201,6 +231,56 @@ Erlang.mk also comes with plugins for the following formats: | .proto | src/ | Protocol buffers | ebin/*.beam |=== +=== Compilation options + +Erlang.mk provides a few variables that you can use to customize +the build process and the resulting files. + +==== 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 +the http://www.erlang.org/doc/man/erlc.html[erlc Manual] for the +full list. + +By default, Erlang.mk will set the following options: + +[source,make] +ERLC_OPTS = -Werror +debug_info +warn_export_vars +warn_shadow_vars +warn_obsolete_guard + +In other words: warnings as errors, debug info (recommended) and +enable warnings for exported variables, shadow variables and +obsolete guard functions. + +You can redefine this variable in your Makefile to change it +completely, either before or after including Erlang.mk: + +[source,make] +ERLC_OPTS = +debug_info + +You can also filter out some options from the defaults Erlang.mk +sets, by defining ERLC_OPTS after including Erlang.mk using the +`:=` operator. + +[source,make] +---- +include erlang.mk + +ERLC_OPTS := $(filter-out -Werror,$(ERLC_OPTS)) +---- + +==== ERLC_EXCLUDE + +`ERLC_EXCLUDE` can be used to exclude some modules from the +compilation. It's there for handling special cases, you should +not normally need it. + +To exclude a module, simply list it in the variable, either +before or after including Erlang.mk: + +[source,make] +ERLC_EXCLUDE = cowboy_http2 + === Cold and hot builds The first time you run `make`, Erlang.mk will build everything. @@ -235,10 +315,64 @@ transforms have changed. Erlang.mk also automatically keeps track of which files should be compiled first, for example when you have behaviors used by other modules in your project. -=== Generated source files === +If your project is stable, you may want to disable generating +the dependency tracking file every time you compile. You can +do this by adding the following line to your 'Makefile': + +[source,make] +NO_MAKEDEP ?= 1 + +As you can see, the snippet above uses `?=` instead of a +simple equal sign. This is to allow you to temporarily override +this value when you do make substantial changes to your project +(including a new header file, new module with dependencies, etc.) +and want to rebuild the dependency tracking file. You'll be +able to use the following command: + +[source,bash] +$ NO_MAKEDEP= make + +Otherwise, `make clean app` will of course force the +recompilation of your project. + +Erlang.mk can also keep track of the source files generated +by other means, for example if you generate code from a data +file in your repository. + +=== Generating Erlang source + +Erlang.mk provides hooks at different stages of the build process. +When your goal is to generate Erlang source files, you can +add your own rules before or after the dependency tracking +file is generated. To do this, you would add your hook before +or after including the 'erlang.mk' file. + +The easiest way is after: -Generated source files are supported: they should be listed as -dependencies to `$(PROJECT).d`: +[source,make] +---- +PROJECT = example + +include erlang.mk + +$(PROJECT).d:: src/generated_mod.erl + +src/generated_mod.erl:: gen-mod.sh + $(gen_verbose) ./gen-mod.sh $@ +---- + +In this case we use `$(gen_verbose)` to hide the details of +the build by default. Erlang.mk will simply say what file +is it currently generating. + +When using an external script to generate the Erlang source +file, it is recommended to depend on that script, so that +the source file gets generated again when the script gets +modified. + +If for whatever reason you prefer to hook before including +Erlang.mk, don't forget to set the `.DEFAULT_GOAL` variable, +otherwise nothing will get built: [source,make] ---- @@ -250,14 +384,10 @@ $(PROJECT).d:: src/generated_mod.erl include erlang.mk -src/generated_mod.erl:: +src/generated_mod.erl:: gen-mod.sh $(gen_verbose) ./gen-mod.sh $@ ---- -Note how `.DEFAULT_GOAL` is set to `all` near the beginning. Without -this, `$(PROJECT).d` would become the default target, changing the -expected behavior of this `Makefile`. - === Cleaning Building typically involves creating a lot of new files. Some |