Nine Nines: Getting started

+

Creating a folder for your project

+

The first step is always to create a new folder that will +contain your project.

+

$ 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:

+

$ wget https://raw.githubusercontent.com/ninenines/erlang.mk/master/erlang.mk

+

Or:

+

$ curl https://raw.githubusercontent.com/ninenines/erlang.mk/master/erlang.mk

+

Alternatively, just 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:

+

$ make -f erlang.mk bootstrap

+

Something similar to the following snippet will then appear +on your screen:

+

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 +Updating Erlang.mk chapter for more +information.

+

Of course, the generated project can now be compiled:

+

$ 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:

+

$ 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:

+

$ 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:

+

$ make bootstrap-rel

+

This target can be combined with bootstrap or bootstrap-lib to +create a project that will build a release:

+

$ 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 Packages and dependencies +chapter for more information.

+

When you run make from now on, Erlang.mk will compile your +project and build the release:

+

$ 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 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:

+

$ 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)
+(hello_joe@127.0.0.1)1>

+

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:

+

$ 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 +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:

+

$ 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:

+

$ 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:

+

$ 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!

+

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, +you can always run make help:

+

$ 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 <essen@ninenines.eu>
+
+Usage: [V=1] make [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 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 contact@ninenines.eu.

+

99s

Getting started