~ salmonella-environment-setup (master) 76c096fc625cd34d8bc948e6f2fdbf7e5c74fc4e

commit 76c096fc625cd34d8bc948e6f2fdbf7e5c74fc4e
Author:     Mario Domenech Goulart <mario@parenteses.org>
AuthorDate: Sun Dec 24 14:27:54 2017 +0100
Commit:     Mario Domenech Goulart <mario@parenteses.org>
CommitDate: Sun Dec 24 14:28:47 2017 +0100

    salmonella: Add README

diff --git a/README b/README
new file mode 100644
index 0000000..741d26c
--- /dev/null
+++ b/README
@@ -0,0 +1,149 @@
+== Introduction
+
+This file contains instructions on how to build CHICKEN and run
+salmonella using salmonella-run-publish.
+
+To run tests for multiple settings (e.g., branches, C toolchains,
+different build options etc.), we use a wrapper script:
+run-salmonella.sh in this directory.
+
+
+== Requirements
+
+The following system tools are required:
+
+* bzip2
+* GNU make
+* A working C toolchain
+* tar
+* svn
+* git
+* dot (from GraphViz)
+* gzip
+
+The following CHICKEN tools are required
+
+* salmonella
+* salmonella-html-report
+* salmonella-feeds
+* salmonella-diff
+* salmonella-run-publish
+* henrietta-cache (optional -- only for salmonella-run-publish's
+  local-mode)
+
+
+The following directory layout is assumed by run-salmonella.sh (see
+"Initial setup" for more details):
+
+$HOME/src/chicken-infrastructure
+    Clone of the chicken-infrastructure repository
+
+$HOME/local/chicken
+    CHICKEN 4 installation directory
+
+$HOME/local/chicken-5
+    CHICKEN 5 installation directory
+
+
+The following directory layout will be generated by run-salmonella.sh
+after tests:
+
+$HOME/salmonella/build
+    Work directory for salmonella builds
+
+$HOME/salmonella/reports
+    Salmonella reports, RSS feeds and log files to be served by a web
+    server.
+
+
+== Initial setup
+
+The instructions below apply if you want to test both CHICKEN 4 and
+CHICKEN 5.
+
+=== Install CHICKEN 4 & required eggs
+
+run-salmonella.sh will look for CHICKEN 4 tools in
+$HOME/local/chicken.  I usually install CHICKEN setting
+PREFIX=$HOME/local/chicken-<version> and create a symlink
+chicken -> chicken-<version> in $HOME/local (that eases
+updating CHICKEN).
+
+Once CHICKEN 4 is installed, we can use it to install the required
+eggs.  At the moment the recommendation is to install eggs from git
+(order is important):
+
+$ git clone https://github.com/mario-goulart/salmonella
+$ cd salmonella
+$ $HOME/local/chicken/bin/chicken-install
+
+$ git clone https://github.com/mario-goulart/salmonella-html-report
+$ cd salmonella-html-report
+$ $HOME/local/chicken/bin/chicken-install
+
+$ git clone https://github.com/mario-goulart/salmonella-diff
+$ cd salmonella-diff
+$ $HOME/local/chicken/bin/chicken-install
+
+$ git clone https://github.com/mario-goulart/salmonella-feeds
+$ cd salmonella-feeds
+$ $HOME/local/chicken/bin/chicken-install
+
+$ git clone https://github.com/mario-goulart/salmonella-run-publish
+$ cd salmonella-run-publish
+$ $HOME/local/chicken/bin/chicken-install
+
+
+=== Install CHICKEN 5 & required eggs
+
+If you plan to test CHICKEN 5, you'll need CHICKEN 4 and the eggs
+mentioned in the previous section.  Additionally, you'll need CHICKEN
+5 and salmonella for CHICKEN 5.
+
+run-salmonella.sh will look for CHICKEN 5 tools in
+$HOME/local/chicken-5.  I usually install CHICKEN setting
+PREFIX=$HOME/local/chicken-<version> and create a symlink
+chicken-5 -> chicken-<version> in $HOME/local (that eases
+updating CHICKEN).
+
+Once CHICKEN 5 is installed, we can use it to install salmonella for
+CHICKEN 5.
+
+$ git clone https://github.com/mario-goulart/salmonella salmonella-5
+$ cd salmonella-5
+$ git checkout chicken-5
+$ $HOME/local/chicken-5/bin/chicken-install
+
+
+== Configuring salmonella jobs
+
+run-salmonella.sh will look for configuration files in the
+chicken-infrastructure repository, specifically:
+
+* $HOME/src/chicken-infrastructure/salmonella/${OS}-common
+* $HOME/src/chicken-infrastructure/salmonella/salmonella-${OS}-${ARCH}
+
+where ${OS} is the value returned by (software-version) and ${ARCH} is
+the value returned by (machine-type) by CHICKEN.
+
+run-salmonella.sh will look for configuration files with .conf suffix
+in those directories.  The conf files are Scheme files that usually
+set salmonella-run-publish parameters.  Take a look at the
+configuration files in linux-common for examples.
+
+run-salmonella.sh will also read a `settings.sh' file from the
+directories mentioned above.  This file will be load shell settings
+("source") in the current environment.  That can be useful if you want
+to set environment variables.
+
+
+== Running run-salmonella.sh
+
+After you've got everything installed and configured, you can call
+run-salmonella.sh with the configuration file names (without
+extension) as arguments.  Example:
+
+  $HOME/src/chicken-infrastructure/salmonella/run-salmonella.sh chicken-4 chicken-5
+
+This will make run-salmonella.sh pick the chicken-4.conf and
+chicken-5.conf files for ${OS} and ${ARCH}.