The release tools really do not care a lot about how you decide to structure your packages internally. All they pay attention to is that there have to be couple of files in the package's root directory, and that all the nested packages are simple subdirectories below the containing package. Otherwise the developers are free to do what they want.
It is, however, useful to have conventions that make packages easier to maintain and understand. This section describes a set of conventions that has been found to be easy to work with in a very large number of software projects. If you have doubts about the usefulness of this model or have problems with it, feel free to present questions to the authors.
A good rule of thumb is that the package root directory should not contain too many files. If the number of the files in the package is not negligible, push them into subdirectories. Documentation, manual pages and data files should all be kept in subdirectories. By keeping the root directory clean you will help others to navigate in your package. If you name the subdirectories well, it will be easier for others to locate what they are looking for.
Having said that, there are some files that should be present in the package root directory: installation instructions, news tracking the latest changes, and so forth. Each software project should decide which of these it requires and which are merely complimentary. Consult your project's documentation for more details.
In general it is a good idea to make all special files stand out somehow. A particularly nice convention is to have all the important files to show up near the beginning of a directory listing. On unix systems the easiest way to achieve this is to uppercase the names of the important files. If several other files in the package start with a capital letter, one can resort to prefixing the important file names with the number 0 to force them to the front of the collating order.
The package root directory for package P should contain the following subdirectories.
Directory for interface include files--the header files that other packages will need. Private header files should not go into this directory. The config.h.in file should be in this directory if the package needs one.
The need for this directory is one of the few hard requirements that the release tools make on package organisation. Since symbolic links are not used, header files cannot be renamed or reorganised by the tools. Hence, somewhere there must be a directory with the package's name and header files must be directly below it.
Directory for all the source files. If the package consists of several independent parts, one should use a separate subdirectory for each of them (or split the package into several packages). Header files private to the implementation should be in this directory.
Directory for configuration files such as scripts needed by the package's configure.in script and configuration-dependent fragment and header files. For example, the file config/hpux.h might be copied to P/os.h during configuration on a HP-UX operating system. If there are several per-target configuration files, it will probably be a good idea to create a subdirectory for each target. It usually is not a good idea to deal with every possible canonical system name, but to drop the insignificant parts.
Directory for documentation other than unix manual pages. Documentation should be available at least as a web (or in a format from which a web can be produced in a makefile). The web should include the file index.html such that when the package will be installed, its documentation can be put into a subdirectory of its own automatically.
UNIX manual pages for the package.
In addition to these directories, the files listed below should be in the package's top level directory. The files are ordered in the order of importance. Some of them may also need to exist in some of the package's subdirectories. For instance, if there are several independent source directories, each of them would probably have its own change log and to-do list.
A declaration of the properties of this package. This file is further explained below.
Every package must have a makefile and since the release tools depend on using GNU make, the file should be called GNUmakefile. Other make programs will then fail immediately by the virtue of not finding a makefile at all. A package that has a configure script is also responsible for creating the makefile, and in such case the real makefile is usually called GNUmakefile.in.
GNU autoconf-generated script that will automatically adapt the package to the build environment. While not strictly required to exist in every package, it is a good idea to have at least a minimal configure script as described below.
A short package description that also points to other important files in the package.
Information about the package versions and recent changes. This file should document the major changes made to the package compared to previous versions. Recent changes should be listed before less recent ones. The file should maintain the full record back to the very first version, so that users can scroll to see what has changed and when. If the file becomes unwieldly large, older parts can be split into several files named NEWS.0, NEWS.1..., where NEWS.0 is the oldest one.
Detailed change history. Users of emacs can easily update this file by typing C-x 4 a (or with the M-x add-change-log-entry command). Ideally the contents of this file will be detailed enough that CVS commit comments can be as simple as ``See ChangeLog.''
To give you a feeling of what this file is all about, here is an extract from the GNU C/C++ compiler's ChangeLog:
Sun Nov 26 14:41:49 1995 Douglas Rupp (drupp@cs.washington.edu)
* Makefile.in (stamp-objlist): Change .o to $objext.
* alpha/win-nt.h (CPP_PREDEFINES): Set __unaligned and __stdcall
to null.
(ASM_SPEC): Add a translation for -g to -Zi.
* winnt/ld.c (main): Don't pass -g to link.
* winnt/oldnames.c: Reformat and add some new functions for gnat1.
* winnt/win-nt.h (LINK_SPEC): Pass -g to ld.exe.
Increase default stack size.
* configure ({alpha-dec,i386-ibm}-winnt3.5): Add oldnames.o
to extra_objs.
* libgcc2.c (trampoline): Add getpagesize and mprotect for WINNT. |
Legal rights declaration. Somebody will own the intellectual properties of the package, regarless of whether or not the information is written down somewhere. You should record it here so that no ambiguities can arise.
Directions for installing the package. Special options accepted by configure should be mentioned here.
A record of where the package was acquired if it did not originate from this software project. The information should include at least a URL, maintainer's mail address or vendor's name and contact information. See also AUTHORS.
A record of the package authors if the information is more verbose than what can be stored in the PACKAGE file. This file is only needed if the package originates from the software project. The information should include at least each author's name and contact information (e.g. e-mail or snail mail address, or a relatively stable web home page). See also ORIGIN.
List of possible future features and extensions. The file should list bug fixes only when they also incorporate changes to features.
List of known bugs. Your problem reporting system may render this file unnecessary.