How to set up PyTango job in Mr Jenkins
---------------------------------------

1. Go to 'Manage Jenkins' -> 'Configure System' -> 'Global properties', tick 'Environment variables' and add a new pare name: INSTITUTE, value: YOURINSTITUTENAME. Having it done Mr Jenkins will automatically set an environmental variable 'INSTITUTE' with the provided value on every machine it builds the project.

2. 'Create a new job' and name it PyTango. Tick 'Build multi-configuration project'.

3. Add 'Description' - what the project is, what are the deliverables (libs, binaries...) and paths where the deliverables are stored. Configure your build script (described below) so the deliverables end up in a directory /tmp/jenkins/jobs/PyTango (just a convention).

4. In S'ource Code Management' tick 'Subversion' and provide the 'Repository URL' to the trunk (https://tango-cs.svn.sourceforge.net/svnroot/tango-cs/bindings/PyTango/trunk). In the Local module directory input field enter dot (.). Thanks to this, the temporary bash file created by Mr Jenkins will be executed from the directory in which the project files are stored on the slave machines - which provides you an easy access to your build scripts.

5. In 'Build Triggers' tick 'Build after other projects are built' if you want to trigger the build of PyTango job after another project is build (e.g. TangoLib) and provide the 'Project name'. If you want to schedule a build at a particular days and hours, tick 'Poll SCM'. Acquaint yourself with the syntax by clicking the question mark icon on the right hand side.

6. If you want to build your the project on different machines, testing its compatibility with numerous operating systems, etc. use the 'Configuration Matrix'. 'Add axis', choose 'Slaves', change the 'name' to SLAVE, tick nodes of your choice (the project will be build just on the nodes you choose). If you want to build your project in various ways (e.g. the debug and release versions) 'Add axis' choose 'User-defined axis' and provide a 'name' (e.g. DEBUGMODE) and space separated values (e.g. debug release). This will make Mr Jenkins execute two builds for the same project and create an environmental variable DEBUGMODE for each build with a different value. This value can be read in the build script and based on it different actions can be taken to build the project in different ways.

7. Go to 'Build' choose 'Execute shell' and enter:
	cd ci
	./build.sh
   If the configuration of Mr Jenkins was done following the aforementioned steps, this will execute the build script tailored for your INSTITUTE. More about the build script and the ci directory file structure below.
   
8. Go to 'Post-build Actions' and choose 'E-mail Notification' to inform you about any broken builds.


Appendix A
The 'ci' folder structure and the build script.

In the 'ci' folder there is a 'build.sh' script. This is a default script and can be copied to any new project to support Continuous Integration with the use of Mr Jenkins in different institutes.

The 'build.sh' script simply checks if Mr Jenkins has set up the INSTITUTE environmental variable (look point 1.) and whether in the 'ci' folder exists a directory named 'YOURINSTITUTENAME'. If so, the 'build.sh' enters the YOURINSTITUTENAME directory and executes a 'build.sh' script within it. This is an institute tailored build script.

The 'YOURINSTITUTENAME/build.sh' script contains the recipe of how to build the project in your institute.

If you build the project on different machines and systems it is quite likely that the configuration of the build will be different for different nodes (slaves, machines, hosts).
For this purpose node dependent properties files have been introduced. The idea is that in the 'YOURINSTITUTENAME' there should be a file for each node used by Mr Jenkins. The file should have the same name as the node name, e.g. 'mynode'. Mr Jenkins automatically sets up an environmental variable called 'NODE_NAME' on each machine it executes a job. The NODE_NAME is the name defined in 'Manage Jenkins' -> 'Manage Nodes' -> 'Name' and this name should be given to the properties file name.
The below code manages the node properties files:

if [ ! -z "$NODE_NAME" -a -f "$NODE_NAME" ]
then
	source "$NODE_NAME"
else
	echo "The settings file for the node $NODE_NAME does not exist!"
	echo "Create ci/$INSTITUTE/$NODE_NAME file."
	exit 1
fi

If the file '$NODE_NAME' exists in the 'YOURINSTITUTENAME' directory its content is sourced in the 'build.sh' file and therefore all the variables set in the file are available in the build script.

To make use of them, write your 'build.sh' script in the most generic way you can. When you need to put a node dependent configuration, use a variable. Set a value of this variable in the node properties file (providing different values for different nodes). This way configuring you build after adding or removing a node is limited to simply adding or removing a file in the 'YOURINSTITUTENAME' directory.
