PACKAGERS

   1
   2 Information to packagers of XZ Utils
   3 ====================================
   4
   5     0. Preface
   6     1. Package naming
   7     2. Package description
   8     3. License
   9     4. configure options
  10     5. Additional documentation
  11     6. Extra files
  12     7. Installing XZ Utils and LZMA Utils in parallel
  13     8. Example
  14
  15
  16 0. Preface
  17 ----------
  18
  19     This document is meant for people who create and maintain XZ Utils
  20     packages for operating system distributions. The focus is on GNU/Linux
  21     systems, but most things apply to other systems too.
  22
  23     While the standard "configure && make DESTDIR=$PKG install" should
  24     give a pretty good package, there are some details which packagers
  25     may want to tweak.
  26
  27     Packagers should also read the INSTALL file.
  28
  29
  30 1. Package naming
  31 -----------------
  32
  33     The preferred name for the XZ Utils package is "xz", because that's
  34     the name of the upstream tarball. Naturally you may have good reasons
  35     to use some other name; I won't get angry about it. ;-) It's just nice
  36     to be able to point people to the correct package name without asking
  37     what distro they have.
  38
  39     If your distro policy is to split things into small pieces, here is
  40     one suggestion:
  41
  42         xz              xz, xzdec, scripts (xzdiff, xzgrep, etc.), docs
  43         xz-lzma         lzma, unlzma, lzcat, lzgrep etc. symlinks and
  44                         lzmadec binary for compatibility with LZMA Utils
  45         liblzma         liblzma.so.*
  46         liblzma-devel   liblzma.so, liblzma.a, API headers
  47
  48
  49 2. Package description
  50 ----------------------
  51
  52     Here is a suggestion which you may use as the package description.
  53     If you can use only one-line description, pick only the first line.
  54     Naturally, feel free to use some other description if you find it
  55     better, and maybe send it to me too.
  56
  57         Library and command line tools for XZ and LZMA compressed files
  58
  59         XZ Utils provide a general purpose data compression library
  60         and command line tools. The native file format is the .xz
  61         format, but also the legacy .lzma format is supported. The .xz
  62         format supports multiple compression algorithms, of which LZMA2
  63         is currently the primary algorithm. With typical files, XZ Utils
  64         create about 30 % smaller files than gzip.
  65
  66     If you are splitting XZ Utils into multiple packages, here are some
  67     suggestions for package descriptions:
  68
  69     xz:
  70
  71         Command line tools for XZ and LZMA compressed files
  72
  73         This package includes the xz compression tool and other command
  74         line tools from XZ Utils. xz has command line syntax similar to
  75         that of gzip. The native file format is the .xz format, but also
  76         the legacy .lzma format is supported. The .xz format supports
  77         multiple compression algorithms, of which LZMA2 is currently the
  78         primary algorithm. With typical files, XZ Utils create about 30 %
  79         smaller files than gzip.
  80
  81         Note that this package doesn't include the files needed for
  82         LZMA Utils 4.32.x compatibility. Install also the xz-lzma
  83         package to make XZ Utils emulate LZMA Utils 4.32.x.
  84
  85     xz-lzma:
  86
  87         LZMA Utils emulation with XZ Utils
  88
  89         This package includes executables and symlinks to make
  90         XZ Utils emulate lzma, unlzma, lzcat, and other command
  91         line tools found from the legacy LZMA Utils 4.32.x package.
  92
  93     liblzma:
  94
  95         Library for XZ and LZMA compressed files
  96
  97         liblzma is a general purpose data compression library with
  98         an API similar to that of zlib. liblzma supports multiple
  99         algorithms, of which LZMA2 is currently the primary algorithm.
 100         The native file format is .xz, but also the legacy .lzma
 101         format and raw streams (no headers at all) are supported.
 102
 103         This package includes the shared library.
 104
 105     liblzma-devel:
 106
 107         Library for XZ and LZMA compressed files
 108
 109         This package includes the API headers, static library, and
 110         other development files related to liblzma.
 111
 112
 113 3. License
 114 ----------
 115
 116     If the package manager supports a license field, you probably should
 117     put GPLv2+ there (GNU GPL v2 or later). The interesting parts of
 118     XZ Utils are in the public domain, but some less important files
 119     ending up into the binary package are under GPLv2+. So it is simplest
 120     to just say GPLv2+ if you cannot specify "public domain and GPLv2+".
 121
 122     If you split XZ Utils into multiple packages as described earlier
 123     in this file, liblzma and liblzma-dev packages will contain only
 124     public domain code (from XZ Utils at least; compiler or linker may
 125     add some third-party code, which may be copyrighted).
 126
 127
 128 4. configure options
 129 --------------------
 130
 131     Unless you are building a package for a distribution that is meant
 132     only for embedded systems, don't use the following configure options:
 133
 134         --enable-debug
 135         --enable-encoders (*)
 136         --enable-decoders
 137         --enable-match-finders
 138         --enable-checks
 139         --enable-small (*)
 140         --disable-threads (*)
 141         --disable-microlzma (*)
 142         --disable-lzip-decoder (*)
 143
 144     (*) These are OK when building xzdec and lzmadec as described
 145         in INSTALL.
 146
 147     xzdec and lzmadec don't provide any functionality that isn't already
 148     available in the xz tool. Shipping xzdec and lzmadec without size
 149     optimization and statically-linked liblzma isn't very useful. Doing
 150     that would give users the xzdec man page, which may make it easier
 151     for people to find out that such tools exists, but the executables
 152     wouldn't have any advantage over the full-featured xz.
 153
 154
 155 5. Additional documentation
 156 ---------------------------
 157
 158     "make install" copies some additional documentation to $docdir
 159     (--docdir in configure). There is a copy of the GNU GPL v2, which
 160     can be replaced with a symlink if your distro ships with shared
 161     copies of the common license texts.
 162
 163     liblzma API is currently only documented using Doxygen tags in the
 164     API headers. It hasn't been tested much how good results Doxygen
 165     is able to make from the tags (e.g. Doxyfile might need tweaking,
 166     the tagging may need to be improved etc.), so it might be simpler
 167     to just let people read docs directly from the .h files for now,
 168     and also save quite a bit in package size at the same time.
 169
 170
 171 6. Extra files
 172 --------------
 173
 174     The "extra" directory contains some small extra tools or other files.
 175     The exact set of extra files can vary between XZ Utils releases. The
 176     extra files have only limited use or they are too dangerous to be
 177     put directly to $bindir (7z2lzma.sh is a good example, since it can
 178     silently create corrupt output if certain conditions are not met).
 179
 180     If you feel like it, you may copy the extra directory under the doc
 181     directory (e.g. /usr/share/doc/xz/extra). Maybe some people will find
 182     them useful. However, most people needing these tools probably are
 183     able to find them from the source package too.
 184
 185     The "debug" directory contains some tools that are useful only when
 186     hacking on XZ Utils. Don't package these tools.
 187
 188
 189 7. Installing XZ Utils and LZMA Utils in parallel
 190 -------------------------------------------------
 191
 192     XZ Utils and LZMA Utils 4.32.x can be installed in parallel by
 193     omitting the compatibility symlinks (lzma, unlzma, lzcat, lzgrep etc.)
 194     from the XZ Utils package. It's probably a good idea to still package
 195     the symlinks into a separate package so that users may choose if they
 196     want to use XZ Utils or LZMA Utils for handling .lzma files.
 197
 198
 199 8. Example
 200 ----------
 201
 202     Here is an example for i686 GNU/Linux that
 203       - links xz and lzmainfo against shared liblzma;
 204       - links size-optimized xzdec and lzmadec against static liblzma
 205         while avoiding libpthread dependency;
 206       - includes only shared liblzma in the final package; and
 207       - copies also the "extra" directory to the package.
 208
 209     PKG=/tmp/xz-pkg
 210     tar xf xz-x.y.z.tar.gz
 211     cd xz-x.y.z
 212     ./configure \
 213             --prefix=/usr \
 214             --disable-static \
 215             --disable-xzdec \
 216             --disable-lzmadec \
 217             CFLAGS='-march=i686 -mtune=generic -O2'
 218     make
 219     make DESTDIR=$PKG install-strip
 220     make clean
 221     ./configure \
 222             --prefix=/usr \
 223             --disable-shared \
 224             --disable-nls \
 225             --disable-encoders \
 226             --enable-small \
 227             --disable-threads \
 228             CFLAGS='-march=i686 -mtune=generic -Os'
 229     make -C src/liblzma
 230     make -C src/xzdec
 231     make -C src/xzdec DESTDIR=$PKG install-strip
 232     cp -a extra $PKG/usr/share/doc/xz
 233