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        4.1. Static vs. dynamic linking of liblzma
  11        4.2. Optimizing xzdec and lzmadec
  12     5. Additional documentation
  13     6. Extra files
  14     7. Installing XZ Utils and LZMA Utils in parallel
  15     8. Example
  16
  17
  18 0. Preface
  19 ----------
  20
  21     This document is meant for people who create and maintain XZ Utils
  22     packages for operating system distributions. The focus is on GNU/Linux
  23     systems, but most things apply to other systems too.
  24
  25     While the standard "configure && make DESTDIR=$PKG install" should
  26     give a pretty good package, there are some details which packagers
  27     may want to tweak.
  28
  29     Packagers should also read the INSTALL file.
  30
  31
  32 1. Package naming
  33 -----------------
  34
  35     The preferred name for the XZ Utils package is "xz", because that's
  36     the name of the upstream tarball. Naturally you may have good reasons
  37     to use some other name; I won't get angry about it. ;-) It's just nice
  38     to be able to point people to the correct package name without asking
  39     what distro they have.
  40
  41     If your distro policy is to split things into small pieces, here is
  42     one suggestion:
  43
  44         xz              xz, xzdec, scripts (xzdiff, xzgrep, etc.), docs
  45         xz-lzma         lzma, unlzma, lzcat, lzgrep etc. symlinks and
  46                         lzmadec binary for compatibility with LZMA Utils
  47         liblzma         liblzma.so.*
  48         liblzma-devel   liblzma.so, liblzma.a, API headers
  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
 115 3. License
 116 ----------
 117
 118     If the package manager supports a license field, you probably should
 119     put GPLv2+ there (GNU GPL v2 or later). The interesting parts of
 120     XZ Utils are in the public domain, but some less important files
 121     ending up into the binary package are under GPLv2+. So it is simplest
 122     to just say GPLv2+ if you cannot specify "public domain and GPLv2+".
 123
 124     If you split XZ Utils into multiple packages as described earlier
 125     in this file, liblzma and liblzma-dev packages will contain only
 126     public domain code (from XZ Utils at least; compiler or linker may
 127     add some third-party code, which may be copyrighted).
 128
 129
 130 4. configure options
 131 --------------------
 132
 133     Unless you are building a package for a distribution that is meant
 134     only for embedded systems, don't use the following configure options:
 135
 136         --enable-debug
 137         --enable-encoders (*)
 138         --enable-decoders
 139         --enable-match-finders
 140         --enable-checks
 141         --enable-small (*)
 142         --disable-threads (*)
 143
 144     (*) These are OK when building xzdec and lzmadec as explained later.
 145
 146     You may use --enable-werror but be careful with it since it may break
 147     the build due to some useless warning when the build environment
 148     changes (like CPU architecture or compiler version).
 149
 150
 151 4.1. Static vs. dynamic linking of liblzma
 152
 153     The default is to link the most important command line tools against
 154     static liblzma, and the less important tools against shared liblzma.
 155     This can be changed by passing --enable-dynamic to configure, or by
 156     not building static libraries at all by passing --disable-static
 157     to configure. It is mildly recommended that you use the default, but
 158     the configure options make it easy to do otherwise if the distro policy
 159     so requires.
 160
 161     On 32-bit x86, linking against static liblzma can give a minor
 162     speed improvement. Static libraries on x86 are usually compiled as
 163     position-dependent code (non-PIC) and shared libraries are built as
 164     position-independent code (PIC). PIC wastes one register, which can
 165     make the code slightly slower compared to a non-PIC version. (Note
 166     that this doesn't apply to x86-64.)
 167
 168     Linking against static liblzma avoids a dependency on liblzma shared
 169     library, and makes it slightly easier to copy the command line tools
 170     between systems (e.g. quick 'n' dirty emergency recovery of some
 171     files). It also allows putting the command line tools to /bin while
 172     leaving liblzma to /usr/lib (assuming that your distribution uses
 173     such a file system hierarchy), if no other file in /bin would require
 174     liblzma.
 175
 176     If you don't want to distribute static libraries but you still
 177     want to link the command line tools against static liblzma, it is
 178     probably easiest to build both static and shared liblzma, but after
 179     "make DESTDIR=$PKG install" remove liblzma.a and modify liblzma.la
 180     to not contain a reference to liblzma.a.
 181
 182
 183 4.2. Optimizing xzdec and lzmadec
 184
 185     xzdec and lzmadec are intended to be relatively small instead of
 186     optimizing for the best speed. Thus, it is a good idea to build
 187     xzdec and lzmadec separately:
 188
 189       - Only decoder code is needed, so you can speed up the build
 190         slightly by passing --disable-encoders to configure. This
 191         shouldn't affect the final size of the executables though,
 192         because the linker is able to omit the encoder code anyway.
 193
 194       - xzdec and lzmadec will never use multithreading capabilities of
 195         liblzma. You can avoid dependency on libpthread by passing
 196         --disable-threads to configure.
 197
 198       - There are and will be no translated messages for xzdec and
 199         lzmadec, so it is fine to pass also --disable-nls to configure.
 200
 201       - To select somewhat size-optimized variant of some things in
 202         liblzma, pass --enable-small to configure.
 203
 204       - Tell the compiler to optimize for size instead of speed.
 205         E.g. with GCC, put -Os into CFLAGS.
 206
 207
 208 5. Additional documentation
 209 ---------------------------
 210
 211     "make install" copies some additional documentation to $docdir
 212     (--docdir in configure). These a copy of the GNU GPL v2, which can
 213     be replaced with a symlink if your distro ships with shared copies
 214     of the common license texts.
 215
 216
 217 6. Extra files
 218 --------------
 219
 220     The "extra" directory contains some small extra tools or other files.
 221     The exact set of extra files can vary between XZ Utils releases. The
 222     extra files have only limited use or they are too dangerous to be
 223     put directly to $bindir (7z2lzma.sh is a good example, since it can
 224     silently create corrupt output if certain conditions are not met).
 225
 226     If you feel like it, you may copy the extra directory under the doc
 227     directory (e.g. /usr/share/doc/xz/extra). Maybe some people will find
 228     them useful. However, most people needing these tools probably are
 229     able to find them from the source package too.
 230
 231     The "debug" directory contains some tools that are useful only when
 232     hacking on XZ Utils. Don't package these tools.
 233
 234
 235 7. Installing XZ Utils and LZMA Utils in parallel
 236 -------------------------------------------------
 237
 238     XZ Utils and LZMA Utils 4.32.x can be installed in parallel by
 239     omitting the compatibility symlinks (lzma, unlzma, lzcat, lzgrep etc.)
 240     from the XZ Utils package. It's probably a good idea to still package
 241     the symlinks into a separate package so that users may choose if they
 242     want to use XZ Utils or LZMA Utils for handling .lzma files.
 243
 244
 245 8. Example
 246 ----------
 247
 248     Here is an example for i686 GNU/Linux that
 249       - links xz against static liblzma;
 250       - includes only shared liblzma in the final package;
 251       - links xzdec and lzmadec against static liblzma while
 252         avoiding libpthread dependency.
 253
 254     PKG=/tmp/xz-pkg
 255     tar xf xz-x.y.z.tar.gz
 256     cd xz-x.y.z
 257     ./configure \
 258             --prefix=/usr \
 259             --sysconfdir=/etc \
 260             CFLAGS='-march=i686 -O2'
 261     make
 262     make DESTDIR=$PKG install-strip
 263     rm -f $PKG/usr/lib/lib*.a
 264     sed -i "s/^old_library=.*$/old_library=''/" $PKG/usr/lib/lib*.la
 265     make clean
 266     ./configure \
 267             --prefix=/usr \
 268             --sysconfdir=/etc \
 269             --disable-shared \
 270             --disable-nls \
 271             --disable-encoders \
 272             --enable-small \
 273             --disable-threads \
 274             CFLAGS='-march=i686 -Os'
 275     make -C src/liblzma
 276     make -C src/xzdec
 277     make -C src/xzdec DESTDIR=$PKG install-strip
 278     cp -a extra $PKG/usr/share/doc/xz
 279