{{TableOfContents}}This page documents the interface between the Jenkins front endand the Fuego core engine.

From Jenkins to Fuego [edit section]

= From Jenkins to Fuego =

Environment variables passed during a build [edit section]

== Environment variables passed during a build ==

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

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

=== Built-in Jenkins variables for shell script jobs ===; 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]

=== Fuego variables passed from Jenkins interface ===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]

=== Variables from the target definition (config.xml for the board) ===; 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]

= From Fuego to Fuego =; 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]

= Example Values =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.boardBUILD_ID=2016-06-23_22-50-43BUILD_NUMBER=7BUILD_TAG=jenkins-Functional.bc-7BUILD_URL=http://127.0.0.1:8080/job/Functional.bc/7/Device=bbbFUEGO_ENGINE_PATH=/home/jenkinsFUEGO_PARSER_PATH=/home/jenkins/scripts/parserJENKINS_HOME=/var/lib/jenkinsJENKINS_URL=http://127.0.0.1:8080/JOB_NAME=Functional.bcJOB_URL=http://127.0.0.1:8080/job/Functional.bc/EXECUTOR_NUMBER=0NODE_NAME=bbbNODE_LABLES=bbbOF_BOARD_FILE=/home/jenkins/overlays//boards/bbb.boardOF_CLASSDIR=/home/jenkins/overlays//baseOF_CLASSDIR_ARGS='--classdir /home/jenkins/overlays//base'OF_DEFAULT_SPECDIR=/home/jenkins/overlays//test_specs/OF_DISTRIB_FILE=/home/jenkins/overlays//distribs/nologger.distOF_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.jsonOF_TESTPLAN_ARGS='--testplan /home/jenkins/overlays//testplans/testplan_default.json'Reboot=falseRebuild=falseTarget_Cleanup=trueTEST_HOME=/home/jenkins/tests/Functional.bcTESTDIR=Functional.bcTESTPLAN=testplan_defaultTRIPLET=Functional.bc-WORKSPACE=/home/jenkins/buildzone}}}

More variables (not from Jenkins):{{{FUEGO_LOGS_PATH}}}

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

== Scripts to detect Fuego data - boards, tests, etc. ==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

 * 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'

 * 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]

= From Fuego to Jenkins = * 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]

== Jenkins-cli interface ==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 informationabout 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]

== Scripts to process Fuego data ==

Groovy Postbuild [edit section]

=== Groovy Postbuild ===In Fuego, Jenkins has the Groovy Postbuild plugin installed.

Every test is configured to run a postbuild script, which augmentsthe 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 APIsfor 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