mirror of https://git.tukaani.org/xz.git
Update docs.
This commit is contained in:
Lasse Collin
parent
f0fa880d24
commit
ce34ec4f54
192
INSTALL
192
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
|
||||
<http://gforge.cs.vu.nl/gf/project/minix/tracker/?action=TrackerItemEdit&tracker_item_id=537>.
|
||||
|
||||
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.
|
||||
|
||||
|
|
|
|||
104
PACKAGERS
104
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
|
||||
|
|
|
|||
17
TODO
17
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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue