<HTML
><HEAD
><TITLE
>Good distribution-making practice</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.63
"><LINK
REL="HOME"
TITLE="Software Release Practice HOWTO"
HREF="index.html"><LINK
REL="PREVIOUS"
TITLE="Good development practice"
HREF="develpractice.html"><LINK
REL="NEXT"
TITLE="Good documentation practice"
HREF="documentation.html"></HEAD
><BODY
CLASS="SECT1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>Software Release Practice HOWTO</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="develpractice.html"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="documentation.html"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="DISTPRACTICE"
>7. Good distribution-making practice</A
></H1
><P
>These guidelines describe how your distribution should look when
someone downloads, retrieves and unpacks it.</P
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="TARBALLS"
>7.1. Make sure tarballs always unpack into a single new directory</A
></H2
><P
>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.
<EM
>Never do this!</EM
></P
><P
>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 <EM
>beneath</EM
> the current one.</P
><P
>Here's a makefile trick that, assuming your distribution directory is
named `foobar' and SRC contains a list of your distribution files,
accomplishes this.</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="PROGRAMLISTING"
>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))</PRE
></FONT
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="README"
>7.2. Have a README</A
></H2
><P
>Have a file called <TT
CLASS="FILENAME"
>README</TT
> or
<TT
CLASS="FILENAME"
>READ.ME</TT
> that is a roadmap of your source
distribution. By ancient convention, this is the first file intrepid
explorers will read after unpacking the source.</P
><P
>Good things to have in the README include:</P
><P
></P
><OL
TYPE="1"
><LI
><P
>A brief description of the project.</P
></LI
><LI
><P
>A pointer to the project website (if it has
one)</P
></LI
><LI
><P
>Notes on the developer's build environment and
potential portability problems.</P
></LI
><LI
><P
>A roadmap describing important files and subdirectories.</P
></LI
><LI
><P
>Either build/installation instructions or a pointer to a file
containing same (usually <TT
CLASS="FILENAME"
>INSTALL</TT
>).</P
></LI
><LI
><P
>Either a maintainers/credits list or a pointer to a
file containing same (usually
<TT
CLASS="FILENAME"
>CREDITS</TT
>).</P
></LI
><LI
><P
>Either recent project news or a pointer to a file
containing same (usually <TT
CLASS="FILENAME"
>NEWS</TT
>).</P
></LI
></OL
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="FILENAMES"
>7.3. Respect and follow standard file naming practices</A
></H2
><P
>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.</P
><P
>Here are some standard top-level file names and what they mean. Not
every distribution needs all of these.</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>README or READ.ME</DT
><DD
><P
>the roadmap file, to be read first</P
></DD
><DT
>INSTALL</DT
><DD
><P
> configuration, build, and installation instructions</P
></DD
><DT
>CREDITS</DT
><DD
><P
> list of project contributers</P
></DD
><DT
>NEWS</DT
><DD
><P
> recent project news</P
></DD
><DT
>HISTORY</DT
><DD
><P
> project history</P
></DD
><DT
>COPYING</DT
><DD
><P
> project license terms (GNU convention)</P
></DD
><DT
>LICENSE</DT
><DD
><P
> project license terms</P
></DD
><DT
>MANIFEST</DT
><DD
><P
> list of files in the distribution</P
></DD
><DT
>FAQ</DT
><DD
><P
> plain-text Frequently-Asked-Questions document for
the project</P
></DD
><DT
>TAGS</DT
><DD
><P
> generated tag file for use by Emacs or vi</P
></DD
></DL
></DIV
><P
>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).</P
><P
>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.</P
><P
>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).</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="UPGRADEABILITY"
>7.4. Design for Upgradability</A
></H2
><P
>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.</P
><P
>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):</P
><TABLE
BORDER="1"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="SCREEN"
>/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</PRE
></FONT
></TD
></TR
></TABLE
><P
>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.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="RPMS"
>7.5. Provide RPMs</A
></H2
><P
>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).</P
><P
>Accordingly, it's a good idea for your project site to provide
installable RPMs as well as source tarballs.</P
><P
>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.</P
><P
>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.</P
><P
>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.</P
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="develpractice.html"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="documentation.html"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Good development practice</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
> </TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Good documentation practice</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
