From The Linux Foundation

This is a newbie's guide to building the LSB specification. It will walk you through obtaining the software you need, making a copy of the spec you can edit locally, modifying the spec, testing that the spec builds correctly, and merging your changes up into the official version control branches.

Installing software

The following packages were the only ones I had to install on my Ubuntu Hardy Heron (8.04 LTS) system to get up and running. Depending on which Linux distribution you're running, and which packages you already have installed, you may need to install a slightly different set. Also, the same packages may have different names in different distributions, so you may have to experiment. The Debian/Ubuntu name is given in parentheses below for each package after its human-readable name. If your distribution uses a different name, please append it.

• Bazaar, easy to use distributed version control system (bzr)
• Collection of tools for Bazaar (bzrtools)
• DocBook, standard SGML representation system for technical documents (docbook)
• Modular DocBook DSSSL stylesheets for print and HTML (docbook-dsssl)
• Convert Docbook files to other formats: HTML, RTF, PS, man, PDF (docbook-utils)
• MySQL database server (mysql-server)
• OpenJade implementation of the DSSSL language (openjade)

Thus, under Debian GNU/Linux or a Debian-based distrubution such as Ubuntu, the following command line should download and install most of the software you need to work on the specification, including dependencies:

# apt-get install bzr bzrtools docbook docbook-dsssl docbook-utils mysql-server openjade

Of course, if your distribution isn't based on Debian, you would use its standard installation method, such as yum install for Red Hat or Fedora.

Checking out branches

The LSB project uses a distributed version control system, where you create branches off the official LSB branches, and then do your work in those local branches. You need to make a directory to contain the spec branches, then enter the directory.

$ cd ~
$ mkdir LSB
$ cd LSB

Next, make subdirectories within the main LSB directory for any branches you will be editing. You will need at least the development branches.

$ mkdir devel

Enter the development directory, and then make the local copies of the branches that you will need to build the documentation.

$ cd devel
$ bzr branch http://bzr.linux-foundation.org/lsb/devel/books
$ bzr branch http://bzr.linux-foundation.org/lsb/devel/booksets
$ bzr branch http://bzr.linux-foundation.org/lsb/devel/build_env
$ bzr branch http://bzr.linux-foundation.org/lsb/devel/lsbspec
$ bzr branch http://bzr.linux-foundation.org/lsb/devel/specdb

Important: If you are not working with the development branches, you will need to change the string devel in every line above. If you don't, you will cause problems for everyone else using Bazaar. For example, the string for the LSB 3.2 branches is 32, so you would type something like this:

$ mkdir 32
$ cd 32
$ bzr branch http://bzr.linux-foundation.org/lsb/32/books
...

Creating the database

For some work, you will need a copy of the LSB specification database. It is possible to work against the official database on the Linux Foundation server, but for performance reasons it's preferable to set up a local server. To create the database, first add the following lines to your profile (.bash_profile or the equivalent):

export LSBDB=lsb
export LSBUSER=root
export LSBDBHOST=localhost
export LSBDBPASSWD="yourpassword"

The last can be blank if you don't choose to set a MySQL password. Source the profile or open a new shell after you add these lines.

You must also create the database, so as superuser, type the following:

# mysqladmin create lsb

Then enter the specdb directory, and type the following command (as yourself, but with the environment settings above):

$ make restore

This will populate your local copy of the database. Now you're ready to work on the spec documents.

Writing and editing documents

If you are merely editing an existing document, skip to the Checking in changes section below. However, if you wish to add a new document to LSB, you will probably take something like the following steps. (This assumes that there is already a database entry for the document.)

1. Create the file
2. bzr add file1 file2 file3 ...
3. make
4. make gensrc (generate source)
5. make
6. Test your changes (build the documentation)

Let's go through these steps one at a time. Suppose you are creating a "man page" for the Linux seq command.

Note: What we call man pages are not really meant to be displayed by the man command, but they are similar in scope and subject matter to Linux man pages.

Create the file

Starting in your LSB/devel directory if you are working in the development branches, you would enter the lsbspec directory, which is where most of the spec work is done, then the LSB subdirectory, which contains subdirectories for each of the architectures supported by the LSB, such as AMD4 and PPC32. Of these, select generic, which contains documentation applicable to all architectures. The file for the seq command is called seq.sgml and is located in the subdirectory command, which contains documentation for basic Linux commands. Finally, create the file seq.sgml. All together, type the following commands (for Emacs substitute your favorite text editor).

$ cd lsbspec/LSB/generic/command
$ emacs seq.sgml

The seq.sgml file is a flat text file that contains DocBook SGML markup. DocBook markup is beyond the scope of this document. We'll just assume you have made your changes and saved the file.

Add the file

After you create your file, add it with Bazaar; otherwise, the build process will not notice there is a new file.

$ bzr add seq.sgml

Make

Next, while you are still in the same directory, type the following command:

$ make

If all goes well, make will display a line of text like the following one.

m4 -P -Uindex -Uformat command.m4 >command.sgml

This shows that seq.sgml was incorporated into the file command.sgml, which "rolls up" all of the commands in the command directory into one file.

Generate source

Whenever you add an entirely new file or set of files, always type the following commands.

$ make gensrc
$ make

If the two commands succeed, you will see a series of messages that end without any error.

Test your changes

The lsbspec directory only contains the spec sources. The specifications we publish are built in the following two directories:

• books - individual items of documentation
• booksets - modules that roll up smaller pieces of documentation, such as "man pages"

In this example, we're working on the Desktop specification (actually eight specifications: generic plus seven architecture-specific parts), so change to the proper directory for the seq command and type make, as follows.

$ cd ~/LSB/devel/booksets/LSB-Core-generic
$ make

If you have made a syntax error in the file you were editing, the build process will fail and return a series of messages, ending in something like the following:

make: *** [htmlspec] Error 8

If the build process succeeds, you will see a series of messages that end without any error.

Now you can confirm your changes by opening the appropriate HTML file in the current directory with a web browser. From the command line, for example:

$ firefox LSB-Core-generic.html

When you are satisfied with the changes you've made, check them in, as described in the next section.

Checking in changes

Once you have made the changes you want to the specification, such as creating, updating, or deleting documents, you will probably take something like the following steps:

1. bzr commit file1 file2 file3 ...
2. bzr merge
3. bzr commit (not necessary if the merge didn't do anything)
4. bzr send -o /home/myname/myname.bundle http://bzr.linux-foundation.org/lsb/devel/lsbspec
5. [Upload to PQM. See below.]
6. bzr pull (if the last step was successful)

Let's go through these steps one at a time.

Commit

$ bzr commit file1 file2 file3

Using the bzr commit command followed by the name of every file you changed will create a new revision that contains your changes. If you leave out the list of filenames, bzr will offer to commit all the changes in the branch you're working in, which may or may not be what you want. To see what bzr thinks has changed relative to the last commit, do bzr status.

If you're working on a lot of changes you may want to commit as individual parts start to work, you don't need to save up everything for one big commit. This is mostly a matter of working style.

If the change you're working on is in response to a bugzilla entry, please include the bug number in the commit message.

Merge

$ bzr merge

Prior to pushing your changes up to the official branches, you will want to make sure you have picked up any other changes that may have been pushed up by other developers while you were working disconnected in your own branches. This process is called merging. It's actually the same thing that happens when you push up your changes, but in the other direction (you'll merge your changes into the official branch instead of merging changes from the official branch into your branch). If there are changes in the official branch and you don't merge them, then your merge up to the official branch will simply fail ("these branches have diverged").

The bzr merge command will merge any new revisions in the "parent" branch (the offficial branch) into your working branch. There are a few possible outcomes:

1. no changes to merge
2. changes were merged
3. there were merge issues that bzr could not resolve automatically

In the latter case, you will need to work to resolve those issues. That's beyond the scope of this guide, so we'll skip that possibility for now.

Commit

If you merge after committing your local changes, as above, then you may have a modified working tree. The "send" command discussed in the following section works only on committed changes, so in this case you need to commit the changes brought in by the merge.

Note: This step is not necessary if the merge in the last step didn't do anything.

$ bzr commit

Create a bundle

$ bzr send -o /home/myname/myname.bundle http://bzr.linux-foundation.org/lsb/devel/lsbspec

The bzr send command will create a bundle of changes ready to submit to the central Linux Foundation code base. The -o filename sequence describes where to save the generated bundle file. The URL describes what to construct the bundle against; effectively it means generate a change request against this branch. bzr will remember the URL so normally it only needs to be specified the first time a bundle is generated for a particular branch. If you need to refresh your memory on what it's remembering, do bzr show-paths and look for the submit to branch entry.

Important: Again, if you are not working with the development branches, change the string devel in the URL above appropriately. If you don't, you will cause problems for everyone else using Bazaar. For example, for the LSB 3.2 branches, you would use the following URL: http://bzr.linux-foundation.org/lsb/32/lsbspec

Upload the bundle

After you have created your bundle, upload it to PQM for merging into the official code base, at the same URL you used in the last command (this sounds obvious, but there's a chance your change might actually merge correctly into a different branch if they're pretty similar - and if so the state will be different than you expect, and will also end up causing problems for other Bazaar users). Continuing with our example, you would take the following steps.

1. Open the URL http://bzr.linux-foundation.org/lsb/devel in your web browser.
2. Click on the branch you intend to merge to (lsbspec in this example)
3. Click the merge button at the top of the page.
4. Enter your username and password for linuxfoundation.org.
5. Select the bundle file you created above.
6. Click Submit Query

PQM runs disconnected so you will only hear if there was a problem with the submission from the web form, not whether the merge actually works. PQM wakes up every ten minutes, so within several minutes, you should receive an email message telling you whether your merge succeeded or failed.

If your merge failed, contact licquia@linux-foundation.org to discuss what went wrong and how to fix it. If your merge succeeded, proceed to the next step.

Pull

$ bzr pull

If your merge succeeded, you should now synchronize the changes in central code base back into your own repository with the bzr pull command.

Success

You have now successfully made changes in your own repository and merged them with the central repository. I hope that this document has made learning bzr and distributed version control a little less painful, if not painless.