Using Faxien and Sinan
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:
So, according to it, you have to run:
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 which you have submitted 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. Faxien logs are placed in /tmp/faxien.err_log and in /tmp/faxien.sasl_log files.
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), change its owner to www-data (`sudo chown www-data /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"
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 to 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