Lasse Collin | 99f9e87 | 2009-07-19 13:14:20 +0300 | [diff] [blame] | 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 |
Lasse Collin | 99f9e87 | 2009-07-19 13:14:20 +0300 | [diff] [blame] | 10 | 5. Additional documentation |
| 11 | 6. Extra files |
| 12 | 7. Installing XZ Utils and LZMA Utils in parallel |
| 13 | 8. Example |
| 14 | |
| 15 | |
| 16 | 0. 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 | |
| 30 | 1. 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 | |
| 49 | 2. 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 | |
| 113 | 3. 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 | |
| 128 | 4. 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 Collin | ce34ec4 | 2010-10-19 10:21:08 +0300 | [diff] [blame] | 142 | (*) These are OK when building xzdec and lzmadec as described |
| 143 | in INSTALL. |
Lasse Collin | 99f9e87 | 2009-07-19 13:14:20 +0300 | [diff] [blame] | 144 | |
Lasse Collin | ce34ec4 | 2010-10-19 10:21:08 +0300 | [diff] [blame] | 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. |
Lasse Collin | 99f9e87 | 2009-07-19 13:14:20 +0300 | [diff] [blame] | 151 | |
| 152 | |
| 153 | 5. Additional documentation |
| 154 | --------------------------- |
| 155 | |
| 156 | "make install" copies some additional documentation to $docdir |
Lasse Collin | ce34ec4 | 2010-10-19 10:21:08 +0300 | [diff] [blame] | 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. |
Lasse Collin | 99f9e87 | 2009-07-19 13:14:20 +0300 | [diff] [blame] | 167 | |
| 168 | |
| 169 | 6. 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 | |
| 187 | 7. 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 | |
| 197 | 8. Example |
| 198 | ---------- |
| 199 | |
| 200 | Here is an example for i686 GNU/Linux that |
Lasse Collin | ce34ec4 | 2010-10-19 10:21:08 +0300 | [diff] [blame] | 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. |
Lasse Collin | 99f9e87 | 2009-07-19 13:14:20 +0300 | [diff] [blame] | 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 \ |
Lasse Collin | ce34ec4 | 2010-10-19 10:21:08 +0300 | [diff] [blame] | 212 | --disable-static \ |
| 213 | --disable-xzdec \ |
| 214 | --disable-lzmadec \ |
| 215 | CFLAGS='-march=i686 -mtune=generic -O2' |
Lasse Collin | 99f9e87 | 2009-07-19 13:14:20 +0300 | [diff] [blame] | 216 | make |
| 217 | make DESTDIR=$PKG install-strip |
Lasse Collin | 99f9e87 | 2009-07-19 13:14:20 +0300 | [diff] [blame] | 218 | make clean |
| 219 | ./configure \ |
| 220 | --prefix=/usr \ |
Lasse Collin | 99f9e87 | 2009-07-19 13:14:20 +0300 | [diff] [blame] | 221 | --disable-shared \ |
| 222 | --disable-nls \ |
| 223 | --disable-encoders \ |
| 224 | --enable-small \ |
| 225 | --disable-threads \ |
Lasse Collin | ce34ec4 | 2010-10-19 10:21:08 +0300 | [diff] [blame] | 226 | CFLAGS='-march=i686 -mtune=generic -Os' |
Lasse Collin | 99f9e87 | 2009-07-19 13:14:20 +0300 | [diff] [blame] | 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 | |