liblzma: remove unversioned lzma_code@Base compatibility symbol
[xz/debian.git] / PACKAGERS
blob6c5d219cb7ec29e6ec560d1883a6aa0d50c47c3c
2 Information to packagers of XZ Utils
3 ====================================
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
16 0. Preface
17 ----------
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.
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.
27     Packagers should also read the INSTALL file.
30 1. Package naming
31 -----------------
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.
39     If your distro policy is to split things into small pieces, here is
40     one suggestion:
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
49 2. Package description
50 ----------------------
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.
57         Library and command line tools for XZ and LZMA compressed files
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.
66     If you are splitting XZ Utils into multiple packages, here are some
67     suggestions for package descriptions:
69     xz:
71         Command line tools for XZ and LZMA compressed files
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.
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.
85     xz-lzma:
87         LZMA Utils emulation with XZ Utils
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.
93     liblzma:
95         Library for XZ and LZMA compressed files
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.
103         This package includes the shared library.
105     liblzma-devel:
107         Library for XZ and LZMA compressed files
109         This package includes the API headers, static library, and
110         other development files related to liblzma.
113 3. License
114 ----------
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+".
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).
128 4. configure options
129 --------------------
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:
134         --enable-debug
135         --enable-encoders (*)
136         --enable-decoders
137         --enable-match-finders
138         --enable-checks
139         --enable-small (*)
140         --disable-threads (*)
142     (*) These are OK when building xzdec and lzmadec as described
143         in INSTALL.
145     xzdec and lzmadec don't provide any functionality that isn't already
146     available in the xz tool. Shipping xzdec and lzmadec without size
147     optimization and statically-linked liblzma isn't very useful. Doing
148     that would give users the xzdec man page, which may make it easier
149     for people to find out that such tools exists, but the executables
150     wouldn't have any advantage over the full-featured xz.
153 5. Additional documentation
154 ---------------------------
156     "make install" copies some additional documentation to $docdir
157     (--docdir in configure). There is a copy of the GNU GPL v2, which
158     can be replaced with a symlink if your distro ships with shared
159     copies of the common license texts.
161     liblzma API is currently only documented using Doxygen tags in the
162     API headers. It hasn't been tested much how good results Doxygen
163     is able to make from the tags (e.g. Doxyfile might need tweaking,
164     the tagging may need to be improved etc.), so it might be simpler
165     to just let people read docs directly from the .h files for now,
166     and also save quite a bit in package size at the same time.
169 6. Extra files
170 --------------
172     The "extra" directory contains some small extra tools or other files.
173     The exact set of extra files can vary between XZ Utils releases. The
174     extra files have only limited use or they are too dangerous to be
175     put directly to $bindir (7z2lzma.sh is a good example, since it can
176     silently create corrupt output if certain conditions are not met).
178     If you feel like it, you may copy the extra directory under the doc
179     directory (e.g. /usr/share/doc/xz/extra). Maybe some people will find
180     them useful. However, most people needing these tools probably are
181     able to find them from the source package too.
183     The "debug" directory contains some tools that are useful only when
184     hacking on XZ Utils. Don't package these tools.
187 7. Installing XZ Utils and LZMA Utils in parallel
188 -------------------------------------------------
190     XZ Utils and LZMA Utils 4.32.x can be installed in parallel by
191     omitting the compatibility symlinks (lzma, unlzma, lzcat, lzgrep etc.)
192     from the XZ Utils package. It's probably a good idea to still package
193     the symlinks into a separate package so that users may choose if they
194     want to use XZ Utils or LZMA Utils for handling .lzma files.
197 8. Example
198 ----------
200     Here is an example for i686 GNU/Linux that
201       - links xz and lzmainfo against shared liblzma;
202       - links size-optimized xzdec and lzmadec against static liblzma
203         while avoiding libpthread dependency;
204       - includes only shared liblzma in the final package; and
205       - copies also the "extra" directory to the package.
207     PKG=/tmp/xz-pkg
208     tar xf xz-x.y.z.tar.gz
209     cd xz-x.y.z
210     ./configure \
211             --prefix=/usr \
212             --disable-static \
213             --disable-xzdec \
214             --disable-lzmadec \
215             CFLAGS='-march=i686 -mtune=generic -O2'
216     make
217     make DESTDIR=$PKG install-strip
218     make clean
219     ./configure \
220             --prefix=/usr \
221             --disable-shared \
222             --disable-nls \
223             --disable-encoders \
224             --enable-small \
225             --disable-threads \
226             CFLAGS='-march=i686 -mtune=generic -Os'
227     make -C src/liblzma
228     make -C src/xzdec
229     make -C src/xzdec DESTDIR=$PKG install-strip
230     cp -a extra $PKG/usr/share/doc/xz