Erlang App. Management with Rebar

转自：http://alancastro.org/2010/05/01/erlang-application-management-with-rebar.htmlIntroduction

Rebar is a build and packaging tool for Erlang applications. It is implemented in Erlang and the only dependency is the Erlang Virtual Machine, so it can work as a stand-alone escript in your project. Rebar was created by Dave Smith from Basho, creators of Riak. In this tutorial I’ll be creating a sample application, building it and generating a release for it, all of this with Rebar.

Application Requirements

Rebar expects that your applications follows the OTP Design Principles. The application directory must have the following sub-directories:

• src – Contains the Erlang source code.
• ebin – Contains the Erlang object code, the beam files. The .app file is also placed here.
• priv – Used for application specific files. For example, C executables are placed here. The function code:priv_dir/1 should be used to access this directory.
• include – Used for include files.

Don’t worry about this, Rebar can create applications with this kind of directory structure automatically.

Installation

To install Rebar is very easy, just download it at: http://hg.basho.com/rebar/downloads/rebar. After getting it just run a chmod u+x rebar. Rebar depends on Erlang R13B03 (or later), so I advise you to get Erlang OTP source code em build it. There is a tutorial here: http://wiki.github.com/erlang/otp/installation.

Rebar’s Features

To see what Rebar offers just execute ./rebar -c and you’ll be able to see all of Rebar’s commands.

$ ./rebar -canalyze Analyze with Dialyzerbuild_plt Build Dialyzer PLTcheck_plt Check Dialyzer PLTclean Cleancompile Compile sourcescreate template= [var=foo,...] Create skel based on template and varscreate-app Create simple app skelcreate-node Create simple node skelcheck-deps Display to be fetched dependenciesget-deps Fetch dependenciesdelete-deps Delete fetched dependenciesgenerate [dump_spec=0/1] Build release with reltoolinstall [target=] Install build into targeteunit [suite=foo] Run eunit [test/foo_tests.erl] testsint_test [suite=] [case=] Run ct suites in ./int_testperf_test [suite=] [case=] Run ct suites in ./perf_testtest [suite=] [case=] Run ct suites in ./test

I won’t be using all of the commands listed above for the sample application, so if you get more interested in it take a look at the source code.

Getting Started

To get started off I’ll go step by step on creating a new project with rebar.

$ mkdir mysample$ cd mysample$ wget http://hg.basho.com/rebar/downloads/rebar$ chmod u+x rebar$ ./rebar create-app appid=mysample==> mysample (create-app)Writing ebin/mysample.appWriting src/mysample_app.erlWriting src/mysample_sup.erl

This was pretty easy to follow. Rebar creates this directory structure based on a previous created template. If you want to add new templates or change the ones that exists take a look at Rebar’s source code: http://bitbucket.org/basho/rebar/src and navigate to priv/templates/simpleapp.template.

Well, for now we’ve had Rebar create our initial application directories and files. Let’s take a look at the source code we’ve got so far:

ebin/mysample.app – Application descriptor

{application, mysample, [ {description, ""}, {vsn, "1"}, {modules, [ mysample_app, mysample_sup ]}, {registered, []}, {applications, [ kernel, stdlib ]}, {mod, { mysample_app, []}}, {env, []} ]}.

src/mysample_app.erl – Application callback module

-module(mysample_app).-behaviour(application).-export([start/2, stop/1]).start(_StartType, _StartArgs) -> mysample_sup:start_link().stop(_State) -> ok.

src/mysample_sup.erl – Supervisor callback module

-module(mysample_sup).-behaviour(supervisor).-export([start_link/0]).-export([init/1]).-define(CHILD(I, Type), {I, {I, start_link, []}, permanent, 5000, Type, [I]}).start_link() -> supervisor:start_link({local, ?MODULE}, ?MODULE, []).init([]) -> {ok, { {one_for_one, 5, 10}, []} }.

The generated code is almost a fully working simple application, but there is one thing missing, a Generic Server ! So the next step is to create one. I’ll create a generic server called mysample_server.erl.

Place this code in src/mysample_server.erl:

-module(mysample_server).-behaviour(gen_server).-export([start_link/0, say_hello/0]).-export([init/1, handle_call/3, handle_cast/2, handle_info/2, terminate/2, code_change/3]).start_link() -> gen_server:start_link({local, ?MODULE}, ?MODULE, [], []).init([]) -> {ok, []}.say_hello() -> gen_server:call(?MODULE, hello).%% callbackshandle_call(hello, _From, State) -> io:format("Hello from server!~n", []), {reply, ok, State};handle_call(_Request, _From, State) -> Reply = ok, {reply, Reply, State}.handle_cast(_Msg, State) -> {noreply, State}.handle_info(_Info, State) -> {noreply, State}.terminate(_Reason, _State) -> ok.code_change(_OldVsn, State, _Extra) -> {ok, State}.

The next step is make the generic server part of the application, this is done by doing the following steps:

• Add mysample_server into ebin/mysample.app under the modules tuple.
• Make mysample_server a child of mysample supervisor.

So by making this changes we have the following new codes:

ebin/mysample.app:

{application, mysample, [ {description, ""}, {vsn, "1"}, {modules, [ mysample_app, mysample_sup, mysample_server ]}, {registered, []}, {applications, [ kernel, stdlib ]}, {mod, { mysample_app, []}}, {env, []} ]}.

src/mysample_sup.erl:

-module(mysample_sup).-behaviour(supervisor).-export([start_link/0]).-export([init/1]).-define(CHILD(I, Type), {I, {I, start_link, []}, permanent, 5000, Type, [I]}).start_link() -> supervisor:start_link({local, ?MODULE}, ?MODULE, []).init([]) -> MySampleServer = ?CHILD(mysample_server, worker), {ok, { {one_for_one, 5, 10}, [MySampleServer]} }.

Now that we’ve made every change, let’s compile the project:

$ ./rebar compile==> mysample (compile)Compiled src/mysample_app.erlCompiled src/mysample_sup.erlCompiled src/mysample_server.erl

Now take a look at your ebin directory and check if each module has a beam file placed there.

What about now? We’ve got an application module, a supervisor, and a simple generic server, but what do we do with it? Well, wouldn’t be great to make your application work as a service that you can start, stop, and restart whenever you want? You can create this using some Erlang tools, but with Rebar you can do this in a very very easy way. Summarizing what I’ve just said: “Rebar can help you create an Erlang Release”.

To create a release we have to create a new directory in the root of our project called rel and create a node in it. A node is kind of a standalone Erlang VM for our application to run on.

$ mkdir rel$ cd rel$ ../rebar create-node nodeid=mysample==> rel (create-node)Writing reltool.configWriting overlay/erts-vsn/bin/erlWriting overlay/erts-vsn/bin/nodetoolWriting overlay/bin/mysampleWriting overlay/etc/app.configWriting overlay/etc/vm.args$ cd -

We’ve just created a node for our application to run on, this node is created using a template just like the one used in the application creation. You can see it at Rebar’s source code: http://bitbucket.org/basho/rebar/src/ and then head to priv/templates/simplenode.template.

Now we’re almost done. We only need to make some changes to the rel/reltool.config, file that contains the release configuration, so it can be compatible with our application’s modules.

Here is the changed version of the generated file, I will put * around the lines I changed, notice that they don’t belong to the real code.

{sys, [ *{lib_dirs, ["../../"]}*, {rel, "mysample", "1", [ kernel, stdlib, sasl, *mysample* ]}, {rel, "start_clean", "", [ kernel, stdlib ]}, {boot_rel, "mysample"}, {profile, embedded}, {excl_sys_filters, ["^bin/.*", "^erts.*/bin/(dialyzer|typer)"]}, *{app, mysample, [{incl_cond, include}]}*, {app, sasl, [{incl_cond, include}]} ]}.{rebar, [ {empty_dirs, [ "log/sasl" ]}, {overlay, "overlay"} ]}.

If you want to know the meaning of each of this tuple’s options, look at Reltool Manual.

Now lets make this directory visible for rebar, for that we create rebar.config file in the root directory of our project.

rebar.config:

{sub_dirs, ["rel"]}.

Configuration is now over! Lets generate our release:

$ ./rebar generate

This command creates a release of your application. Take a look at yours rel/mysample folder and you’ll be able to see something like this:

$ ls rel/mysamplebin erts-5.7.4 etc lib log releases

Now let’s run our release service, see the step by step below:

$ chmod u+x rel/mysample/bin/mysample$ ./rel/mysample/bin/mysampleUsage: mysample {start|stop|restart|reboot|ping|console|attach}

Seems that everything is alright. To make sure your application was packed in the release, run your service with console ./rel/mysample/bin/mysample consoleand execute application:which_applications().. Check if you got something like this:

(mysample@127.0.0.1)1> application:which_applications().[{mysample,[],"1"}, {sasl,"SASL CXC 138 11","2.1.8"}, {stdlib,"ERTS CXC 138 10","1.16.4"}, {kernel,"ERTS CXC 138 10","2.13.4"}](mysample@127.0.0.1)2> mysample_server:say_hello().Hello from server!

If yes, you’ve done it! If not, make sure you’ve followed everything correctly.

Conclusions

The purpose of this tutorial was to give an introduction to a tool that helps we manage our Erlang applications. I think Rebar has a long way to go from here, but it is on the right track. It’s a great tool and if there were more documentation available there would have more people using it. I’ve talked about some of it’s most important features here, but in the beggining I showed that there is a lot more to it than just than compile and generate functions. So get Rebar and start using it on your next project.

Feel free to put your comments below and thank you for reading this post.