From 9d6293e411f33338c0cf02c862038548b384cb14 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Thu, 31 Jul 2014 19:33:07 +0200 Subject: Switch to the new erlang.mk --- README.md | 367 +++++++++++++++++++++++++++++++++++++++----------------------- 1 file changed, 230 insertions(+), 137 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index f6450aa..b412dd5 100644 --- a/README.md +++ b/README.md @@ -11,8 +11,7 @@ Requirements `erlang.mk` requires GNU Make and expects to be ran in a standard unix environment with Erlang installed and in the `$PATH`. -`erlang.mk` uses `wget` for downloading the package index file -when the `pkg://` scheme is used. +`erlang.mk` uses `wget` for downloading the package index file. `erlang.mk` will NOT work if the path contains spaces. This is a limitation of POSIX compatible make build tools. @@ -25,24 +24,71 @@ Makefile: ``` Makefile PROJECT = my_project - include erlang.mk ``` -Dependencies +Alternatively you can use the following command to generate a skeleton +of an OTP application: + +``` bash +$ make -f erlang.mk bootstrap +``` + +To generate a skeleton of an OTP library: + +``` bash +$ make -f erlang.mk bootstrap-lib +``` + +Finally if you are going to create a release of this project you may +want to also use the `bootstrap-rel` target. + +You can combine targets to perform many operations. For example, the +shell command `make clean app` will have the effect of recompiling +the application fully, without touching the dependencies. + +A common workflow when editing a file would be to run `make` regularly +to see if it compiles (or less often `make clean app` if you want to +recompile everything), followed by `make dialyze` to see if there are +any type errors and then `make tests` to run the test suites. The +result of the test runs can be browsed from the `logs/index.html` file. + +Getting help ------------ -Erlang projects often depend on other projects to run. Adding dependencies -to the Makefile is easy. You need to create the variable `DEPS` listing -the names of all the dependencies, along with one `dep_$(NAME)` variable -per dependency giving the git repository and commit to retrieve. +You can use `make help` to get help about erlang.mk or its plugins. -These variables should be defined before the include line. +Packages +-------- + +A package index functionality is included with erlang.mk. + +To use a package, you simply have to add it to the `DEPS` variable +in your Makefile. For example this depends on Cowboy: ``` Makefile -DEPS = cowboy bullet -dep_cowboy = https://github.com/extend/cowboy.git 0.8.4 -dep_bullet = https://github.com/extend/bullet.git 0.4.1 +PROJECT = my_project +DEPS = cowboy +include erlang.mk +``` + +If the project you want is not included in the package index, or if +you want a different version, a few options are available. You can +edit the package file and contribute to it by opening a pull request. +You can use a custom package file, in which case you will probably +want to set the `PKG_FILE2` variable to its location. Or you can +put the project information directly in the Makefile. + +In the latter case you need to create a variable `dep_*` with the +asterisk replaced by the project name, for example `cowboy`. This +variable must contain three things: the fetching method used, the +URL and the version requested. + +The following snippet overrides the Cowboy version required: + +``` Makefile +DEPS = cowboy +dep_cowboy = git https://github.com/extend/cowboy 1.0.0 ``` They will always be compiled using the command `make`. If the dependency @@ -60,173 +106,220 @@ dep_ct_helper = https://github.com/extend/ct_helper.git master Please note that the test dependencies will only be compiled once when they are fetched, unlike the normal dependencies. -Package index +Releases +-------- + +If a `relx.config` file is present, erlang.mk will download `relx` +automatically and build the release into the `_rel` folder. This +is the default command when the file exists. + +No special configuration is required for this to work. + +Customization ------------- -A very basic package index is included with erlang.mk. You can list -all known packages with the `make pkg-list` command. You can search -a package with the `make pkg-search q=STRING` command, replacing -`STRING` with what you want to search. Use quotes around the string -if needed. +A custom erlang.mk may be created by editing the `build.config` +file and then running `make`. Only the core package handling +and erlc support are required. + +If you need more functionality out of your Makefile, you can add extra +targets after the include line, or create an erlang.mk plugin. + +Defining a target before the include line will override the default +target `all`. + +The rest of this README starts by listing the core functionality +and then details each plugin individually. + +Core functionality +------------------ + +The following targets are standard: + +`all` is equivalent to `deps app rel`. -In addition, it is possible to specify dependencies in a simplified -manner if they exist in the package index. The above example could -instead read as: +`deps` fetches and compiles the dependencies. + +`app` compiles the application. + +`rel` builds the release. + +`docs` generates the documentation. + +`tests` runs the test suites. + +`clean` deletes the output files. + +`distclean` deletes the output files but also any intermediate +files that are usually worth keeping around to save time, +and any other files needed by plugins (for example the Dialyzer +PLT file). + +`help` gives some help about using erlang.mk. + +You may add additional operations to them by using the double +colons. Make will run all targets sharing the same name when +invoked. ``` Makefile -DEPS = cowboy bullet -dep_cowboy = pkg://cowboy 0.8.4 -dep_bullet = pkg://bullet 0.4.1 +clean:: + @rm anotherfile ``` -erlang.mk will look inside the index for the proper URL and use it -for fetching the dependency. +You can enable verbose mode by calling Make with the variable +`V` set to 1. -All packages featured in the index are compatible with erlang.mk -with no extra work required. +``` bash +$ V=1 make -Releases --------- +Core package functionality +-------------------------- -If a `relx.config` file is present, erlang.mk will download `relx` -automatically and build the release into the `_rel` folder. This -is the default command when the file exists. +The following targets are specific to packages: -No special configuration is required for this to work. +`pkg-list` lists all packages in the index. -Compiled files --------------- +`pkg-search n=STRING` searches the index for STRING. -The following files will be automatically compiled: +Packages are downloaded into `DEPS_DIR` (`./deps/` by default). -| Wildcard | Description | -| ------------------------ | ----------------------------- | -| `src/$(PROJECT).app.src` | OTP application resource file | -| `src/*.erl` | Erlang source files | -| `src/*.core` | Core Erlang source files | -| `src/*.xrl` | Leex source files | -| `src/*.yrl` | Yecc source files | -| `templates/*.dtl` | ErlyDTL template files | +The package index file is downloaded from `PKG_FILE_URL` +and saved in `PKG_FILE2`. +``` +Core compiler functionality +--------------------------- -Only the `.app.src` file and at least one `.erl` file are required. +erlang.mk will automatically compile the OTP application +resource file found in `src/$(PROJECT).app.src` (do note it +requires an empty `modules` line); Erlang source files found +in `src/*.erl` or any subdirectory; Core Erlang source files +found in `src/*.core` or any subdirectory; Leex source files +found in `src/*.xrl` or any subdirectory; and Yecc source +files found in `src/*.yrl` or any subdirectory. -Commands --------- +You can change compilation options by setting the `ERLC_OPTS` +variable. It takes the arguments that will then be passed to +`erlc`. For more information, please see `erl -man erlc`. -The following targets are defined: - -| Targets | Description | -| ------------ | -------------------------------------------- | -| `all` | Compile the application and all dependencies | -| `clean-all` | Clean the application and all dependencies | -| `app` | Compile the application | -| `clean` | Clean the application | -| `deps` | Compile the dependencies | -| `clean-deps` | Clean the dependencies | -| `docs` | Generate the Edoc documentation | -| `clean-docs` | Clean the Edoc documentation | -| `test_*` | Run the common_test suite `*` | -| `tests` | Run all the common_test suites | -| `build-plt` | Generate the PLT needed by Dialyzer | -| `dialyze` | Run Dialyzer on the application | -| `pkg-list` | List packages in the index | -| `pkg-search` | Search for packages in the index | -| `rel` | Build a release | -| `clean-rel` | Delete the previously built release | - -Cleaning means removing all generated and temporary files. - -Dependencies are fetched as soon as a command involving them is -invoked. This means that most of the targets will trigger a -dependency fetch. It is only done once per dependency. - -You can run an individual test suite by using the special `test_*` -targets. For example if you have a common_test suite named `spdy` -and you want to run only this suite and not the others, you can -use the `make test_spdy` command. +You can specify a list of modules to be compiled first using +the `COMPILE_FIRST` variable. -The default target when calling `make` is `all` when no `relx.config` -exists, and `rel` when it does exist. +Bootstrap plugin +---------------- -You can combine targets to perform many operations. For example, the -shell command `make clean app` will have the effect of recompiling -the application fully, without touching the dependencies. +This plugin is available by default. It adds the following +targets: -A common workflow when editing a file would be to run `make` regularly -to see if it compiles (or less often `make clean app` if you want to -recompile everything), followed by `make dialyze` to see if there are -any type errors and then `make tests` to run the test suites. The -result of the test runs can be browsed from the `logs/index.html` file. +`bootstrap` generates a skeleton of an OTP application. -Options -------- +`bootstrap-lib` generates a skeleton of an OTP library. + +`bootstrap-rel` generates the files needed to build a release. + +`new` generate a skeleton module based on one of the available +templates. -The following variables can be overriden: +`list-templates` lists the available templates. -`V` defines the verbosity of the commands. You can set it -to an empty value to make commands verbose. +C compiler plugin +----------------- -`ERLC_OPTS` allows you to change the `erlc` compilation -options. You should always compile with at least the `+debug_info` set. +This plugin is not included by default. It is meant to +simplify the management of projects that include C source +code, like NIFs. -`COMPILE_FIRST` is a list of modules (not filenames) that should be -compiled before all others. +If the file `$(C_SRC_DIR)/Makefile` exists, then the plugin +simply calls it when needed. Otherwise it tries to compile +it directly. -`DEPS_DIR` is the path to the directory where the dependencies are -downloaded to. It defaults to `deps`. It will be propagated into -all the subsequent make calls, allowing all dependencies to use -the same folder as expected. +You can use a different directory than `./c_src` by setting +the `C_SRC_DIR` variable. -`EDOC_OPTS` allows you to specify -[options](http://www.erlang.org/doc/man/edoc.html#run-3) to pass to -`edoc` when building the documentation. Notice: not all options are -documented in one place; follow the links to get to the options for -the various operations of the documentation generation. +You can override the output file by setting the `C_SRC_OUTPUT` +variable. -`TEST_ERLC_OPTS` allows you to change the `erlc` compilation -options that are used for building the project for testing, but -also the tests themselves. Unlike `ERLC_OPTS` it doesn't consider -warnings to be errors and does not warn when `export_all` is used. +You can override the temporary file containing information +about Erlang's environment by setting the `C_SRC_ENV` variable. +This file is automatically generated on first run. -`CT_SUITES` is the list of common_test suites to run when you use -the `make tests` command. The default behaviour is to autodetect your -common_test suites. If you only want to run the tests in `ponies_SUITE` -you should set this variable to `ponies`. +Finally you can add extra compiler options using the +`C_SRC_OPTS` variable. You can also override the defaults +`CC` and `CFLAGS` if required. -`CT_OPTS` allows you to specify extra common_test options. +Common_test plugin +------------------ -`PLT_APPS` is the list of applications to include when building the -`.plt` file for Dialyzer. You do not need to put `erts`, `kernel` or -`stdlib` in there because they will always be included. The applications -the project depends on will also be included. +This plugin is available by default. -`DIALYZER_PLT` allows you to change the PLT file used by dialyzer. +There is nothing to configure to use it, simply create your +test suites in the `./test/` directory and erlang.mk will +figure everything out automatically. -`DIALYZER_OPTS` allows you to change the `dialyzer` options. +You can override the list of suites that will run when using +`make tests` by setting the `CT_SUITES` variable. -`PKG_FILE` allows you to change the location of the package index file -on your system. +You can add extra `ct_run` options by defining the `CT_OPTS` +variable. For more information please see `erl -man ct_run`. -`PKG_FILE_URL` allows you to change the URL from which the package index -file is fetched. +You can run an individual test suite by using the special `ct-*` +targets. For example if you have a common_test suite named `spdy` +and you want to run only this suite and not the others, you can +use the `make ct-spdy` command. -`RELX_CONFIG` is the location of the `relx.config` file, if any. +Dialyzer plugin +--------------- -`RELX` is the location of the `relx` executable for building releases. +This plugin is available by default. It adds the following +targets: -`RELX_URL` is the location where `relx` can be downloaded if it is -not found locally. +`plt` builds the PLT file for this application. -`RELX_OPTS` is for setting relx in-line options, if any. +`dialyze` runs Dialyzer. -Extra targets -------------- +The PLT file is built in `./$(PROJECT).plt` by default. +You can override this location by setting the `DIALYZER_PLT` +variable. -If you need more functionality out of your Makefile, you can add extra -targets after the include line. +The `PLT_APPS` variable lists the applications that will be +included in the PLT file. There is no need to specify `erts`, +`kernel`, `stdlib` or the project's dependencies here, as they +are automatically added. -Defining a target before the include line will override the default -target `all`. +Dialyzer options can be modified by defining the `DIALYZER_OPTS` +variable. For more information please see `erl -man dialyzer`. + +EDoc plugin +----------- + +This plugin is available by default. + +EDoc options can be specified in Erlang format by defining +the `EDOC_OPTS` variable. For more information please see +`erl -man edoc`. + +ErlyDTL plugin +-------------- + +This plugin is available by default. It adds automatic +compilation of ErlyDTL templates found in `templates/*.dtl` +or any subdirectory. + +Relx plugin +----------- + +This plugin is available by default. + +You can change the location of the `relx` executable +(downloaded automatically) by defining the `RELX` variable, +and the location of the configuration file by defining +the `RELX_CONFIG` variable. + +The URL used to download `relx` can be overriden by setting +the `RELX_URL` variable. + +You can change the generated releases location by setting +the `RELX_OUTPUT_DIR` variable. Any other option should go +in the `RELX_OPTS` variable. Support ------- -- cgit v1.2.3