diff options
| -rw-r--r-- | README.md | 113 | ||||
| -rw-r--r-- | doc/src/guide/book.asciidoc | 6 | ||||
| -rw-r--r-- | doc/src/guide/limitations.asciidoc | 45 | ||||
| -rw-r--r-- | doc/src/guide/why.asciidoc | 80 |
4 files changed, 147 insertions, 97 deletions
@@ -1,23 +1,12 @@ erlang.mk ========= -Common Makefile rules for building and testing Erlang applications. +A build tool for Erlang that just works. -Also features support for dependencies and a package index. +[Check out our upcoming user guide!](doc/src/guide/book.asciidoc) -[Check out our upcoming documentation!](doc/src/guide/book.asciidoc) - -Why erlang.mk? --------------- - -A number of reasons might push someone to use erlang.mk instead of -an Erlang-based build tool, including but not limited to the following: - - * You want a very fast compilation and test cycle - * You want the full power of Unix at your disposal when hooking into your build tool - * You want to be able to easily edit the damn build tool and fix it when it fails - * You want to use the deps mechanism with non-Erlang Makefile-based projects - * Your project will be part of a larger make or automake based environment +The README only contains legacy documentation that was not moved to +the guide yet. Check there if you don't find what you're looking for. Requirements ------------ @@ -25,41 +14,8 @@ 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. - -`erlang.mk` will NOT work if the path contains spaces. This is a -limitation of POSIX compatible make build tools. - -Usage ------ - -Add the file `erlang.mk` to your project, then use the following base -Makefile: - -``` Makefile -PROJECT = my_project -include erlang.mk -``` - -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. +Common workflow +--------------- 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 @@ -67,11 +23,6 @@ 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 ------------- - -You can use `make help` to get help about erlang.mk or its plugins. - Packages -------- @@ -152,11 +103,11 @@ when used as dependency. The patching occurs only once, immediately after the package has been fetched. -erlang.mk defines a number of packages to be patched. You can add -more packages to the list by appending the `AUTOPATCH` variable. +The autopatch feature is applied to all dependencies. To disable +it for a dependency, use the `NO_AUTOPATCH` variable: ``` Makefile -AUTOPATCH += gproc +NO_AUTOPATCH += gproc ``` Releases @@ -226,6 +177,11 @@ You can enable verbose mode by calling Make with the variable $ V=1 make ``` +Parallel execution +------------------ + +*Parallel execution is currently disabled.* + Parallel execution can be enabled through the use of the `-j` option. The following output showcases concurrent downloading of dependencies. @@ -255,15 +211,12 @@ Core package functionality The following targets are specific to packages: -`pkg-list` lists all packages in the index. +`search` lists all packages in the index. -`pkg-search q=STRING` searches the index for STRING. +`search q=STRING` searches the index for STRING. Packages are downloaded into `DEPS_DIR` (`./deps/` by default). -The package index file is downloaded from `PKG_FILE_URL` -and saved in `PKG_FILE2`. - Core compiler functionality --------------------------- @@ -294,39 +247,6 @@ If `{id, "git"},` is found in your project's `.app.src`, the extended output of `git describe ...` will replace it. This can be retrieved at runtime via `application:get_key/2`. -Updating erlang.mk ------------------- - -You can update erlang.mk by running `make erlang-mk`. This automated -update will always take the latest erlang.mk version, compile it and -replace the erlang.mk of your project with the updated version. - -If your project includes a `build.config`, erlang.mk will use it -when building the updated version. - -The `ERLANG_MK_BUILD_CONFIG` variable can be used to rename the -`build.config` file. - -The `ERLANG_MK_BUILD_DIR` variable contains the path to the -temporary directory used to build the updated erlang.mk. - -Bootstrap plugin ----------------- - -This plugin is available by default. It adds the following -targets: - -`bootstrap` generates a skeleton of an OTP application. - -`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. - -`list-templates` lists the available templates. - C/C++ compiler plugin --------------------- @@ -437,7 +357,6 @@ subdirectories names in the compiled module name add `DTL_FULL_PATH=1` into your Makefile - `a/b/templatename.dtl` will be compiled into `a_b_templatename_dtl.beam`. - Escript plugin -------------- diff --git a/doc/src/guide/book.asciidoc b/doc/src/guide/book.asciidoc index 4a29e83..9e23082 100644 --- a/doc/src/guide/book.asciidoc +++ b/doc/src/guide/book.asciidoc @@ -10,6 +10,8 @@ include::overview.asciidoc[Overview] include::updating.asciidoc[Updating Erlang.mk] +include::limitations.asciidoc[Limitations] + = Code include::app.asciidoc[Building] @@ -17,3 +19,7 @@ include::app.asciidoc[Building] = Advanced include::external_plugins.asciidoc[External plugins] + += About Erlang.mk + +include::why.asciidoc[Why erlang.mk?] diff --git a/doc/src/guide/limitations.asciidoc b/doc/src/guide/limitations.asciidoc new file mode 100644 index 0000000..86ca918 --- /dev/null +++ b/doc/src/guide/limitations.asciidoc @@ -0,0 +1,45 @@ +== Limitations + +No software is perfect. + +It's very important, when evaluating and when using a tool, +to understand its limitations, so as to avoid making mistakes +and wasting valuable time. + +This chapter lists all known limitations of Erlang.mk. + +=== Erlang must be available + +Currently Erlang.mk requires you to install Erlang beforehand. +Installing Erlang is not always easy, particularly if you need +a specific version of Erlang for a specific project. + +In addition, the Erlang being used must be in your `$PATH` +before you use Erlang.mk. + +In the future we envision, Erlang.mk could manage the Erlang +version you need to use a project. Erlang.mk already does this +for running tests when using `make ci`, so doing this during +development is just a step away. + +=== Spaces in path + +Erlang.mk will currently not work properly if the path to the +project contains spaces. To check if that is the case, use the +command `pwd`. + +This issue is due to how Makefiles work. There might be ways +to solve it, we have not given up on it, but it's very low +priority considering how simple the workaround is. + +=== Dependency tracking and modification times + +Erlang source files that depend on other files will have their +modification time updated when they need to be recompiled due +to a dependency having changed. This could cause some editors to +think the file changed when it didn't. + +Erlang.mk must use this method in order to be able to compile +files in one `erlc` invocation. The benefits greatly outweigh +the issue in this case and so there are currently no plans to +fix this behavior. diff --git a/doc/src/guide/why.asciidoc b/doc/src/guide/why.asciidoc new file mode 100644 index 0000000..37aa676 --- /dev/null +++ b/doc/src/guide/why.asciidoc @@ -0,0 +1,80 @@ +== Why Erlang.mk + +Why would you choose Erlang.mk, if not for its +link:overview.asciidoc[many features]? This chapter will +attempt to answer that. + +=== 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. + +=== 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... + +=== 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. + +=== 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 about 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`. + +=== 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. + +=== 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. |