diff options
Diffstat (limited to 'docs/en/erlang.mk/1/guide/getting_started.asciidoc')
| -rw-r--r-- | docs/en/erlang.mk/1/guide/getting_started.asciidoc | 326 |
1 files changed, 0 insertions, 326 deletions
diff --git a/docs/en/erlang.mk/1/guide/getting_started.asciidoc b/docs/en/erlang.mk/1/guide/getting_started.asciidoc deleted file mode 100644 index de40f364..00000000 --- a/docs/en/erlang.mk/1/guide/getting_started.asciidoc +++ /dev/null @@ -1,326 +0,0 @@ -[[getting_started]] -== 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://erlang.mk/erlang.mk - -Or: - -[source,bash] -$ curl -O https://erlang.mk/erlang.mk - -Alternatively, just https://erlang.mk/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 -xref:updating[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 xref:deps[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 xref:relx[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! - -=== 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: - -[source,make] -include erlang.mk - -For a step by step: - -[source,bash] ----- -$ 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. - -=== 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 -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 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: - -[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! - -=== 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`: - -[source,bash] ----- -$ 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 <[email protected]> - -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 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][]. |