| OLD | NEW | 
|    1  |    1  | 
|    2 Information to packagers of XZ Utils |    2 Information to packagers of XZ Utils | 
|    3 ==================================== |    3 ==================================== | 
|    4  |    4  | 
|    5     0. Preface |    5     0. Preface | 
|    6     1. Package naming |    6     1. Package naming | 
|    7     2. Package description |    7     2. Package description | 
|    8     3. License |    8     3. License | 
|    9     4. configure options |    9     4. configure options | 
|   10        4.1. Static vs. dynamic linking of liblzma |  | 
|   11        4.2. Optimizing xzdec and lzmadec |  | 
|   12     5. Additional documentation |   10     5. Additional documentation | 
|   13     6. Extra files |   11     6. Extra files | 
|   14     7. Installing XZ Utils and LZMA Utils in parallel |   12     7. Installing XZ Utils and LZMA Utils in parallel | 
|   15     8. Example |   13     8. Example | 
|   16  |   14  | 
|   17  |   15  | 
|   18 0. Preface |   16 0. Preface | 
|   19 ---------- |   17 ---------- | 
|   20  |   18  | 
|   21     This document is meant for people who create and maintain XZ Utils |   19     This document is meant for people who create and maintain XZ Utils | 
| (...skipping 112 matching lines...) Expand 10 before | Expand all | Expand 10 after  Loading... | 
|  134     only for embedded systems, don't use the following configure options: |  132     only for embedded systems, don't use the following configure options: | 
|  135  |  133  | 
|  136         --enable-debug |  134         --enable-debug | 
|  137         --enable-encoders (*) |  135         --enable-encoders (*) | 
|  138         --enable-decoders |  136         --enable-decoders | 
|  139         --enable-match-finders |  137         --enable-match-finders | 
|  140         --enable-checks |  138         --enable-checks | 
|  141         --enable-small (*) |  139         --enable-small (*) | 
|  142         --disable-threads (*) |  140         --disable-threads (*) | 
|  143  |  141  | 
|  144     (*) These are OK when building xzdec and lzmadec as explained later. |  142     (*) These are OK when building xzdec and lzmadec as described | 
 |  143         in INSTALL. | 
|  145  |  144  | 
|  146     You may use --enable-werror but be careful with it since it may break |  145     xzdec and lzmadec don't provide any functionality that isn't already | 
|  147     the build due to some useless warning when the build environment |  146     available in the xz tool. Shipping xzdec and lzmadec without size | 
|  148     changes (like CPU architecture or compiler version). |  147     optimization and statically-linked liblzma isn't very useful. Doing | 
|  149  |  148     that would give users the xzdec man page, which may make it easier | 
|  150  |  149     for people to find out that such tools exists, but the executables | 
|  151 4.1. Static vs. dynamic linking of liblzma |  150     wouldn't have any advantage over the full-featured xz. | 
|  152  |  | 
|  153     The default is to link the most important command line tools against |  | 
|  154     static liblzma, and the less important tools against shared liblzma. |  | 
|  155     This can be changed by passing --enable-dynamic to configure, or by |  | 
|  156     not building static libraries at all by passing --disable-static |  | 
|  157     to configure. It is mildly recommended that you use the default, but |  | 
|  158     the configure options make it easy to do otherwise if the distro policy |  | 
|  159     so requires. |  | 
|  160  |  | 
|  161     On 32-bit x86, linking against static liblzma can give a minor |  | 
|  162     speed improvement. Static libraries on x86 are usually compiled as |  | 
|  163     position-dependent code (non-PIC) and shared libraries are built as |  | 
|  164     position-independent code (PIC). PIC wastes one register, which can |  | 
|  165     make the code slightly slower compared to a non-PIC version. (Note |  | 
|  166     that this doesn't apply to x86-64.) |  | 
|  167  |  | 
|  168     Linking against static liblzma avoids a dependency on liblzma shared |  | 
|  169     library, and makes it slightly easier to copy the command line tools |  | 
|  170     between systems (e.g. quick 'n' dirty emergency recovery of some |  | 
|  171     files). It also allows putting the command line tools to /bin while |  | 
|  172     leaving liblzma to /usr/lib (assuming that your distribution uses |  | 
|  173     such a file system hierarchy), if no other file in /bin would require |  | 
|  174     liblzma. |  | 
|  175  |  | 
|  176     If you don't want to distribute static libraries but you still |  | 
|  177     want to link the command line tools against static liblzma, it is |  | 
|  178     probably easiest to build both static and shared liblzma, but after |  | 
|  179     "make DESTDIR=$PKG install" remove liblzma.a and modify liblzma.la |  | 
|  180     to not contain a reference to liblzma.a. |  | 
|  181  |  | 
|  182  |  | 
|  183 4.2. Optimizing xzdec and lzmadec |  | 
|  184  |  | 
|  185     xzdec and lzmadec are intended to be relatively small instead of |  | 
|  186     optimizing for the best speed. Thus, it is a good idea to build |  | 
|  187     xzdec and lzmadec separately: |  | 
|  188  |  | 
|  189       - Only decoder code is needed, so you can speed up the build |  | 
|  190         slightly by passing --disable-encoders to configure. This |  | 
|  191         shouldn't affect the final size of the executables though, |  | 
|  192         because the linker is able to omit the encoder code anyway. |  | 
|  193  |  | 
|  194       - xzdec and lzmadec will never use multithreading capabilities of |  | 
|  195         liblzma. You can avoid dependency on libpthread by passing |  | 
|  196         --disable-threads to configure. |  | 
|  197  |  | 
|  198       - There are and will be no translated messages for xzdec and |  | 
|  199         lzmadec, so it is fine to pass also --disable-nls to configure. |  | 
|  200  |  | 
|  201       - To select somewhat size-optimized variant of some things in |  | 
|  202         liblzma, pass --enable-small to configure. |  | 
|  203  |  | 
|  204       - Tell the compiler to optimize for size instead of speed. |  | 
|  205         E.g. with GCC, put -Os into CFLAGS. |  | 
|  206  |  151  | 
|  207  |  152  | 
|  208 5. Additional documentation |  153 5. Additional documentation | 
|  209 --------------------------- |  154 --------------------------- | 
|  210  |  155  | 
|  211     "make install" copies some additional documentation to $docdir |  156     "make install" copies some additional documentation to $docdir | 
|  212     (--docdir in configure). These a copy of the GNU GPL v2, which can |  157     (--docdir in configure). There is a copy of the GNU GPL v2, which | 
|  213     be replaced with a symlink if your distro ships with shared copies |  158     can be replaced with a symlink if your distro ships with shared | 
|  214     of the common license texts. |  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. | 
|  215  |  167  | 
|  216  |  168  | 
|  217 6. Extra files |  169 6. Extra files | 
|  218 -------------- |  170 -------------- | 
|  219  |  171  | 
|  220     The "extra" directory contains some small extra tools or other files. |  172     The "extra" directory contains some small extra tools or other files. | 
|  221     The exact set of extra files can vary between XZ Utils releases. The |  173     The exact set of extra files can vary between XZ Utils releases. The | 
|  222     extra files have only limited use or they are too dangerous to be |  174     extra files have only limited use or they are too dangerous to be | 
|  223     put directly to $bindir (7z2lzma.sh is a good example, since it can |  175     put directly to $bindir (7z2lzma.sh is a good example, since it can | 
|  224     silently create corrupt output if certain conditions are not met). |  176     silently create corrupt output if certain conditions are not met). | 
| (...skipping 14 matching lines...) Expand all  Loading... | 
|  239     omitting the compatibility symlinks (lzma, unlzma, lzcat, lzgrep etc.) |  191     omitting the compatibility symlinks (lzma, unlzma, lzcat, lzgrep etc.) | 
|  240     from the XZ Utils package. It's probably a good idea to still package |  192     from the XZ Utils package. It's probably a good idea to still package | 
|  241     the symlinks into a separate package so that users may choose if they |  193     the symlinks into a separate package so that users may choose if they | 
|  242     want to use XZ Utils or LZMA Utils for handling .lzma files. |  194     want to use XZ Utils or LZMA Utils for handling .lzma files. | 
|  243  |  195  | 
|  244  |  196  | 
|  245 8. Example |  197 8. Example | 
|  246 ---------- |  198 ---------- | 
|  247  |  199  | 
|  248     Here is an example for i686 GNU/Linux that |  200     Here is an example for i686 GNU/Linux that | 
|  249       - links xz against static liblzma; |  201       - links xz and lzmainfo against shared liblzma; | 
|  250       - includes only shared liblzma in the final package; |  202       - links size-optimized xzdec and lzmadec against static liblzma | 
|  251       - links xzdec and lzmadec against static liblzma while |  203         while avoiding libpthread dependency; | 
|  252         avoiding libpthread dependency. |  204       - includes only shared liblzma in the final package; and | 
 |  205       - copies also the "extra" directory to the package. | 
|  253  |  206  | 
|  254     PKG=/tmp/xz-pkg |  207     PKG=/tmp/xz-pkg | 
|  255     tar xf xz-x.y.z.tar.gz |  208     tar xf xz-x.y.z.tar.gz | 
|  256     cd xz-x.y.z |  209     cd xz-x.y.z | 
|  257     ./configure \ |  210     ./configure \ | 
|  258             --prefix=/usr \ |  211             --prefix=/usr \ | 
|  259             --sysconfdir=/etc \ |  212             --disable-static \ | 
|  260             CFLAGS='-march=i686 -O2' |  213             --disable-xzdec \ | 
 |  214             --disable-lzmadec \ | 
 |  215             CFLAGS='-march=i686 -mtune=generic -O2' | 
|  261     make |  216     make | 
|  262     make DESTDIR=$PKG install-strip |  217     make DESTDIR=$PKG install-strip | 
|  263     rm -f $PKG/usr/lib/lib*.a |  | 
|  264     sed -i "s/^old_library=.*$/old_library=''/" $PKG/usr/lib/lib*.la |  | 
|  265     make clean |  218     make clean | 
|  266     ./configure \ |  219     ./configure \ | 
|  267             --prefix=/usr \ |  220             --prefix=/usr \ | 
|  268             --sysconfdir=/etc \ |  | 
|  269             --disable-shared \ |  221             --disable-shared \ | 
|  270             --disable-nls \ |  222             --disable-nls \ | 
|  271             --disable-encoders \ |  223             --disable-encoders \ | 
|  272             --enable-small \ |  224             --enable-small \ | 
|  273             --disable-threads \ |  225             --disable-threads \ | 
|  274             CFLAGS='-march=i686 -Os' |  226             CFLAGS='-march=i686 -mtune=generic -Os' | 
|  275     make -C src/liblzma |  227     make -C src/liblzma | 
|  276     make -C src/xzdec |  228     make -C src/xzdec | 
|  277     make -C src/xzdec DESTDIR=$PKG install-strip |  229     make -C src/xzdec DESTDIR=$PKG install-strip | 
|  278     cp -a extra $PKG/usr/share/doc/xz |  230     cp -a extra $PKG/usr/share/doc/xz | 
|  279  |  231  | 
| OLD | NEW |