Erlang Central

Difference between revisions of "Using Faxien and Sinan"

From ErlangCentral Wiki

Line 1: Line 1:
== Author ==
== Author ==
Michał Ptaszek
Michał Ptaszek

Revision as of 14:23, 4 July 2008



Michał Ptaszek

Using Faxien and Sinan Overview

Faxien is easy-to-use and convinient tool for managing Erlang/OTP applications and releases in our system. It supports obtaining and publishing packages from and to repositories.

Sinan is a build system for Erlang/OTP projects, which has support for dependency checking, building, creating releases, tars and running dialyzer. Both of that products were created by Erlware - an Erlang developer central.

More information about Faxien and Sinan you can find on Erlware home site

Installing Faxien and Sinan

In order to install Faxien, you should get one of the bootstrap installers (platform-indepentent python version or the one suitable for your system) from Google Code project page. Then run it typing:

python ./
sh ./faxien-launcher-*.sh [path_to_install_directory]

If you have installed Faxien as a root (in default directory, i.e. /usr/local/erlware) you have to install all applications/releases also as a root.

Now, after having Faxien installed, we want to get Sinan too:

faxien install-release sinan

Creating project with Sinan

To list all Sinan commands with short descriptions you should run:

sinan help

So, according to it, you have to run:

sinan gen

and provide Sinan all the information it needs. If you want to use any local repository for satisfying dependencies (during the development cycle we can use some applications, which are not in global one) you should add it to the list during "sinan gen" wizard - or after it by editing _build.cfg file in the main project directory.

Sinan should generate default directory tree for your project. It should looks like (running `tree` in my_project directory):

|-- _build.cfg
|-- doc
`-- lib
    `-- my_app
        |-- doc
        |   `-- overview.edoc
        |-- ebin
        |   `--
        |-- include
        `-- src
            |-- my_app_app.erl
            `-- my_app_sup.erl

Let's make a short description about generated files:

  • _build.cfg - major configuration file for Sinan. It contains information about project name, version, URI's to repositories, ignored apps and so on.
  • doc - after generating project scaffold is empty, but that's the place where you should place your documentation files
  • lib - directory where your application files will be stored. It's structure is the same as Erlang application convence. To add new application to your project you should create it's directory tree here (with proper ebin/.app file)

So - now your project is ready to be developed.

After writing some part of code you will probably want to test/compile it:

# it's the same as `sinan build`
# or for launching tests
sinan test 

Sinan will automatically deal with all the dependencies you used in your applications (try to download them from the repositories you which you have passed during the generator wizard). Unfortunately, if Sinan can't find some package which will satisfy one of the dependecy - it will crash without the information about missing package. In some cases it is possible to figure out what's wrong by checking the log: ~/.sinan/logs/kernel.log.

Built project will be placed in _build/development directory (it is default path - you can change it in your _build.cfg file).

Creating new repository

Sometimes you will have to create your own, local repository. So if you are not interested in doing that, skip to the next section.

I have decided to set up local repository using Lighttpd server with its mod_webdav. Firstly - install both (on Debian):

sudo apt-get install lighttpd lighttpd-mod-webdav

Then, create a directory for your repository (e.g. /var/www/repo) and modify /etc/lighttpd/lighttpd.conf as follows:

  • uncomment "mod_wbdav" in server.modules section
  • add this code to the end of the file:
    webdav.activate = "enable" = "disable"
    webdav.sqlite-db-name = "/var/run/lighttpd/lighttpd.webdav_lock.db"

After doing that you will be able to access your repository via or via http://your_externel_ip_address/repo.

In some cases, when Sinan's dependecy check fails you can look at your lighttpd logs (they are placed in /var/log/lighttpd/ directory): from time to time they can tell you something more about the source of the error.

Generating release and distribution tar's

After the long hours of developing your project, finally comes the time to generate your release. Sinan has got a function to do it. All you need is to run:

sinan release
# or for creating tarballs:
sinan dist

There is a relation between Sinan's commands:

check_depends -> build -> release -> dist

so you don't need to invoke `sinan release` before creating tarballs.

To provide an easy way of launching our release you have to prepare a proper start script. To do it, create cmds directory in your project main folder and write such a script inside it:


#### Fill in values for these variables ####

test -h $0 && PROG=$(readlink $0)
PREFIX=$(cd $(dirname $(dirname $PROG)); pwd)

export ROOTDIR=$PREFIX/application_packages/$ERTS_VSN
export BINDIR=$PREFIX/erts_packages/erts-$ERTS_VSN/bin
export EMU=beam
export PROGNAME=erl


$BINDIR/erlexec -config $REL_DIR/sys.config -boot $REL_DIR/$REL_NAME $INVOCATION_SUFFIX

(this script is the modified version of script published on Erlware's tutorial:

Because of that script, everyone who will install your release, will be able to run your release by typing name of that script in his shell (of course, his PATH environment must point at bin/ directory inside the root Faxien's folder).

Publishing your application/release

After some time, when you have tested your application and you are ready to share it with other people, you will probably want to publish it on some repository servers.

In order to publish your application, you will need to go your build directory (by default it is _build/development), change to apps folder and simply run:

faxien publish name_of_your_application

Faxien should publish your application on all repositories it has. To change them, take a look at:

faxien help
faxien help commands
faxien help examples

If you want to publish your release, switch to the tar directory (by default _build/development/tar) and use the same command as above:

faxien publish name_of_your_application-version.tar.gz

Installing applications/releases from Faxien's repositories

The last thing you need to know is how to get and install any package from the repository. Faxien has built in his own search engine, so when you don't exactly remember the name of the package, use it:

faxien search
# or if you want to use some help
faxien help search

Ok, let's assume you know the name of the package you want to install. To do it, run as a root (if you have installed Faxien in the default directory - or don't have write permissions to its root folder):

# for application:
faxien install-app
# for release: 
faxien install-release

The desired package will be placed in application_packages/$ERTS_VSN/ or release_packages/ directory inside the Faxien's root folder.


Well, that's everything you need to know about Sinan and Faxien. Now, you are able to

  • generate new project
  • build it
  • make release
  • publish it
  • install it

Good luck!