Major documentation update.

Installation and packaging instructions were added.
README and other generic docs were revised.

Some of the documentation files are now installed to $docdir.

1 files changed, 278 insertions, 0 deletions

diff --git a/PACKAGERS b/PACKAGERS
new file mode 100644
index 00000000..da5158ce
--- /dev/null
+++ b/PACKAGERS
@@ -0,0 +1,278 @@
+
+Information to packagers of XZ Utils
+====================================
+
+    0. Preface
+    1. Package naming
+    2. Package description
+    3. License
+    4. configure options
+       4.1. Static vs. dynamic linking of liblzma
+       4.2. Optimizing xzdec and lzmadec
+    5. Additional documentation
+    6. Extra files
+    7. Installing XZ Utils and LZMA Utils in parallel
+    8. Example
+
+
+0. Preface
+----------
+
+    This document is meant for people who create and maintain XZ Utils
+    packages for operating system distributions. The focus is on GNU/Linux
+    systems, but most things apply to other systems too.
+
+    While the standard "configure && make DESTDIR=$PKG install" should
+    give a pretty good package, there are some details which packagers
+    may want to tweak.
+
+    Packagers should also read the INSTALL file.
+
+
+1. Package naming
+-----------------
+
+    The preferred name for the XZ Utils package is "xz", because that's
+    the name of the upstream tarball. Naturally you may have good reasons
+    to use some other name; I won't get angry about it. ;-) It's just nice
+    to be able to point people to the correct package name without asking
+    what distro they have.
+
+    If your distro policy is to split things into small pieces, here is
+    one suggestion:
+
+        xz              xz, xzdec, scripts (xzdiff, xzgrep, etc.), docs
+        xz-lzma         lzma, unlzma, lzcat, lzgrep etc. symlinks and
+                        lzmadec binary for compatibility with LZMA Utils
+        liblzma         liblzma.so.*
+        liblzma-devel   liblzma.so, liblzma.a, API headers
+
+
+2. Package description
+----------------------
+
+    Here is a suggestion which you may use as the package description.
+    If you can use only one-line description, pick only the first line.
+    Naturally, feel free to use some other description if you find it
+    better, and maybe send it to me too.
+
+        Library and command line tools for XZ and LZMA compressed files
+
+        XZ Utils provide a general purpose data compression library
+        and command line tools. The native file format is the .xz
+        format, but also the legacy .lzma format is supported. The .xz
+        format supports multiple compression algorithms, of which LZMA2
+        is currently the primary algorithm. With typical files, XZ Utils
+        create about 30 % smaller files than gzip.
+
+    If you are splitting XZ Utils into multiple packages, here are some
+    suggestions for package descriptions:
+
+    xz:
+
+        Command line tools for XZ and LZMA compressed files
+
+        This package includes the xz compression tool and other command
+        line tools from XZ Utils. xz has command line syntax similar to
+        that of gzip. The native file format is the .xz format, but also
+        the legacy .lzma format is supported. The .xz format supports
+        multiple compression algorithms, of which LZMA2 is currently the
+        primary algorithm. With typical files, XZ Utils create about 30 %
+        smaller files than gzip.
+
+        Note that this package doesn't include the files needed for
+        LZMA Utils 4.32.x compatibility. Install also the xz-lzma
+        package to make XZ Utils emulate LZMA Utils 4.32.x.
+
+    xz-lzma:
+
+        LZMA Utils emulation with XZ Utils
+
+        This package includes executables and symlinks to make
+        XZ Utils emulate lzma, unlzma, lzcat, and other command
+        line tools found from the legacy LZMA Utils 4.32.x package.
+
+    liblzma:
+
+        Library for XZ and LZMA compressed files
+
+        liblzma is a general purpose data compression library with
+        an API similar to that of zlib. liblzma supports multiple
+        algorithms, of which LZMA2 is currently the primary algorithm.
+        The native file format is .xz, but also the legacy .lzma
+        format and raw streams (no headers at all) are supported.
+
+        This package includes the shared library.
+
+    liblzma-devel:
+
+        Library for XZ and LZMA compressed files
+
+        This package includes the API headers, static library, and
+        other development files related to liblzma.
+
+
+3. License
+----------
+
+    If the package manager supports a license field, you probably should
+    put GPLv2+ there (GNU GPL v2 or later). The interesting parts of
+    XZ Utils are in the public domain, but some less important files
+    ending up into the binary package are under GPLv2+. So it is simplest
+    to just say GPLv2+ if you cannot specify "public domain and GPLv2+".
+
+    If you split XZ Utils into multiple packages as described earlier
+    in this file, liblzma and liblzma-dev packages will contain only
+    public domain code (from XZ Utils at least; compiler or linker may
+    add some third-party code, which may be copyrighted).
+
+
+4. configure options
+--------------------
+
+    Unless you are building a package for a distribution that is meant
+    only for embedded systems, don't use the following configure options:
+
+        --enable-debug
+        --enable-encoders (*)
+        --enable-decoders
+        --enable-match-finders
+        --enable-checks
+        --enable-small (*)
+        --disable-threads (*)
+
+    (*) These are OK when building xzdec and lzmadec as explained later.
+
+    You may use --enable-werror but be careful with it since it may break
+    the build due to some useless warning when the build environment
+    changes (like CPU architecture or compiler version).
+
+
+4.1. Static vs. dynamic linking of liblzma
+
+    The default is to link the command line tools against static liblzma.
+    This can be changed by passing --enable-dynamic to configure, or by
+    not building static libraries at all by passing --disable-static to
+    configure. It is mildly recommended that you use the default and link
+    the command line tools against static liblzma, but the configure
+    options make it easy to do otherwise if the distro policy so requires.
+
+    On 32-bit x86, linking against static liblzma can give a minor
+    speed improvement. Static libraries on x86 are usually compiled as
+    position-dependent code (non-PIC) and shared libraries are built as
+    position-independent code (PIC). PIC wastes one register, which can
+    make the code slightly slower compared to a non-PIC version. (Note
+    that this doesn't apply to x86-64.)
+
+    Linking against static liblzma avoids a dependency on liblzma shared
+    library, and makes it slightly easier to copy the command line tools
+    between systems (e.g. quick 'n' dirty emergency recovery of some
+    files). It also allows putting the command line tools to /bin while
+    leaving liblzma to /usr/lib (assuming that your distribution uses
+    such a file system hierarchy), if no other file in /bin would require
+    liblzma.
+
+    If you don't want to distribute static libraries but you still
+    want to link the command line tools against static liblzma, it is
+    probably easiest to build both static and shared liblzma, but after
+    "make DESTDIR=$PKG install" remove liblzma.a and modify liblzma.la
+    to not contain a reference to liblzma.a.
+
+
+4.2. Optimizing xzdec and lzmadec
+
+    xzdec and lzmadec are intended to be relatively small instead of
+    optimizing for the best speed. Thus, it is a good idea to build
+    xzdec and lzmadec separately:
+
+      - Only decoder code is needed, so you can speed up the build
+        slightly by passing --disable-encoders to configure. This
+        shouldn't affect the final size of the executables though,
+        because the linker is able to omit the encoder code anyway.
+
+      - xzdec and lzmadec will never use multithreading capabilities of
+        liblzma. You can avoid dependency on libpthread by passing
+        --disable-threads to configure.
+
+      - There are and will be no translated messages for xzdec and
+        lzmadec, so it is fine to pass also --disable-nls to configure.
+
+      - To select somewhat size-optimized variant of some things in
+        liblzma, pass --enable-small to configure.
+
+      - Tell the compiler to optimize for size instead of speed.
+        E.g. with GCC, put -Os into CFLAGS.
+
+
+5. Additional documentation
+---------------------------
+
+    "make install" copies some additional documentation to $docdir
+    (--docdir in configure). These a copy of the GNU GPL v2, which can
+    be replaced with a symlink if your distro ships with shared copies
+    of the common license texts.
+
+
+6. Extra files
+--------------
+
+    The "extra" directory contains some small extra tools or other files.
+    The exact set of extra files can vary between XZ Utils releases. The
+    extra files have only limited use or they are too dangerous to be
+    put directly to $bindir (7z2lzma.sh is a good example, since it can
+    silently create corrupt output if certain conditions are not met).
+
+    If you feel like it, you may copy the extra directory under the doc
+    directory (e.g. /usr/share/doc/xz/extra). Maybe some people will find
+    them useful. However, most people needing these tools probably are
+    able to find them from the source package too.
+
+    The "debug" directory contains some tools that are useful only when
+    hacking on XZ Utils. Don't package these tools.
+
+
+7. Installing XZ Utils and LZMA Utils in parallel
+-------------------------------------------------
+
+    XZ Utils and LZMA Utils 4.32.x can be installed in parallel by
+    omitting the compatibility symlinks (lzma, unlzma, lzcat, lzgrep etc.)
+    from the XZ Utils package. It's probably a good idea to still package
+    the symlinks into a separate package so that users may choose if they
+    want to use XZ Utils or LZMA Utils for handling .lzma files.
+
+
+8. Example
+----------
+
+    Here is an example for i686 GNU/Linux that
+      - links xz against static liblzma;
+      - includes only shared liblzma in the final package;
+      - links xzdec and lzmadec against static liblzma while
+        avoiding libpthread dependency.
+
+    PKG=/tmp/xz-pkg
+    tar xf xz-x.y.z.tar.gz
+    cd xz-x.y.z
+    ./configure \
+            --prefix=/usr \
+            --sysconfdir=/etc \
+            CFLAGS='-march=i686 -O2'
+    make
+    make DESTDIR=$PKG install-strip
+    rm -f $PKG/usr/lib/lib*.a
+    sed -i "s/^old_library=.*$/old_library=''/" $PKG/usr/lib/lib*.la
+    make clean
+    ./configure \
+            --prefix=/usr \
+            --sysconfdir=/etc \
+            --disable-shared \
+            --disable-nls \
+            --disable-encoders \
+            --enable-small \
+            --disable-threads \
+            CFLAGS='-march=i686 -Os'
+    make -C src/liblzma
+    make -C src/xzdec
+    make -C src/xzdec DESTDIR=$PKG install-strip
+    cp -a extra $PKG/usr/share/doc/xz
+