1*5a645f22SBen Gras 2*5a645f22SBen GrasInformation to packagers of XZ Utils 3*5a645f22SBen Gras==================================== 4*5a645f22SBen Gras 5*5a645f22SBen Gras 0. Preface 6*5a645f22SBen Gras 1. Package naming 7*5a645f22SBen Gras 2. Package description 8*5a645f22SBen Gras 3. License 9*5a645f22SBen Gras 4. configure options 10*5a645f22SBen Gras 5. Additional documentation 11*5a645f22SBen Gras 6. Extra files 12*5a645f22SBen Gras 7. Installing XZ Utils and LZMA Utils in parallel 13*5a645f22SBen Gras 8. Example 14*5a645f22SBen Gras 15*5a645f22SBen Gras 16*5a645f22SBen Gras0. Preface 17*5a645f22SBen Gras---------- 18*5a645f22SBen Gras 19*5a645f22SBen Gras This document is meant for people who create and maintain XZ Utils 20*5a645f22SBen Gras packages for operating system distributions. The focus is on GNU/Linux 21*5a645f22SBen Gras systems, but most things apply to other systems too. 22*5a645f22SBen Gras 23*5a645f22SBen Gras While the standard "configure && make DESTDIR=$PKG install" should 24*5a645f22SBen Gras give a pretty good package, there are some details which packagers 25*5a645f22SBen Gras may want to tweak. 26*5a645f22SBen Gras 27*5a645f22SBen Gras Packagers should also read the INSTALL file. 28*5a645f22SBen Gras 29*5a645f22SBen Gras 30*5a645f22SBen Gras1. Package naming 31*5a645f22SBen Gras----------------- 32*5a645f22SBen Gras 33*5a645f22SBen Gras The preferred name for the XZ Utils package is "xz", because that's 34*5a645f22SBen Gras the name of the upstream tarball. Naturally you may have good reasons 35*5a645f22SBen Gras to use some other name; I won't get angry about it. ;-) It's just nice 36*5a645f22SBen Gras to be able to point people to the correct package name without asking 37*5a645f22SBen Gras what distro they have. 38*5a645f22SBen Gras 39*5a645f22SBen Gras If your distro policy is to split things into small pieces, here is 40*5a645f22SBen Gras one suggestion: 41*5a645f22SBen Gras 42*5a645f22SBen Gras xz xz, xzdec, scripts (xzdiff, xzgrep, etc.), docs 43*5a645f22SBen Gras xz-lzma lzma, unlzma, lzcat, lzgrep etc. symlinks and 44*5a645f22SBen Gras lzmadec binary for compatibility with LZMA Utils 45*5a645f22SBen Gras liblzma liblzma.so.* 46*5a645f22SBen Gras liblzma-devel liblzma.so, liblzma.a, API headers 47*5a645f22SBen Gras 48*5a645f22SBen Gras 49*5a645f22SBen Gras2. Package description 50*5a645f22SBen Gras---------------------- 51*5a645f22SBen Gras 52*5a645f22SBen Gras Here is a suggestion which you may use as the package description. 53*5a645f22SBen Gras If you can use only one-line description, pick only the first line. 54*5a645f22SBen Gras Naturally, feel free to use some other description if you find it 55*5a645f22SBen Gras better, and maybe send it to me too. 56*5a645f22SBen Gras 57*5a645f22SBen Gras Library and command line tools for XZ and LZMA compressed files 58*5a645f22SBen Gras 59*5a645f22SBen Gras XZ Utils provide a general purpose data compression library 60*5a645f22SBen Gras and command line tools. The native file format is the .xz 61*5a645f22SBen Gras format, but also the legacy .lzma format is supported. The .xz 62*5a645f22SBen Gras format supports multiple compression algorithms, of which LZMA2 63*5a645f22SBen Gras is currently the primary algorithm. With typical files, XZ Utils 64*5a645f22SBen Gras create about 30 % smaller files than gzip. 65*5a645f22SBen Gras 66*5a645f22SBen Gras If you are splitting XZ Utils into multiple packages, here are some 67*5a645f22SBen Gras suggestions for package descriptions: 68*5a645f22SBen Gras 69*5a645f22SBen Gras xz: 70*5a645f22SBen Gras 71*5a645f22SBen Gras Command line tools for XZ and LZMA compressed files 72*5a645f22SBen Gras 73*5a645f22SBen Gras This package includes the xz compression tool and other command 74*5a645f22SBen Gras line tools from XZ Utils. xz has command line syntax similar to 75*5a645f22SBen Gras that of gzip. The native file format is the .xz format, but also 76*5a645f22SBen Gras the legacy .lzma format is supported. The .xz format supports 77*5a645f22SBen Gras multiple compression algorithms, of which LZMA2 is currently the 78*5a645f22SBen Gras primary algorithm. With typical files, XZ Utils create about 30 % 79*5a645f22SBen Gras smaller files than gzip. 80*5a645f22SBen Gras 81*5a645f22SBen Gras Note that this package doesn't include the files needed for 82*5a645f22SBen Gras LZMA Utils 4.32.x compatibility. Install also the xz-lzma 83*5a645f22SBen Gras package to make XZ Utils emulate LZMA Utils 4.32.x. 84*5a645f22SBen Gras 85*5a645f22SBen Gras xz-lzma: 86*5a645f22SBen Gras 87*5a645f22SBen Gras LZMA Utils emulation with XZ Utils 88*5a645f22SBen Gras 89*5a645f22SBen Gras This package includes executables and symlinks to make 90*5a645f22SBen Gras XZ Utils emulate lzma, unlzma, lzcat, and other command 91*5a645f22SBen Gras line tools found from the legacy LZMA Utils 4.32.x package. 92*5a645f22SBen Gras 93*5a645f22SBen Gras liblzma: 94*5a645f22SBen Gras 95*5a645f22SBen Gras Library for XZ and LZMA compressed files 96*5a645f22SBen Gras 97*5a645f22SBen Gras liblzma is a general purpose data compression library with 98*5a645f22SBen Gras an API similar to that of zlib. liblzma supports multiple 99*5a645f22SBen Gras algorithms, of which LZMA2 is currently the primary algorithm. 100*5a645f22SBen Gras The native file format is .xz, but also the legacy .lzma 101*5a645f22SBen Gras format and raw streams (no headers at all) are supported. 102*5a645f22SBen Gras 103*5a645f22SBen Gras This package includes the shared library. 104*5a645f22SBen Gras 105*5a645f22SBen Gras liblzma-devel: 106*5a645f22SBen Gras 107*5a645f22SBen Gras Library for XZ and LZMA compressed files 108*5a645f22SBen Gras 109*5a645f22SBen Gras This package includes the API headers, static library, and 110*5a645f22SBen Gras other development files related to liblzma. 111*5a645f22SBen Gras 112*5a645f22SBen Gras 113*5a645f22SBen Gras3. License 114*5a645f22SBen Gras---------- 115*5a645f22SBen Gras 116*5a645f22SBen Gras If the package manager supports a license field, you probably should 117*5a645f22SBen Gras put GPLv2+ there (GNU GPL v2 or later). The interesting parts of 118*5a645f22SBen Gras XZ Utils are in the public domain, but some less important files 119*5a645f22SBen Gras ending up into the binary package are under GPLv2+. So it is simplest 120*5a645f22SBen Gras to just say GPLv2+ if you cannot specify "public domain and GPLv2+". 121*5a645f22SBen Gras 122*5a645f22SBen Gras If you split XZ Utils into multiple packages as described earlier 123*5a645f22SBen Gras in this file, liblzma and liblzma-dev packages will contain only 124*5a645f22SBen Gras public domain code (from XZ Utils at least; compiler or linker may 125*5a645f22SBen Gras add some third-party code, which may be copyrighted). 126*5a645f22SBen Gras 127*5a645f22SBen Gras 128*5a645f22SBen Gras4. configure options 129*5a645f22SBen Gras-------------------- 130*5a645f22SBen Gras 131*5a645f22SBen Gras Unless you are building a package for a distribution that is meant 132*5a645f22SBen Gras only for embedded systems, don't use the following configure options: 133*5a645f22SBen Gras 134*5a645f22SBen Gras --enable-debug 135*5a645f22SBen Gras --enable-encoders (*) 136*5a645f22SBen Gras --enable-decoders 137*5a645f22SBen Gras --enable-match-finders 138*5a645f22SBen Gras --enable-checks 139*5a645f22SBen Gras --enable-small (*) 140*5a645f22SBen Gras --disable-threads (*) 141*5a645f22SBen Gras 142*5a645f22SBen Gras (*) These are OK when building xzdec and lzmadec as described 143*5a645f22SBen Gras in INSTALL. 144*5a645f22SBen Gras 145*5a645f22SBen Gras xzdec and lzmadec don't provide any functionality that isn't already 146*5a645f22SBen Gras available in the xz tool. Shipping xzdec and lzmadec without size 147*5a645f22SBen Gras optimization and statically-linked liblzma isn't very useful. Doing 148*5a645f22SBen Gras that would give users the xzdec man page, which may make it easier 149*5a645f22SBen Gras for people to find out that such tools exists, but the executables 150*5a645f22SBen Gras wouldn't have any advantage over the full-featured xz. 151*5a645f22SBen Gras 152*5a645f22SBen Gras 153*5a645f22SBen Gras5. Additional documentation 154*5a645f22SBen Gras--------------------------- 155*5a645f22SBen Gras 156*5a645f22SBen Gras "make install" copies some additional documentation to $docdir 157*5a645f22SBen Gras (--docdir in configure). There is a copy of the GNU GPL v2, which 158*5a645f22SBen Gras can be replaced with a symlink if your distro ships with shared 159*5a645f22SBen Gras copies of the common license texts. 160*5a645f22SBen Gras 161*5a645f22SBen Gras liblzma API is currently only documented using Doxygen tags in the 162*5a645f22SBen Gras API headers. It hasn't been tested much how good results Doxygen 163*5a645f22SBen Gras is able to make from the tags (e.g. Doxyfile might need tweaking, 164*5a645f22SBen Gras the tagging may need to be improved etc.), so it might be simpler 165*5a645f22SBen Gras to just let people read docs directly from the .h files for now, 166*5a645f22SBen Gras and also save quite a bit in package size at the same time. 167*5a645f22SBen Gras 168*5a645f22SBen Gras 169*5a645f22SBen Gras6. Extra files 170*5a645f22SBen Gras-------------- 171*5a645f22SBen Gras 172*5a645f22SBen Gras The "extra" directory contains some small extra tools or other files. 173*5a645f22SBen Gras The exact set of extra files can vary between XZ Utils releases. The 174*5a645f22SBen Gras extra files have only limited use or they are too dangerous to be 175*5a645f22SBen Gras put directly to $bindir (7z2lzma.sh is a good example, since it can 176*5a645f22SBen Gras silently create corrupt output if certain conditions are not met). 177*5a645f22SBen Gras 178*5a645f22SBen Gras If you feel like it, you may copy the extra directory under the doc 179*5a645f22SBen Gras directory (e.g. /usr/share/doc/xz/extra). Maybe some people will find 180*5a645f22SBen Gras them useful. However, most people needing these tools probably are 181*5a645f22SBen Gras able to find them from the source package too. 182*5a645f22SBen Gras 183*5a645f22SBen Gras The "debug" directory contains some tools that are useful only when 184*5a645f22SBen Gras hacking on XZ Utils. Don't package these tools. 185*5a645f22SBen Gras 186*5a645f22SBen Gras 187*5a645f22SBen Gras7. Installing XZ Utils and LZMA Utils in parallel 188*5a645f22SBen Gras------------------------------------------------- 189*5a645f22SBen Gras 190*5a645f22SBen Gras XZ Utils and LZMA Utils 4.32.x can be installed in parallel by 191*5a645f22SBen Gras omitting the compatibility symlinks (lzma, unlzma, lzcat, lzgrep etc.) 192*5a645f22SBen Gras from the XZ Utils package. It's probably a good idea to still package 193*5a645f22SBen Gras the symlinks into a separate package so that users may choose if they 194*5a645f22SBen Gras want to use XZ Utils or LZMA Utils for handling .lzma files. 195*5a645f22SBen Gras 196*5a645f22SBen Gras 197*5a645f22SBen Gras8. Example 198*5a645f22SBen Gras---------- 199*5a645f22SBen Gras 200*5a645f22SBen Gras Here is an example for i686 GNU/Linux that 201*5a645f22SBen Gras - links xz and lzmainfo against shared liblzma; 202*5a645f22SBen Gras - links size-optimized xzdec and lzmadec against static liblzma 203*5a645f22SBen Gras while avoiding libpthread dependency; 204*5a645f22SBen Gras - includes only shared liblzma in the final package; and 205*5a645f22SBen Gras - copies also the "extra" directory to the package. 206*5a645f22SBen Gras 207*5a645f22SBen Gras PKG=/tmp/xz-pkg 208*5a645f22SBen Gras tar xf xz-x.y.z.tar.gz 209*5a645f22SBen Gras cd xz-x.y.z 210*5a645f22SBen Gras ./configure \ 211*5a645f22SBen Gras --prefix=/usr \ 212*5a645f22SBen Gras --disable-static \ 213*5a645f22SBen Gras --disable-xzdec \ 214*5a645f22SBen Gras --disable-lzmadec \ 215*5a645f22SBen Gras CFLAGS='-march=i686 -mtune=generic -O2' 216*5a645f22SBen Gras make 217*5a645f22SBen Gras make DESTDIR=$PKG install-strip 218*5a645f22SBen Gras make clean 219*5a645f22SBen Gras ./configure \ 220*5a645f22SBen Gras --prefix=/usr \ 221*5a645f22SBen Gras --disable-shared \ 222*5a645f22SBen Gras --disable-nls \ 223*5a645f22SBen Gras --disable-encoders \ 224*5a645f22SBen Gras --enable-small \ 225*5a645f22SBen Gras --disable-threads \ 226*5a645f22SBen Gras CFLAGS='-march=i686 -mtune=generic -Os' 227*5a645f22SBen Gras make -C src/liblzma 228*5a645f22SBen Gras make -C src/xzdec 229*5a645f22SBen Gras make -C src/xzdec DESTDIR=$PKG install-strip 230*5a645f22SBen Gras cp -a extra $PKG/usr/share/doc/xz 231*5a645f22SBen Gras 232