第2章 入门

原文连接  https://erlang.mk/guide/getting_started.html

 

Chapter 2. Getting started

 

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

本章将介绍如何开始使用Erlang.mk

 

2.1. Creating a folder for your project

2.1. 为您的项目建立一个文件夹

 

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.

大多数人倾向于把他们的全部项目放在一个公有的文件夹中，对此，咱们建议保持一个相似于你的远程存储库的组织方式。例如，对于github用户，将你的全部项目放在一个与你用户名相同的公共文件夹中。例如，对于Cowboy项目，路径是 $HOME/ninenines/cowboy

 

2.2. Downloading Erlang.mk

2.2. 下载Erlang.mk

 

At the time of writing, Erlang.mk is unlikely to be present in your Erlang distribution, or even in your OS packages.

在写这篇文章时，Erlang.mk不太可能出如今你的Erlang分发中，甚至不在你的操做系统软件包中。

 

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.

确保你刚刚下载的文件被放在了咱们以前建立的工程文件夹中。

 

2.3. Getting started with OTP applications

2.3. 开始使用OTP应用程序

 

An OTP application is an Erlang application that has a supervision tree. In other words, it will always have processes running.

一个OTP应用程序就是一个具备监督树的Erlang应用程序。换句话说，它始终有进程运行

 

This kind of project can be automatically generated by Erlang.mk. All you need to do is use the bootstrap target:

这种项目能够经过Erlang.mk自动生成。你只须要使用‘bootstrap’做为编译目标： 

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

这是Erlang.mk的自我引导。事实上，你最初下载的文件只包含引导所需的代码。这个操做只作一次。更多信息，请参考 Updating Erlang.mk章节。

 

Of course, the generated project can now be compiled:

固然，刚刚生成的项目如今已经能够编译了：

$ make

 

Cheers!

干杯！

 

2.4. Getting started with OTP libraries

2.4. 开始使用OTP库

 

An OTP library is an Erlang application that has no supervision tree. In other words, it is nothing but modules.

一个OTP库是一个没有监督树的Erlang应用程序。换句话说，它只是个模块。

 

This kind of project can also be generated by Erlang.mk, using the bootstrap-lib target:

这种项目也能够由Erlang.mk使用 ‘bootstrap-lib’ 做为编译目标而生成： 

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

Erlang.mk将再次自我引导并为你的项目生成全部文件。你如今能够编译它：

$ make

 

Enjoy!

请享用！

 

2.5. Getting started with OTP releases

2.5. 开始使用OTP发行版

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.

OTP发行版由Erlang运行时系统(ERTS)以及节点运行须要的全部库和文件的组合。它彻底独立，一般能够按原样发送到你的生产环境，并没有需任何额外的设置便可运行。

 

Erlang.mk can of course bootstrap your project to generate releases. You can use the bootstrap-rel target for this purpose:

Erlang.mk固然能够引导你的项目来生成版本。你可使用 ‘bootstrap-rel’ 做为编译目标来达到这个目的:

$ make bootstrap-rel

 

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

bootstrap-rel 能够连同 bootstrap 或者 bootstrap-lib 一块儿来建立一个项目并构建出一个版本：

$ 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命令时，Erlang.mk将会编译你的项目并构建出版本：

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

第一次运行这个命令时，Erlang.mk会下载发行版本的编译工具relx。因此当你看到更多输出时，请不用担忧。

 

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_releasescript, or simply run make run. The latter will also compile your project and build the release if it wasn’t already:

你可使用 ./_rel/hello_joe_release/bin/hello_joe_releasescript 来启动发行版，或者直接运行 make run。若是项目尚未编译发布，后者将编译你的项目并创建发行版：

 

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

就是这么简单！

 

2.6. Getting started from scratch

2.6. 在已有程序中开始使用Erlang.mk

 

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.

 

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:

Erlang.mk很是容易设置：你只须要建立一个文件夹，把Erlang.mk文件放在里面，而且在Makefile写一行:

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.

如今开始，你能够建立一个src/folder或者开始使用模版。

 

2.7. Using spaces instead of tabs

2.7. 使用空格而不是tab键

 

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.

经过模版建立文件时，Erlang.mk默认使用tab。使用tab而不用空格，部分是由于我的喜爱，部分是由于相比于将空格转换为tab，将tab转换为空格会更容易。

 

Use the SP variable if you prefer spaces. Set it to the number of spaces per indentation level you want.

若是你喜欢使用空格，请使用SP变量，设置你须要的缩进空格数。

 

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.

当你开始引导项目时，这个变量将会自动添加到Makefile中，因此你只须要在开始时提供便可。

 

2.8. Using templates

2.8. 使用模版

 

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!

你们都知道Erlang OTP的特性是倾向于提供一些样板供用户使用。除非建立新的模版，通常来讲使用已有的模版极少有问题。这也是为何Erlang.mk不只带有OTP生成项目的模版，并且还有本身特有的模版！（好比下面执行make list-templates命令时显示的cowboy_http模版？！）

 

You can list all available templates with the list-templates target:

你可使用list-templates编译目标列出全部可用的模版:

 

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

假设要生成gen_server模版，你所要作的只是用适当的参数调用make new：

$ make new t=gen_server n=my_server

 

This will create a module located in src/my_server.erl using the gen_server template.

这将在src/my_server.erl中建立一个使用gen_server的模版。

 

This module is automatically compiled the next time you run make:

这个模版在下次运行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!

剩下的事就是用你喜欢的编辑器打开它，并让它作一些事！

 

2.9. Hiding Erlang.mk from git

2.9. 在git版本库中隐藏Erlang.mk

 

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.

Erlang.mk是一个很大的文本文件，因此它能够很容易的在大部分git diff和git grep命令中显示，你能够经过告诉git Erlang.mk是一个二进制文件来避免这种状况。

 

Add this to your .gitattributes file. This is a file that you can create at the root of your repository:

在.gitattributes 文件中指定Erlang.mk是二进制文件。.gitattributes是一个能够在你的存储库根目录建立的文件:

 

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.

（执行上面的命令发现），Erlang.mk文件仍然会出如今diffs和greps命令中，可是做为二进制文件，意味着它的内容将不会被默认显示。

 

2.10. Getting help

2.10. 得到帮助

 

During development, if you don’t remember the name of a target, you can always run make help:

在开发过程当中，若是你不记得某个target的名字，你始终能够经过运行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.

若是这份指南还有任何你认为没有提供的答案，请在官方存储库提交一个ticket，咱们将努力改进这份指南。

 

Commercial support is available through Nine Nines. Please contact Loïc Hoguin by sending an email to contact@ninenines.eu.

同时Nine Nines也提供商业支持，若是有须要，请发送邮件至contact@ninenines.eu.联系Loïc Hoguin。