Erlang Central

Difference between revisions of "Using Faxien and Sinan"

From ErlangCentral Wiki

Line 12: Line 12:
  
 
== Installing Faxien and Sinan ==
 
== 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 [http://code.google.com/p/faxien/downloads/list Google Code project page].
+
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 [http://code.google.com/p/faxien/downloads/list Google Code project page]. Then run it typing:
 +
<code caption="Code listing 1.0">
 +
python ./faxien-launcher-universal.py
 +
or
 +
sh ./faxien-launcher-*.sh [path_to_install_directory]
 +
</code>
 +
 
 +
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:
 +
<code caption="Code listing 1.1">
 +
faxien install-release sinan
 +
</code>
 +
 
 +
 
 +
== Creating project with Sinan ==
 +
To list all Sinan commands with short descriptions you should run:
 +
<code caption="Code listing 2.0">
 +
sinan help
 +
</code>
 +
 
 +
So, according to it, you have to run:
 +
<code caption="Code listing 2.1">
 +
sinan gen
 +
</code>
 +
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):
 +
<code caption="Code listing 2.2">
 +
.
 +
|-- _build.cfg
 +
|-- doc
 +
`-- lib
 +
    `-- my_app
 +
        |-- doc
 +
        |  `-- overview.edoc
 +
        |-- ebin
 +
        |  `-- my_app.app
 +
        |-- include
 +
        `-- src
 +
            |-- my_app_app.erl
 +
            `-- my_app_sup.erl
 +
</code>
 +
 
 +
Let's make a short description about generated files:
 +
<ul>
 +
<li><b>_build.cfg</b> - major configuration file for Sinan. It contains information about project name, version, URI's to repositories, ignored apps and so on.</li>
 +
<li><b>doc</b> - after generating project scaffold is empty, but that's the place where you should place your documentation files</li>
 +
<li><b>lib</b> - 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)</li>
 +
</ul>
 +
 
 +
So - now your project is ready to be developed.
 +
 
 +
After writing some part of code you will probably want to test/compile it:
 +
<code caption="Code listing 2.3">
 +
# it's the same as `sinan build`
 +
sinan
 +
# or for launching tests
 +
sinan test
 +
</code>
 +
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):
 +
<code caption="Code listing 3.0">
 +
sudo apt-get install lighttpd lighttpd-mod-webdav
 +
</code>
 +
Then, create a directory for your repository (e.g. /var/www/repo) and modify /etc/lighttpd/lighttpd.conf as follows:
 +
<ul>
 +
<li>uncomment "mod_wbdav" in server.modules section</li>
 +
<li>add this code to the end of the file:
 +
 
 +
<code caption="Code listing 3.1">
 +
webdav.activate = "enable"
 +
webdav.is-readonly = "disable"
 +
webdav.sqlite-db-name = "/var/run/lighttpd/lighttpd.webdav_lock.db"
 +
</code>
 +
</ul>
 +
 
 +
After doing that you will be able to access your repository via http://127.0.0.1/repo 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:
 +
<code caption="Code listing 4.0">
 +
sinan release
 +
# or for creating tarballs:
 +
sinan dist
 +
</code>
 +
 
 +
There is a relation between Sinan's commands:
 +
<code caption="Code listing 4.1">
 +
check_depends -> build -> release -> dist
 +
</code>
 +
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:
 +
<code caption="Code listing 4.2">
 +
#!/bin/sh
 +
 
 +
#### Fill in values for these variables ####
 +
REL_NAME=your_application_name
 +
REL_VSN=your_release_version
 +
ERTS_VSN=your_erts_version
 +
INVOCATION_SUFFIX="additional_information_for_erlexec_,_leave_blank_if_you_don't_want_to_pass_anything"
 +
###########################################
 +
 
 +
PROG=$0
 +
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
 +
export LD_LIBRARY_PATH=$PREFIX/erts/$ERTS_VSN/lib
 +
 
 +
REL_DIR=$PREFIX/release_packages/$REL_NAME-$REL_VSN/release
 +
 
 +
$BINDIR/erlexec -config $REL_DIR/sys.config -boot $REL_DIR/$REL_NAME $INVOCATION_SUFFIX
 +
</code>
 +
(this script is the modified version of script published on Erlware's tutorial: http://www.erlware.org/erlware/tutorial.html).
 +
 
 +
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:
 +
<code caption="Code listing 5.0">
 +
faxien publish name_of_your_application
 +
</code>
 +
Faxien should publish your application on all repositories it has. To change them, take a look at:
 +
<code caption="Code listing 5.1">
 +
faxien help
 +
faxien help commands
 +
faxien help examples
 +
</code>
 +
 
 +
If you want to publish your release, switch to the tar directory (by default _build/development/tar) and use the same command as above:
 +
<code caption="Code listing 5.2">
 +
faxien publish name_of_your_application-version.tar.gz
 +
</code>
 +
 
 +
 
 +
== 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:
 +
<code caption="Code listing 6.0">
 +
faxien search
 +
# or if you want to use some help
 +
faxien help search
 +
</code>
 +
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):
 +
<code caption="Code listing 6.1">
 +
# for application:
 +
faxien install-app
 +
# for release:
 +
faxien install-release
 +
</code>
 +
The desired package will be placed in application_packages/$ERTS_VSN/ or release_packages/ directory inside the Faxien's root folder.
 +
 
 +
== Summary ==
 +
Well, that's everything you need to know about Sinan and Faxien. Now, you are able to
 +
<ul>
 +
<li>generate new project</li>
 +
<li>build it</li>
 +
<li>make release</li>
 +
<li>publish it</li>
 +
<li>install it</li>
 +
</ul>
 +
 
 +
 
 +
Good luck!

Revision as of 13:36, 4 July 2008

Contents

Author

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 ./faxien-launcher-universal.py
or
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
        |   `-- my_app.app
        |-- 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`
sinan
# 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"
    webdav.is-readonly = "disable"
    webdav.sqlite-db-name = "/var/run/lighttpd/lighttpd.webdav_lock.db"
    

After doing that you will be able to access your repository via http://127.0.0.1/repo 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:

#!/bin/sh

#### Fill in values for these variables ####
REL_NAME=your_application_name
REL_VSN=your_release_version
ERTS_VSN=your_erts_version
INVOCATION_SUFFIX="additional_information_for_erlexec_,_leave_blank_if_you_don't_want_to_pass_anything"
###########################################

PROG=$0
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
export LD_LIBRARY_PATH=$PREFIX/erts/$ERTS_VSN/lib

REL_DIR=$PREFIX/release_packages/$REL_NAME-$REL_VSN/release

$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: http://www.erlware.org/erlware/tutorial.html).

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.

Summary

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!