blob: 6c5d219cb7ec29e6ec560d1883a6aa0d50c47c3c [file] [log] [blame]
Lasse Collin99f9e872009-07-19 13:14:20 +03001
2Information 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
Lasse Collin99f9e872009-07-19 13:14:20 +030010 5. Additional documentation
11 6. Extra files
12 7. Installing XZ Utils and LZMA Utils in parallel
13 8. Example
14
15
160. 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
301. 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
492. 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
1133. 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
1284. 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
Lasse Collince34ec42010-10-19 10:21:08 +0300142 (*) These are OK when building xzdec and lzmadec as described
143 in INSTALL.
Lasse Collin99f9e872009-07-19 13:14:20 +0300144
Lasse Collince34ec42010-10-19 10:21:08 +0300145 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.
Lasse Collin99f9e872009-07-19 13:14:20 +0300151
152
1535. Additional documentation
154---------------------------
155
156 "make install" copies some additional documentation to $docdir
Lasse Collince34ec42010-10-19 10:21:08 +0300157 (--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.
160
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.
Lasse Collin99f9e872009-07-19 13:14:20 +0300167
168
1696. Extra files
170--------------
171
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).
177
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.
182
183 The "debug" directory contains some tools that are useful only when
184 hacking on XZ Utils. Don't package these tools.
185
186
1877. Installing XZ Utils and LZMA Utils in parallel
188-------------------------------------------------
189
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.
195
196
1978. Example
198----------
199
200 Here is an example for i686 GNU/Linux that
Lasse Collince34ec42010-10-19 10:21:08 +0300201 - 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.
Lasse Collin99f9e872009-07-19 13:14:20 +0300206
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 \
Lasse Collince34ec42010-10-19 10:21:08 +0300212 --disable-static \
213 --disable-xzdec \
214 --disable-lzmadec \
215 CFLAGS='-march=i686 -mtune=generic -O2'
Lasse Collin99f9e872009-07-19 13:14:20 +0300216 make
217 make DESTDIR=$PKG install-strip
Lasse Collin99f9e872009-07-19 13:14:20 +0300218 make clean
219 ./configure \
220 --prefix=/usr \
Lasse Collin99f9e872009-07-19 13:14:20 +0300221 --disable-shared \
222 --disable-nls \
223 --disable-encoders \
224 --enable-small \
225 --disable-threads \
Lasse Collince34ec42010-10-19 10:21:08 +0300226 CFLAGS='-march=i686 -mtune=generic -Os'
Lasse Collin99f9e872009-07-19 13:14:20 +0300227 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
231