From 92b54aacc0de5446dd5497c39897b0bbff72e626 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Wed, 13 Jun 2018 09:54:12 +0200 Subject: Rebuild using Asciideck --- .../erlang.mk/1/guide/getting_started/index.html | 422 ++++++++------------- 1 file changed, 159 insertions(+), 263 deletions(-) (limited to 'docs/en/erlang.mk/1/guide/getting_started/index.html') diff --git a/docs/en/erlang.mk/1/guide/getting_started/index.html b/docs/en/erlang.mk/1/guide/getting_started/index.html index 70ea7527..e6f3b05f 100644 --- a/docs/en/erlang.mk/1/guide/getting_started/index.html +++ b/docs/en/erlang.mk/1/guide/getting_started/index.html @@ -62,362 +62,258 @@

Getting started

-

This chapter explains how to get started using Erlang.mk.

-
+

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.

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

-
-
-
+$ 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://erlang.mk/erlang.mk
-

Or:

-
-
-
$ curl -O https://erlang.mk/erlang.mk
-

Alternatively, just click on this link.

-

Make sure you put the file inside the folder we created previously.

-
- -
+
$ curl -O https://erlang.mk/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!

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

-
- -
+
$ 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
+ 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:
+===> 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
+ APP    hello_joe.app.src
  GEN    distclean-relx-rel
-===> Starting relx build process ...
-===> Resolving OTP Applications from directories:
+===> 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!

-
- -
+===> 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!

Getting started from scratch

-
-

If you already have an application, or you want to have full -control over what files will be created, you can setup Erlang.mk -manually.

-

Erlang.mk is very easy to setup: all that you need to do is to -create a folder, put Erlang.mk in it, and write a one line -Makefile containing:

-
-
-
include erlang.mk
-

For a step by step:

-
-
$ mkdir hello_joe
 $ cd hello_joe
-$ curl https://erlang.mk/erlang.mk -o erlang.mk
-$ echo "include erlang.mk" > Makefile
-$ make
-

From that point onward you can create an src/ folder or start -using templates.

-
- -
+$ curl https://erlang.mk/erlang.mk -o erlang.mk +$ echo "include erlang.mk" > Makefile +$ make +
+

From that point onward you can create an src/ folder or start using templates.

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.

-
- -
+
$ 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 gen_statem 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
+ ERLC my_server.erl + APP hello_joe.app.src
-

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.

-
-
-
+

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-2016 Loïc Hoguin <essen@ninenines.eu>
+
$ make help
+erlang.mk (version 1.2.0-642-gccd2b9f) is distributed under the terms of the ISC License.
+Copyright (c) 2013-2016 Loïc Hoguin <essen@ninenines.eu>
 
-Usage: [V=1] make [target]...
+Usage: [V=1] make [target]...
 
-Core targets:
-  all           Run deps, app and rel targets in that order
+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
+  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
+  help          Display this help and exit
+  erlang-mk     Update erlang.mk to the latest version
 
-Bootstrap targets:
+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
+  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.

-
-
+... + +

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.

+ -- cgit v1.2.3