X-JHBuild: A thin JHBuild wrapper with plug-ins.

[Dirk Wallenstein]

I wasn't aware of the benefits of JHBuild for a long time. Therefore, to
also address people like the former-me:

Why would you want to use JHBuild and X-JHBuild?
------------------------------------------------
JHBuild offers general and per-module settings for configure switches and
make command-lines. It has [reverse-]dependency trees. It notifies on
build failures. Shows meta info of a module. And more.
The only thing that was missing, in my opinion, was facilitated access
to these features in an Xorg context, and the possibility to extent it
with own scripts. That's the point of X-JHBuild, a thin wrapper around
JHBuild. It's attached to this mail.

The complete jhbuild commandline interface, almost:
---------------------------------------------------
X-JHBuild supports the complete jhbuild command-line interface, with a
little restriction on what you can pass to the -f/--file and
-m/--moduleset options. You can only specify files without extension
below ~/.x-jhbuild/{config,modulesets}/. You'll get useful error
messages and improved syntax checks in exchange.

A very concise tutorial:
------------------------
This is just meant to get X-JHBuild up and running, and demonstrate a
few simple commands with it.

First, you have to install jhbuild. What follows are a few lines from
the wiki page at [1]:
        $> git clone git://git.gnome.org/jhbuild
        $> cd jhbuild
        $> ./autogen.sh
        $> make
        $> make install
    (On FreeBSD, do gmake && gmake install  .)
    The jhbuild executable is installed to ~/.local/bin/jhbuild. You will
    need to either symlink to it, [...] or add it to your $PATH.

Now, unpack the attached archive and place the resulting '.x-jhbuild'
directory in your home directory.
Then, make the script ~/.x-jhbuild/bin/x-jhbuild available in $PATH.
    $> tar xvjf <the-attachment> -C ~
    $> export PATH="${PATH}:~/.x-jhbuild/bin"

The default configuration uses the locations '~/xorg-source' and
'~/xorg-install' for the sources and the resulting installation,
respectively. You can change that by editing the two variables in the
'Main Configuration' section in '~/.x-jhbuild/config/default.xjh'.
There's more documentation in that file and diverse examples how to
apply more advanced configuration.
    $> ${EDITOR} ~/.x-jhbuild/config/default.xjh

As an example with a few dependencies, let's build libXau.
See what libXau depends on:
    $> x-jhbuild list libXau

Now, get the sources, build and install the deps and libXau:
    $> x-jhbuild build libXau

Later you realize libXau has been updated upstream. This command will
update the sources:
    $> x-jhbuild update libXau

Only libXau has been changed, so just build that:
    $> x-jhbuild buildone libXau

If you want to build all of Xorg:
    $> x-jhbuild build xorg

JHBuild Cheat Sheet
-------------------
A very much censored cheat sheet, to direct your focus to the most
important functionality. You can get an overview of all commands and
options with:
        $> jhbuild --help
        $> jhbuild <command> --help
There's a manual at [2].

For all commands, if you don't specify modules, the setting from the
config file will be used. That is 'xorg' in the default config file and
will pull in almost everything. Try 'x-jhbuild list -a' to see what
module ids are available

All jhbuild commands are available through x-jhbuild.

jhbuild build [options] [modules...] # build modules and all deps
      [-c|--clean] # make clean prior to build
      [-a|--autogen] # restart autogen prior to build
      [-s|--skip=module,module,...] # don't build the listed modules
      [-t|--start-at=module] # useful to restart a failed build
      [-n|--no-network] # don't update prior to build
                        # (there's a permanent config file setting, too)
jhbuild buildone [-can] module... # build named modules only
      [-can] # like 'build'
jhbuild update [module...] # update named modules and deps
jhbuild updateone module... # update named modules only
jhbuild clean [module...] # clean module and deps
jhbuild cleanone [module...] # clean named modules only
jhbuild uninstall module... # uninstall named modules only

jhbuild info module... # You must have seen this.
jhbuild list [module...] # Print named modules and their deps.
jhbuild rdepends [options] [module] # show reverse deps.
                                    # Modules that rely on the named module.
        [--dependencies] # show intermediate modules. Dependency paths.
        [--direct] # show only direct deps

Layout
------
The attached archive contains the following tree structure that has to
be unpacked and placed in you home directory.
~/.x-jhbuild
      |-- bin
      |   `-- x-jhbuild
      |-- config
      |   |-- default.xjh
      |   `-- tracking.xjh
      |-- modulesets
      |   |-- tracking.modules
      |   `-- xorg.modules
      `-- plugins
          |-- addthis
          |-- revdep-rebuild
          `-- testme

The main script is ~/.x-jhbuild/bin/x-jhbuild.

The config directory contains configuration files, that you can select
on the command-line without the '.xjh' extension. In order to avoid a
processing section in config files, the jhbuild limitations will be
enforced by x-jhbuild -- no tilde preamble and only absolute paths.

The modulesets directory contains modules files, that you can select on
the commandline and in the configuration file without the '.modules'
suffix (The suffix is a jhbuild requirement).

In the plugins directory are scripts that you can invoke like
jhbuild-commands ('testme' just prints envvars). Example:
    $> x-jhbuild testme
    $> x-jhbuild -f tracking -m xorg testme testarg1 testarg2
Plug-ins get the context from special environment variables. Currently
they know about:
    - installation prefix
    - checkoutroot (location of the sources)
    - configuration file path
    - modules file path
    - how to callback x-jhbuild
    - general environment modifications in the config file
The distributed plug-ins are only very simple examples.

addthis
-------
The example plugin 'addthis' adds the directory basename of the current
repo to the end of the commandline. Therefore this call:
    [libXau] $> x-jhbuild addthis buildone -n
would expand to this:
    [libXau] $> x-jhbuild buildone -n libXau
This works for most of the repos, as the common case is that the
module-id correspond to the repo root basedir. I personally find this
very useful and would like to implement that as an x-jhbuild
command-line switch. In case this is wanted by more people it could be
enabled for every repo root by introducing a special file that holds
deviating jhbuild module-ids. Or a git-config setting?
Deviations I've found while skimming: libGl, font-utils, font-alias,
xcb-util, xcb-proto.
Now, that I think about it, the cwd module could be the default when
there's no module specified on the command-line, and the setting from
the config file could be selected with a switch...

Please tell me what you think
-----------------------------
Though this generally works, this is still a proposal/example. Ask, nag,
improve, ...

Greetings,
Dirk

[1] http://www.x.org/wiki/JhBuildInstructions
[2] http://library.gnome.org/devel/jhbuild/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: x-jhbuild-0.1.tar.bz2
Type: application/x-bzip2
Size: 22582 bytes
Desc: not available
URL: <http://lists.x.org/archives/xorg-devel/attachments/20100506/1d9cc9f8/attachment-0001.bin>