440 lines
8.5 KiB
HTML
440 lines
8.5 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|
<HTML
|
|
><HEAD
|
|
><TITLE
|
|
>Good distribution-making practice</TITLE
|
|
><META
|
|
NAME="GENERATOR"
|
|
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><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
|
|
SUMMARY="Header navigation 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"
|
|
ACCESSKEY="P"
|
|
>Prev</A
|
|
></TD
|
|
><TD
|
|
WIDTH="80%"
|
|
ALIGN="center"
|
|
VALIGN="bottom"
|
|
></TD
|
|
><TD
|
|
WIDTH="10%"
|
|
ALIGN="right"
|
|
VALIGN="bottom"
|
|
><A
|
|
HREF="documentation.html"
|
|
ACCESSKEY="N"
|
|
>Next</A
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"></DIV
|
|
><DIV
|
|
CLASS="sect1"
|
|
><H1
|
|
CLASS="sect1"
|
|
><A
|
|
NAME="distpractice"
|
|
></A
|
|
>7. Good distribution-making practice</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"
|
|
></A
|
|
>7.1. Make sure tarballs always unpack into a single new directory</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. SRC may also contain names of subdirectories to
|
|
be included whole.</P
|
|
><TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><FONT
|
|
COLOR="#000000"
|
|
><PRE
|
|
CLASS="programlisting"
|
|
> 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))
|
|
</PRE
|
|
></FONT
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
><DIV
|
|
CLASS="sect2"
|
|
><H2
|
|
CLASS="sect2"
|
|
><A
|
|
NAME="readme"
|
|
></A
|
|
>7.2. Have a README</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"
|
|
></A
|
|
>7.3. Respect and follow standard file naming practices</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
|
|
>AUTHORS</DT
|
|
><DD
|
|
><P
|
|
> list of project contributers.</P
|
|
><P
|
|
>An older, still-acceptable convention for this is to name it CREDITS</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"
|
|
></A
|
|
>7.4. Design for Upgradability</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="0"
|
|
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="checksums"
|
|
></A
|
|
>7.5. Provide checksums</H2
|
|
><P
|
|
>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.</P
|
|
><P
|
|
>While there are several commands you can use for this purpose (such
|
|
as <B
|
|
CLASS="command"
|
|
>sum</B
|
|
> and <B
|
|
CLASS="command"
|
|
>cksum</B
|
|
>) it is best to use a
|
|
cryptographically-secure hash function. The GPG package provides this
|
|
capability via the <TT
|
|
CLASS="option"
|
|
>—detach-sign</TT
|
|
> option; so does the GNU
|
|
command <B
|
|
CLASS="command"
|
|
>md5sum</B
|
|
>.</P
|
|
><P
|
|
>For each binary you ship, your project web page should list
|
|
the checksum and the command you used to generate it.</P
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="NAVFOOTER"
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"><TABLE
|
|
SUMMARY="Footer navigation table"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
CELLPADDING="0"
|
|
CELLSPACING="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="left"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="develpractice.html"
|
|
ACCESSKEY="P"
|
|
>Prev</A
|
|
></TD
|
|
><TD
|
|
WIDTH="34%"
|
|
ALIGN="center"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="index.html"
|
|
ACCESSKEY="H"
|
|
>Home</A
|
|
></TD
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="right"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="documentation.html"
|
|
ACCESSKEY="N"
|
|
>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
|
|
> |