OSD Source Code Tour
Introduction
Ref: OSD Source Location
Almost all OSD components are built from community released tarballs, with various patches applied on top of this. This has been our preferred method of managing our sources because it ensures that we push as many patches as possible upstream to the community. This gives us the opportunity to be good community players, as well as reducing the burden of maintaining these patches in the future. Using untouched community released tarballs also makes tracking bugs upstream a lot easier, ensuring that we keep a good level of control into the stability of a particular component.
Under the hood
The OSD sources are managed in Subversion in a module called 'spec-files'. This module contains rpm-like build recipes, called spec files and patches.
As is common with many other open source projects managed with Subversion, 'trunk' always contains the latest development code. If you are looking for stable code, that is often already released, it is likely that there is a specific branch for that.
The OSD sources have the following directory structure -
- ChangeLog
- Any non-trivial code change should have a ChangeLog entry, with the appropriate information of what has been changed, removed or added. If you are fixing a specific bug, then it is useful to include the bug number for this. All ChangeLog entries have the following form -
YYYY-MM-DD Joe Bloggs <joe_bloggs@foobar.com>
* zenity.spec, patches/zenity-01-rule-world.diff: Add patch
to make zenity rule the world.
There is a useful script available called 'prepare-ChangeLog.pl' that you can use to automatically generate your ChangeLog entry, based on what files you have modified in Subversion. This script is located in the scripts directory.
- *.spec
- These are the spec files used for the Solaris builds. Solaris packages are built using a combination of "base spec files" (see below) and a Solaris spec file which defines how the packages are put together. This is because a Solaris package usually includes multiple GNOME modules.
- base-specs/*.spec
- The spec files, one per GNOME module, are the building blocks for package generation. See below for more details on the file format.
- closed/*.spec
- The spec files for packages that are not (or not yet) open source are stored in the closed subdirectory. While you are welcome to look at the spec files, the source tarballs for these packages are not publicly available.
- docs
- This directory contains some documentation on how to build and develop OSD for your convenience.
- ext-sources
- Anything that is used as a SOURCE in the spec file that isn't a patch or the base tarball source is placed here. We try to avoid putting source code in this directory if at all possible.
- scripts
- This directory contains a few useful scripts that we use, either during development, or packaging.
- manpages
- All man pages for the various GNOME components are stored here. Before you can build anything, you need to generate manpage tarballs, by typing "make" in this directory. (See po-sun too)
- po-sun
- Localization files for OSD or Solaris specific strings is stored in this directory. Before you can build certain packages, you need to generate "po-sun" tarballs by typing "make" in this directory.
- patches
- All the patches that are used in the spec files are stored here. They are usually labelled [module]-[n]-[description].diff eg. gnome-panel-01-menu-stripe.diff. Globalization patches are generally suffixed with either g11n-potfiles, g11n-ui, g11n-keys and g11n-schemas for clarity.
- include
- Files in this directory are used in most spec files using the %include directive, which is similar to #include in the C programming language.
- prototypes
- Prototype files describe the contents of Solaris SVr4 packages. See man -s4 prototype for details. In the OSD build system, these files are generated automatically, This directory are for your reference -- you can use them to verify that you build includes all files that are expected to be there and only those.
Spec Files
The spec file is the heart of creating RPM packages. RPM packages are a common packaging format in a number of Linux distributions. We have historically used these to build packages for JDS on Linux, and now we continue to use them as part of a 2 step build environment for Solaris.
All the OSD spec files are standardized against RPM 4.0 and should enough to easily build RPM binary and source packages - if they don't, then there is a bug that you may want to tell us about. To read more about the spec file format, you should read Maximum RPM.
Default template
To make our spec files maintainable, we have a default format for all our spec files. This is relatively easy to achieve, since many of the OSD components come from gnome.org, and are already standardized in terms of a build environment. The default templates, for both Linux and Solaris packaging, are detailed in the docs directory of 'spec-files'.