From 136d443b5c38bee96f5d995dfea3629ef07564c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Thu, 18 Jul 2019 09:59:28 +0200 Subject: Announce Ranch 2.0.0-rc.1 Adds Ranch 2.0 documentation and removes documentation for very old Cowboy and Ranch, along with Erlang.mk documentation which is available on its own website. --- .../erlang.mk/1/guide/getting_started/index.html | 418 --------------------- 1 file changed, 418 deletions(-) delete mode 100644 docs/en/erlang.mk/1/guide/getting_started/index.html (limited to 'docs/en/erlang.mk/1/guide/getting_started') diff --git a/docs/en/erlang.mk/1/guide/getting_started/index.html b/docs/en/erlang.mk/1/guide/getting_started/index.html deleted file mode 100644 index 4231ac41..00000000 --- a/docs/en/erlang.mk/1/guide/getting_started/index.html +++ /dev/null @@ -1,418 +0,0 @@ - - - - - - - - - - Nine Nines: Getting started - - - - - - - - - - - - - - -
-
-
-
-

99s

-
-
- -
- -
    -
  • - Github -
    • -
  • - -
    • -
-
-
-
-
- - -
- -
-
-
-
- -

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.

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

-

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!

-

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.

-

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

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

- - - - - - - - - - - - - - - - -
- -
- - -

- Erlang.mk - 1 - - User Guide -

- -
    - - - -
- -

Navigation

- -

Version select

-
    - - - -
  • 1
    • - -
- -

Like my work? Donate!

-

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

-
- - - - - - - - - -

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

- - - -
-
-
-
- - - - - - - - - -- cgit v1.2.3