diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/src/guide/book.asciidoc | 11 | ||||
| -rw-r--r-- | doc/src/guide/getting_started.asciidoc | 262 | ||||
| -rw-r--r-- | doc/src/guide/overview.asciidoc | 88 | ||||
| -rw-r--r-- | doc/src/guide/updating.asciidoc | 62 |
4 files changed, 423 insertions, 0 deletions
diff --git a/doc/src/guide/book.asciidoc b/doc/src/guide/book.asciidoc new file mode 100644 index 0000000..e858ae8 --- /dev/null +++ b/doc/src/guide/book.asciidoc @@ -0,0 +1,11 @@ +// a2x: --dblatex-opts "-P latex.output.revhistory=0 -P doc.publisher.show=0 -P index.numbered=0" +// a2x: -d book --attribute tabsize=4 + += Erlang.mk User Guide +Loïc Hoguin <[email protected]> + +include::getting_started.asciidoc[Getting started] + +include::overview.asciidoc[Overview] + +include::updating.asciidoc[Updating Erlang.mk] diff --git a/doc/src/guide/getting_started.asciidoc b/doc/src/guide/getting_started.asciidoc new file mode 100644 index 0000000..3fd9ebd --- /dev/null +++ b/doc/src/guide/getting_started.asciidoc @@ -0,0 +1,262 @@ +== Getting started + +This chapter explains how to get started using Erlang.mk. + +=== Creating a folder for your project + +The first step is always to create a new folder that will +contain your project. + +[source,bash] +$ mkdir hello_joe +$ cd hello_joe + +Most people tend to put all their projects side by side in +a common folder. We recommend keeping an organization similar +to your remote repositories. For example, for GitHub users, +put all your projects in a common folder with the same name +as your username. For example '$HOME/ninenines/cowboy' for +the Cowboy project. + +=== Downloading Erlang.mk + +At the time of writing, Erlang.mk is unlikely to be present +in your Erlang distribution, or even in your OS packages. + +The next step is therefore to download it: + +[source,bash] +$ wget https://raw.githubusercontent.com/ninenines/erlang.mk/master/erlang.mk + +Or: + +[source,bash] +$ curl https://raw.githubusercontent.com/ninenines/erlang.mk/master/erlang.mk + +Alternatively, just https://raw.githubusercontent.com/ninenines/erlang.mk/master/erlang.mk[click on this link]. + +Make sure you put the file inside the folder we created previously. + +=== Getting started with OTP applications + +An OTP application is an Erlang application that has a supervision +tree. In other words, it will always have processes running. + +This kind of project can be automatically generated by Erlang.mk. +All you need to do is use the `bootstrap` target: + +[source,bash] +$ make -f erlang.mk bootstrap + +Something similar to the following snippet will then appear +on your screen: + +[source,bash] +---- +git clone https://github.com/ninenines/erlang.mk .erlang.mk.build +Cloning into '.erlang.mk.build'... +remote: Counting objects: 4035, done. +remote: Compressing objects: 100% (12/12), done. +remote: Total 4035 (delta 8), reused 4 (delta 4), pack-reused 4019 +Receiving objects: 100% (4035/4035), 1.10 MiB | 784.00 KiB/s, done. +Resolving deltas: 100% (2442/2442), done. +Checking connectivity... done. +if [ -f build.config ]; then cp build.config .erlang.mk.build; fi +cd .erlang.mk.build && make +make[1]: Entering directory '/home/essen/tmp/hello_joe/.erlang.mk.build' +awk 'FNR==1 && NR!=1{print ""}1' core/core.mk index/*.mk core/index.mk core/deps.mk plugins/protobuffs.mk core/erlc.mk core/docs.mk core/test.mk plugins/asciidoc.mk plugins/bootstrap.mk plugins/c_src.mk plugins/ci.mk plugins/ct.mk plugins/dialyzer.mk plugins/edoc.mk plugins/elvis.mk plugins/erlydtl.mk plugins/escript.mk plugins/eunit.mk plugins/relx.mk plugins/shell.mk plugins/triq.mk plugins/xref.mk plugins/cover.mk \ + | sed 's/^ERLANG_MK_VERSION = .*/ERLANG_MK_VERSION = 1.2.0-642-gccd2b9f/' > erlang.mk +make[1]: Leaving directory '/home/essen/tmp/hello_joe/.erlang.mk.build' +cp .erlang.mk.build/erlang.mk ./erlang.mk +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 +information. + +Of course, the generated project can now be compiled: + +[source,bash] +$ make + +Cheers! + +=== Getting started with OTP libraries + +An OTP library is an Erlang application that has no supervision +tree. In other words, it is nothing but modules. + +This kind of project can also be generated by Erlang.mk, using +the `bootstrap-lib` target: + +[source,bash] +$ make -f erlang.mk bootstrap-lib + +Erlang.mk will once again bootstrap itself and generate all +the files for your project. You can now compile it: + +[source,bash] +$ make + +Enjoy! + +=== Getting started with OTP releases + +An OTP release is the combination of the Erlang RunTime System (ERTS) +along with all the libraries and files that your node will need +to run. It is entirely self contained, and can often be sent as-is +to your production system and run without any extra setup. + +Erlang.mk can of course bootstrap your project to generate releases. +You can use the `bootstrap-rel` target for this purpose: + +[source,bash] +$ make bootstrap-rel + +This target can be combined with `bootstrap` or `bootstrap-lib` to +create a project that will build a release: + +[source,bash] +$ 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] +chapter for more information. + +When you run `make` from now on, Erlang.mk will compile your +project and build the release: + +[source,bash] +$ make + APP hello_joe.app.src + GEN distclean-relx-rel + GEN /home/essen/tmp/hello_joe/relx +===> Starting relx build process ... +===> Resolving OTP Applications from directories: + /home/essen/tmp/hello_joe/ebin + /usr/lib/erlang/lib + /home/essen/tmp/hello_joe/deps +===> Resolved hello_joe_release-1 +===> Including Erts from /usr/lib/erlang +===> release successfully created! + +The first time you run this command, Erlang.mk will download +_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] +chapter for various tips to speed up build time during +development. + +You can start the release using the './_rel/hello_joe_release/bin/hello_joe_release' +script, or simply run `make run`. The latter will also compile +your project and build the release if it wasn't already: + +[source,bash] +---- +$ make run + APP hello_joe.app.src + GEN distclean-relx-rel +===> Starting relx build process ... +===> Resolving OTP Applications from directories: + /home/essen/tmp/hello_joe/ebin + /usr/lib/erlang/lib + /home/essen/tmp/hello_joe/deps +===> Resolved hello_joe_release-1 +===> Including Erts from /usr/lib/erlang +===> release successfully created! +Exec: /home/essen/tmp/hello_joe/_rel/hello_joe_release/erts-7.0/bin/erlexec -boot /home/essen/tmp/hello_joe/_rel/hello_joe_release/releases/1/hello_joe_release -boot_var ERTS_LIB_DIR /home/essen/tmp/hello_joe/_rel/hello_joe_release/erts-7.0/../lib -env ERL_LIBS /home/essen/tmp/hello_joe/_rel/hello_joe_release/releases/1/lib -config /home/essen/tmp/hello_joe/_rel/hello_joe_release/releases/1/sys.config -args_file /home/essen/tmp/hello_joe/_rel/hello_joe_release/releases/1/vm.args -- console +Root: /home/essen/tmp/hello_joe/_rel/hello_joe_release +/home/essen/tmp/hello_joe/_rel/hello_joe_release +heart_beat_kill_pid = 16389 +Erlang/OTP 18 [erts-7.0] [source] [64-bit] [smp:4:4] [async-threads:10] [hipe] [kernel-poll:false] + +Eshell V7.0 (abort with ^G) +([email protected])1> +---- + +Simple as that! + +=== Using templates + +It is no secret that Erlang's OTP behaviors tend to have some +boilerplate. It is rarely an issue of course, except when +creating new modules. That's why Erlang.mk not only comes with +templates for generating projects, but also individual modules! + +You can list all available templates with the `list-templates` +target: + +[source,bash] +$ make list-templates +Available templates: cowboy_http cowboy_loop cowboy_rest cowboy_ws gen_fsm gen_server ranch_protocol supervisor + +To generate a module, let's say a `gen_server`, all you need to +do is to call `make new` with the appropriate arguments: + +[source,bash] +$ make new t=gen_server n=my_server + +This will create a module located in 'src/my_server.erl' +using the `gen_server` template. + +This module is automatically compiled the next time you run +`make`: + +[source,bash] +$ make + ERLC my_server.erl + APP hello_joe.app.src + +All that's left to do is to open it in your favorite editor +and make it do something! + +=== Getting help + +During development, if you don't remember the name of a target, +you can always run `make help`: + +[source,bash] +---- +$ make help +erlang.mk (version 1.2.0-642-gccd2b9f) is distributed under the terms of the ISC License. +Copyright (c) 2013-2015 Loïc Hoguin <[email protected]> + +Usage: [V=1] make [-jNUM] [target]... + +Core targets: + all Run deps, app and rel targets in that order + app Compile the project + deps Fetch dependencies (if needed) and compile them + search q=... Search for a package in the built-in index + rel Build a release for this project, if applicable + docs Build the documentation for this project + install-docs Install the man pages for this project + check Compile and run all tests and analysis for this project + tests Run the tests for this project + clean Delete temporary and output files from most targets + distclean Delete all temporary and output files + help Display this help and exit + erlang-mk Update erlang.mk to the latest version + +Bootstrap targets: + bootstrap Generate a skeleton of an OTP application + bootstrap-lib Generate a skeleton of an OTP library + bootstrap-rel Generate the files needed to build a release + new t=TPL n=NAME Generate a module NAME based on the template TPL + list-templates List available templates +... +---- + +This guide should provide any other answer. If not, please +open a ticket on https://github.com/ninenines/erlang.mk/issues[the official repository] +and we will work on improving the guide. + +Commercial support is available through Nine Nines. Please contact +Loïc Hoguin by sending an email to mailto:[email protected][]. diff --git a/doc/src/guide/overview.asciidoc b/doc/src/guide/overview.asciidoc new file mode 100644 index 0000000..a81dd7a --- /dev/null +++ b/doc/src/guide/overview.asciidoc @@ -0,0 +1,88 @@ +== Overview + +Now that you know how to get started, let's take a look at +what Erlang.mk can do for you. + +=== Building your project + +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] +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]. + +Erlang.mk embraces the concept of link:deps.asciidoc[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]. + +=== Exploring the package index + +Erlang.mk comes with a link:deps.asciidoc[built-in package index]. +It is built as an extension of the dependency system and is +meant to be used for discovery purposes. + +No package is ever installed, they are only used as dependencies +and are always project-specific. They can be thought of as a +shortcut over plain dependencies. + +You can get a list of all packages known to Erlang.mk by using +the `search` target: + +[source,bash] +$ make search + +You can also use this target to search across all packages, for +example to find all packages related to Cowboy: + +[source,bash] +$ make search q=cowboy + +=== Generating documentation + +Erlang.mk supports _EDoc_ and _Asciidoc_. + +link:edoc.asciidoc[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 +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. + +=== Running tests + +Erlang.mk supports a lot of different testing and static +analysis tools. + +The link:shell.asciidoc[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 +be enabled during tests. + +Erlang.mk comes with features to make your life easier when +setting up and using link:ci.asciidoc[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. + +=== 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 +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/updating.asciidoc b/doc/src/guide/updating.asciidoc new file mode 100644 index 0000000..ecd4a70 --- /dev/null +++ b/doc/src/guide/updating.asciidoc @@ -0,0 +1,62 @@ +== Updating Erlang.mk + +This chapter describes how to update the 'erlang.mk' file +in your repository. + +=== Initial bootstrap + +The first time you use Erlang.mk, it will bootstrap itself. +It always uses the most recent version for this, so you don't +have to update after creating your project. + +=== Updating + +Later on though, updating becomes a necessity. Erlang.mk +developers and contributors relentlessly improve the project +and add new features; it would be a waste not to benefit +from this. + +That's why updating Erlang.mk is so simple. All you need +to do is to call `make erlang-mk`: + +[source,bash] +---- +$ make erlang-mk +git clone https://github.com/ninenines/erlang.mk .erlang.mk.build +Cloning into '.erlang.mk.build'... +remote: Counting objects: 4035, done. +remote: Compressing objects: 100% (12/12), done. +remote: Total 4035 (delta 8), reused 4 (delta 4), pack-reused 4019 +Receiving objects: 100% (4035/4035), 1.10 MiB | 1000.00 KiB/s, done. +Resolving deltas: 100% (2442/2442), done. +Checking connectivity... done. +if [ -f build.config ]; then cp build.config .erlang.mk.build; fi +cd .erlang.mk.build && make +make[1]: Entering directory '/home/essen/tmp/emkg/hello_joe/.erlang.mk.build' +awk 'FNR==1 && NR!=1{print ""}1' core/core.mk index/*.mk core/index.mk core/deps.mk plugins/protobuffs.mk core/erlc.mk core/docs.mk core/test.mk plugins/asciidoc.mk plugins/bootstrap.mk plugins/c_src.mk plugins/ci.mk plugins/ct.mk plugins/dialyzer.mk plugins/edoc.mk plugins/elvis.mk plugins/erlydtl.mk plugins/escript.mk plugins/eunit.mk plugins/relx.mk plugins/shell.mk plugins/triq.mk plugins/xref.mk plugins/cover.mk \ + | sed 's/^ERLANG_MK_VERSION = .*/ERLANG_MK_VERSION = 1.2.0-642-gccd2b9f/' > erlang.mk +make[1]: Leaving directory '/home/essen/tmp/emkg/hello_joe/.erlang.mk.build' +cp .erlang.mk.build/erlang.mk ./erlang.mk +rm -rf .erlang.mk.build +---- + +All that's left to do is to commit the file! + +Yep, it's that easy. + +=== Customizing the build + +Erlang.mk allows you to customize which plugins are to be included +in the 'erlang.mk' file. You can do so by maintaining your own +'build.config' file in your repository. Erlang.mk will automatically +use it the next time you run `make erlang-mk`. + +The 'build.config' file contains the list of all files that will +be built into the resulting 'erlang.mk' file. You can start from +the https://github.com/ninenines/erlang.mk/blob/master/build.config[most recent version] +and customize to your needs. + +You can also name the file differently or put it in a separate folder +by modifying the value for `ERLANG_MK_BUILD_CONFIG`. You can also +tell Erlang.mk to use a different temporary directory by changing +the `ERLANG_MK_BUILD_DIR` variable. |