X-JHBuild
X-JHBuild is a framework for building and working with X.org modules. It makes use of JHBuild and is specialized for working with modules that use Git as VCS.
http://sourceforge.net/projects/x-jhbuild/
Contents
Requirements
The sqlite3 command line tool is required for parts of the shell customization.
A Python version 2.6 <= x < 3 is required.
Installing X-JHBuild
If you have been using a X-JHBuild version prior to 0.1.5, please note that you need to convert your installation and repo-groups as described in the release mail for X-JHBuild-0.1.5 .
To install X-JHBuild as well as private versions of JHBuild and Git-Python execute the following commands:
git clone git://x-jhbuild.git.sourceforge.net/gitroot/x-jhbuild/x-jhbuild cd x-jhbuild make install
The last command creates the directory ~/.x-jhbuild where it is possible to customize global aspects of X-JHBuild. The .internal subdirectory is a temporary installation location. Files in there will be overwritten and possibly wiped out when updating X-JHBuild. The main script must be available through PATH under the name xjh. It is located at:
~/.local/bin/xjh
There are useful shell helpers in:
~/.local/share/x-jhbuild/shell-utility-functions.sh
They allow to extend the git-sign in the prompt and facilitate navigation within a repository group.
Building
If all you want is to quickly build all bleeding edge X.org modules, just navigate to a (possibly new) directory where you want to have all the sources and execute:
xjh init xjh build
By default, the result will be located in the INSTALL sub-directory.
If you want to build the xorg-server and all drivers, while following the progress in a nice HTML log, execute the following:
xjh tinderwrap start xorg-drivers
Help
Get main help and a list of all X-JHBuild subcommands:
xjh -h
Get a list of all JHBuild subcommands (this only works in an initialized repository group):
xjh help
All subcommands support the -h/--help options:
xjh <subcommand> -h
The JHBuild Manual applies to the JHBuild subcommands (xjh help), the configuration in the buildconfig section and modulesets.
Shell Customization
To display repository group related information in the prompt and facilitate inter-module navigation there are utility functions available in ~/.local/share/x-jhbuild/shell-utility-functions.sh.
There are two functions that you can re-implement to customize the appearance of the prompt: __xjh_prompt_prepare and __xjh_sign_color. Both example functions are documented and fully functional. To try them out, use statements like the following in your shell startup file.
# The bash completion for Git, does also contain the __git_ps1 function which
# is already supported in__xjh_prompt_prepare. The location of that file is
# distribution specific.
source /usr/share/bash-completion/git
# Source x-jhbuild shell helpers
source ~/.local/share/x-jhbuild/shell-utility-functions.sh
# In Bash, use PROMPT_COMMAND to prepare the environment that is then accessible in PS1.
PROMPT_COMMAND=__xjh_prompt_prepare
# An example prompt could look like this:
PS1='\[\033[32;49m\]\u@\h \[\033[36;49m\]${XJH_PROMPT_PATH}\[\033[00m\]\[$(__xjh_sign_color)\]${XJH_PROMPT_SIGN}\[\033[32;49m\] \$\[\033[00m\] 'The navigation function makes it easy to jump to a module inside of a repository group, and is able to clone a destination repository if it does not exist. To create the alias cdx for that navigation function and activate bash command line completion for it, add the following:
alias cdx=__xjh_repogroup_internal_cd complete -F __xjh_bash_completion_for_repogroup_internal_cd cdx
Jots
Configuration
The settings in the global configuration file ~/.x-jhbuild/xjhrc will be subsequently overridden by the ones in a repository group at .xjh/xjhrc and optionally the selected config token in .xjh/xjhrc.token/. These files use an ini style format that is described in the example file at ~/.x-jhbuild/xjhrc.example. The plug-in config can be used to display available configurations and documentation for each option. All JHBuild configuration options are located in or below the buildconfig section.
Plug-ins
You can put your own plug-ins into the directory ~/.x-jhbuild/plugins. Plug-ins are executables that can obtain diverse information from the environment. Useful environment variables can be inspected by executing the plug-in show-env. Plug-ins can store persistent data in the directory $XJHBUILD_PLUGIN_DATA_PATH. Files or directories created there, should have a prefix that corresponds to the plug-in name. For shell plug-ins that use the new installation (e.g. start the server), the plug-in show-env displays examples how to easily apply the necessary modifications to $PATH and $LD_LIBRARY_PATH.
Modulesets
You can put your own modulesets into the directory ~/.x-jhbuild/modulesets. It is possible to include other modulesets at the same location where the specified moduleset can be found by simply adding include tags with relative href attributes, like:
<include href="xjh.modules"/>
There are two main ways of specifying moduleset locations. The moduleset-repo access needs to be configured in the configuration section core.moduleset-repo.
1. Convenient, token based. Without .modules suffix. Without any path separator:
xjh : in the global configuration directory at ~/.x-jhbuild/modulesets
o:xjh : moduleset repo accessed through http.
r:xjh : moduleset repo accessed locally. (cloned if necessary)
2. Arbitrary locations. With .modules suffix. With at least one path separator
/tmp/my.modules : absolute paths.
http://where.ever.com/more.modules : a http-URL
r:people/xyz/audit.modules : repo relative paths.
It is also possible to define moduleset location aliases in the configuration.
Moduleset Stack
The moduleset stack records all modulesets that are currently active. It can be inspected and modified with the plug-in ms-man.
With this stack it is possible to extend a moduleset provided by a project with your own modules and forks. There is a documented example moduleset installed to ~/.x-jhbuild/modulesets/example-extension.modules that can be used as a template for writing such modulesets.
CWD-Module Adaption and Activation
It is possible to automatically append the name of the module that belongs to the current working directory to the command line. This makes it easy to work with the current module. It is also possible to activate an inactive CWD-Module for one call. See xjh -h for more.
Forks
It is possible to use a clone in place of the corresponding main module by means of a simple configuration option. For example, to use the xorg-server of mrx in place of the main module, add this configuration snippet:
[module.xorg-server] fork = mrx/xorg-server
From now on, with the few exceptions mentioned below, wherever you see or use the module-id xorg-server it will refer to mrx/xorg-server. There is always only one repository of a kind (xorg-server in this example) in the set of active modules.
Only a few parts of X-JHBuild are aware of forks and can deal with or display real module-ids (mrx/xorg-server in this example). Those parts are the navigation function, the plug-in status when used with the option --forks, and the plug-in fork-man.
Fork Definitions
Forks are defined in modulesets.
A fork can comprise a whole new module definition when wrapped into a <fork-module> element.
<fork-module name="forkname">
<autotools id="main-module-id" ... >
...
</autotools>
</fork-module>To only replace the branch in a copy of the main module, it is possible to wrap a branch definition into a <fork-branch> element.
<fork-branch name="forkname" id="main-module-id"> <branch ... /> </fork-module>
In both cases the id attribute specifies the main module of which it is a fork.
For fork-names, there is the policy to use an identification and a slash as prefix to the main module id for which it is a fork, like in mrx/xorg-server.
Writing Plug-ins in Python
Plug-ins that use Python will have access to all the tools provided in the xjhbuild library, as well as to Git-Python and JHBuild.
Git-Python Access
You can directly use Git-Python or use the xjhbuild.gitaccess library module, which tries to make information about a Git repository available more easily. It is possible to execute any Git command with python syntax and obtain the output of it, by means of the class git.cmd.Git. See the Git-Python documentation section Using Git Directly.
JHBuild Access
Information about all the modules can be obtained through the library module xjhbuild.modaccess. The plug-in modinfo is basically just a frontend to modaccess. So, if you need some of the information that modinfo provides in your own plug-in, take a look at modaccess. If you want something completely different from JHBuild you can import the jhbuild library module with all necessary modifications by executing
from xjhbuild.jhbuild4xjh import *
Configuration
Using the configuration mechanism is as easy as describing a configuration section and collecting the settings when needed. There are currently two sorts of configuration sections:
The multi-type version contains a collection of known options with distinct type, default value, and description.
configsection_status = xjhconfig.ConfigSectionMultiType(
section_name=__file__,
options=(
("color-config", "cyan, green, red, gray", "help message"),
("log-width", 80, "more help"),
)
)
The same-type version contains an arbitrary number of options that all have the same type.
configsection_command_alias = xjhconfig.ConfigSectionSameType(
section_name=[__file__, 'subsection-one', 'subsection-two'],
option_type=list,
section_desc="help for this section."
)Both section types support the same interface. It is documented in the library module configsection. However, configsection is supposed to be from-included into another library module that applies project specific adaption, and should be imported nowhere else. The intention is that there is a Singleton/Borg class that makes the project wide configuration available. For X-JHBuild this is the library module xjhconfig.
It is possible to obtain single options, a dictionary of all options, or an option messenger object similar to what OptionParser produces. Defined at the global plug-in scope, these sections can be displayed with the plug-in config.
Supported value types are bool, string, integer, float, and sequences. The format is explained in ~/.x-jhbuild/xjhrc.example. It is also possible to have an arbitrary number of subsections, where the structure of such subsections is defined by an instance of one of the two classes described above. See configsection.DynamicSubsections for more.
There is a naming policy for plug-in sections, to easily relate a configuration section to a plug-in, and to prevent ambiguities: The top-level section of a plug-in should have the same name as the plug-in. It is possible to specify __file__ to accomplish that. Because the subsection separator is a dot, it is no longer possible to have a dot in a plug-in name. If you follow this policy config can automatically display those sections.
Other tools
There are a lot of tools in the xjhbuild library. Some examples:
Get the name of the CWD-Module:
xjhbuild.cwdmodule.get_cwd_module()
To obtain the root directory of the current repository group, or the path to sub-locations within the xjh-directory:
xjhbuild.repogroup.get_repogroup_root()
xjhbuild.repogroup.get_xjh_path('plugindata')A simple tool to color, indent, and truncate terminal output is:
xjhbuild.termout.FormattedTerminalOutput
There are diverse small tools in the library module utils:
xjhbuild.utils
Error Generation
If anything from xjhbuild is imported (if xjhbuild.__inti__.py is executed), the current sys.excepthook will be wrapped by another excepthook that will display only the string representation without the traceback for exceptions that have a name that ends in CommonError. The exit code will be 1. To always use the previous excepthook, set the environment variable $XJHBUILD_SHOW_TRACEBACK to a non-empty value.
Announce Mails
Ancient Mails
Up to version 0.1.5 all releases were announced in one thread on xorg-devel. The information in there is largely obsolete.