diff options
Diffstat (limited to 'doc/src')
28 files changed, 757 insertions, 81 deletions
diff --git a/doc/src/guide/app.asciidoc b/doc/src/guide/app.asciidoc index 1320577..99ff052 100644 --- a/doc/src/guide/app.asciidoc +++ b/doc/src/guide/app.asciidoc @@ -1,3 +1,4 @@ +[[building]] == Building Erlang.mk can do a lot of things, but it is, first and @@ -5,7 +6,7 @@ foremost, a build tool. In this chapter we will cover the basics of building a project with Erlang.mk. For most of this chapter, we will assume that you are -using a project link:getting_started.asciidoc[generated by Erlang.mk]. +using a project xref:getting_started[generated by Erlang.mk]. === How to build @@ -46,13 +47,18 @@ up generating releases. ==== Application -You can build your application specifically, without -looking at handling dependencies or generating a release, -by running the following command: +You can build your application and dependencies without +generating a release by running the following command: [source,bash] $ make app +To build your application without touching dependencies +at all, you can use the `SKIP_DEPS` variable: + +[source,bash] +$ make app SKIP_DEPS=1 + This command is very useful if you have a lot of dependencies and develop on a machine with slow file access, like the Raspberry Pi and many other embedded devices. @@ -71,27 +77,26 @@ $ make deps This will fetch and compile all dependencies and their dependencies, recursively. -link:deps.asciidoc[Packages and dependencies] are covered +xref:deps[Packages and dependencies] are covered in the next chapter. ==== Release -You can generate the release, skipping the steps for building -the application and dependencies, by running the following -command: +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: [source,bash] $ make rel -This command can be useful if nothing changed except the -release configuration files. - -Consult the link:relx.asciidoc[Releases] chapter for more +Consult the xref:relx[Releases] chapter for more information about what releases are and how they are generated. -Note that this command may fail if a required dependency -is missing. - === Application resource file When building your application, Erlang.mk will generate the @@ -147,7 +152,7 @@ DEPS = cowlib ranch Any space before and after the value is dropped. -link:deps.asciidoc[Dependencies] are covered in details in +xref:deps[Dependencies] are covered in details in the next chapter. ==== Legacy method @@ -220,7 +225,7 @@ then built normally. 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 link:ports.asciidoc[NIFs and port drivers] +C code, as described in the xref:ports[NIFs and port drivers] chapter. Erlang.mk also comes with plugins for the following formats: diff --git a/doc/src/guide/architecture.asciidoc b/doc/src/guide/architecture.asciidoc deleted file mode 100644 index f96606b..0000000 --- a/doc/src/guide/architecture.asciidoc +++ /dev/null @@ -1,5 +0,0 @@ -== Architecture - -// @todo Write it. - -Placeholder chapter. diff --git a/doc/src/guide/asciidoc.asciidoc b/doc/src/guide/asciidoc.asciidoc index 6ba43ec..cc8336b 100644 --- a/doc/src/guide/asciidoc.asciidoc +++ b/doc/src/guide/asciidoc.asciidoc @@ -1,5 +1,82 @@ -== Asciidoc documentation +[[asciidoc]] +== AsciiDoc documentation -// @todo Write it. +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. -Placeholder chapter. +=== Requirements + +It is necessary to have http://asciidoc.org/[AsciiDoc], +http://xmlsoft.org/XSLT/xsltproc2.html[xsltproc] and +http://dblatex.sourceforge.net/[dblatex] installed on your +system for Erlang.mk to generate documentation from AsciiDoc sources. + +=== Writing AsciiDoc documentation + +http://asciidoc.org/[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 http://asciidoc.org/userguide.html[AsciiDoc user guide] +describes the AsciiDoc syntax. + +The https://github.com/ninenines/erlang.mk/tree/master/doc/src/guide[Erlang.mk user guide] +is written in AsciiDoc and can be used as an example. The entry +file is https://github.com/ninenines/erlang.mk/blob/master/doc/src/guide/book.asciidoc[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. + +=== Configuration + +All of the AsciiDoc related configuration can be done directly +inside the files themselves. + +=== Usage + +To build all documentation: + +[source,bash] +$ make docs + +To build only the AsciiDoc documentation: + +[source,bash] +$ make asciidoc + +To build only the user guide: + +[source,bash] +$ make asciidoc-guide + +To build only the manual: + +[source,bash] +$ make asciidoc-manual + +To install man pages on Unix: + +[source,bash] +$ 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: + +[source,bash] +$ 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. diff --git a/doc/src/guide/book.asciidoc b/doc/src/guide/book.asciidoc index f084e6f..a39b907 100644 --- a/doc/src/guide/book.asciidoc +++ b/doc/src/guide/book.asciidoc @@ -1,4 +1,5 @@ // a2x: --dblatex-opts "-P latex.output.revhistory=0 -P doc.publisher.show=0 -P index.numbered=0" +// a2x: --xsltproc-opts "--stringparam use.id.as.filename 1" // a2x: -d book --attribute tabsize=4 = Erlang.mk User Guide @@ -14,6 +15,7 @@ include::updating.asciidoc[Updating Erlang.mk] include::limitations.asciidoc[Limitations] +[[code]] = Code include::app.asciidoc[Building] @@ -28,12 +30,14 @@ include::escripts.asciidoc[Escripts] include::compat.asciidoc[Compatibility with other build tools] +[[docs]] = Documentation include::asciidoc.asciidoc[Asciidoc documentation] include::edoc.asciidoc[EDoc comments] +[[tests]] = Tests include::shell.asciidoc[Erlang shell] @@ -42,8 +46,6 @@ include::eunit.asciidoc[EUnit] include::common_test.asciidoc[Common Test] -include::property_based_testing.asciidoc[Property based testing] - include::coverage.asciidoc[Code coverage] include::ci.asciidoc[Continuous integration] @@ -52,16 +54,18 @@ include::dialyzer.asciidoc[Dialyzer] include::xref.asciidoc[Xref] +[[plugins]] = Third-party plugins include::external_plugins.asciidoc[External plugins] +include::external_plugins_list.asciidoc[List of plugins] + +[[about]] = About Erlang.mk include::why.asciidoc[Why erlang.mk?] include::history.asciidoc[Short history] -include::architecture.asciidoc[Architecture] - include::contributing.asciidoc[Contributing] diff --git a/doc/src/guide/ci.asciidoc b/doc/src/guide/ci.asciidoc index 8a96ed4..24cfc05 100644 --- a/doc/src/guide/ci.asciidoc +++ b/doc/src/guide/ci.asciidoc @@ -1,3 +1,4 @@ +[[ci]] == Continuous integration // @todo Write it. diff --git a/doc/src/guide/common_test.asciidoc b/doc/src/guide/common_test.asciidoc index 7daeae5..aec8747 100644 --- a/doc/src/guide/common_test.asciidoc +++ b/doc/src/guide/common_test.asciidoc @@ -1,5 +1,91 @@ +[[ct]] == Common Test -// @todo Write it. +Common Test is Erlang's functional testing framework. +Erlang.mk automates the discovery and running of Common +Test suites. -Placeholder chapter. +=== Writing tests + +The http://www.erlang.org/doc/apps/common_test/write_test_chapter.html[Common Test user guide] +is the best place to learn how to write tests. Erlang.mk +requires that file names for test suites end with '_SUITE.erl' +and that the files be located in the '$(TEST_DIR)' directory. +This defaults to 'test/'. + +=== Configuration + +The `CT_OPTS` variable allows you to set extra Common Test +options. Options are documented in the +http://www.erlang.org/doc/apps/common_test/run_test_chapter.html[Common Test user guide]. +You can use it to set Common Test hooks, for example: + +[source,make] +CT_OPTS = -ct_hooks cowboy_ct_hook + +The `CT_SUITES` variable can be used to override what +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`: + +[source,make] +CT_SUITES = http ws + +=== Usage + +To run all tests (including Common Test): + +[source,bash] +$ make tests + +To run all tests and static checks (including Common Test): + +[source,bash] +$ make check + +You can also run Common Test separately: + +[source,bash] +$ 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: + +[source,bash] +$ make ct-http + +Erlang.mk provides a convenient way to run a specific +group or a specific test case within a specific group, +using the variable `t`. Note that this only applies to +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: + +[source,bash] +$ make ct-http t=http_compress + +Similarly, to run a specific test case in that group: + +[source,bash] +$ make ct-http t=http_compress:headers_dupe + +To do the same against a multi-application repository, +you can use the `-C` option: + +[source,bash] +$ 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: + +[source,bash] +$ make -C deps/cowboy ct-http t=http_compress + +Finally, xref:coverage[code coverage] is available, +but covered in its own chapter. diff --git a/doc/src/guide/compat.asciidoc b/doc/src/guide/compat.asciidoc index 61386e7..8c8f935 100644 --- a/doc/src/guide/compat.asciidoc +++ b/doc/src/guide/compat.asciidoc @@ -1,3 +1,4 @@ +[[compat]] == Compatibility with other build tools Erlang.mk tries its best to be compatible with the other Erlang @@ -20,7 +21,7 @@ and adds a Makefile to the project that Erlang.mk can then use for building: _Autoload_ is documented in more details in the -link:deps.asciidoc[Packages and dependencies] chapter. +xref:deps[Packages and dependencies] chapter. === Erlang.mk projects as Rebar dependencies @@ -49,11 +50,12 @@ the `DEPS` and `ERLC_OPTS` variables, among others. This means that the Rebar family builds your project much the same way as Erlang.mk. +// @todo Sanity check chapter. 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 link:sanity_check.asciidoc[Sanity check] chapter to find -out how to detect such issues. +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` diff --git a/doc/src/guide/contributing.asciidoc b/doc/src/guide/contributing.asciidoc index e712788..58e5de6 100644 --- a/doc/src/guide/contributing.asciidoc +++ b/doc/src/guide/contributing.asciidoc @@ -1,5 +1,116 @@ +[[contributing]] == Contributing -// @todo Write it. +You are welcome and encouraged to contribute. -Placeholder chapter. +This is how. + +=== Priorities + +From the most important to the least important: + +* Bugs +* Package issues/additions +* Refactoring +* Features + +=== Bugs + +If you have found a bug, you should open a ticket. Include +everything relevant including the command you used, output, +a link to the code that triggers the issue, why you think +this is a bug, etc. + +If you think you have found a bug but you are not sure, you +should open a ticket as previously explained. + +If you have found a bug and you need it to be solved RIGHT +NOW, open a ticket as previously explained. + +Once you have opened a ticket, be patient, try to answer +questions in a timely manner and confirm that the bug was +indeed fixed when it is. + +If you can't be patient, either try to solve the bug and +contribute the fix back or become a paying customer. + +=== Code + +The code is located in the 'core/\*.mk' and 'plugins/\*.mk' files. +The tests are located in the 'test/Makefile' and 'test/*.mk' files. + +If you have a fix or a hack for a bug, you should open a +pull request. Any fix should include a test case that fails +before the fix and is working after. + +If you have a test case that reproduces a bug, but no fix for +it, you should open a pull request. + +Changes need to be tested with at least the `make check` +command. A specific test case can be tested using `make check c=CASE` +with `CASE` the name of the target to run. Output can be +modulated using the `V` variable, which is an integer +from 0 to 4. A typical use would be `make check c=dialyzer V=3`. +The value 4 is particular and shows expanded commands right +before they are executed. + +To run tests in parallel, use the `-j` option. It is generally +a good idea to also use the `-k` option to run all tests even +if one fails. For example: `make check -j 32 -k`. + +Some changes should be tested against all packages. Continue +reading for more details on testing them. + +=== Packages + +You can search existing packages using the `make search q=STRING` +command. This can be done both from an Erlang.mk project or +directly from the Erlang.mk repository. + +Packages can be added to the index using the `pkg_add.sh` script. + +[source,bash] +---- +$ git clone https://github.com/$YOURUSERNAME/erlang.mk +$ cd erlang.mk +$ ./pkg_add.sh cowboy git https://github.com/ninenines/cowboy 1.0.0 + http://ninenines.eu "Small, fast and modular HTTP server." +$ git push origin master +---- + +Before sending a pull request, you should test your package. +You can use the following command: `make check p=PACKAGE`, +where `PACKAGE` is the name of the package, for example +`cowboy`. + +To test all packages, the `make packages` command can be used. +This can take a long time. Some packages will fail with certain +versions of Erlang, or if a prerequisite is missing from your system. +You can of course speed things up using the `-j` and `-k` flags. + +After all packages have been tested, you can run the command +`make summary` to know what changed since the previous run. + +=== Documentation + +The documentation is always right. + +If you think you have found a mistake in the documentation, +this is a bug. You can either open a ticket or send a pull +request. + +To make sure that the documentation changes work, install +the listed xref:asciidoc[Requirements] on your system and +run `make docs`. + +=== Feature requests + +If you have an awesome idea or need something that Erlang.mk +doesn't provide yet, open a ticket. Provide as much detail as +possible. + +If you have code, great! Open a pull request as previously +explained. + +If not, you can still improve your feature request by writing +the related documentation. diff --git a/doc/src/guide/coverage.asciidoc b/doc/src/guide/coverage.asciidoc index 5e74f36..f33f878 100644 --- a/doc/src/guide/coverage.asciidoc +++ b/doc/src/guide/coverage.asciidoc @@ -1,3 +1,4 @@ +[[coverage]] == Code coverage // @todo Write it. diff --git a/doc/src/guide/deps.asciidoc b/doc/src/guide/deps.asciidoc index 9335439..eb6f2f0 100644 --- a/doc/src/guide/deps.asciidoc +++ b/doc/src/guide/deps.asciidoc @@ -1,3 +1,4 @@ +[[deps]] == Packages and dependencies Erlang.mk can fetch and compile the dependencies that your @@ -72,7 +73,7 @@ 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 link:ports.asciidoc[NIFs and port drivers] +about that in the xref:ports[NIFs and port drivers] chapter. Another variable, `LOCAL_DEPS`, allows specifying runtime @@ -333,7 +334,7 @@ Erlang.mk will also export the `REBAR_DEPS_DIR` variable for compatibility with Rebar build tools, as long as they are recent enough. -=== Dependencies local to the repository +=== Many applications in one repository In addition to the dependencies that are fetched, Erlang.mk also allows you to have dependencies local to your repository. diff --git a/doc/src/guide/dialyzer.asciidoc b/doc/src/guide/dialyzer.asciidoc index 7377c82..58fe53f 100644 --- a/doc/src/guide/dialyzer.asciidoc +++ b/doc/src/guide/dialyzer.asciidoc @@ -1,5 +1,73 @@ +[[dialyzer]] == Dialyzer -// @todo Write it. +Dialyzer is a tool that will detect discrepancies in your +program. It does so using a technique known as success +typing analysis which has the advantage of providing no +false positives. Dialyzer is able to detect type errors, +dead code and more. -Placeholder chapter. +Erlang.mk provides a wrapper around Dialyzer. + +=== How it works + +Dialyzer requires a PLT file to work. The PLT file contains +the analysis information from all applications which are not +expected to change, or rarely do. These would be all the +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. + +=== 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 +be written to (and read from). By default this is +'$(PROJECT).plt' in the project's directory. Note that +the `DIALYZER_PLT` variable is exported and is understood +by Dialyzer directly. + +The `PLT_APPS` variable can be used to add additional +applications to the PLT. You can either list application +names or paths to these applications. + +Erlang.mk defines two variables for specifying options +for the analysis: `DIALYZER_DIRS` and `DIALYZER_OPTS`. +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. + +=== Usage + +To perform an analysis, run the following command: + +[source,bash] +$ 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: + +[source,bash] +$ 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`. diff --git a/doc/src/guide/edoc.asciidoc b/doc/src/guide/edoc.asciidoc index f54d447..9fc1a74 100644 --- a/doc/src/guide/edoc.asciidoc +++ b/doc/src/guide/edoc.asciidoc @@ -1,5 +1,48 @@ +[[edoc]] == EDoc comments -// @todo Write it. +Erlang.mk provides a thin wrapper on top of EDoc, an application +that generates documentation based on comments found in modules. -Placeholder chapter. +=== Writing EDoc comments + +The http://www.erlang.org/doc/apps/edoc/chapter.html[EDoc user guide] +explains everything you need to know about EDoc comments. + +=== Configuration + +The `EDOC_OPTS` variable allows you to specify additional +EDoc options. Options are documented in the +http://www.erlang.org/doc/man/edoc.html#run-2[EDoc manual]. + +A common use for this variable is to enable Markdown in doc +comments, using the `edown` application: + +[source,make] +DOC_DEPS = edown +EDOC_OPTS = {doclet, edown_doclet} + +=== Usage + +To build all documentation, you would typically use: + +[source,bash] +$ 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: + +[source,bash] +$ make edoc + +You can enable automatic generation on `make docs` by adding +the following to your Makefile: + +[source,make] +---- +docs:: edoc +---- diff --git a/doc/src/guide/escripts.asciidoc b/doc/src/guide/escripts.asciidoc index fcc6080..3d68c77 100644 --- a/doc/src/guide/escripts.asciidoc +++ b/doc/src/guide/escripts.asciidoc @@ -1,3 +1,4 @@ +[[escript]] == Escripts // @todo Write it. diff --git a/doc/src/guide/eunit.asciidoc b/doc/src/guide/eunit.asciidoc index 1a16776..496b674 100644 --- a/doc/src/guide/eunit.asciidoc +++ b/doc/src/guide/eunit.asciidoc @@ -1,5 +1,122 @@ +[[eunit]] == EUnit -// @todo Write it. +EUnit is the tool of choice for unit testing. Erlang.mk +automates a few things on top of EUnit, including the +discovery and running of unit tests. -Placeholder chapter. +=== Writing tests + +The http://www.erlang.org/doc/apps/eunit/chapter.html[EUnit user guide] +is the best place to learn how to write tests. Of note is +that all functions ending with `_test` or `_test_` will be +picked up as EUnit test cases. + +Erlang.mk will automatically pick up tests found in any of +the Erlang modules of your application. It will also pick up +tests located in the '$(TEST_DIR)' directory, which defaults +to 'test/'. + +It is generally a good practice to hide test code from +the code you ship to production. With Erlang.mk, you can +do this thanks to the `TEST` macro. It is only defined +when running tests: + +[source,erlang] +---- +-ifdef(TEST). + +%% Insert tests here. + +-endif. +---- + +Be careful, however, if you include the EUnit header file, +as it also defines the `TEST` macro. Make sure to only include +it inside an `ifdef` block, otherwise tests will always be +compiled. + +[source,erlang] +---- +-ifdef(TEST). + +-include_lib(\"eunit/include/eunit.hrl\"). + +%% Insert tests here. + +-endif. +---- + +Erlang.mk will automatically recompile your code when you +perform a normal build after running tests, and vice versa. + +=== Configuration + +The `EUNIT_OPTS` variable allows you to specify additional +EUnit options. Options are documented in the +http://www.erlang.org/doc/man/eunit.html#test-2[EUnit manual]. +At the time of writing, the only available option is `verbose`: + +[source,make] +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: + +[source,make] +EUNIT_ERL_OPTS = -args_file rel/vm.args -config rel/sys.config + +=== Usage + +To run all tests (including EUnit): + +[source,bash] +$ make tests + +To run all tests and static checks (including EUnit): + +[source,bash] +$ make check + +You can also run EUnit separately: + +[source,bash] +$ make eunit + +EUnit will be quiet by default, only outputting errors. +You can easily make it verbose for a single invocation: + +[source,bash] +$ 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` +module (instead of all tests from the entire project), +one could write: + +[source,bash] +$ make eunit t=cow_http_hd + +Similarly, to run a specific test case: + +[source,bash] +$ make eunit t=cow_http_hd:parse_accept_test_ + +To do the same against a multi-application repository, +you can use the `-C` option: + +[source,bash] +$ 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: + +[source,bash] +$ make -C deps/cowlib eunit t=cow_http_hd + +Finally, xref:coverage[code coverage] is available, +but covered in its own chapter. diff --git a/doc/src/guide/external_plugins.asciidoc b/doc/src/guide/external_plugins.asciidoc index 027b1b9..d3dafaa 100644 --- a/doc/src/guide/external_plugins.asciidoc +++ b/doc/src/guide/external_plugins.asciidoc @@ -1,3 +1,4 @@ +[[plugins_usage]] == External plugins It is often convenient to be able to keep the build files @@ -60,7 +61,7 @@ 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 +For example, if you have two plugins 'mk/dist.mk' and 'mk/templates.mk', you could write the following 'plugins.mk' file: diff --git a/doc/src/guide/external_plugins_list.asciidoc b/doc/src/guide/external_plugins_list.asciidoc new file mode 100644 index 0000000..f30797f --- /dev/null +++ b/doc/src/guide/external_plugins_list.asciidoc @@ -0,0 +1,48 @@ +[[plugins_list]] +== List of plugins + +This is a non-exhaustive list of Erlang.mk plugins, sorted +alphabetically. + +=== efene.mk + +An https://github.com/ninenines/efene.mk[Efene plugin] for Erlang.mk. +http://efene.org/[Efene] is an alternative language for the BEAM. + +=== elixir.mk + +An https://github.com/botsunit/elixir.mk[Elixir plugin] for +Erlang.mk. http://elixir-lang.org/[Elixir] is an alternative +language for the BEAM. + +=== elvis.mk + +An https://github.com/inaka/elvis.mk[Elvis plugin] for Erlang.mk. +Elvis is an https://github.com/inaka/elvis[Erlang style reviewer]. + +=== geas + +https://github.com/crownedgrouse/geas[Geas] gives aggregated +information on a project and its dependencies, and is available +as an Erlang.mk plugin. + +=== hexer.mk + +An https://github.com/inaka/hexer.mk[Hex plugin] for Erlang.mk. +Hex is a https://hex.pm/[package manager for the Elixir ecosystem]. + +=== lfe.mk + +An https://github.com/ninenines/lfe.mk[LFE plugin] for Erlang.mk. +LFE, or http://lfe.io/[Lisp Flavoured Erlang], is an alternative +language for the BEAM. + +=== mix.mk + +A https://github.com/botsunit/mix.mk[Mix plugin] for Erlang.mk, +to generate a compatible configuration file for +http://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html[Mix]. + +=== reload.mk + +A https://github.com/bullno1/reload.mk[live reload plugin] for Erlang.mk. diff --git a/doc/src/guide/getting_started.asciidoc b/doc/src/guide/getting_started.asciidoc index 34280d1..ef2f6e8 100644 --- a/doc/src/guide/getting_started.asciidoc +++ b/doc/src/guide/getting_started.asciidoc @@ -1,3 +1,4 @@ +[[getting_started]] == Getting started This chapter explains how to get started using Erlang.mk. @@ -74,7 +75,7 @@ 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 -link:updating.asciidoc[Updating Erlang.mk] chapter for more +xref:updating[Updating Erlang.mk] chapter for more information. Of course, the generated project can now be compiled: @@ -125,7 +126,7 @@ $ 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 link:deps.asciidoc[Packages and dependencies] +depend on. Consult the xref:deps[Packages and dependencies] chapter for more information. When you run `make` from now on, Erlang.mk will compile your @@ -150,7 +151,7 @@ _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 link:relx.asciidoc[Releases] +hardware just yet. Just consult the xref:relx[Releases] chapter for various tips to speed up build time during development. @@ -183,6 +184,25 @@ Eshell V7.0 (abort with ^G) Simple as that! +=== Using spaces instead of tabs + +Erlang.mk defaults to tabs when creating files from templates. +This is in part because of a personal preference, and in part +because it is much easier to convert tabs to spaces than the +opposite. + +Use the `SP` variable if you prefer spaces. Set it to the number +of spaces per indentation level you want. + +For example, if you prefer two spaces per indentation level: + +[source,bash] +$ make -f erlang.mk bootstrap SP=2 + +When you bootstrap the project initially, the variable automatically +gets added to the Makefile, so you only need to provide it when +you get started. + === Using templates It is no secret that Erlang's OTP behaviors tend to have some @@ -217,6 +237,23 @@ $ make All that's left to do is to open it in your favorite editor and make it do something! +=== Hiding Erlang.mk from git + +Erlang.mk is a large text file. It can easily take a large part of +a `git diff` or a `git grep` command. You can avoid this by telling +Git that 'erlang.mk' is a binary file. + +Add this to your '.gitattributes' file. This is a file that you +can create at the root of your repository: + +---- +erlang.mk -diff +---- + +The 'erlang.mk' file will still appear in diffs and greps, but +as a binary file, meaning its contents won't be shown by default +anymore. + === Getting help During development, if you don't remember the name of a target, diff --git a/doc/src/guide/history.asciidoc b/doc/src/guide/history.asciidoc index 41eec09..9202743 100644 --- a/doc/src/guide/history.asciidoc +++ b/doc/src/guide/history.asciidoc @@ -1,5 +1,66 @@ +[[history]] == Short history -// @todo Write it. +This chapter aims to be a brief record of the life of the +Erlang.mk project. -Placeholder chapter. +=== Before Erlang.mk + +Erlang.mk originates from the Cowboy project. Cowboy started +as a Rebar project and I, Loïc Hoguin, was very happy with it +for a couple years. Over time however I started getting annoyed +and frustrated by a number of things, including bad defaults, +changing defaults and overall slowness. + +In particular, at the time I gave up on Rebar, the Cowboy +test suite was taking about five minutes to run. A quick experiment +showed I could get much lower times by simply invoking `ct_run` +directly. On January 4th, 2013, the Cowboy test suite took less +than a minute to complete. + +Following this success I started removing a little more and, +on the fateful day of January 5th, 2013, removed the dependency +on Rebar entirely. Rebar, and in particular the concept of +dependencies, was, and still is, a pretty strong influence. + +Erlang.mk was conceived. + +A few months passed and, on May 1st, 2013, the Erlang.mk +repository was created. Erlang.mk was born. + +Little did I know how much it would grow. + +=== Lifetime of the project + +Erlang.mk would eventually become a much larger file able to +deal with many more projects than just Cowboy. From the birth +of the project, the biggest force for growth was user contributions, +because Erlang.mk appealed to a variety of people with different +needs, needs that Erlang.mk was not fulfilling yet. + +The project was split into smaller files focused on a different +feature each, and a build script was written to build the single +Erlang.mk file. + +A test suite was contributed by a user, and later taken as a basis +for the current, much more complete test suite. Turns out testing +a Makefile is pretty straightforward. + +A package index was added to solve the problem of discovering +Erlang projects. + +After trying to see if Erlang build tools could cooperate, the +decision was made to improve compatibility with existing Rebar +projects by patching Rebar out, using Rebar. This feature, called +autopatch, proved very successful and made Erlang.mk compatible +with more than 90% of all Erlang projects. + +Erlang.mk documentation was much improved and the Erlang.mk website +was created in the summer of 2015. + +Over the year of 2015, Erlang.mk went from curiosity to a serious +alternative to other Erlang build tools. The user base increased +immensely and large projects started using it, including RabbitMQ +from the 3.6.0 release onward. + +A bright future lies ahead. diff --git a/doc/src/guide/installation.asciidoc b/doc/src/guide/installation.asciidoc index f03dafa..cc18e7f 100644 --- a/doc/src/guide/installation.asciidoc +++ b/doc/src/guide/installation.asciidoc @@ -1,3 +1,4 @@ +[[installation]] == Installation This chapter explains how to setup your system in @@ -95,6 +96,13 @@ to find all packages related to GCC: [source,bash] $ pacman -Ss gcc +If you are going to compile C/C++ code, you will need to +install this package, as Erlang.mk cannot use the normal +"gcc" package: + +[source,bash] +$ pacman -S mingw-w64-x86_64-gcc + You can also run commands under the MSYS2 environment from the Windows command line or batch files. This command will install GNU Make and Git: diff --git a/doc/src/guide/limitations.asciidoc b/doc/src/guide/limitations.asciidoc index 86ca918..1bf33d2 100644 --- a/doc/src/guide/limitations.asciidoc +++ b/doc/src/guide/limitations.asciidoc @@ -1,3 +1,4 @@ +[[limitations]] == Limitations No software is perfect. diff --git a/doc/src/guide/overview.asciidoc b/doc/src/guide/overview.asciidoc index a81dd7a..8fa57fe 100644 --- a/doc/src/guide/overview.asciidoc +++ b/doc/src/guide/overview.asciidoc @@ -1,3 +1,4 @@ +[[overview]] == Overview Now that you know how to get started, let's take a look at @@ -9,20 +10,20 @@ 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 link:app.asciidoc[Erlang-specific files] +Erlang.mk will happily build all xref:building[Erlang-specific files] you throw at it. Other kinds of files too, like C or C++ code -when you are working on link:ports.asciidoc[a NIF or a port driver]. +when you are working on xref:ports[a NIF or a port driver]. -Erlang.mk embraces the concept of link:deps.asciidoc[source dependencies]. +Erlang.mk embraces the concept of xref:deps[source dependencies]. It can fetch dependency source code using a variety of mechanisms, including fetching from Git, Mercurial or SVN. -Erlang.mk will automatically link:relx.asciidoc[generate releases] -when applicable. It can also link:escripts.asciidoc[generate escripts]. +Erlang.mk will automatically xref:relx[generate releases] +when applicable. It can also xref:escript[generate escripts]. === Exploring the package index -Erlang.mk comes with a link:deps.asciidoc[built-in package index]. +Erlang.mk comes with a xref:deps[built-in package index]. It is built as an extension of the dependency system and is meant to be used for discovery purposes. @@ -46,14 +47,14 @@ $ make search q=cowboy Erlang.mk supports _EDoc_ and _Asciidoc_. -link:edoc.asciidoc[EDoc] generates HTML documentation directly from +xref:edoc[EDoc] 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 link:asciidoc.asciidoc[Asciidoc] plugin expects all documentation +The xref:asciidoc[Asciidoc] 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. @@ -63,26 +64,24 @@ your repository. Erlang.mk supports a lot of different testing and static analysis tools. -The link:shell.asciidoc[make shell] command allows you +The xref:shell[make shell] command allows you to test your project manually. You can automate these -unit tests with link:eunit.asciidoc[EUnit] and test -your entire system with link:common_test.asciidoc[Common Test]. -link:property_based_testing.asciidoc[Property based testing] -with Triq is a strong alternative to writing unit tests -manually. link:coverage.asciidoc[Code coverage] can of course +unit tests with xref:eunit[EUnit] and test +your entire system with xref:ct[Common Test]. +xref:coverage[Code coverage] can of course be enabled during tests. Erlang.mk comes with features to make your life easier when -setting up and using link:ci.asciidoc[Continuous integration]. +setting up and using xref:ci[Continuous integration]. On the static analysis side of things, Erlang.mk comes with -support for link:dialyzer.asciidoc[Dialyzer], link:xref.asciidoc[Xref] -and link:elvis.asciidoc[Elvis], performing success typing -analysis, cross reference and style reviewing. +support for xref:dialyzer[Dialyzer] and xref:xref[Xref], +to perform success typing analysis and cross referencing +of the code. === Need more? -Not convinced yet? You can read about link:why.asciidoc[why you should use Erlang.mk] -and its link:history.asciidoc[history]. And if you're still not +Not convinced yet? You can read about xref:why[why you should use Erlang.mk] +and its xref:history[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. diff --git a/doc/src/guide/ports.asciidoc b/doc/src/guide/ports.asciidoc index b4527fb..02c636f 100644 --- a/doc/src/guide/ports.asciidoc +++ b/doc/src/guide/ports.asciidoc @@ -1,3 +1,4 @@ +[[ports]] == NIFs and port drivers Erlang.mk can not only build Erlang projects, but also the C code @@ -35,8 +36,6 @@ It contains a few variable definitions for the environment used for the build: `ERL_INTERFACE_LIB_DIR`:: Path to the Erl_Interface static libraries. -// @todo We should remove this file on clean, not distclean. - === Using a custom Makefile Erlang.mk will automatically run `make` if it detects a Makefile @@ -66,9 +65,19 @@ before including Erlang.mk: [source,make] C_SRC_TYPE = executable -The generated file will be saved to '$(C_SRC_OUTPUT)'. It -defaults to '$(CURDIR)/priv/$(PROJECT).so', the filename -adequately fitting a Unix shared library. +The generated file name varies depending on the type of project +you have (shared library or executable) and on the platform you +build the project on. + +For shared libraries, the generated file name will be +'$(C_SRC_OUTPUT)$(C_SRC_SHARED_EXTENSION)', with the default +being '$(CURDIR)/priv/$(PROJECT)' followed by the extension: +`.dll` on Windows, `.so` everywhere else. + +For executables, the generated file name is +'$(C_SRC_OUTPUT)$(C_SRC_EXECUTABLE_EXTENSION)', with the same +default except for the extension: `.exe` on Windows, and otherwise +nothing. Erlang.mk sets appropriate compile and linker flags by default. These flags vary depending on the platform, and can of course diff --git a/doc/src/guide/property_based_testing.asciidoc b/doc/src/guide/property_based_testing.asciidoc deleted file mode 100644 index c652b2b..0000000 --- a/doc/src/guide/property_based_testing.asciidoc +++ /dev/null @@ -1,5 +0,0 @@ -== Property based testing - -// @todo Write it. - -Placeholder chapter. diff --git a/doc/src/guide/releases.asciidoc b/doc/src/guide/releases.asciidoc index e7b1333..46183e6 100644 --- a/doc/src/guide/releases.asciidoc +++ b/doc/src/guide/releases.asciidoc @@ -1,3 +1,4 @@ +[[relx]] == Releases Erlang.mk relies on _Relx_ for generating releases. This diff --git a/doc/src/guide/shell.asciidoc b/doc/src/guide/shell.asciidoc index 083c160..a527253 100644 --- a/doc/src/guide/shell.asciidoc +++ b/doc/src/guide/shell.asciidoc @@ -1,3 +1,4 @@ +[[shell]] == Erlang shell Erlang.mk provides a convenient target for starting a shell diff --git a/doc/src/guide/updating.asciidoc b/doc/src/guide/updating.asciidoc index ecd4a70..61d913d 100644 --- a/doc/src/guide/updating.asciidoc +++ b/doc/src/guide/updating.asciidoc @@ -1,3 +1,4 @@ +[[updating]] == Updating Erlang.mk This chapter describes how to update the 'erlang.mk' file diff --git a/doc/src/guide/why.asciidoc b/doc/src/guide/why.asciidoc index 3a84940..e91b64c 100644 --- a/doc/src/guide/why.asciidoc +++ b/doc/src/guide/why.asciidoc @@ -1,7 +1,8 @@ +[[why]] == Why Erlang.mk Why would you choose Erlang.mk, if not for its -link:overview.asciidoc[many features]? This chapter will +xref:overview[many features]? This chapter will attempt to answer that. === Erlang.mk is fast diff --git a/doc/src/guide/xref.asciidoc b/doc/src/guide/xref.asciidoc index 889aa41..44ed190 100644 --- a/doc/src/guide/xref.asciidoc +++ b/doc/src/guide/xref.asciidoc @@ -1,3 +1,4 @@ +[[xref]] == Xref // @todo Write it. |