From ce34ec4f54ff8b753da236f371ad8dd23c8135c9 Mon Sep 17 00:00:00 2001 From: Lasse Collin Date: Tue, 19 Oct 2010 10:21:08 +0300 Subject: [PATCH] Update docs. --- INSTALL | 192 ++++++++++++++++++++++++++++++++++++----------------- PACKAGERS | 104 ++++++++--------------------- TODO | 17 +++-- dos/README | 2 +- 4 files changed, 172 insertions(+), 143 deletions(-) diff --git a/INSTALL b/INSTALL index 5cd69a8..339fedb 100644 --- a/INSTALL +++ b/INSTALL @@ -7,20 +7,23 @@ XZ Utils Installation 1.1. Compilers 1.2. Platform-specific notes 1.2.1. IRIX - 1.2.2. Tru64 - 1.2.3. Windows - 1.2.4. DOS - 1.2.5. OS/2 - 1.2.6. OpenVMS + 1.2.2. MINIX 3 + 1.2.3. OpenVMS + 1.2.4. Tru64 + 1.2.5. Windows + 1.2.6. DOS 1.3. Adding support for new platforms 2. configure options + 2.1. Static vs. dynamic linking of liblzma + 2.2. Optimizing xzdec and lzmadec 3. xzgrep and other scripts 3.1. Dependencies 3.2. PATH 4. Troubleshooting 4.1. "No C99 compiler was found." - 4.1. "No POSIX conforming shell (sh) was found." - 4.2. configure works but build fails at crc32_x86.S + 4.2. "No POSIX conforming shell (sh) was found." + 4.3. configure works but build fails at crc32_x86.S + 4.4. Lots of warnings about symbol visibility 0. Preface @@ -66,21 +69,47 @@ XZ Utils Installation work. -1.2.2. Tru64 +1.2.2. MINIX 3 + + The default install of MINIX 3 includes Amsterdam Compiler Kit (ACK), + which doesn't support C99. Install GCC to compile XZ Utils. + + MINIX 3.1.8 (and possibly some other versions too) has bugs in + /usr/include/stdint.h, which has to be patched before XZ Utils + can be compiled correctly. See + . + + XZ Utils doesn't have code to detect the amount of physical RAM and + number of CPU cores on MINIX 3. + + See section 4.4 in this file about symbol visibility warnings (you + may want to pass gl_cv_cc_visibility=no to configure). + + +1.2.3. OpenVMS + + XZ Utils can be built for OpenVMS, but the build system files + are not included in the XZ Utils source package. The required + OpenVMS-specific files are maintained by Jouk Jansen and can be + downloaded here: + + http://nchrem.tnw.tudelft.nl/openvms/software2.html#xzutils + + +1.2.4. Tru64 If you try to use the native C compiler on Tru64 (passing CC=cc to - configure), it is possible that the configure script will complain - that no C99 compiler was found even when the native compiler supports - C99. You can safely override the test for C99 compiler by passing - ac_cv_prog_cc_c99= as the argument to the configure script. + configure), you may need the workaround mention in section 4.1 in + this file (pass also ac_cv_prog_cc_c99= to configure). -1.2.3. Windows +1.2.5. Windows - Building XZ Utils on Windows is supported under MinGW + MSYS and - Cygwin. There is windows/build.bash to ease packaging XZ Utils with - MinGW + MSYS into a redistributable .zip or .7z file. See - windows/INSTALL-Windows.txt for more information. + Building XZ Utils on Windows is supported under MinGW + MSYS, + MinGW-w64 + MSYS, and Cygwin. There is windows/build.bash to + ease packaging XZ Utils with MinGW(-w64) + MSYS into a + redistributable .zip or .7z file. See windows/INSTALL-Windows.txt + for more information. It might be possible to build liblzma with a non-GNU toolchain too, but that will probably require writing a separate makefile. Building @@ -94,7 +123,7 @@ XZ Utils Installation windows/README-Windows.txt for details. -1.2.4. DOS +1.2.6. DOS There is an experimental Makefile in the "dos" directory to build XZ Utils on DOS using DJGPP. Support for long file names (LFN) is @@ -104,24 +133,6 @@ XZ Utils Installation would like to hear if it worked. -1.2.5. OS/2 - - To omit large number of harmless warnings about visibility support, - pass gl_cv_cc_visibility=no as an argument to the configure script. - This isn't mandatory since it should have no effect on the resulting - binaries. - - -1.2.6. OpenVMS - - XZ Utils can be built for OpenVMS, but the build system files are - currently not included in the XZ Utils source package. The required - OpenVMS-specific files are maintained by Jouk Jansen and can be - downloaded here: - - http://nchrem.tnw.tudelft.nl/openvms/software2.html#xzutils - - 1.3. Adding support for new platforms If you have written patches to make XZ Utils to work on previously @@ -139,7 +150,7 @@ XZ Utils Installation 2. configure options -------------------- - In most cases, the defaults are what you want. Most of the options + In most cases, the defaults are what you want. Many of the options below are useful only when building a size-optimized version of liblzma or command line tools. @@ -192,6 +203,29 @@ XZ Utils Installation the liblzma ABI, so this option should be used only when it is known to not cause problems. + --disable-xz + --disable-xzdec + --disable-lzmadec + --disable-lzmainfo + Don't build and install the command line tool mentioned + in the option name. + + NOTE: Disabling xz will skip some tests in "make check". + + NOTE: If xzdec is disabled and lzmadec is left enabled, + a dangling man page symlink lzmadec.1 -> xzdec.1 is + created. + + --disable-lzma-links + Don't create symlinks for LZMA Utils compatibility. + This includes lzma, unlzma, and lzcat. If scripts are + installed, also lzdiff, lzcmp, lzgrep, lzegrep, lzfgrep, + lzmore, and lzless will be omitted if this option is used. + + --disable-scripts + Don't install the scripts xzdiff, xzgrep, xzmore, xzless, + and their symlinks. + --disable-assembler liblzma includes some assembler optimizations. Currently there is only assembler code for CRC32 and CRC64 for @@ -259,28 +293,6 @@ XZ Utils Installation single-threaded applications and want to avoid dependency on libpthread. - --enable-dynamic=TYPE - Specify how command line tools should be linked against - liblzma. Possible TYPES: - - yes All command line tools are linked against - shared liblzma (if shared liblzma was built). - This is equivalent to --enable-dynamic (i.e. - no =TYPE). - - mixed Some tools are linked against static liblzma - and some against shared liblzma. This is the - default and recommended way. - - no All command line tools are linked against - static liblzma (if static liblzma was built). - This is equivalent to --disable-dynamic. - - This option is mostly useful for packagers, if distro - policy requires linking against shared libaries. See the - file PACKAGERS for more information about pros and cons - of this option. - --enable-debug This enables the assert() macro and possibly some other run-time consistency checks. It makes the code slower, so @@ -293,6 +305,52 @@ XZ Utils Installation resulting binaries. +2.1. Static vs. dynamic linking of liblzma + + On 32-bit x86, linking against static liblzma can give a minor + speed improvement. Static libraries on x86 are usually compiled as + position-dependent code (non-PIC) and shared libraries are built as + position-independent code (PIC). PIC wastes one register, which can + make the code slightly slower compared to a non-PIC version. (Note + that this doesn't apply to x86-64.) + + If you want to link xz against static liblzma, the simplest way + is to pass --disable-shared to configure. If you want also shared + liblzma, run configure again and run "make install" only for + src/liblzma. + + +2.2. Optimizing xzdec and lzmadec + + xzdec and lzmadec are intended to be relatively small instead of + optimizing for the best speed. Thus, it is a good idea to build + xzdec and lzmadec separately: + + - To link the tools against static liblzma, pass --disable-shared + to configure. + + - To select somewhat size-optimized variant of some things in + liblzma, pass --enable-small to configure. + + - Tell the compiler to optimize for size instead of speed. + E.g. with GCC, put -Os into CFLAGS. + + - xzdec and lzmadec will never use multithreading capabilities of + liblzma. You can avoid dependency on libpthread by passing + --disable-threads to configure. + + - There are and will be no translated messages for xzdec and + lzmadec, so it is fine to pass also --disable-nls to configure. + + - Only decoder code is needed, so you can speed up the build + slightly by passing --disable-encoders to configure. This + shouldn't affect the final size of the executables though, + because the linker is able to omit the encoder code anyway. + + If you have no use for xzdec or lzmadec, you can disable them with + --disable-xzdec and --disable-lzmadec. + + 3. xzgrep and other scripts --------------------------- @@ -343,7 +401,7 @@ XZ Utils Installation support enough C99. -4.1. "No POSIX conforming shell (sh) was found." +4.2. "No POSIX conforming shell (sh) was found." xzgrep and other scripts need a shell that (roughly) conforms to POSIX. The configure script tries to find such a shell. If @@ -352,7 +410,7 @@ XZ Utils Installation script. -4.2. configure works but build fails at crc32_x86.S +4.3. configure works but build fails at crc32_x86.S The easy fix is to pass --disable-assembler to the configure script. @@ -368,3 +426,15 @@ XZ Utils Installation correct configure triplet using the --build=CPU-COMPANY-SYSTEM option (see INSTALL.generic). + +4.4. Lots of warnings about symbol visibility + + On some systems where symbol visibility isn't supported, GCC may + still accept the visibility options and attributes, which will make + configure think that visibility is supported. This will result in + many compiler warnings. You can avoid the warnings by forcing the + visibility support off by passing gl_cv_cc_visibility=no as an + argument to the configure script. This has no effect on the + resulting binaries, but fewer warnings looks nicer and may allow + using --enable-werror. + diff --git a/PACKAGERS b/PACKAGERS index c5d375a..6c5d219 100644 --- a/PACKAGERS +++ b/PACKAGERS @@ -7,8 +7,6 @@ Information to packagers of XZ Utils 2. Package description 3. License 4. configure options - 4.1. Static vs. dynamic linking of liblzma - 4.2. Optimizing xzdec and lzmadec 5. Additional documentation 6. Extra files 7. Installing XZ Utils and LZMA Utils in parallel @@ -141,77 +139,31 @@ Information to packagers of XZ Utils --enable-small (*) --disable-threads (*) - (*) These are OK when building xzdec and lzmadec as explained later. + (*) These are OK when building xzdec and lzmadec as described + in INSTALL. - You may use --enable-werror but be careful with it since it may break - the build due to some useless warning when the build environment - changes (like CPU architecture or compiler version). - - -4.1. Static vs. dynamic linking of liblzma - - The default is to link the most important command line tools against - static liblzma, and the less important tools against shared liblzma. - This can be changed by passing --enable-dynamic to configure, or by - not building static libraries at all by passing --disable-static - to configure. It is mildly recommended that you use the default, but - the configure options make it easy to do otherwise if the distro policy - so requires. - - On 32-bit x86, linking against static liblzma can give a minor - speed improvement. Static libraries on x86 are usually compiled as - position-dependent code (non-PIC) and shared libraries are built as - position-independent code (PIC). PIC wastes one register, which can - make the code slightly slower compared to a non-PIC version. (Note - that this doesn't apply to x86-64.) - - Linking against static liblzma avoids a dependency on liblzma shared - library, and makes it slightly easier to copy the command line tools - between systems (e.g. quick 'n' dirty emergency recovery of some - files). It also allows putting the command line tools to /bin while - leaving liblzma to /usr/lib (assuming that your distribution uses - such a file system hierarchy), if no other file in /bin would require - liblzma. - - If you don't want to distribute static libraries but you still - want to link the command line tools against static liblzma, it is - probably easiest to build both static and shared liblzma, but after - "make DESTDIR=$PKG install" remove liblzma.a and modify liblzma.la - to not contain a reference to liblzma.a. - - -4.2. Optimizing xzdec and lzmadec - - xzdec and lzmadec are intended to be relatively small instead of - optimizing for the best speed. Thus, it is a good idea to build - xzdec and lzmadec separately: - - - Only decoder code is needed, so you can speed up the build - slightly by passing --disable-encoders to configure. This - shouldn't affect the final size of the executables though, - because the linker is able to omit the encoder code anyway. - - - xzdec and lzmadec will never use multithreading capabilities of - liblzma. You can avoid dependency on libpthread by passing - --disable-threads to configure. - - - There are and will be no translated messages for xzdec and - lzmadec, so it is fine to pass also --disable-nls to configure. - - - To select somewhat size-optimized variant of some things in - liblzma, pass --enable-small to configure. - - - Tell the compiler to optimize for size instead of speed. - E.g. with GCC, put -Os into CFLAGS. + xzdec and lzmadec don't provide any functionality that isn't already + available in the xz tool. Shipping xzdec and lzmadec without size + optimization and statically-linked liblzma isn't very useful. Doing + that would give users the xzdec man page, which may make it easier + for people to find out that such tools exists, but the executables + wouldn't have any advantage over the full-featured xz. 5. Additional documentation --------------------------- "make install" copies some additional documentation to $docdir - (--docdir in configure). These a copy of the GNU GPL v2, which can - be replaced with a symlink if your distro ships with shared copies - of the common license texts. + (--docdir in configure). There is a copy of the GNU GPL v2, which + can be replaced with a symlink if your distro ships with shared + copies of the common license texts. + + liblzma API is currently only documented using Doxygen tags in the + API headers. It hasn't been tested much how good results Doxygen + is able to make from the tags (e.g. Doxyfile might need tweaking, + the tagging may need to be improved etc.), so it might be simpler + to just let people read docs directly from the .h files for now, + and also save quite a bit in package size at the same time. 6. Extra files @@ -246,32 +198,32 @@ Information to packagers of XZ Utils ---------- Here is an example for i686 GNU/Linux that - - links xz against static liblzma; - - includes only shared liblzma in the final package; - - links xzdec and lzmadec against static liblzma while - avoiding libpthread dependency. + - links xz and lzmainfo against shared liblzma; + - links size-optimized xzdec and lzmadec against static liblzma + while avoiding libpthread dependency; + - includes only shared liblzma in the final package; and + - copies also the "extra" directory to the package. PKG=/tmp/xz-pkg tar xf xz-x.y.z.tar.gz cd xz-x.y.z ./configure \ --prefix=/usr \ - --sysconfdir=/etc \ - CFLAGS='-march=i686 -O2' + --disable-static \ + --disable-xzdec \ + --disable-lzmadec \ + CFLAGS='-march=i686 -mtune=generic -O2' make make DESTDIR=$PKG install-strip - rm -f $PKG/usr/lib/lib*.a - sed -i "s/^old_library=.*$/old_library=''/" $PKG/usr/lib/lib*.la make clean ./configure \ --prefix=/usr \ - --sysconfdir=/etc \ --disable-shared \ --disable-nls \ --disable-encoders \ --enable-small \ --disable-threads \ - CFLAGS='-march=i686 -Os' + CFLAGS='-march=i686 -mtune=generic -Os' make -C src/liblzma make -C src/xzdec make -C src/xzdec DESTDIR=$PKG install-strip diff --git a/TODO b/TODO index 9fac1b3..55fc475 100644 --- a/TODO +++ b/TODO @@ -18,15 +18,20 @@ Known bugs XZ Utils compress some files significantly worse than LZMA Utils. This is due to faster compression presets used by XZ Utils, and - can be worked around by using "xz --extreme". However, the presets - need some tweaking and maybe this issue can be minimized without - making the typical case too much slower. + can often be worked around by using "xz --extreme". With some files + --extreme isn't enough though: it's most likely with files that + compress extremely well, so going from compression ratio of 0.003 + to 0.004 means big relative increase in the compressed file size. xz doesn't quote unprintable characters when it displays file names given on the command line. tuklib_exit() doesn't block signals => EINTR is possible. + SIGTSTP is not handled. If xz is stopped, the estimated remaining + time and calculated (de)compression speed won't make sense in the + progress indicator (xz --verbose). + Missing features ---------------- @@ -41,11 +46,13 @@ Missing features Buffer-to-buffer coding could use less RAM (especially when decompressing LZMA1 or LZMA2). - I/O library is not implemented. It will possibly be named libzzf. + I/O library is not implemented (similar to gzopen() in zlib). + It will be a separate library that supports uncompressed, .gz, + .bz2, .lzma, and .xz files. lzma_strerror() to convert lzma_ret to human readable form? This is tricky, because the same error codes are used with - slightly different meanings. + slightly different meanings, and this cannot be fixed anymore. Documentation diff --git a/dos/README b/dos/README index 1ed8493..9456ea1 100644 --- a/dos/README +++ b/dos/README @@ -84,5 +84,5 @@ Bugs Pressing Ctrl-c or Ctrl-Break won't remove the incomplete target file when running under Windows XP Command Prompt (something goes wrong - with SIGINT handling). Use the Windows build of XZ Utils on Windows. + with SIGINT handling). It works correctly under Windows 95/98/98SE/ME. -- 2.39.2