releng Python API
=================

Build script definition
-----------------------

The build script is required to provide one function:

.. py:function:: do_build(context)

   Called to run the actual build.  The context parameter is an instance of
   BuildContext, and can be used to access the build environment and to
   interact with Jenkins.  The function can signal fatal build errors by
   raising BuildError directly; typically, this is done by methods in
   BuildContext if they fail to execute the requested commands.

   When the function is called, the current working directory is set to the
   build directory (whether the build is in- or out-of-source).

The build script can also set a few global variables to influence the behavior
of the build:

.. py:data:: build_options

   If this list value is set to a non-empty list, then these build options are
   used to initialize the build environment.  Useful for non-matrix builds that
   want to, e.g., specify the compiler to use.

.. py:data:: build_out_of_source

   If this boolean value is set to ``True``, the build will be executed
   out-of-source.  By default, the build will be in-source.

.. py:data:: extra_options

   If this dictionary is set, it declares additional build options that the
   script understands.  This can be used to declare options that only influence
   the build script; releng declares only options that affect the build
   environment or the build host assignment.  Syntax is as follows::

     extra_options = {
         'opt': Option.simple,
         'opt-bool': Option.bool,
         'opt-str': Option.string
     }

   The values of the build options can be read from ``context.opts`` in
   do_build().  See ``OptionTypes`` documentation for the available option
   types: in the build script, ``Option`` is bound to ``OptionTypes``.

   Technically, the value in the dictionary is a callable that gets called
   with the name of the option to create an internal handler class for
   processing the option.

.. py:data:: extra_projects

   If this list value is set to a non-empty list, then these repositories are
   also checked out before executing the build.  ``releng`` and ``gromacs``
   repositories are always checked out.
   Currently, only ``Project.REGRESSIONTESTS`` makes sense to specify here.

When the build script is loaded, various enums from the releng package are
injected into the global scope to make them easy to access.

API for build scripts
---------------------

The build script gets input and perfoms most tasks by using data and methods in
a BuildContext instance:

.. py:currentmodule:: releng.context
.. autoclass:: BuildContext
   :members:

The build context contains attributes of the following classes to access
additional information:

.. py:currentmodule:: releng.environment
.. autoclass:: BuildEnvironment
   :members:

.. py:currentmodule:: releng.options
.. autoclass:: BuildOptions

.. py:currentmodule:: releng.integration
.. autoclass:: BuildParameters

.. py:currentmodule:: releng.workspace
.. autoclass:: Workspace
   :members:

API for Jenkins
---------------

The following functions from the ``releng`` package are intended to be called
from scripts in Jenkins build configuration or from workflow scripts
(see :doc:`jenkins-config`).

.. py:currentmodule:: releng
.. autofunction:: run_build

.. autofunction:: read_build_script_config

.. autofunction:: prepare_multi_configuration_build

.. autofunction:: get_actions_from_triggering_comment

.. autofunction:: do_ondemand_post_build

.. autofunction:: get_build_revisions

.. autofunction:: read_source_version_info