##language:en = X-JHBuild = X-JHBuild is a framework for building and working with X.org modules. It makes use of [[http://live.gnome.org/Jhbuild|JHBuild]] and is specialized for working with modules that use [[http://git-scm.com/|Git]] as VCS. <
> <
> http://sourceforge.net/projects/x-jhbuild/ <
> <> == 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 [[http://lists.freedesktop.org/archives/xorg-devel/2010-July/011216.html|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 -h }}} The [[http://library.gnome.org/devel/jhbuild/unstable|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: {{{ }}} 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 {{{}}} element. {{{ ... }}} To only replace the branch in a copy of the main module, it is possible to wrap a branch definition into a {{{}}} element. {{{ }}} 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 [[http://packages.python.org/GitPython/|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 Option''''''Parser 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 Common''''''Error. 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 == * [[http://lists.freedesktop.org/archives/xorg-devel/2010-November/015574.html|x-jhbuild-0.2]] * [[http://lists.freedesktop.org/archives/xorg/2010-December/052073.html|x-jhbuild-0.3]] * [[http://lists.freedesktop.org/archives/xorg-devel/2011-May/022456.html|x-jhbuild-0.4]] === 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. <
> * [[http://lists.freedesktop.org/archives/xorg-devel/2010-May/008111.html|Release 0.1]] * [[http://lists.freedesktop.org/archives/xorg-devel/2010-May/008478.html|Release 0.1.1]] * [[http://lists.freedesktop.org/archives/xorg-devel/2010-May/008519.html|Release 0.1.2]] * [[http://lists.freedesktop.org/archives/xorg-devel/2010-May/009097.html|Release 0.1.3]] * [[http://lists.freedesktop.org/archives/xorg-devel/2010-June/009990.html|Release 0.1.4]] * [[http://lists.freedesktop.org/archives/xorg-devel/2010-July/011216.html|Release 0.1.5]]