These guidelines describe how your distribution should look when
someone downloads, retrieves and unpacks it.
The single most annoying mistake newbie developers make is to build
tarballs that unpack the files and directories in the distribution into
the current directory, potentially stepping on files already located there.
Never do this!
Instead, make sure your archive files all have a common directory part
named after the project, so they will unpack into a single top-level
directory directly beneath the current one.
Here's a makefile trick that, assuming your distribution directory is
named `foobar' and SRC contains a list of your distribution files,
accomplishes this.
foobar-$(VERS).tar.gz:
@ls $(SRC) | sed s:^:foobar-$(VERS)/: >MANIFEST
@(cd ..; ln -s foobar foobar-$(VERS))
(cd ..; tar -czvf foobar/foobar-$(VERS).tar.gz `cat foobar/MANIFEST`)
@(cd ..; rm foobar-$(VERS)) |
Have a file called README or
READ.ME that is a roadmap of your source
distribution. By ancient convention, this is the first file intrepid
explorers will read after unpacking the source.
Good things to have in the README include:
A brief description of the project.
A pointer to the project website (if it has
one)
Notes on the developer's build environment and
potential portability problems.
A roadmap describing important files and subdirectories.
Either build/installation instructions or a pointer to a file
containing same (usually INSTALL).
Either a maintainers/credits list or a pointer to a
file containing same (usually
CREDITS).
Either recent project news or a pointer to a file
containing same (usually NEWS).
Before even looking at the README, your intrepid explorer will
have scanned the filenames in the top-level directory of your unpacked
distribution. Those names can themselves convey information. By
adhering to certain standard naming practices, you can give the
explorer valuable clues about what to look in next.
Here are some standard top-level file names and what they mean. Not
every distribution needs all of these.
- README or READ.ME
the roadmap file, to be read first
- INSTALL
configuration, build, and installation instructions
- CREDITS
list of project contributers
- NEWS
recent project news
- HISTORY
project history
- COPYING
project license terms (GNU convention)
- LICENSE
project license terms
- MANIFEST
list of files in the distribution
- FAQ
plain-text Frequently-Asked-Questions document for
the project
- TAGS
generated tag file for use by Emacs or vi
Note the overall convention that filenames with all-caps names are
human-readable metainformation about the package, rather than build
components (TAGS is an exception to the first, but not to the second).
Having a FAQ can save you a lot of grief. When a question about the
project comes up often, put it in the FAQ; then direct users to read the
FAQ before sending questions or bug reports. A well-nurtured FAQ can
decrease the support burden on the project maintainers by an order of
magnitude or more.
Having a HISTORY or NEWS file with timestamps in it for each release
is valuable. Among other things, it may help establish prior art if
you are ever hit with a patent-infringement lawsuit (this hasn't
happened to anyone yet, but best to be prepared).
Your software will change over time as you put out new releases. Some
of these changes will not be backward-compatible. Accordingly, you
should give serious thought to designing your installation layouts so
that multiple installed versions of your code can coexist on the same
system. This is especially important for libraries -- you can't
count on all your client programs to upgrade in lockstep with your
API changes.
The Emacs, Python, and Qt projects have a good convention for handling
this; version-numbered directories. Here's how an installed Qt
library hierarchy looks (${ver} is the version number):
/usr/lib/qt
/usr/lib/qt-${ver}
/usr/lib/qt-${ver}/bin # Where you find moc
/usr/lib/qt-${ver}/lib # Where you find .so
/usr/lib/qt-${ver}/include # Where you find header files |
With this organization, you can have multiple versions
coexisting. Client programs have to specify the library version they
want, but that's a small price to pay for not having the interfaces
break on them.
The de-facto standard format for installable binary packages is
that used by the Red Hat Package manager, RPM. It's featured in the
most popular Linux distribution, and supported by effectively all
other Linux distributions (except Debian and Slackware; and Debian can
install from RPMs).
Accordingly, it's a good idea for your project site to provide
installable RPMs as well as source tarballs.
It's also a good idea for you to include in your source tarball the RPM
spec file, with a production that makes RPMs from it in your Makefile.
The spec file should have the extension `.spec'; that's how the rpm -t
option finds it in a tarball.
For extra style points, generate your spec file with a shellscript that
automatically plugs in the correct version number by analyzing the Makefile
or a version.h.
Note: if you supply source RPMs, use BuildRoot to make the program be
built in /tmp or /var/tmp. If you don't, during the course of running
the make install part of your build, the install will install the
files in the real final places. This will happen even if there are
file collisions, and even if you didn't want to install the package at
all. When you're done, the files will have been installed and your
system's RPM database will not know about it. Such badly behaved
SRPMs are a minefield and should be eschewed.