Major documentation update.
[icculus/xz.git] / 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 command line tools against static liblzma.
154     This can be changed by passing --enable-dynamic to configure, or by
155     not building static libraries at all by passing --disable-static to
156     configure. It is mildly recommended that you use the default and link
157     the command line tools against static liblzma, but the configure
158     options make it easy to do otherwise if the distro policy so requires.
159
160     On 32-bit x86, linking against static liblzma can give a minor
161     speed improvement. Static libraries on x86 are usually compiled as
162     position-dependent code (non-PIC) and shared libraries are built as
163     position-independent code (PIC). PIC wastes one register, which can
164     make the code slightly slower compared to a non-PIC version. (Note
165     that this doesn't apply to x86-64.)
166
167     Linking against static liblzma avoids a dependency on liblzma shared
168     library, and makes it slightly easier to copy the command line tools
169     between systems (e.g. quick 'n' dirty emergency recovery of some
170     files). It also allows putting the command line tools to /bin while
171     leaving liblzma to /usr/lib (assuming that your distribution uses
172     such a file system hierarchy), if no other file in /bin would require
173     liblzma.
174
175     If you don't want to distribute static libraries but you still
176     want to link the command line tools against static liblzma, it is
177     probably easiest to build both static and shared liblzma, but after
178     "make DESTDIR=$PKG install" remove liblzma.a and modify liblzma.la
179     to not contain a reference to liblzma.a.
180
181
182 4.2. Optimizing xzdec and lzmadec
183
184     xzdec and lzmadec are intended to be relatively small instead of
185     optimizing for the best speed. Thus, it is a good idea to build
186     xzdec and lzmadec separately:
187
188       - Only decoder code is needed, so you can speed up the build
189         slightly by passing --disable-encoders to configure. This
190         shouldn't affect the final size of the executables though,
191         because the linker is able to omit the encoder code anyway.
192
193       - xzdec and lzmadec will never use multithreading capabilities of
194         liblzma. You can avoid dependency on libpthread by passing
195         --disable-threads to configure.
196
197       - There are and will be no translated messages for xzdec and
198         lzmadec, so it is fine to pass also --disable-nls to configure.
199
200       - To select somewhat size-optimized variant of some things in
201         liblzma, pass --enable-small to configure.
202
203       - Tell the compiler to optimize for size instead of speed.
204         E.g. with GCC, put -Os into CFLAGS.
205
206
207 5. Additional documentation
208 ---------------------------
209
210     "make install" copies some additional documentation to $docdir
211     (--docdir in configure). These a copy of the GNU GPL v2, which can
212     be replaced with a symlink if your distro ships with shared copies
213     of the common license texts.
214
215
216 6. Extra files
217 --------------
218
219     The "extra" directory contains some small extra tools or other files.
220     The exact set of extra files can vary between XZ Utils releases. The
221     extra files have only limited use or they are too dangerous to be
222     put directly to $bindir (7z2lzma.sh is a good example, since it can
223     silently create corrupt output if certain conditions are not met).
224
225     If you feel like it, you may copy the extra directory under the doc
226     directory (e.g. /usr/share/doc/xz/extra). Maybe some people will find
227     them useful. However, most people needing these tools probably are
228     able to find them from the source package too.
229
230     The "debug" directory contains some tools that are useful only when
231     hacking on XZ Utils. Don't package these tools.
232
233
234 7. Installing XZ Utils and LZMA Utils in parallel
235 -------------------------------------------------
236
237     XZ Utils and LZMA Utils 4.32.x can be installed in parallel by
238     omitting the compatibility symlinks (lzma, unlzma, lzcat, lzgrep etc.)
239     from the XZ Utils package. It's probably a good idea to still package
240     the symlinks into a separate package so that users may choose if they
241     want to use XZ Utils or LZMA Utils for handling .lzma files.
242
243
244 8. Example
245 ----------
246
247     Here is an example for i686 GNU/Linux that
248       - links xz against static liblzma;
249       - includes only shared liblzma in the final package;
250       - links xzdec and lzmadec against static liblzma while
251         avoiding libpthread dependency.
252
253     PKG=/tmp/xz-pkg
254     tar xf xz-x.y.z.tar.gz
255     cd xz-x.y.z
256     ./configure \
257             --prefix=/usr \
258             --sysconfdir=/etc \
259             CFLAGS='-march=i686 -O2'
260     make
261     make DESTDIR=$PKG install-strip
262     rm -f $PKG/usr/lib/lib*.a
263     sed -i "s/^old_library=.*$/old_library=''/" $PKG/usr/lib/lib*.la
264     make clean
265     ./configure \
266             --prefix=/usr \
267             --sysconfdir=/etc \
268             --disable-shared \
269             --disable-nls \
270             --disable-encoders \
271             --enable-small \
272             --disable-threads \
273             CFLAGS='-march=i686 -Os'
274     make -C src/liblzma
275     make -C src/xzdec
276     make -C src/xzdec DESTDIR=$PKG install-strip
277     cp -a extra $PKG/usr/share/doc/xz
278