Specification for toolchains file

Generic format

This is a specification for the toolchains.yaml file.

toolchains:
  language key:
    - toolchain key
toolchain key:
  default_ivalue: tool
  friendlyLabel: true
  secureSupport: true
  matrix: simple
  cleanup:
    - cleanup command
    - another command
  tool key: |-
    some bash command
    another command
  '*': some ${jervis_toolchain_ivalue} command

Generic format Legend

1. toolchains - This key name must remain toolchains. It will consist of languages and their toolchain order. Validation: This key is required.
2. language key - This key name will change and be one of the values of the list of supported languages in the lifecycles file. For each value in the array in this key it must exist as a top level key because it is a toolchain. Validation: The key name will not be checked against anything. However each value in the array must exist as a top level key because it is a toolchain.
3. toolchain key - This key name will change and can be any arbitrary name that describes the toolchain. Validation: Not required however this key must exist if it is listed in a language key toolchain.
4. default_ivalue - This key name must remain default_ivalue. Validation: Not required. If used then the value must exist as a tool key key or the * will need to exist.
5. friendlyLabel - This key name must remain friendlyLabel. If true then matrix labels will take the form of a friendly label (e.g. jdk:openjdk7 instead of jdk0). Validation: Not required.
6. secureSupport - This key name must remain secureSupport. Validation: Not required.
7. matrix - This key name must remain matrix. Takes three values: disabled, simple, advanced. disabled means it is not meant to be in a matrix build configuration at all. simple is the current behavior which means a list of items in YAML is part of the matrix. advanced is when there is a global key and a matrix key in the YAML. Validation: Not required. If it exists it must be of type String and one of three values: disabled, simple, advanced.
8. cleanup - A list of commands that are designed to clean up data left behind from the toolchain. Validation: Not required. If it exists it must be of type String or List containing only Strings.
9. tool key - A key that contains an array or single string of the script to be executed for this tool key. Validation: Not always required. If default_ivalue is set and the * key does not exist then this key is required. If it exists it must be of type String or List containing only Strings.
10. * - The * is the default key that gets referenced if a tool index value (ivalue) is not used. Validation: Not always required. If default_ivalue is set and the tool key does not exist for the default_ivalue then this key is required.

A more specific toolchain example

toolchains:
  groovy:
    - env
    - jdk
  java:
    - env
    - jdk
  python:
    - env
    - python
  ruby:
    - env
    - rvm
    - jdk
compiler:
  gcc: |-
    export CXX="g++"
    export CC="gcc"
  clang: |-
    export CXX="clang++"
    export CC="clang"
env:
  secureSupport: true
  matrix: advanced
  '*': export ${jervis_toolchain_ivalue}
jdk:
  default_ivalue: openjdk7
  openjdk6: |-
    export JAVA_HOME="/usr/lib/jvm/java-6-openjdk-amd64/"
    export PATH="${JAVA_HOME}/bin:${PATH}"
    java -version
  openjdk7: |-
    export JAVA_HOME="/usr/lib/jvm/java-7-openjdk-amd64/"
    export PATH="${JAVA_HOME}/bin:${PATH}"
    java -version
  oraclejdk7: |-
    export JAVA_HOME="/opt/java-7-oraclejdk-amd64/"
    export PATH="${JAVA_HOME}/bin:${PATH}"
    java -version
  oraclejdk8: |-
    export JAVA_HOME="/opt/java-8-oraclejdk-amd64/"
    export PATH="${JAVA_HOME}/bin:${PATH}"
    java -version
python:
  default_ivalue: '2.7'
  '2.6': |-
    source ~/virtualenv/python2.6/bin/activate
    python --version
    pip --version
  '2.7': |-
    source ~/virtualenv/python2.7/bin/activate
    python --version
    pip --version
  '3.2': |-
    source ~/virtualenv/python3.2/bin/activate
    python --version
    pip --version
  '3.3': |-
    source ~/virtualenv/python3.3/bin/activate
    python --version
    pip --version
  '3.4': |-
    source ~/virtualenv/python3.4/bin/activate
    python --version
    pip --version
  pypy: |-
    source ~/virtualenv/pypy/bin/activate
    python --version
    pip --version
  pypy3: |-
    source ~/virtualenv/pypy3/bin/activate
    python --version
    pip --version
rvm:
  default_ivalue: 1.9.3
  '*': |-
    source "$HOME/.rvm/scripts/rvm"
    if ! rvm list | grep -q "${jervis_toolchain_ivalue}";then
      rvm install "${jervis_toolchain_ivalue}"
      rvm "${jervis_toolchain_ivalue}" do gem install bundler
    fi
    rvm use ${jervis_toolchain_ivalue}
    ruby --version

The toolchains key expresses which order in which different keys will be written out. For instance, "java": ["env","jdk"] means that in the shell builder script first the env toolchain commands will be written out and then the jdk toolchain commands will be written out. The toolchains key also determins what is a matrix builder. If the toolchain in the yaml file only contains a single item then it is not a matrix build. If the toolchain in the yaml file only contains multiple items then it is a matrix build job.

If default_ivalue key exists then the command will automatically be written out as if the user specified that version of the toolchain in their yaml file. If the default_ivalue key does not exist and the user doesn't specify the toolchain in their yaml file then nothing will be written out.

If secureSupport key exists and is true then it means that this toolchain supports secure fields.

As the user specifies toolchains in their yaml file keys inside of the toolchains.yaml will be looked up. If the toolchain key does not exist then jervis will check if the * key exists. If the * key exists then it will use that key for generating commands. If the * key does not exist then it will simply not write out anything.

If you include the text ${jervis_toolchain_ivalue} it will be interpolated with the index value of the toolchain being used. For example, if the version of rvm in the yaml file is set to 2.1.5 then all instances of ${jervis_toolchain_ivalue} will be replaced with 2.1.5.

Example yaml files and outputs

A simple ruby yaml file.

language: ruby

Based on the rules above the following would be output as the toolchains portion of the script.

#env toolchain
#rvm toolchain
source "$HOME/.rvm/scripts/rvm"
if ! rvm list | grep -q "1.9.3";then
  rvm install "1.9.3"
  rvm "1.9.3" do rvm gem install bundler
fi
rvm use 1.9.3
ruby --version
#jdk toolchain
export JAVA_HOME="/usr/lib/jvm/java-7-openjdk-amd64/"
export PATH="${JAVA_HOME}/bin:${PATH}"
java -version

Let's look at a slightly more complicated yaml file for Groovy based on Jervis.

language: groovy
env:
  - GROOVY_VERSION="2.2.2"
jdk:
  - oraclejdk8

Based on the rules the following would be output as the toolchains portion of the script.

#env toolchain
export GROOVY_VERSION="2.2.2"
#jdk toolchain
export JAVA_HOME="/opt/java-8-oraclejdk-amd64/"
export PATH="${JAVA_HOME}/bin:${PATH}"
java -version

A more complicated matrix building yaml file based on issue #7. This should be created by a generator class.

language: groovy
env:
  - GROOVY_VERSION="1.8.9"
  - GROOVY_VERSION="2.2.2"
  - GROOVY_VERSION="2.3.0"
jdk:
  - openjdk7
  - oraclejdk7
  - oraclejdk8

Here's the build matrix based on the rules.

#env toolchain
case ${env}
  0)
export GROOVY_VERSION="1.8.9"
    ;;
  1)
export GROOVY_VERSION="2.2.2"
    ;;
  2)
export GROOVY_VERSION="2.3.0"
    ;;
esac
#jdk toolchain
case ${jdk}
  0)
export JAVA_HOME="/usr/lib/jvm/java-7-openjdk-amd64/"
export PATH="${JAVA_HOME}/bin:${PATH}"
java -version
    ;;
  1)
export JAVA_HOME="/opt/java-7-oraclejdk-amd64/"
export PATH="${JAVA_HOME}/bin:${PATH}"
java -version
    ;;
  2)
export JAVA_HOME="/opt/java-8-oraclejdk-amd64/"
export PATH="${JAVA_HOME}/bin:${PATH}"
java -version
    ;;
esac