8 1.2. Platform-specific notes
13 1.2.5. Solaris, OpenSolaris, and derivatives
17 1.3. Adding support for new platforms
19 2.1. Static vs. dynamic linking of liblzma
20 2.2. Optimizing xzdec and lzmadec
21 3. xzgrep and other scripts
25 4.1. "No C99 compiler was found."
26 4.2. "No POSIX conforming shell (sh) was found."
27 4.3. configure works but build fails at crc32_x86.S
28 4.4. Lots of warnings about symbol visibility
29 4.5. "make check" fails
30 4.6. liblzma.so (or similar) not found when running xz
36 If you aren't familiar with building packages that use GNU Autotools,
37 see the file INSTALL.generic for generic instructions before reading
40 If you are going to build a package for distribution, see also the
41 file PACKAGERS. It contains information that should help making the
42 binary packages as good as possible, but the information isn't very
43 interesting to those making local builds for private use or for use
44 in special situations like embedded systems.
47 1. Supported platforms
48 ----------------------
50 XZ Utils are developed on GNU/Linux, but they should work on many
51 POSIX-like operating systems like *BSDs and Solaris, and even on
52 a few non-POSIX operating systems.
57 A C99 compiler is required to compile XZ Utils. If you use GCC, you
58 need at least version 3.x.x. GCC version 2.xx.x doesn't support some
59 C99 features used in XZ Utils source code, thus GCC 2 won't compile
62 XZ Utils takes advantage of some GNU C extensions when building
63 with GCC. Because these extensions are used only when building
64 with GCC, it should be possible to use any C99 compiler.
67 1.2. Platform-specific notes
71 If you use IBM XL C compiler, pass CC=xlc_r to configure. If
72 you use CC=xlc instead, you must disable threading support
73 with --disable-threads (usually not recommended).
78 MIPSpro 7.4.4m has been reported to produce broken code if using
79 the -O2 optimization flag ("make check" fails). Using -O1 should
82 A problem has been reported when using shared liblzma. Passing
83 --disable-shared to configure works around this. Alternatively,
84 putting "-64" to CFLAGS to build a 64-bit version might help too.
89 The default install of MINIX 3 includes Amsterdam Compiler Kit (ACK),
90 which doesn't support C99. Install GCC to compile XZ Utils.
92 MINIX 3.1.8 and older have bugs in /usr/include/stdint.h, which has
93 to be patched before XZ Utils can be compiled correctly. See
94 <http://gforge.cs.vu.nl/gf/project/minix/tracker/?action=TrackerItemEdit&tracker_item_id=537>.
96 MINIX 3.2.0 and later use a different libc and aren't affected by
99 XZ Utils doesn't have code to detect the amount of physical RAM and
100 number of CPU cores on MINIX 3.
102 See section 4.4 in this file about symbol visibility warnings (you
103 may want to pass gl_cv_cc_visibility=no to configure).
108 XZ Utils can be built for OpenVMS, but the build system files
109 are not included in the XZ Utils source package. The required
110 OpenVMS-specific files are maintained by Jouk Jansen and can be
113 http://nchrem.tnw.tudelft.nl/openvms/software2.html#xzutils
116 1.2.5. Solaris, OpenSolaris, and derivatives
118 The following linker error has been reported on some x86 systems:
120 ld: fatal: relocation error: R_386_GOTOFF: ...
122 This can be worked around by passing gl_cv_cc_visibility=no
123 as an argument to the configure script.
128 If you try to use the native C compiler on Tru64 (passing CC=cc to
129 configure), you may need the workaround mention in section 4.1 in
130 this file (pass also ac_cv_prog_cc_c99= to configure).
135 Building XZ Utils on Windows is supported under MinGW + MSYS,
136 MinGW-w64 + MSYS, and Cygwin. There is windows/build.bash to
137 ease packaging XZ Utils with MinGW(-w64) + MSYS into a
138 redistributable .zip or .7z file. See windows/INSTALL-Windows.txt
139 for more information.
141 It might be possible to build liblzma with a non-GNU toolchain too,
142 but that will probably require writing a separate makefile. Building
143 the command line tools with non-GNU toolchains will be harder than
144 building only liblzma.
146 Even if liblzma is built with MinGW, the resulting DLL or static
147 library can be used by other compilers and linkers, including MSVC.
148 Thus, it shouldn't be a problem to use MinGW to build liblzma even
149 if you cannot use MinGW to build the rest of your project. See
150 windows/README-Windows.txt for details.
155 There is an experimental Makefile in the "dos" directory to build
156 XZ Utils on DOS using DJGPP. Support for long file names (LFN) is
157 needed. See dos/README for more information.
159 GNU Autotools based build hasn't been tried on DOS. If you try, I
160 would like to hear if it worked.
163 1.3. Adding support for new platforms
165 If you have written patches to make XZ Utils to work on previously
166 unsupported platform, please send the patches to me! I will consider
167 including them to the official version. It's nice to minimize the
168 need of third-party patching.
170 One exception: Don't request or send patches to change the whole
171 source package to C89. I find C99 substantially nicer to write and
172 maintain. However, the public library headers must be in C89 to
173 avoid frustrating those who maintain programs, which are strictly
180 In most cases, the defaults are what you want. Many of the options
181 below are useful only when building a size-optimized version of
182 liblzma or command line tools.
184 --enable-encoders=LIST
186 Specify a comma-separated LIST of filter encoders to
187 build. See "./configure --help" for exact list of
188 available filter encoders. The default is to build all
191 If LIST is empty or --disable-encoders is used, no filter
192 encoders will be built and also the code shared between
193 encoders will be omitted.
195 Disabling encoders will remove some symbols from the
196 liblzma ABI, so this option should be used only when it
197 is known to not cause problems.
199 --enable-decoders=LIST
201 This is like --enable-encoders but for decoders. The
202 default is to build all supported decoders.
204 --enable-match-finders=LIST
205 liblzma includes two categories of match finders:
206 hash chains and binary trees. Hash chains (hc3 and hc4)
207 are quite fast but they don't provide the best compression
208 ratio. Binary trees (bt2, bt3 and bt4) give excellent
209 compression ratio, but they are slower and need more
210 memory than hash chains.
212 You need to enable at least one match finder to build the
213 LZMA1 or LZMA2 filter encoders. Usually hash chains are
214 used only in the fast mode, while binary trees are used to
215 when the best compression ratio is wanted.
217 The default is to build all the match finders if LZMA1
218 or LZMA2 filter encoders are being built.
221 liblzma support multiple integrity checks. CRC32 is
222 mandatory, and cannot be omitted. See "./configure --help"
223 for exact list of available integrity check types.
225 liblzma and the command line tools can decompress files
226 which use unsupported integrity check type, but naturally
227 the file integrity cannot be verified in that case.
229 Disabling integrity checks may remove some symbols from
230 the liblzma ABI, so this option should be used only when
231 it is known to not cause problems.
237 Don't build and install the command line tool mentioned
240 NOTE: Disabling xz will skip some tests in "make check".
242 NOTE: If xzdec is disabled and lzmadec is left enabled,
243 a dangling man page symlink lzmadec.1 -> xzdec.1 is
247 Don't create symlinks for LZMA Utils compatibility.
248 This includes lzma, unlzma, and lzcat. If scripts are
249 installed, also lzdiff, lzcmp, lzgrep, lzegrep, lzfgrep,
250 lzmore, and lzless will be omitted if this option is used.
253 Don't install the scripts xzdiff, xzgrep, xzmore, xzless,
257 liblzma includes some assembler optimizations. Currently
258 there is only assembler code for CRC32 and CRC64 for
261 All the assembler code in liblzma is position-independent
262 code, which is suitable for use in shared libraries and
263 position-independent executables. So far only i386
264 instructions are used, but the code is optimized for i686
265 class CPUs. If you are compiling liblzma exclusively for
266 pre-i686 systems, you may want to disable the assembler
269 --enable-unaligned-access
270 Allow liblzma to use unaligned memory access for 16-bit
271 and 32-bit loads and stores. This should be enabled only
272 when the hardware supports this, i.e. when unaligned
273 access is fast. Some operating system kernels emulate
274 unaligned access, which is extremely slow. This option
275 shouldn't be used on systems that rely on such emulation.
277 Unaligned access is enabled by default on x86, x86-64,
278 and big endian PowerPC.
281 Reduce the size of liblzma by selecting smaller but
282 semantically equivalent version of some functions, and
283 omit precomputed lookup tables. This option tends to
284 make liblzma slightly slower.
286 Note that while omitting the precomputed tables makes
287 liblzma smaller on disk, the tables are still needed at
288 run time, and need to be computed at startup. This also
289 means that the RAM holding the tables won't be shared
290 between applications linked against shared liblzma.
292 This option doesn't modify CFLAGS to tell the compiler
293 to optimize for size. You need to add -Os or equivalent
294 flag(s) to CFLAGS manually.
296 --enable-assume-ram=SIZE
297 On the most common operating systems, XZ Utils is able to
298 detect the amount of physical memory on the system. This
299 information is used by the options --memlimit-compress,
300 --memlimit-decompress, and --memlimit when setting the
301 limit to a percentage of total RAM.
303 On some systems, there is no code to detect the amount of
304 RAM though. Using --enable-assume-ram one can set how much
305 memory to assume on these systems. SIZE is given as MiB.
306 The default is 128 MiB.
308 Feel free to send patches to add support for detecting
309 the amount of RAM on the operating system you use. See
310 src/common/tuklib_physmem.c for details.
313 Disable threading support. This makes some things
314 thread-unsafe, meaning that if multithreaded application
315 calls liblzma functions from more than one thread,
316 something bad may happen.
318 Use this option if threading support causes you trouble,
319 or if you know that you will use liblzma only from
320 single-threaded applications and want to avoid dependency
324 This enables the assert() macro and possibly some other
325 run-time consistency checks. It makes the code slower, so
326 you normally don't want to have this enabled.
329 If building with GCC, make all compiler warnings an error,
330 that abort the compilation. This may help catching bugs,
331 and should work on most systems. This has no effect on the
335 2.1. Static vs. dynamic linking of liblzma
337 On 32-bit x86, linking against static liblzma can give a minor
338 speed improvement. Static libraries on x86 are usually compiled as
339 position-dependent code (non-PIC) and shared libraries are built as
340 position-independent code (PIC). PIC wastes one register, which can
341 make the code slightly slower compared to a non-PIC version. (Note
342 that this doesn't apply to x86-64.)
344 If you want to link xz against static liblzma, the simplest way
345 is to pass --disable-shared to configure. If you want also shared
346 liblzma, run configure again and run "make install" only for
350 2.2. Optimizing xzdec and lzmadec
352 xzdec and lzmadec are intended to be relatively small instead of
353 optimizing for the best speed. Thus, it is a good idea to build
354 xzdec and lzmadec separately:
356 - To link the tools against static liblzma, pass --disable-shared
359 - To select somewhat size-optimized variant of some things in
360 liblzma, pass --enable-small to configure.
362 - Tell the compiler to optimize for size instead of speed.
363 E.g. with GCC, put -Os into CFLAGS.
365 - xzdec and lzmadec will never use multithreading capabilities of
366 liblzma. You can avoid dependency on libpthread by passing
367 --disable-threads to configure.
369 - There are and will be no translated messages for xzdec and
370 lzmadec, so it is fine to pass also --disable-nls to configure.
372 - Only decoder code is needed, so you can speed up the build
373 slightly by passing --disable-encoders to configure. This
374 shouldn't affect the final size of the executables though,
375 because the linker is able to omit the encoder code anyway.
377 If you have no use for xzdec or lzmadec, you can disable them with
378 --disable-xzdec and --disable-lzmadec.
381 3. xzgrep and other scripts
382 ---------------------------
386 POSIX shell (sh) and bunch of other standard POSIX tools are required
387 to run the scripts. The configure script tries to find a POSIX
388 compliant sh, but if it fails, you can force the shell by passing
389 gl_cv_posix_shell=/path/to/posix-sh as an argument to the configure
392 Some of the scripts require also mktemp. The original mktemp can be
393 found from <http://www.mktemp.org/>. On GNU, most will use the mktemp
394 program from GNU coreutils instead of the original implementation.
395 Both mktemp versions are fine for XZ Utils (and practically for
396 everything else too).
401 The scripts assume that the required tools (standard POSIX utilities,
402 mktemp, and xz) are in PATH; the scripts don't set the PATH themselves.
403 Some people like this while some think this is a bug. Those in the
404 latter group can easily patch the scripts before running the configure
405 script by taking advantage of a placeholder line in the scripts.
407 For example, to make the scripts prefix /usr/bin:/bin to PATH:
409 perl -pi -e 's|^#SET_PATH.*$|PATH=/usr/bin:/bin:\$PATH|' \
416 4.1. "No C99 compiler was found."
418 You need a C99 compiler to build XZ Utils. If the configure script
419 cannot find a C99 compiler and you think you have such a compiler
420 installed, set the compiler command by passing CC=/path/to/c99 as
421 an argument to the configure script.
423 If you get this error even when you think your compiler supports C99,
424 you can override the test by passing ac_cv_prog_cc_c99= as an argument
425 to the configure script. The test for C99 compiler is not perfect (and
426 it is not as easy to make it perfect as it sounds), so sometimes this
427 may be needed. You will get a compile error if your compiler doesn't
431 4.2. "No POSIX conforming shell (sh) was found."
433 xzgrep and other scripts need a shell that (roughly) conforms
434 to POSIX. The configure script tries to find such a shell. If
435 it fails, you can force the shell to be used by passing
436 gl_cv_posix_shell=/path/to/posix-sh as an argument to the configure
440 4.3. configure works but build fails at crc32_x86.S
442 The easy fix is to pass --disable-assembler to the configure script.
444 The configure script determines if assembler code can be used by
445 looking at the configure triplet; there is currently no check if
446 the assembler code can actually actually be built. The x86 assembler
447 code should work on x86 GNU/Linux, *BSDs, Solaris, Darwin, MinGW,
448 Cygwin, and DJGPP. On other x86 systems, there may be problems and
449 the assembler code may need to be disabled with the configure option.
451 If you get this error when building for x86-64, you have specified or
452 the configure script has misguessed your architecture. Pass the
453 correct configure triplet using the --build=CPU-COMPANY-SYSTEM option
454 (see INSTALL.generic).
457 4.4. Lots of warnings about symbol visibility
459 On some systems where symbol visibility isn't supported, GCC may
460 still accept the visibility options and attributes, which will make
461 configure think that visibility is supported. This will result in
462 many compiler warnings. You can avoid the warnings by forcing the
463 visibility support off by passing gl_cv_cc_visibility=no as an
464 argument to the configure script. This has no effect on the
465 resulting binaries, but fewer warnings looks nicer and may allow
466 using --enable-werror.
469 4.5. "make check" fails
471 A likely reason is that libtool links the test programs against
472 an installed version of liblzma instead of the version that was
473 just built. This is obviously a bug which seems to happen on
474 some platforms. A workaround is to uninstall the old liblzma
477 If the problem isn't the one described above, then it's likely
478 a bug in XZ Utils or in the compiler. See the platform-specific
479 notes in this file for possible known problems. Please report
480 a bug if you cannot solve the problem. See README for contact
484 4.6. liblzma.so (or similar) not found when running xz
486 If you installed the package with "make install" and get an error
487 about liblzma.so (or a similarly named file) being missing, try
488 running "ldconfig" to update the run-time linker cache (if your
489 operating system has such a command).