1 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 10 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 142 (*) These are OK when building xzdec and lzmadec as described 143 in INSTALL. 144 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. 151 152 1535. Additional documentation 154--------------------------- 155 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. 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. 167 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 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. 206 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 231 232