Erlang App. Management with Rebar
Introduction
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 -c
analyze Analyze with Dialyzer
build_plt Build Dialyzer PLT
check_plt Check Dialyzer PLT
clean Clean
compile Compile sources
create template= [var=foo,...] Create skel based on template
and vars
create-app Create simple app skel
create-node Create simple node skel
check-deps Display to be fetched dependencies
get-deps Fetch dependencies
delete-deps Delete fetched dependencies
generate [dump_spec=0/1] Build release with reltool
install [target=] Install build into target
eunit [suite=foo] Run eunit [test/foo_tests.erl]
tests
int_test [suite=] [case=] Run ct suites in ./int_test
perf_test [suite=] [case=] Run ct suites in ./perf_test
test [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.app
Writing src/mysample_app.erl
Writing 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).
%% callbacks
handle_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.erl
Compiled src/mysample_sup.erl
Compiled 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 reland 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.config
Writing overlay/erts-vsn/bin/erl
Writing overlay/erts-vsn/bin/nodetool
Writing overlay/bin/mysample
Writing overlay/etc/app.config
Writing 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/mysamplefolder and you’ll be able to see something like this:
$ ls rel/mysample
bin 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/mysample
Usage: 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 console and executeapplication: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 generatefunctions. So get Rebar and start using it on your next project.
Комментариев нет:
Отправить комментарий