Contents: From Jenkins to Fuego Environment variables passed during a build Built-in Jenkins variables for shell script jobs Fuego variables passed from Jenkins interface Variables from the target definition (config.xml for the board) From Fuego to Fuego Example Values Scripts to detect Fuego data - boards, tests, etc. From Fuego to Jenkins Jenkins-cli interface Scripts to process Fuego data Groovy Postbuild

This page documents the interface between the Jenkins front end and the Fuego core engine.

From Jenkins to Fuego [edit section]

Environment variables passed during a build [edit section]

Built-in Jenkins variables for shell script jobs [edit section]

BUILD_ID

The current test run id, such as "2005-08-22_23-59-59" (YYYY-MM-DD_hh-mm-ss)

BUILD_NUMBER

The current test run number, such as "153". This appears to be selected as the next numerical number in sequence, by the Jenkins system, at the start of a job.

BUILD_TAG

String of "jenkins-${JOB_NAME}-${BUILD_NUMBER}". Convenient to put into a resource file, a jar file, etc for easier identification.

BUILD_URL

Full URL of this test run, like http://server:port/jenkins/job/foo/15/

EXECUTOR_NUMBER

The unique number that identifies the current executor (among executors of the same machine) that's carrying out this test run. This is the number you see in the "test executor status", except that the number starts from 0, not 1.

JENKINS_HOME

The absolute path of the directory assigned on the master node for Jenkins to store data.

JENKINS_URL

Full URL of Jenkins, like http://server:port/jenkins/

JOB_NAME

Name of runned test or test suite, such as "foo" or "foo/bar". In Fuego, this will be something like: Functional.foo or Benchmark.bar

JOB_URL

Full URL of this test or test suite, like http://server:port/jenkins/job/foo/

NODE_LABELS

Whitespace-separated list of labels that the node is assigned.

NODE_NAME

Name of the slave if the test run is on a slave, or "master" if run on master. In the case of Fuego, this is the board name (e.g. 'beagleboneblack')

WORKSPACE

The absolute path of the directory assigned to the test run as a workspace. For Fuego, this is always /home/jenkins/buildzone

Fuego variables passed from Jenkins interface [edit section]

These variables are defined in the job definition for a test:

Device

This is the target board to run the test on. Note that this is selected by the end user from the output of getTargets.groovy

Reboot

Indicates to reboot the target device before running the test

Rebuild

Indicates that build instances of the test suite should be deleted, and the test suite rebuilt from the tarball

Target_Cleanup

Indicates to clean up test materials after the test ends

TESTPLAN

This has the name of the testplan used for this test job. Note that this selected by the end user from the output of getTestplans.groovy. (example value: testplan_default)

Variables from the target definition (config.xml for the board) [edit section]

BOARD_OVERLAY

path to the board file. This comes from Jenkins config.xml for the target that was selected for the test. (example: boards/beagleboneblack.board)

DISTRIB

indicates the distribution file for the board. This comes from Jenkins config.xml for the target that was selected for the test. It's primary purpose is to select the logging features of the distribution on the target (to indicate whether there's a logger present on target). The value is often 'distribs/nologger.dist'

From Fuego to Fuego [edit section]

FUEGO_ENGINE_PATH

path to the root of the fuego engine. (usually /home/jenkins)

FUEGO_PARSER_PATH

path to the parser directory (usually /home/jenkins/scripts/parser)

OF_BOARD_FILE

full path to the board file

OF_CLASSDIR

full path to the overlay class directory (usually /home/jenkins/overlays//base)

OF_CLASSDIR_ARGS

argument specifying the overlay class directory (usually '--classdir /home/jenkins/overlays//base')

OF_DEFAULT_SPECDIR

path to directory containing test specs (usually /home/jenkins/overlays//test_specs)

OF_DISTRIB_FILE

path to the distribution file for the target board (often /home/jenkins/overlays//distribs/nologger.dist

OF_OVFILES

FIXTHIS - document what OF_OVFILES is for

OF_OVFILES_ARGS

FIXTHIS - document what OF_OVFILES_ARGS is for

OF_ROOT

root directory for overlay generator (usually /home/jenkins/overlays/)

OF_SPECDIR_ARGS

argument to specify the test spec directory (usually '--specdir /home/jenkins/overlays//test_specs/')

OF_TESTPLAN_ARGS

OF_TESTPLAN

full path to the JSON test plan file for this test (often /home/jenkins/overlays//testplans/testplan_default.json)

OF_TESTPLAN_ARGS

argument specifying the path to the testplan (often '--testplan /home/jenkins/overlays//testplans/testplan_default.json')

TEST_HOME

home directory for the test materials for this test (example: /home/jenkins/tests/Functional.bc)

TESTDIR

base directory name of the test (example: Functional.bc)

TRIPLET

FIXTHIS - document TRIPLET

Example Values [edit section]

Here are the values from a run using the Jenkins front-end with Functional.bc on a bbb (beagle-bone black) board: (these were sorted alphabetically)

BOARD_OVERLAY=boards/bbb.board
BUILD_ID=2016-06-23_22-50-43
BUILD_NUMBER=7
BUILD_TAG=jenkins-Functional.bc-7
BUILD_URL=http://127.0.0.1:8080/job/Functional.bc/7/
Device=bbb
FUEGO_ENGINE_PATH=/home/jenkins
FUEGO_PARSER_PATH=/home/jenkins/scripts/parser
JENKINS_HOME=/var/lib/jenkins
JENKINS_URL=http://127.0.0.1:8080/
JOB_NAME=Functional.bc
JOB_URL=http://127.0.0.1:8080/job/Functional.bc/
EXECUTOR_NUMBER=0
NODE_NAME=bbb
NODE_LABLES=bbb
OF_BOARD_FILE=/home/jenkins/overlays//boards/bbb.board
OF_CLASSDIR=/home/jenkins/overlays//base
OF_CLASSDIR_ARGS='--classdir /home/jenkins/overlays//base'
OF_DEFAULT_SPECDIR=/home/jenkins/overlays//test_specs/
OF_DISTRIB_FILE=/home/jenkins/overlays//distribs/nologger.dist
OF_OVFILES=
OF_OVFILES_ARGS=
OF_ROOT=/home/jenkins/overlays/
OF_SPECDIR_ARGS='--specdir /home/jenkins/overlays//test_specs/'
OF_TESTPLAN_ARGS=
OF_TESTPLAN=/home/jenkins/overlays//testplans/testplan_default.json
OF_TESTPLAN_ARGS='--testplan /home/jenkins/overlays//testplans/testplan_default.json'
Reboot=false
Rebuild=false
Target_Cleanup=true
TEST_HOME=/home/jenkins/tests/Functional.bc
TESTDIR=Functional.bc
TESTPLAN=testplan_default
TRIPLET=Functional.bc-
WORKSPACE=/home/jenkins/buildzone

More variables (not from Jenkins):

FUEGO_LOGS_PATH

Scripts to detect Fuego data - boards, tests, etc. [edit section]

These are scriptler programs, referenced in the test definitions inside Jenkins:

• getTargets.groovy - produces a list of targets
  • list is created by reading the list of Jenkins 'slaves'
  • is used to generate the list of variables seen by the user when manually executing a test

• getTestplans - produces a list of testplans
  • list is created by reading the files in /home/jenkins/overlays/testplans and finding the files ending with '.json'
  • takes argument of 'test_name'
  • value chosen by user is value of 'TESTPLAN' for a test run
• getTests.groovy - gets a list of tests for populating the Jenkins interface
  • list is created by scanning the list of Jenkins instance items and matching the items starting with 'Run', 'Service' and 'Matrix'

These are located in /home/jenkins/fuego/plugins-conf/scriptler/scripts

From Fuego to Jenkins [edit section]

• FIXTHIS - add interface to perform Jenkins operations from the scripts
• To abort a job, fuego does:
  • wget -qO- ${BUILD_URL}/stop
  • this is called by common.sh:abort_job()
• To check if another test instance is running (do a lock check), fuego does:
  • wget -qO- "$(cat ${LOCKFILE})/api/xml?xpath=*/building/text%28%29"
    • LOCKFILE was previously set to hold the contents: ${BUILD_URL}, so this resolves to:
      • wget -qO- ${BUILD_URL}/api/xml?xpath=*/building/text()
  • this is called by functions.sh:concurrent_check()

Jenkins-cli interface [edit section]

You can run jenkins commands from the command line, using the pre-installed jenkins-cli interface. Note that Fuego does not use this interface (that I can tell).

jenkins-cli.jar is located in the Docker container at:

   /var/cache/jenkins/war/WEB-INF/jenkins-cli.jar

See https://wiki.jenkins-ci.org/display/JENKINS/Jenkins+CLI for information about using this plugin.

Here is a list of available commands for this plugin:

  build
    Runs a test, and optionally waits until its completion.
  cancel-quiet-down
    Cancel the effect of the "quiet-down" command.
  clear-queue
    Clears the test run queue
  connect-node
    Reconnect to a node
  console
    Retrieves console output of a build
  copy-job
    Copies a test.
  create-job
    Creates a new test by reading stdin as a configuration XML file.
  delete-builds
    Deletes test record(s).
  delete-job
    Deletes a test
  delete-node
    Deletes a node
  disable-job
    Disables a test
  disconnect-node
    Disconnects from a node
  enable-job
    Enables a test
  get-job
    Dumps the test definition XML to stdout
  groovy
    Executes the specified Groovy script.
  groovysh
    Runs an interactive groovy shell.
  help
    Lists all the available commands.
  install-plugin
    Installs a plugin either from a file, an URL, or from update center.
  install-tool
    Performs automatic tool installation, and print its location to stdout. Can be only called from inside a test run.
  keep-build
    Mark the test run to keep the test run forever.
  list-changes
    Dumps the changelog for the specified test(s).
  list-jobs
    Lists all tests in a specific view or item group.
  list-plugins
    Outputs a list of installed plugins.
  login
    Saves the current credential to allow future commands to run without explicit credential information.
  logout
    Deletes the credential stored with the login command.
  mail
    Reads stdin and sends that out as an e-mail.
  offline-node
    Stop using a node for performing test runs temporarily, until the next "online-node" command.
  online-node
    Resume using a node for performing test runs, to cancel out the earlier "offline-node" command.
  quiet-down
    Quiet down Jenkins, in preparation for a restart. Don't start any test runs.
  reload-configuration
    Discard all the loaded data in memory and reload everything from file system. Useful when you modified config files directly on disk.
  restart
    Restart Jenkins
  safe-restart
    Safely restart Jenkins
  safe-shutdown
    Puts Jenkins into the quiet mode, wait for existing test runs to be completed, and then shut down Jenkins.
  session-id
    Outputs the session ID, which changes every time Jenkins restarts
  set-build-description
    Sets the description of a test run.
  set-build-display-name
    Sets the displayName of a test run
  set-build-result
    Sets the result of the current test run. Works only if invoked from within a test run.
  shutdown
    Immediately shuts down Jenkins server
  update-job
    Updates the test definition XML from stdin. The opposite of the get-job command
  version
    Outputs the current version.
  wait-node-offline
    Wait for a node to become offline
  wait-node-online
    Wait for a node to become online
  who-am-i
    Reports your credential and permissions

Scripts to process Fuego data [edit section]

Groovy Postbuild [edit section]

In Fuego, Jenkins has the Groovy Postbuild plugin installed.

Every test is configured to run a postbuild script, which augments the information in the system for the test run.

There is code in a test job configuration, to run the script: /home/jenkins/scripts/postbuild.groovy

A parameter to this script is a "manager" object, which provides APIs for createSummary(), addErrorBadge(), and addShortText()

These are used to add extra information to the run instance: abort reason - if Fuego errored out firmware revision - in all cases