Premiers pas

Quelques manipulations sont nécessaires pour configurer JHBuild avant de pouvoir compiler des logiciels. Certains logiciels sont nécessaires au fonctionnement de JHBuild, et il est aussi nécessaire d'installer des outils indispensables à l'obtention et à la construction des sources de logiciels.

II.I. Installation de JHBuild

JHBuild requires a Python runtime. Verify Python >= 3.5 is installed.

The recommended way to download JHBuild is via the version control system, git. This can be achieved with the following command. It is recommended to run the command from a new directory where all source code will be installed, for example, ~/jhbuild/checkout.

$ git clone https://gitlab.gnome.org/GNOME/jhbuild.git
...
$

Cela va télécharger JHBuild dans un nouveau dossier nommé jhbuild dans le répertoire actuel. Ensuite, pour le construire et l'installer :

$ cd jhbuild
$ ./autogen.sh
...
$ make
...
$ make install
...
$

If gnome-common, yelp-tools and autotools are available, autogen.sh will configure JHBuild to install via autotools. If gnome-common, yelp-tools and autotools are not available, autogen.sh will configure JHBuild to install via a plain Makefile. To always use the plain Makefile method pass --simple-install to autogen.sh.

Si les étapes ci-dessus se sont déroulées avec succès, un petit script shell sera installé dans ~/.local/bin pour lancer JHBuild. Ajoutez ce chemin dans votre variable PATH :

$ PATH=$PATH:~/.local/bin
$

Pour ajouter ~/.local/bin de façon permanente à la variable PATH, exécutez la commande suivante :

$ echo 'PATH=$PATH:~/.local/bin' >> ~/.bashrc
$

II.II. Configuration de JHBuild

JHBuild can be configured via a configuration file. The default location is ~/.config/jhbuildrc. If a configuration file does not exist, the defaults are used. The configuration file uses Python syntax. An example is provided, see examples/sample.jhbuildrc. Copy examples/sample.jhbuildrc to ~/.config/jhbuildrc and customize as required.

The sample configuration will make JHBuild build the meta-gnome-core and meta-gnome-apps-tested modules and dependencies from the gnome-apps module set. JHBuild will unpack source trees to ~/jhbuild/checkout/ and install all files to subdirectories of ~/jhbuild/install/. The two directories must be writable.

Les variables de configuration sont documentées dans Section V ― Référence du fichier de configuration. En voici quelques-unes parmi les plus utilisées :

repos

Un dictionnaire pouvant être utilisé pour indiquer un emplacement de dépôt alternatif pour un dépôt spécifique. Cette variable de configuration est utile pour les développeurs de modules. Par défaut, JHBuild extrait le code dans les dépôts par un accès anonyme. Les clés du dictionnaire sont des noms de dépôts courts et les valeurs sont des chaînes d'accès à des emplacements de dépôts alternatifs. Par exemple :

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

Une chaîne ou une liste de chaînes indiquant le ou les noms des jeux de modules à utiliser. Cela peut être le nom de fichier d'un jeu de modules inclus dans JHBuild (sans chemin ni extension) ou un URL HTTP complet d'un jeu de modules géré en externe. Les jeux de modules ayant un URL HTTP sont placés dans un cache local. Si le nom d'un module figure dans plus d'un jeu de modules, le dernier jeu de modules dans la liste est prioritaire. Les jeux de modules fournis avec JHBuild sont mis à jour au gré de la progression du développement de GNOME.

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'].

checkoutroot

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

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/'.

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.

cmakeargs

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

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

mesonargs

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

ninjaargs

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

II.III. Prérequis pour la construction

Before any modules can be built, it is necessary to have certain build tools installed. Common build tools include the GNU Autotools (autoconf, automake, libtool and gettext), The GNU Toolchain (binutils, gcc, g++), make, pkg-config and Python, depending on which modules will be built.

JHBuild peut vérifier si ces outils sont installés sur votre système à l'aide de la commande sanitycheck :

$ jhbuild sanitycheck

If this command displays any messages, please install the required package from your distribution's repository. A list of package names for different distributions is maintained on the GNOME wiki. Run the sanitycheck command again after installing the distribution's packages to ensure the required tools are present.

II.IV. Utilisation de JHBuild

After set up is complete, JHBuild can be used to build software. To build all the modules selected in the ~/.config/jhbuildrc file, run the following command:

$ jhbuild build

JHBuild va télécharger, configurer, compiler et installer chaque module. Si une erreur se produit à n'importe quelle étape, JHBuild présente un menu pour savoir ce qu'il doit faire. Les choix possibles comprennent le passage dans un shell pour corriger l'erreur, une nouvelle passe de construction à différentes étapes, l'abandon de la construction du module ou la non prise en compte de l'erreur en continuant le processus.

L'abandon d'un module provoque l'échec de construction de tout module dépendant de ce module.

Voici un exemple de menu qui est affiché :

  [1] Rerun phase build
  [2] Ignore error and continue to install
  [3] Give up on module
  [4] Start shell
  [5] Reload configuration
  [6] Go to phase "wipe directory and start over"
  [7] Go to phase "configure"
  [8] Go to phase "clean"
  [9] Go to phase "distclean"
choice: 

Il est aussi possible de construire un jeu différent de modules (et leurs dépendances) en passant les noms des modules en paramètre de la commande build. Par exemple, pour construire gtk+ :

$ jhbuild build gtk+

Si JHBuild est interrompu en cours de construction d'un module, quelle qu'en soit la raison, il est possible de reprendre la construction à partir d'un module précis en utilisant l'option --start-at :

$ jhbuild build --start-at=pango

Pour construire un ou plusieurs modules en ignorant leurs dépendances, JHBuild fournit la commande buildone. Pour que cette commande se déroule correctement, toutes les dépendances du module indiqué doivent être préalablement construites et installées, ou fournies par des paquets de votre distribution.

$ jhbuild buildone gtk+

When actively developing a module, you are likely in a source working directory. The make will invoke the build system and install the module. This will be a key part of your edit-compile-install-test cycle.

$ jhbuild make

Pour obtenir une liste ordonnancée des modules et des dépendances que JHBuild va construire, utilisez la commande list :

$ jhbuild list

Pour obtenir des informations sur un module particulier, utilisez la commande info :

$ jhbuild info gtk+

Pour télécharger ou mettre à jour toutes les sources de logiciels sans rien compiler, utilisez la commande update. Cette commande donne l'occasion de modifier les sources avant la compilation et peut se révéler utile quand la disponibilité de bande passante Internet est instable.

$ jhbuild update

Plus tard, JHBuild peut tout construire sans télécharger ni mettre à jour les sources :

$ jhbuild build --no-network

Pour lancer une commande précise dans le même environnement utilisé par JHBuild, utilisez la commande run :

$ jhbuild run program

Pour lancer un shell avec l'environnement utilisé par JHBuild, utilisez la commande shell :

$ jhbuild shell