Configuration File Reference

The ~/.config/jhbuildrc file uses standard Python syntax. The file is run, and the resulting variables defined in the namespace are used to control how JHBuild acts. A set of default values are inserted into the namespace before running the user’s configuration file.

Boolean configuration variables are set using syntax as demonstrated in the following example:

use_local_modulesets = True

String configuration variables are set using syntax as demonstrated in the following example:

autogenargs = '--disable-static --disable-gtk-doc'

List configuration variables are set using syntax as demonstrated in the following example:

skip = ['mozilla', 'pulseaudio']

Dictionary configuration variables are set using syntax as demonstrated in the following example:

repos['git.gnome.org'] = 'ssh://username@git.gnome.org/git/'

Configuration Variables

alwaysautogen

A boolean value if set to True, always run autogen.sh. This is equivalent to passing --autogen option to JHBuild. Defaults to False.

autogenargs

A string containing arguments passed to the autogen.sh script of all modules. Can be overridden for particular modules using the module_autogenargs dictionary.

branches

A dictionary specifying which branch to use for specific modules. This is useful if you are making some changes on a branch of a module and want JHBuild to build that branch instead of the one listed in the module set.

The definition of branches depends on the module VCS:

  • CVS: revision. E.g. 'BRANCH-PROJECT-0_8'

  • Bazaar: URI of module branch. E.g. 'http://bzr.example.net/project/gnome-2-28'

  • Git: tuple, with first part being an optional repository (or the None value) and the second part the name of the branch. E.g. ('git://git.example.net/project', 'gnome-2-28')

    branches['modulename'] = (None, 'branchname')

  • Subversion: URI of module branch. E.g. 'svn://svn.example.net/project/gnome-2-28'

builddir_pattern

A printf style formatting pattern used to generate build directory names. This is only used when using separate source and build trees. The %s in the format string will be replaced with checkoutdir. Defaults to '%s'.

buildroot

A string specifying the parent directory to place build trees. Defaults to ~/.cache/jhbuild/build. Setting the value to None causes builds to be performed within the source trees.

buildscript

A string specifying which buildscript to use. The recommended setting is the default, terminal. In particular, do not set to gtk.

build_policy

A string specifying which modules to build. The three possible options are all, to build all modules requested, updated to build only modules which have changed, or updated-deps to build modules which have changed or which have dependencies which have changed. Defaults to updated-deps.

checkoutroot

A string specifying the directory to unpack source trees to. Unless buildroot is set, builds will occur in this directory too. Defaults to ~/checkout/gnome.

checkout_mode

A string specifying how the checkout is performed for directories in version control. Defaults to update. This can be set per module using module_checkout_mode. Possible values are update (update checkout directory), clobber (wipe out directory before checking out the sources), export (wipe out directory then create a tarball of the sources containing any patches) and copy (checkout in a directory different from the one it will build).

cmakeargs

A string containing arguments passed to the cmake invocation of all modules. Can be overridden for particular modules using the module_cmakeargs dictionary. Defaults to ''.

copy_dir

A string specifying the directory to copy to, if the copy checkout_mode is in use. Defaults to the checkout directory.

export_dir

A string specifying the directory to export to, if the export checkout_mode is in use. Defaults to the checkout directory.

cvs_program

A string specifying which program to use for CVS support. This can be git-cvsimport, or cvs. Defaults to cvs.

disable_Werror

A boolean value (default True) which controls if --disable-Werror will be passed to automake builds. Many packages use this flag as a way to disable fatal compiler warnings. The value of True is selected as a reasonable default for those using jhbuild as a means to get an up-to-date version of software packages without being side-tracked by build failures in other people’s modules. Setting this value to False may make sense for those using jhbuild as part of a continuous integration or testing system.

dvcs_mirror_dir

A string specifying a local mirror directory. JHBuild will create local mirrors of repositories at the specified directory. The mirrors can be shared by multiple repository groups, saving space and time because hard-links will be used for local clones. The commands update and updateone will create the mirrors and fetch new commits from the online repositories. This option is only supported by Git and Bazaar repositories.

exit_on_error

A boolean value specifying whether to exit immediately when a module fails to build. This is primarily useful in noninteractive mode, in order to prevent additional modules from building after one fails. Setting this value to True is equivalent to passing the --exit-on-error option. Defaults to False.

extra_prefixes

A list of strings specifying, in precedence order, the list of extra prefixes. JHBuild sets many environment variables (such as LD_LIBRARY_PATH, PKG_CONFIG_PATH and XDG_DATA_DIRS) based on the prefix variable. Adding directories to extra_prefixes will cause these prefixes to be included as well, at a lower precedence than the JHBuild prefix, but at a higher precedence than system directories. This variable is empty by default except on systems that install software in /usr/local, in which case it contains this directory.

help_website

A tuple specifying a help website name and URL. The website is displayed in the tinderbox html for failed modules. %(module)s in the URL will be replaced with the module name. To disable, set help_website to None. Defaults to ('Gnome Live!', 'http://live.gnome.org/JhbuildIssues/%(module)s').

installprog

A string specifying a program to use as replacement for /usr/bin/install.

ignore_suggests

A boolean value specifying whether to ignore soft dependencies when calculating the dependency tree. Defaults to False.

interact

A boolean value specifying whether to interact with the user. Setting this value to False is equivalent to passing the --no-interact option. Defaults to True.

makeargs

A string listing additional arguments to be passed to make. JHBuild will automatically append the parallel execution option (-j) based upon available CPU cores. Defaults to ''.

makecheck

A boolean value specifying whether to run make check after make. Defaults to False.

makecheck_advisory

A boolean value specifying whether failures when running make check should be advisory only and not cause a build failure. Defaults to False.

makeclean

A boolean value specifying whether to run make clean before make. Defaults to False.

makedist

A boolean value specifying whether to run make dist after make. Defaults to False. This setting is equivalent to passing the --dist option.

makedistcheck

A boolean value specifying whether to run make distcheck after make. Defaults to False. This setting is equivalent to passing the --distcheck option.

mesonargs

A string containing arguments passed to the meson invocation of all modules. Can be overridden for particular modules using the module_mesonargs dictionary. Defaults to ''.

module_autogenargs

A dictionary mapping module names to strings specifying the arguments to be passed to autogen.sh. The setting in module_autogenargs is used instead of the global autogenargs setting. If a particular module isn’t listed in the dictionary, the global autogenargs will be used.

module_checkout_mode

A dictionary specifying which checkout mode to use for modules. This overrides the global checkout_mode setting.

module_cmakeargs

A dictionary mapping module names to strings specifying the arguments to be passed to cmake. The setting in module_cmakeargs is used instead of the global cmakeargs setting. If a particular module isn’t listed in the dictionary, the global cmakeargs will be used.

module_makeargs

A dictionary mapping module names to strings specifying the arguments to pass to make. The setting in module_makeargs replaces the value of makeargs. If a particular module isn’t listed in the dictionary, the global makeargs will be used.

module_makecheck

A dictionary mapping module names to boolean values specifying whether to run make check after make. The setting in module_makecheck replaces the value of makecheck. If a particular module isn’t listed in the dictionary, the global makecheck will be used.

module_mesonargs

A dictionary mapping module names to strings specifying the arguments to be passed to meson. The setting in module_mesonargs is used instead of the global mesonargs setting. If a particular module isn’t listed in the dictionary, the global mesonargs will be used.

module_ninjaargs

A dictionary mapping module names to strings specifying the arguments to pass to ninja. The setting in module_ninjaargs replaces the value of ninjaargs. If a particular module isn’t listed in the dictionary, the global ninjaargs will be used.

module_nopoison

A dictionary mapping module names to boolean values. If a module is set to True, JHBuild will attempt to build dependent modules even if the specified module failed. The setting in module_nopoison replaces the value of nopoison. If a particular module isn’t listed in the dictionary, the global nopoison will be used.

module_extra_env

A dictionary mapping module names to dictionaries with extra environment variables to pass when executing commands for the module.

module_static_analyzer

Dictionary mapping module names to boolean values indicating whether static analysis should be performed while building that module. This allows the global static_analyzer configuration option to be overridden.

modules

A list of strings specifying the modules to build. The list of modules actually built will be recursively expanded to include all the dependencies unless the buildone command is used. Defaults to ['meta-gnome-desktop'].

moduleset

A string or list of strings specifying the name(s) of the module set(s) to use. This can either be the filename of a moduleset included with JHBuild (excluding the path and extension), or a full HTTP URL to an externally managed moduleset. HTTP URL modulesets are cached locally. If a module with the same name is present in more than one moduleset, the last set listed takes priority. Modulesets provided with JHBuild are updated to match the current GNOME development release.

modulesets_dir

A string specifying the directory containing the modulesets to use. Defaults to the modulesets/ directory in JHBuild sources.

nice_build

Run builds under the SCHED_IDLE priority on Linux, nice on other Unix. This can dramatically improve desktop interactivity for parallel builds while having only a negligible impact on build throughput.

ninjaargs

A string listing additional arguments to be passed to ninja. Defaults to ''.

nobuild

A boolean value, if set to True JHBuild will not build modules, but just download and unpack the sources. The default value is False.

nonetwork

A boolean value specifying whether to access the network. This affects checking out or updating CVS modules, downloading tarballs and updating module sets. Setting this to True is equivalent to passing the --no-network option. Defaults to False.

nonotify

A boolean value specifying whether to emit notifications using the notification daemon. If set to False, notifications are emitted. Defaults to True.

nopoison

A boolean value, if set to True JHBuild attempts to build modules even if one or more of the module’s dependencies failed to build. This option is equivalent to the --no-poison argument. The default value is False.

notrayicon

A boolean value specifying whether to show an icon in the system tray using Zenity. If set to False, an icon is shown. Defaults to True.

noxvfb

A boolean value, if set to True JHBuild will run any graphical tests on the real X server, rather than using Xvfb. This option is equivalent to passing --no-xvfb. The default value is False.

partial_build

A boolean value, if set to True JHBuild will not build dependency modules if corresponding system packages are installed and sufficient version. Defaults to True.

prefix

A string specifying the prefix to install modules to. prefix must be an absolute path. This directory must be writable. Defaults to '~/jhbuild/install/'.

pretty_print

A boolean value specifying whether to pretty format the subprocess output. Only CVS output supports pretty printing. Disable if the pretty printing causes problems. Defaults to True.

progress_bar

A boolean value specifying whether to display a progress bar during quiet_mode. Defaults to True.

quiet_mode

A boolean value, if set to True disables the output of running commands. Defaults to False.

repos

A dictionary specifying an alternative repository location for a particular repository. This configuration variable is useful to a module developer. By default, JHBuild will check out code from repositories using an anonymous repository location. The dictionary keys are short repository names and the values are the alternative repository location strings. For example:

repos['git.gnome.org'] = 'ssh://username@git.gnome.org/git/'

shallow_clone

A boolean value specifying if JHBuild should prefer smaller version control downloads. Equivalent to git clone --depth 1 or bzr co --light. Defaults to False.

skip

A list of modules to skip. This --skip command line option extends the list. This list is empty by default. If the list contains the special value '*', JHBuild will skip all modules not explicitly listed in the modules variable. This may be useful if you want to build modules without their implicit dependencies. The list supports fnmatch()-style globs, e.g. py* to skip all modules starting with py.

static_analyzer

A boolean value: if set to True, run a static analysis tool on each module as it’s being built. Defaults to False.

static_analyzer_outputdir

Root directory below which static analysis reports will be saved (if static_analyzer is True). Defaults to /tmp/jhbuild_static_analyzer.

static_analyzer_template

Command template for the static analyzer. This has the parameters outputdir (the value of the static_analyzer_outputdir configuration variable) and module (the name of the module currently being built) substituted into it printf-style. The resulting command is used as a prefix to make when building a module. Defaults to scan-build.

sticky_date

A string if set, and if supported by the underlying version control system, JHBuild will update the source tree to the specified date before building. An ISO date format is required, e.g. 'yyyy-mm-dd'. Defaults to None.

svn_program

A string specifying which program to use for subversion support. This can be svn, git-svn or bzr. Defaults to svn.

system_libdirs

A list of strings specifying the system library paths. This is used when setting the default values of some environment variables, such as PKG_CONFIG_PATH.

tarballdir

A string if set, tarballs will be downloaded to the specified directory instead of checkoutroot. This is useful if you have multiple JHBuild environments or regularly clear out checkoutroot and want to reduce bandwidth usage. Defaults to '~/.cache/jhbuild/downloads'.

tinderbox_outputdir

A string specifying the directory to store jhbuild tinderbox output. This string can be overridden by the --output option. Defaults to None, so either the command line option must be used or this variable must be set in the configuration file.

trycheckout

A boolean value, if set to True JHBuild will automatically try to solve failures by 1) running autogen.sh again, and 2) checking out a newer version of a module from version control. This setting is equivalent to passing the --try-checkout option.

use_local_modulesets

A boolean value that specifies to use modulesets that were checked out along the JHBuild source code; instead of downloading them on-the-fly from GNOME version control system. Defaults to False.

xvfbargs

A string listing arguments to pass to Xvfb if running graphical tests.

conditions

A set of condition (strings) that can influence the modules that are built and the options that are used for building them. You should use conditions.add() and conditions.discard() to modify the list if you want to make changes.

The original set of conditions is determined on a per-OS basis and can be modified using the --conditions= commandline argument. The changes made by --conditions are visible at the time that jhbuildrc is sourced, so you can set other variables based on the current value of the set, but --conditions will be applied again after any changes made by jhbuildrc.

Other Configuration File Structures

In addition to the above variables, there are other settings that can be set in the configuration file:

os.environ

A dictionary representing the environment. This environment is passed to processes that JHBuild spawns.

Some influential environment variables include CPPFLAGS, CFLAGS, INSTALL and LDFLAGS. For example:

os.environ['CFLAGS'] = '-O0 -g'
addpath(envvar, pathname)

This will add a directory to the PATH environment variable. addpath will correctly handle the case when the environment variable is initially empty (having a stray colon at the beginning or end of an environment variable can have unexpected consequences).

prependpath(envvar, pathname)

After processing the configuration file, JHBuild will alter some paths based on variables such as prefix (e.g. adding $prefix/bin to the start of PATH).

The prependpath function works like addpath, except that the environment variable is modified after JHBuild has made its changes to the environment.