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. SRC may also contain names of subdirectories to be included whole.
foobar-$(VERS).tar.gz: @find $(SRC) -type f | 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.
the roadmap file, to be read first
configuration, build, and installation instructions
list of project contributers.
An older, still-acceptable convention for this is to name it CREDITS
recent project news
project history
project license terms (GNU convention)
project license terms
list of files in the distribution
plain-text Frequently-Asked-Questions document for the project
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.
Provide checksums with your binaries (tarballs, RPMs, etc.). This will allow people to verify that they haven't been corrupted or had Trojan-horse code inserted in them.
While there are several commands you can use for this purpose (such as sum and cksum) it is best to use a cryptographically-secure hash function. The GPG package provides this capability via the —detach-sign option; so does the GNU command md5sum.
For each binary you ship, your project web page should list the checksum and the command you used to generate it.