Building

Introduction

This page describes the process used to build (, test, package, and release) the DocBook-XSL package. The original process was written while the project was hosted on sf.net, and many details may still reflect that. The goal is to clean the process up and simplify the build infrastructure as much as possible. Once it's stable, we can include these instructions in the source repository itself.

The DocBook XSL stylesheets are presently built and tested using Travis CI, so this documentation should always reflect the worflow encoded in the Travis CI configuration

Prerequisites

Building and testing is done using an Ubuntu 14.04 container, with the following packages:

• xsltproc
• libxml-xpath-perl
• libsaxon-java
• libxml-commons-resolver1.1-java
• libsaxon-java
• libxerces2-java
• trang
• imagemagick
• dblatex

In addition, this file needs to be copied to ~/.xmlc.

Building

From the toplevel directory, simply invoking make will build everything. (Note that invoking make twice shouldn't do anything other than traversing the directory structure.)

Testing

From the toplevel directory, invoking make check will run tests. TODO: Augment and document the test suite.

Packaging

From the toplevel directory, invoking make dist will create a dist directory and put newly generated packages into it. This process will also clone the install tree and remove namespaces to make the stylesheets suitable for use with DocBook 4. The version number being used for documentation as well as package names will be pulled out of VERSION.xsl.

TODO: This needs expanding.

Building snapshots

Right now each commit to the master branch will result in a new travis-ci build, including

• make
• make check
• make dist
• upload the packages to the project's release area
• upload the stylesheets to cdn.docbook.org

During normal operation, the 'version' variable in VERSION.xsl is set to 'snapshot', which means the generated package have names such as 'docbook-xsl-snapshot.tar.gz', and the content uploaded to cdn.docbook.org will be in 'xsl/snapshot' and 'xsl-nons/snapshot'.

• Building releases

---

A release build starts its life like a snapshot build, with two differences:

• the 'version' variable in VERSION.xsl is set to an actual release version number (e.g. '1.79.2').
• the release notes in RELEASE-NOTES.xml should be updated by copying (and editing) relevant bits from NEWS.xml (Note that users typically aren't interested in the details from individual commit messages.)

With those changes done, a successful travis-ci build will result in a new snapshot tag and 'prerelease', so all that remains to do is:

• change the 'prerelease' tag to 'release'
• add a release note
• publish the release wherever needed (the docbook-app mailing list, at least).