<h2>JDS Source Code Tour</h2>

<h3>Introduction</h3>

<p>
Almost all JDS 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.
</p>

<h3>Under the hood</h3>

<p>
The JDS sources are managed in CVS in a module called 'spec-files'. The naming,
and much of the build environment, is historic, since JDS was first released on
Linux. Since then, much of the build environment has remained the same, with
some extension for a common build and source environment for JDS on Solaris.
</p>

<p>
As is common with many other open source projects managed with CVS, 'HEAD' 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.
</p>

<p>
The JDS sources have the following directory structure -
</p>

<dl> 
  <dt>
    <b>ChangeLog</b>
  </dt>
  <dd>
    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 -
<pre>
<code>
YYYY-MM-DD  Joe Bloggs &lt;[email protected]&gt;

        * zenity.spec, patches/zenity-01-rule-world.diff: Add patch
        to make zenity rule the world.
</code>
</pre>
    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 CVS. This script is located in the
    <b>scripts</b> directory.
  </dd>

  <dt><b>*.spec</b></dt>
  <dd>
      The spec files, one per GNOME module, are the building blocks for
      package generation. See below for more details on the file format.
  </dd>

   <dt><b>docs</b></dt>
   <dd>
      This directory contains some documentation on how to build and develop
      JDS for your convenience.
   </dd>

   <dt><b>ext-sources</b></dt>
   <dd>
       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.
   </dd>

   <dt><b>scripts</b></dt>
   <dd>
       This directory contains a few useful scripts that we use, either 
       during development, or packaging.
   </dd>

   <dt><b>manpages</b></dt>
   <dd>All man pages for the various GNOME components are stored here</dd>

   <dt><b>patches</b></dt>
   <dd>
       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.
   </dd>

   <dt><b>Solaris</b></dt>
   <dd>
       All the patches, 'spec' files and build scripts are stored here for the 
       Solaris builds. It has a similar directory structure to the top level 
       of 'spec-files'. Solaris packages are built using a combination of the 
       base spec file, and an extension spec file which defines how the packages
       are put together.
   </dd>
</dl>

<h3>Spec Files</h3>

<p>
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.
</p>

<p>
All the JDS 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 
<a href="http://www.rpm.org/max-rpm/index.html">Maximum RPM</a>.
</p>

<h4>Default template</h4>

<p>
To make our spec files maintainable, we have the following default format for all our spec files.
This is relatively easy to achieve, since many of the JDS 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 <b>docs</b> directory of 'spec-files'.
</p>