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         liblzma-doc     Example programs and, if enabled at build time,
  48                         Doxygen-generated liblzma API docs (HTML)
  49
  50
  51 2. Package description
  52 ----------------------
  53
  54     Here is a suggestion which you may use as the package description.
  55     If you can use only one-line description, pick only the first line.
  56     Naturally, feel free to use some other description if you find it
  57     better, and maybe send it to me too.
  58
  59         Library and command line tools for XZ and LZMA compressed files
  60
  61         XZ Utils provide a general purpose data compression library
  62         and command line tools. The native file format is the .xz
  63         format, but also the legacy .lzma format is supported. The .xz
  64         format supports multiple compression algorithms, of which LZMA2
  65         is currently the primary algorithm. With typical files, XZ Utils
  66         create about 30 % smaller files than gzip.
  67
  68     If you are splitting XZ Utils into multiple packages, here are some
  69     suggestions for package descriptions:
  70
  71     xz:
  72
  73         Command line tools for XZ and LZMA compressed files
  74
  75         This package includes the xz compression tool and other command
  76         line tools from XZ Utils. xz has command line syntax similar to
  77         that of gzip. The native file format is the .xz format, but also
  78         the legacy .lzma format is supported. The .xz format supports
  79         multiple compression algorithms, of which LZMA2 is currently the
  80         primary algorithm. With typical files, XZ Utils create about 30 %
  81         smaller files than gzip.
  82
  83         Note that this package doesn't include the files needed for
  84         LZMA Utils 4.32.x compatibility. Install also the xz-lzma
  85         package to make XZ Utils emulate LZMA Utils 4.32.x.
  86
  87     xz-lzma:
  88
  89         LZMA Utils emulation with XZ Utils
  90
  91         This package includes executables and symlinks to make
  92         XZ Utils emulate lzma, unlzma, lzcat, and other command
  93         line tools found from the legacy LZMA Utils 4.32.x package.
  94
  95     liblzma:
  96
  97         Library for XZ and LZMA compressed files
  98
  99         liblzma is a general purpose data compression library with
 100         an API similar to that of zlib. liblzma supports multiple
 101         algorithms, of which LZMA2 is currently the primary algorithm.
 102         The native file format is .xz, but also the legacy .lzma
 103         format and raw streams (no headers at all) are supported.
 104
 105         This package includes the shared library.
 106
 107     liblzma-devel:
 108
 109         Library for XZ and LZMA compressed files
 110
 111         This package includes the API headers, static library, and
 112         other development files related to liblzma.
 113
 114     liblzma-doc:
 115
 116         liblzma API documentation in HTML and example usage
 117
 118         This package includes the Doxygen-generated liblzma API
 119         HTML docs and example programs showing how to use liblzma.
 120
 121
 122 3. License
 123 ----------
 124
 125     If the package manager supports a license field, you probably should
 126     put GPLv2+ there (GNU GPL v2 or later). The interesting parts of
 127     XZ Utils are under the BSD Zero Clause License (0BSD), but some less
 128     important files ending up into the binary package are under GPLv2+.
 129     So it is simplest to just say GPLv2+ if you cannot specify
 130     "BSD0 and GPLv2+".
 131
 132     If you split XZ Utils into multiple packages as described earlier
 133     in this file, liblzma and liblzma-dev packages will contain only
 134     0BSD-licensed code from XZ Utils (compiler or linker may add some
 135     third-party code which may have other licenses).
 136
 137
 138 4. configure options
 139 --------------------
 140
 141     Unless you are building a package for a distribution that is meant
 142     only for embedded systems, don't use the following configure options:
 143
 144         --enable-debug
 145         --enable-encoders (*)
 146         --enable-decoders
 147         --enable-match-finders
 148         --enable-checks
 149         --enable-small (*)
 150         --disable-threads (*)
 151         --disable-microlzma (*)
 152         --disable-lzip-decoder (*)
 153
 154     (*) These are OK when building xzdec and lzmadec as described
 155         in INSTALL.
 156
 157     xzdec and lzmadec don't provide any functionality that isn't already
 158     available in the xz tool. Shipping xzdec and lzmadec without size
 159     optimization and statically-linked liblzma isn't very useful. Doing
 160     that would give users the xzdec man page, which may make it easier
 161     for people to find out that such tools exists, but the executables
 162     wouldn't have any advantage over the full-featured xz.
 163
 164
 165 5. Additional documentation
 166 ---------------------------
 167
 168     "make install" copies some additional documentation to $docdir
 169     (--docdir in configure). There is a copy of the GNU GPL v2, which
 170     can be replaced with a symlink if your distro ships with shared
 171     copies of the common license texts.
 172
 173     The Doxygen-generated liblzma API documentation (HTML) is built and
 174     installed if the configure option --enable-doxygen is used (it's
 175     disabled by default). This requires that Doxygen is available. The
 176     API documentation is installed by "make install" to $docdir/api.
 177
 178         NOTE: The files generated by Doxygen include content from
 179         Doxygen itself. Check the license info before distributing
 180         the Doxygen-generated files.
 181
 182
 183 6. Extra files
 184 --------------
 185
 186     The "extra" directory contains some small extra tools or other files.
 187     The exact set of extra files can vary between XZ Utils releases. The
 188     extra files have only limited use or they are too dangerous to be
 189     put directly to $bindir (7z2lzma.sh is a good example, since it can
 190     silently create corrupt output if certain conditions are not met).
 191
 192     If you feel like it, you may copy the extra directory under the doc
 193     directory (e.g. /usr/share/doc/xz/extra). Maybe some people will find
 194     them useful. However, most people needing these tools probably are
 195     able to find them from the source package too.
 196
 197     The "debug" directory contains some tools that are useful only when
 198     hacking on XZ Utils. Don't package these tools.
 199
 200
 201 7. Installing XZ Utils and LZMA Utils in parallel
 202 -------------------------------------------------
 203
 204     XZ Utils and LZMA Utils 4.32.x can be installed in parallel by
 205     omitting the compatibility symlinks (lzma, unlzma, lzcat, lzgrep etc.)
 206     from the XZ Utils package. It's probably a good idea to still package
 207     the symlinks into a separate package so that users may choose if they
 208     want to use XZ Utils or LZMA Utils for handling .lzma files.
 209
 210
 211 8. Example
 212 ----------
 213
 214     Here is an example for i686 GNU/Linux that
 215       - links xz and lzmainfo against shared liblzma;
 216       - links size-optimized xzdec and lzmadec against static liblzma
 217         while avoiding libpthread dependency;
 218       - includes only shared liblzma in the final package; and
 219       - copies also the "extra" directory to the package.
 220
 221     PKG=/tmp/xz-pkg
 222     tar xf xz-x.y.z.tar.gz
 223     cd xz-x.y.z
 224     ./configure \
 225             --prefix=/usr \
 226             --disable-static \
 227             --disable-xzdec \
 228             --disable-lzmadec \
 229             CFLAGS='-march=i686 -mtune=generic -O2'
 230     make
 231     make DESTDIR=$PKG install-strip
 232     make clean
 233     ./configure \
 234             --prefix=/usr \
 235             --disable-shared \
 236             --disable-nls \
 237             --disable-encoders \
 238             --enable-small \
 239             --disable-threads \
 240             CFLAGS='-march=i686 -mtune=generic -Os'
 241     make -C src/liblzma
 242     make -C src/xzdec
 243     make -C src/xzdec DESTDIR=$PKG install-strip
 244     cp -a extra $PKG/usr/share/doc/xz
 245