These guidelines describe how your distribution should look when someone downloads, retrieves and unpacks it.
The single most annoying mistake fledgling contributors make is to build tarballs that unpack the files and directories in the distribution into the current directory, potentially overwriting 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. Conventionally, the name of the directory should be the same as the stem of the tarball's name. So, for example, a tarball named foo-0.23.tar.gz is expected to unpack into a subdirectory named foo-0.23.
Example19.1 shows a makefile trick that, assuming your distribution directory is named “foobar” and SRC contains a list of your distribution files, accomplishes this.
Example19.1.tar archive maker production.
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))
Include a file called README that is a roadmap of your source distribution. By ancient convention (originating with Dennis Ritchie himself before 1980, and promulgated on Usenet in the early 1980s), this is the first file intrepid explorers will read after unpacking the source.
README files should be short and easy to read. Make yours an introduction, not an epic. Good things to have in the README include the following:
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).
Project mailing list addresses.
At one time this file was commonly READ.ME, but this interacts badly with browsers, who are all too likely to assume that the .ME suffix means it's not textual and can only be downloaded rather than browsed. This usage is deprecated.
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 where to look 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 contributors (GNU convention).
Recent project news.
Project history.
Log of significant changes between revisions.
Project license terms (GNU convention).
Project license terms.
Plain-text Frequently-Asked-Questions document for the project.
Note the overall convention that filenames with all-caps names are human-readable metainformation about the package, rather than build components. This elaboration of the README was developed early on at the Free Software Foundation.
Having a FAQ file 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 (another practice that seems to have been made routine by the FSF). 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, multiple versions can coexist. 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. This good practice avoids the notorious “DLL Hell” failure mode of Windows.
The de facto standard format for installable binary packages under Linux 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 project 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.
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.
