Add first three chapters of new documentation

1 files changed, 262 insertions, 0 deletions

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