Why

Rebar is a relatively new set of Erlang/OTP development tools. Rebar makes it easier to develop and maintain Erlang/OTP applications and releases.

Zotonic is built on Erlang/OTP. An understanding of Erlang/OTP conventions is essential if you wish to read Zotonic source code, develop Zotonic modules, or contribute code or patches to Zotonic.

As yet, Zotonic is not maintained under Rebar. But developing a skeletal Erlang/OTP application under Rebar is a great way to dip your feet into Erlang/OTP development.

By following each step in this tutorial carefully, and referring back to the many excellent on-line Erlang documentation resources, you will accelerate your progress up the daunting Erlang/OTP learning curve. And more, you'll learn how to read and understand Zotonic source code while you're at it.

In this tutorial we'll use rebar to create, compile, and test two Erlang applications. One will include a simple gen_server.

In Part II, we'll generate documentation, run eunit tests, and create a release that can be copied and run on a suitable host system.

Assumptions

You have Erlang R14B or later installed on your system. You have Internet access and basic Bash command line skills. File editing tasks refer to vim. But you can use your code editor of choice.

This tutorial was tested on Ubuntu 11.04.

How

How can I install and learn Rebar? ................................. Create a root directory for experimentation. Let's call it "learn.":

$ mkdir learn 
$ cd learn

Download the rebar binary

In the shell:

learn$ wget https://github.com/downloads/basho/rebar/rebar
chmod u+x rebar

How can I create an application

In the shell:

learn$ ./rebar create-app appid=zzz 
learn$ ls rebar src

Note that Rebar has created a directory named `src`:

learn $ ls src 
zzz_app.erl zzz.app.src zzz_sup.erl

Note that Rebar has created three Erlang modules. Open them up and take a look in your favorite code editor:

Learn more about Erlang applications: http://www.erlang.org/doc/design_principles/applications.html http://www.erlang.org/doc/man/application.html

How can I add a gen_server template to my new application?

In the shell:

learn$ ./rebar create template=simplesrv srvid=zzz_srv 
learn$ ls src 
zzz_app.erl zzz.app.src zzz_srv.erl zzz_sup.erl

Open up zzz_svr.erl and look it over. For more info, study these gen_gerver` resources: http://www.erlang.org/doc/design_principles/gen_server_concepts.html http://www.erlang.org/doc/man/gen_server.html .. highlight: erlang How can I make my new gen_server do something? .............................................. Add two functions to the API-exportdirective as follows:: -export([start_link/0, say_/0, stop/0]). Add the say_hello/0 function as follows:: say_hello() -> gen_server:call(?MODULE, hello). %% callbacks handle_call(hello, _From, State) -> io:format("Hello from zzz_srv!~n", []), {reply, ok, State}; handle_call(_Request, _From, State) -> Reply = ok, {reply, Reply, State}. Add the stop/0 function:: stop() -> gen_server:cast(?MODULE, stop). handle_cast(stop, State) -> {stop, normal, State}; NOTE: If your gen_server is under supervision, there's a better way to stop your server. See: Section 2.6 of gen_server Concepts - Stopping: http://www.erlang.org/doc/design_principles/gen_server_concepts.html You could compile this code with Rebar now, but let's defer. To really get the hang, let's create TWO applications. We'll put them under a new directory, `apps/`:: learn$ mkdir apps learn$ mkdir apps/zzz learn$ mkdir apps/zzz_lib learn$ ls apps zzz zzz_lib learn$ mv src apps/zzz learn$ ls apps/zzz src Now we'll create the zzz_lib application:: learn$ ./rebar create-app appid=zzz_lib learn$ ls apps rebar src And let's make it do something: learn$ cd src Create and save a module called hello.erl that does something:: -module(hello). -export([hello/0]). hello() -> io:format("Hello for zzz_lib!", []). Back in the shell:: learn$ cd .. learn$ ls apps rebar src And, finally, move thesrcdirectory toapps/zzz_lib:: learn$ mv src apps/zzz_lib How can I compile these two applications? ......................................... First, we need to create arebar.configfile in our project home directory. Open the file rebar.config, add the following directive, and save:: {sub_dirs, ["apps/zzz", "apps/zzz/src", "apps/zzz_lib", "apps/zzz_lib/src" ] }. Back in the shell:: learn$ ls apps rebar rebar.config src Now compile:: learn$ ./rebar compile If you see the following, pat yourself on the back:: ==> zzz (compile) Compiled src/zzz_sup.erl Compiled src/zzz_app.erl Compiled src/zzz_srv.erl ==> zzz_lib (compile) ==> learn1 (compile) Compiled src/zzz_lib_app.erl Compiled src/hello.erl Compiled src/zzz_lib_sup.erl Check out the ebin directories learn$ ls apps/zzz/ebin zzz.app zzz_app.beam zzz_srv.beam zzz_sup.beam learn$ ls apps/zzz_lib/ebin hello.beam zzz_lib.app zzz_lib_app.beam zzz_lib_sup.beam You're now ready to rock and roll!! How can I test? ............... learn$ erl -pa apps/*/ebin 1> zzz_srv:start_link(). {ok,<0.34.0>} 2> zzz_srv:say_hello(). Hello from server! 3> zzz_srv:stop(). ok 4> hello:hello(). Hello from zzz_lib! ok Troubleshooting --------------- I got an error when I compiled. What now? make sure yourrebar.config`` directive, as shown above, is correct.

Make sure you have this directory structure:

learn$ tree
.
apps
│   ├── zzz
│   │   ├── ebin
│   │   └── src
│   │       ├── zzz_app.erl
│   │       ├── zzz.app.src
│   │       ├── zzz_srv.erl
│   │       └── zzz_sup.erl
│   └── zzz_lib
│       └── src
│           ├── hello.erl
│           ├── zzz_lib_app.erl
│           ├── zzz_lib.app.src
│           └── zzz_lib_sup.erl
├── rebar
└── rebar.config

Fix any source code errors, and recompile:

learn$ ./rebar compile

What you've learned

You've now had a good soak in basic Erlang/OTP conventions and Erlang. You can install Rebar, create an Erlang/OTP applications, and compile them. You've also created a simple gen_server.

Where to go from here

Study the on-line and printed Erlang documentation upside and sideways. Skim to see what's there, then reread everytime you have a problem. You'll be an Erlang/OTP wizard before you know it.