~ salmonella-environment-setup (master) /README
Trap1== Introduction23This file contains instructions on how to build CHICKEN and run4salmonella using salmonella-run-publish.56To run tests for multiple settings (e.g., branches, C toolchains,7different build options etc.), we use a wrapper script:8run-salmonella.sh in this directory.91011== Requirements1213The following system tools are required:1415* bzip216* GNU make17* A working C toolchain18* tar19* svn20* git21* dot (from GraphViz)22* gzip2324The following CHICKEN tools are required2526* salmonella27* salmonella-html-report28* salmonella-feeds29* salmonella-diff30* salmonella-run-publish31* henrietta-cache (optional -- only for salmonella-run-publish's32 local-mode)333435The following directory layout is assumed by run-salmonella.sh (see36"Initial setup" for more details):3738$HOME/local/chicken-439 CHICKEN 4 installation directory (in case CHICKEN 4 tools are used)4041$HOME/local/chicken-542 CHICKEN 5 installation directory (used by default)4344By default CHICKEN 5 tools are going to be used. If you want to use45CHICKEN 4 tools instead, set the `CHICKEN_TESTS_MAJOR_VERSION'46environment variable to 4.474849The following directory layout will be generated by run-salmonella.sh50after tests:5152$HOME/salmonella/build53 Work directory for salmonella builds5455$HOME/salmonella/reports56 Salmonella reports, RSS feeds and log files to be served by a web57 server.585960=== Account conventions for dedicated salmonella machines6162run-salmonella.sh can be used on regular systems with regular user63accounts. For dedicated salmonella machines we follow a convention of64using the following user accounts:6566* chicken: regular user account to run salmonella jobs. This user67 runs run-salmonella.sh via cron.6869* awful: in case the salmonella machine serves the salmonella reports70 and assorted salmonella log files generated by the test jobs, the71 web server conventionally runs under the awful account, which can be72 a system account.737475== Initial setup7677The instructions below apply if you want to run salmonella jobs using78CHICKEN 5 tools.798081=== Install CHICKEN 5 & required eggs8283run-salmonella.sh will look for CHICKEN 5 tools in84$HOME/local/chicken-5. I usually install CHICKEN setting85PREFIX=$HOME/local/chicken-<version> and create a symlink86chicken-5 -> chicken-<version> in $HOME/local (that eases87updating CHICKEN).8889Once CHICKEN 5 is installed, we can use it to install the required90eggs. At the moment some eggs are only available in git:9192$ $HOME/local/chicken-5/bin/chicken-install salmonella-html-report salmonella-diff salmonella-feeds9394$ git clone https://github.com/mario-goulart/salmonella-run-publish95$ cd salmonella-run-publish96$ $HOME/local/chicken-5/bin/chicken-install979899== Configuring salmonella jobs100101run-salmonella.sh will look for configuration files (files with a102`.conf' sufix) in the `conf' directory of the local copy of the103salmonella-environment-setup repository. The configuration files are104Scheme files that usually set salmonella-run-publish parameters.105106run-salmonella.sh will also read `settings.sh' files from the107configuration directory. These files will be load shell settings108("source") in the current environment. That can be useful if you want109to set environment variables. run-salmonella.sh will look for110settings files in the following directories, according to the111following order:112113* $HOME/src/salmonella-environment-setup/conf/shell-settings/${OS}114* $HOME/src/salmonella-environment-setup/conf/shell-settings/${OS}-${ARCH}115116Where ${OS} is the value returned by (software-version) and ${ARCH} is117the value returned by (machine-type) by CHICKEN.118119120== Running run-salmonella.sh121122After you've got everything installed and configured, you can call123run-salmonella.sh with the configuration file names (without124extension) as arguments. Example:125126$HOME/src/salmonella-environment-setup/run-salmonella.sh chicken-5 chicken-5-clang127128This will make run-salmonella.sh pick the chicken-5.conf and129chicken-5-clang.conf files and shell settings files for ${OS} and130${ARCH}.131132To run those jobs periodically, just configure a crontab entry for the133run-salmonella.sh command line.134135136== Setting up the web server137138Setting up the web server is optional, as it is possible to generate139reports on a system (which doesn't run the web server) and serve them140from another system.141142The web server is a custom hack to serve salmonella reports out of143compressed tar files. To install it, run:144145$ chicken-install awful-salmonella-tar146147The default configuration of the web server in the148salmonella-environment-setup repository (`awful' directory) assumes149some conventions:150151* The web server runs under the `awful' user account.152153* Web server logs go to /var/log/awful (the awful user must be able to154 write to that directory).155156* HTML files extracted from salmonella reports in compressed tar157 format are cached under /var/cache/awful-salmonella-tar (the awful158 user must be able to write to that directory).159160* Configuration files are conventionally kept at /etc/awful (normally161 it contains symlinks to actual files in the local copy of the162 salmonella-environment-setup repository). A typical configuration163 for the web server can be set up like (assuming164 salmonella-environment-setup is cloned under165 $HOME/src/salmonella-environment-setup):166167 $ mkdir /etc/awful168 $ cd /etc/awful169 $ ln -s $HOME/src/salmonella-environment-setup/awful/awful-salmonella-tar.conf awful.conf170 $ ln -s $HOME/src/salmonella-environment-setup/awful/privileged.conf171172The default configuration expects to serve files from173/home/chicken/salmonella/reports (that's hardcoded in awful.conf).174Since web bots can scan salmonella reports and request a lot of files,175it's recommended to install the robots.txt file in the web server's176document directory:177178$ cd /home/chicken/salmonella/reports179$ ln -s /home/chicken/src/salmonella-environment-setup/awful/robots.txt180181How to start and stop the server is system-dependent and not covered182by this document. The `awful' directory in the183salmonella-environment-setup repository contains some assorted scripts184for some systems).