examplePkg: Detailed Recommendations $Name: $

SoftRelTools and the various other release procedures are extremely flexable in their requirements as to what constitutes a release "package". To make it easier for the casual user to find code and documentation we've put together a recommended organization along with templates for all of the recommended elements. This package is it. Remember, this is only recommended and there is a lot of latitude for the individual developer to modify this according to his/her individual requirements, likes and dislikes.

There are two parts to this recommendation:

Directory Structure
Web based Package Documentation

Directory Structure

There are many directory structures possible within the SoftRelTools/cvs code development system. In fact, there are very few that are not possible. The simplest is a single directory where everything is all in that one directory. This is a fine organization for very small packages, we have some such. When the number of files grows to more than 10-20 it becomes difficult to find the files of interest in such an organization however.

This example package treats a slightly more complicated situation, and is recommended for even the smallest packages. Variations, applicable for larger packages are pointed out below. Each package should contain the following directories:

Sample Directory Structure

src/
"pkg-name"/
- "pkg-name"/"pkg-name"Private/
doc/
test
data/
ups/

Description of Sample Structure

src/, a directory containing the source code for your package. For a large package this may need to be several directories.
"pkg-name"/, is a subdirectory with the same name as the package which contains the packages public headers and includes.
- "pkg-name"/"pkg-name"Private/, a subdirectory of the main header directory, name the same as the package with the word "Private" appended to make explicite that it contains headers that are "private" to the package. The reason for making it a subdirectory is that "#include 'pkg-name/pkg-namePrivate/file.h'" will work to find private file file.h.
doc/, a directory containing the package's documentation.
test/, a directory containing test code to test the package. For large packages this directory may need to contain several subdirectories containing code to test the individual pieces of the package. In that case test/ would contain code to test the overall package.
data/, a directory containing any fixed data needed by your package.
ups/, a directory containing the setup and unsetup scripts needed by ups (ie setup) to set and unset any environmental variables or aliases that you need to run any programs built using your package.

Web based Package Documentation

We intend to make use of our Web Servers' directory indexing features to provide automatically updated access to our source code and it's documentation. The entire release directory tree is available as: http://d0gbert.fnal.gov/d0dist We intend to make full use of this.

Therefore, we recommend that all directories except doc/ contain HEADER.html and/or README.html files. HEADER.html is displayed as the header above the direcory list, README.html is displayed as a footer.

doc/ is a special case. In this case the czar may wish more control over what's visable. So s/he can elect to use either the HEADER/README.html mechanism with the directory index, or the server's default file name mechanism. If no file name is specified in a url the server first looks for a file named index.html. If it exists, it is displayed as a normal web page. No directory index is displayed in this case.

NOTE: The index displayed allows for the addition of "descriptions" for each file. The only way I've found to add this description requires access to the server's configuration files. This is a high maintenance method. I'll keep looking for a better, semi-automatic way to do this. Hopefully there is a method that we can use.

In either case, the minimum information that should be provided for each directory is:

the package name and current version (cvs rtag name).
a short description of the directory's (or at the top level the package's) purpose.
the package czar's name
the package czar's mailto: link
where appropriate, a link to the top level documentation:

A typical HEADER.html might be:

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
  <head>
    <title>examplePkg $Name:  $</title>
  </head>
  <body>
    <h3>examplePkg $Name:  $</h3>
    This is an example of a software package for the D0 experiment at Fermilab
    that does absolutely nothing. It's just and example that shows the 
    recommended directory structure of a typical (not all) software packages.
    It also supplies templates of all recommended elements.
    <p>
      This is HEADER.html and becomes the header above the directory listing of
      your package.
    <p>
      See <a href="doc/">examplePkg</a> for details.
    <p>
    <address><a href="mailto:czar-address@fnal.gov">Czar's Name</a></address>
<!-- Created: Wed Dec 10 16:00:00 CST 1997 -->
<!-- hhmts start -->
Last modified: Wed Jan 28 14:00:00 CST 1998
<!-- hhmts end -->
  </body>
</html>

NOTE the use of the string $Name: $ in the example. During a cvs checkout and cvs export, that is a release, the string $Name: $ is converted to $Name: $ automatically. So you don't have to edit all your files for each release.

NOTE: in most of the templates, I've used both HEADER.html and README.html files and have put part of the required information in each.

NOTE: only relative addressing should be used for links within the release tree. In general you won't know the full url for those. To link to another package (pkgB) from the top level of your package, you can use:
eg) <a href="../pkgB">pkgB</a>
This will only work if the reader has gotten there through the releases/ directory path. It won't work through the packages/ path, you need to know the version name of the target package. However, this is not a fatal problem. It is only through a release that it makes sense to refer to another package. All packages can exist in several versions and specific versions of packages are only tied together through a release.

This example package is not yet quite complete. The GNUmakefiles don't actually do anything and may, in fact, be wrong. I intend to write a few simple "Hello World" type programs to illustrate common build procedures and use of arch_spec_xxx.mk files. The setup and unsetup scripts also need some real examples of what you might want to do. Currently these are just dummies.

In addition, I intend to provide a script (similar to newpkg that will export this example package into a working directory and modify it by changing the package name appropriately and probably add the czar's name and mailto links.

I welcome comments, corrections and suggestions:

Alan Jonckheere

Czar's Name

Last modified: Wed Jan 28 14:00:00 CST 1998