1 2XZ Utils Installation 3===================== 4 5 0. Preface 6 1. Supported platforms 7 1.1. Compilers 8 1.2. Platform-specific notes 9 1.2.1. AIX 10 1.2.2. IRIX 11 1.2.3. MINIX 3 12 1.2.4. OpenVMS 13 1.2.5. Solaris, OpenSolaris, and derivatives 14 1.2.6. Tru64 15 1.2.7. Windows 16 1.2.8. DOS 17 1.3. Adding support for new platforms 18 2. configure options 19 2.1. Static vs. dynamic linking of liblzma 20 2.2. Optimizing xzdec and lzmadec 21 3. xzgrep and other scripts 22 3.1. Dependencies 23 3.2. PATH 24 4. Troubleshooting 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 31 32 330. Preface 34---------- 35 36 If you aren't familiar with building packages that use GNU Autotools, 37 see the file INSTALL.generic for generic instructions before reading 38 further. 39 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. 45 46 471. Supported platforms 48---------------------- 49 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. 53 54 551.1. Compilers 56 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 60 XZ Utils. 61 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. 65 66 671.2. Platform-specific notes 68 691.2.1. AIX 70 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). 74 75 761.2.2. IRIX 77 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 80 work. 81 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. 85 86 871.2.3. MINIX 3 88 89 The default install of MINIX 3 includes Amsterdam Compiler Kit (ACK), 90 which doesn't support C99. Install GCC to compile XZ Utils. 91 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>. 95 96 MINIX 3.2.0 and later use a different libc and aren't affected by 97 the above bug. 98 99 XZ Utils doesn't have code to detect the amount of physical RAM and 100 number of CPU cores on MINIX 3. 101 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). 104 105 1061.2.4. OpenVMS 107 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 111 downloaded here: 112 113 http://nchrem.tnw.tudelft.nl/openvms/software2.html#xzutils 114 115 1161.2.5. Solaris, OpenSolaris, and derivatives 117 118 The following linker error has been reported on some x86 systems: 119 120 ld: fatal: relocation error: R_386_GOTOFF: ... 121 122 This can be worked around by passing gl_cv_cc_visibility=no 123 as an argument to the configure script. 124 125 test_scripts.sh in "make check" may fail if good enough tools are 126 missing from PATH (/usr/xpg4/bin or /usr/xpg6/bin). See sections 127 4.5 and 3.2 for more information. 128 129 1301.2.6. Tru64 131 132 If you try to use the native C compiler on Tru64 (passing CC=cc to 133 configure), you may need the workaround mention in section 4.1 in 134 this file (pass also ac_cv_prog_cc_c99= to configure). 135 136 1371.2.7. Windows 138 139 Building XZ Utils on Windows is supported under the following 140 environments: 141 142 - MinGW-w64 + MSYS (32-bit and 64-bit x86): This is used 143 for building the official binary packages for Windows. 144 There is windows/build.bash to ease packaging XZ Utils with 145 MinGW(-w64) + MSYS into a redistributable .zip or .7z file. 146 See windows/INSTALL-MinGW.txt for more information. 147 148 - MinGW + MSYS (32-bit x86): I haven't recently tested this. 149 150 - Cygwin 1.7.35 and later: NOTE that using XZ Utils >= 5.2.0 151 under Cygwin older than 1.7.35 can lead to DATA LOSS! If 152 you must use an old Cygwin version, stick to XZ Utils 5.0.x 153 which is safe under older Cygwin versions. You can check 154 the Cygwin version with the command "cygcheck -V". 155 156 - Microsoft Visual Studio 2013 update 2 or later (MSVC for short): 157 See windows/INSTALL-MSVC.txt for more information. 158 159 It may be possible to build liblzma with other toolchains too, but 160 that will probably require writing a separate makefile. Building 161 the command line tools with non-GNU toolchains will be harder than 162 building only liblzma. 163 164 Even if liblzma is built with MinGW(-w64), the resulting DLL can 165 be used by other compilers and linkers, including MSVC. See 166 windows/README-Windows.txt for details. 167 168 1691.2.8. DOS 170 171 There is an experimental Makefile in the "dos" directory to build 172 XZ Utils on DOS using DJGPP. Support for long file names (LFN) is 173 needed. See dos/README for more information. 174 175 GNU Autotools based build hasn't been tried on DOS. If you try, I 176 would like to hear if it worked. 177 178 1791.3. Adding support for new platforms 180 181 If you have written patches to make XZ Utils to work on previously 182 unsupported platform, please send the patches to me! I will consider 183 including them to the official version. It's nice to minimize the 184 need of third-party patching. 185 186 One exception: Don't request or send patches to change the whole 187 source package to C89. I find C99 substantially nicer to write and 188 maintain. However, the public library headers must be in C89 to 189 avoid frustrating those who maintain programs, which are strictly 190 in C89 or C++. 191 192 1932. configure options 194-------------------- 195 196 In most cases, the defaults are what you want. Many of the options 197 below are useful only when building a size-optimized version of 198 liblzma or command line tools. 199 200 --enable-encoders=LIST 201 --disable-encoders 202 Specify a comma-separated LIST of filter encoders to 203 build. See "./configure --help" for exact list of 204 available filter encoders. The default is to build all 205 supported encoders. 206 207 If LIST is empty or --disable-encoders is used, no filter 208 encoders will be built and also the code shared between 209 encoders will be omitted. 210 211 Disabling encoders will remove some symbols from the 212 liblzma ABI, so this option should be used only when it 213 is known to not cause problems. 214 215 --enable-decoders=LIST 216 --disable-decoders 217 This is like --enable-encoders but for decoders. The 218 default is to build all supported decoders. 219 220 --enable-match-finders=LIST 221 liblzma includes two categories of match finders: 222 hash chains and binary trees. Hash chains (hc3 and hc4) 223 are quite fast but they don't provide the best compression 224 ratio. Binary trees (bt2, bt3 and bt4) give excellent 225 compression ratio, but they are slower and need more 226 memory than hash chains. 227 228 You need to enable at least one match finder to build the 229 LZMA1 or LZMA2 filter encoders. Usually hash chains are 230 used only in the fast mode, while binary trees are used to 231 when the best compression ratio is wanted. 232 233 The default is to build all the match finders if LZMA1 234 or LZMA2 filter encoders are being built. 235 236 --enable-checks=LIST 237 liblzma support multiple integrity checks. CRC32 is 238 mandatory, and cannot be omitted. See "./configure --help" 239 for exact list of available integrity check types. 240 241 liblzma and the command line tools can decompress files 242 which use unsupported integrity check type, but naturally 243 the file integrity cannot be verified in that case. 244 245 Disabling integrity checks may remove some symbols from 246 the liblzma ABI, so this option should be used only when 247 it is known to not cause problems. 248 249 --enable-external-sha256 250 Try to use SHA-256 code from the operating system libc 251 or similar base system libraries. This doesn't try to 252 use OpenSSL or libgcrypt or such libraries. 253 254 The reasons to use this option: 255 256 - It makes liblzma slightly smaller. 257 258 - It might improve SHA-256 speed if the implementation 259 in the operating is very good (but see below). 260 261 External SHA-256 is disabled by default for two reasons: 262 263 - On some operating systems the symbol names of the 264 SHA-256 functions conflict with OpenSSL's libcrypto. 265 This causes weird problems such as decompression 266 errors if an application is linked against both 267 liblzma and libcrypto. This problem affects at least 268 FreeBSD 10 and older and MINIX 3.3.0 and older, but 269 other OSes that provide a function "SHA256_Init" might 270 also be affected. FreeBSD 11 has the problem fixed. 271 NetBSD had the problem but it was fixed it in 2009 272 already. OpenBSD uses "SHA256Init" and thus never had 273 a conflict with libcrypto. 274 275 - The SHA-256 code in liblzma is faster than the SHA-256 276 code provided by some operating systems. If you are 277 curious, build two copies of xz (internal and external 278 SHA-256) and compare the decompression (xz --test) 279 times: 280 281 dd if=/dev/zero bs=1024k count=1024 \ 282 | xz -v -0 -Csha256 > foo.xz 283 time xz --test foo.xz 284 285 --disable-xz 286 --disable-xzdec 287 --disable-lzmadec 288 --disable-lzmainfo 289 Don't build and install the command line tool mentioned 290 in the option name. 291 292 NOTE: Disabling xz will skip some tests in "make check". 293 294 NOTE: If xzdec is disabled and lzmadec is left enabled, 295 a dangling man page symlink lzmadec.1 -> xzdec.1 is 296 created. 297 298 --disable-lzma-links 299 Don't create symlinks for LZMA Utils compatibility. 300 This includes lzma, unlzma, and lzcat. If scripts are 301 installed, also lzdiff, lzcmp, lzgrep, lzegrep, lzfgrep, 302 lzmore, and lzless will be omitted if this option is used. 303 304 --disable-scripts 305 Don't install the scripts xzdiff, xzgrep, xzmore, xzless, 306 and their symlinks. 307 308 --disable-doc 309 Don't install the documentation files to $docdir 310 (often /usr/doc/xz or /usr/local/doc/xz). Man pages 311 will still be installed. The $docdir can be changed 312 with --docdir=DIR. 313 314 --disable-assembler 315 liblzma includes some assembler optimizations. Currently 316 there is only assembler code for CRC32 and CRC64 for 317 32-bit x86. 318 319 All the assembler code in liblzma is position-independent 320 code, which is suitable for use in shared libraries and 321 position-independent executables. So far only i386 322 instructions are used, but the code is optimized for i686 323 class CPUs. If you are compiling liblzma exclusively for 324 pre-i686 systems, you may want to disable the assembler 325 code. 326 327 --enable-unaligned-access 328 Allow liblzma to use unaligned memory access for 16-bit 329 and 32-bit loads and stores. This should be enabled only 330 when the hardware supports this, i.e. when unaligned 331 access is fast. Some operating system kernels emulate 332 unaligned access, which is extremely slow. This option 333 shouldn't be used on systems that rely on such emulation. 334 335 Unaligned access is enabled by default on x86, x86-64, 336 and big endian PowerPC. 337 338 --enable-small 339 Reduce the size of liblzma by selecting smaller but 340 semantically equivalent version of some functions, and 341 omit precomputed lookup tables. This option tends to 342 make liblzma slightly slower. 343 344 Note that while omitting the precomputed tables makes 345 liblzma smaller on disk, the tables are still needed at 346 run time, and need to be computed at startup. This also 347 means that the RAM holding the tables won't be shared 348 between applications linked against shared liblzma. 349 350 This option doesn't modify CFLAGS to tell the compiler 351 to optimize for size. You need to add -Os or equivalent 352 flag(s) to CFLAGS manually. 353 354 --enable-assume-ram=SIZE 355 On the most common operating systems, XZ Utils is able to 356 detect the amount of physical memory on the system. This 357 information is used by the options --memlimit-compress, 358 --memlimit-decompress, and --memlimit when setting the 359 limit to a percentage of total RAM. 360 361 On some systems, there is no code to detect the amount of 362 RAM though. Using --enable-assume-ram one can set how much 363 memory to assume on these systems. SIZE is given as MiB. 364 The default is 128 MiB. 365 366 Feel free to send patches to add support for detecting 367 the amount of RAM on the operating system you use. See 368 src/common/tuklib_physmem.c for details. 369 370 --enable-threads=METHOD 371 Threading support is enabled by default so normally there 372 is no need to specify this option. 373 374 Supported values for METHOD: 375 376 yes Autodetect the threading method. If none 377 is found, configure will give an error. 378 379 posix Use POSIX pthreads. This is the default 380 except on Windows outside Cygwin. 381 382 win95 Use Windows 95 compatible threads. This 383 is compatible with Windows XP and later 384 too. This is the default for 32-bit x86 385 Windows builds. The `win95' threading is 386 incompatible with --enable-small. 387 388 vista Use Windows Vista compatible threads. The 389 resulting binaries won't run on Windows XP 390 or older. This is the default for Windows 391 excluding 32-bit x86 builds (that is, on 392 x86-64 the default is `vista'). 393 394 no Disable threading support. This is the 395 same as using --disable-threads. 396 NOTE: If combined with --enable-small, the 397 resulting liblzma won't be thread safe, 398 that is, if a multi-threaded application 399 calls any liblzma functions from more than 400 one thread, something bad may happen. 401 402 --enable-sandbox=METHOD 403 This feature is EXPERIMENTAL in the XZ Utils 5.2.x and 404 disabled by default. If you test this, look especially 405 if message translations and locale-specific decimal and 406 thousand separators (e.g. xz --list foo.xz) work the 407 same way as they do without sandboxing. 408 409 There is limited sandboxing support in the xz tool. If 410 built with sandbox support, it's used automatically when 411 (de)compressing exactly one file to standard output and 412 the options --files or --files0 weren't used. This is a 413 common use case, for example, (de)compressing .tar.xz 414 files via GNU tar. The sandbox is also used for 415 single-file `xz --test' or `xz --list'. 416 417 Supported METHODs: 418 419 auto Look for a supported sandboxing method 420 and use it if found. If no method is 421 found, then sandboxing isn't used. 422 423 no Disable sandboxing support. 424 425 capsicum 426 Use Capsicum (FreeBSD >= 10) for 427 sandboxing. If no Capsicum support 428 is found, configure will give an error. 429 430 --enable-symbol-versions 431 Use symbol versioning for liblzma. This is enabled by 432 default on GNU/Linux, other GNU-based systems, and 433 FreeBSD. 434 435 --enable-debug 436 This enables the assert() macro and possibly some other 437 run-time consistency checks. It makes the code slower, so 438 you normally don't want to have this enabled. 439 440 --enable-werror 441 If building with GCC, make all compiler warnings an error, 442 that abort the compilation. This may help catching bugs, 443 and should work on most systems. This has no effect on the 444 resulting binaries. 445 446 4472.1. Static vs. dynamic linking of liblzma 448 449 On 32-bit x86, linking against static liblzma can give a minor 450 speed improvement. Static libraries on x86 are usually compiled as 451 position-dependent code (non-PIC) and shared libraries are built as 452 position-independent code (PIC). PIC wastes one register, which can 453 make the code slightly slower compared to a non-PIC version. (Note 454 that this doesn't apply to x86-64.) 455 456 If you want to link xz against static liblzma, the simplest way 457 is to pass --disable-shared to configure. If you want also shared 458 liblzma, run configure again and run "make install" only for 459 src/liblzma. 460 461 4622.2. Optimizing xzdec and lzmadec 463 464 xzdec and lzmadec are intended to be relatively small instead of 465 optimizing for the best speed. Thus, it is a good idea to build 466 xzdec and lzmadec separately: 467 468 - To link the tools against static liblzma, pass --disable-shared 469 to configure. 470 471 - To select somewhat size-optimized variant of some things in 472 liblzma, pass --enable-small to configure. 473 474 - Tell the compiler to optimize for size instead of speed. 475 E.g. with GCC, put -Os into CFLAGS. 476 477 - xzdec and lzmadec will never use multithreading capabilities of 478 liblzma. You can avoid dependency on libpthread by passing 479 --disable-threads to configure. 480 481 - There are and will be no translated messages for xzdec and 482 lzmadec, so it is fine to pass also --disable-nls to configure. 483 484 - Only decoder code is needed, so you can speed up the build 485 slightly by passing --disable-encoders to configure. This 486 shouldn't affect the final size of the executables though, 487 because the linker is able to omit the encoder code anyway. 488 489 If you have no use for xzdec or lzmadec, you can disable them with 490 --disable-xzdec and --disable-lzmadec. 491 492 4933. xzgrep and other scripts 494--------------------------- 495 4963.1. Dependencies 497 498 POSIX shell (sh) and bunch of other standard POSIX tools are required 499 to run the scripts. The configure script tries to find a POSIX 500 compliant sh, but if it fails, you can force the shell by passing 501 gl_cv_posix_shell=/path/to/posix-sh as an argument to the configure 502 script. 503 504 xzdiff (xzcmp/lzdiff/lzcmp) may use mktemp if it is available. As 505 a fallback xzdiff will use mkdir to securely create a temporary 506 directory. Having mktemp available is still recommended since the 507 mkdir fallback method isn't as robust as mktemp is. The original 508 mktemp can be found from <http://www.mktemp.org/>. On GNU, most will 509 use the mktemp program from GNU coreutils instead of the original 510 implementation. Both mktemp versions are fine. 511 512 In addition to using xz to decompress .xz files, xzgrep and xzdiff 513 use gzip, bzip2, and lzop to support .gz, bz2, and .lzo files. 514 515 5163.2. PATH 517 518 The scripts assume that the required tools (standard POSIX utilities, 519 mktemp, and xz) are in PATH; the scripts don't set the PATH themselves. 520 Some people like this while some think this is a bug. Those in the 521 latter group can easily patch the scripts before running the configure 522 script by taking advantage of a placeholder line in the scripts. 523 524 For example, to make the scripts prefix /usr/bin:/bin to PATH: 525 526 perl -pi -e 's|^#SET_PATH.*$|PATH=/usr/bin:/bin:\$PATH|' \ 527 src/scripts/xz*.in 528 529 5304. Troubleshooting 531------------------ 532 5334.1. "No C99 compiler was found." 534 535 You need a C99 compiler to build XZ Utils. If the configure script 536 cannot find a C99 compiler and you think you have such a compiler 537 installed, set the compiler command by passing CC=/path/to/c99 as 538 an argument to the configure script. 539 540 If you get this error even when you think your compiler supports C99, 541 you can override the test by passing ac_cv_prog_cc_c99= as an argument 542 to the configure script. The test for C99 compiler is not perfect (and 543 it is not as easy to make it perfect as it sounds), so sometimes this 544 may be needed. You will get a compile error if your compiler doesn't 545 support enough C99. 546 547 5484.2. "No POSIX conforming shell (sh) was found." 549 550 xzgrep and other scripts need a shell that (roughly) conforms 551 to POSIX. The configure script tries to find such a shell. If 552 it fails, you can force the shell to be used by passing 553 gl_cv_posix_shell=/path/to/posix-sh as an argument to the configure 554 script. Alternatively you can omit the installation of scripts and 555 this error by passing --disable-scripts to configure. 556 557 5584.3. configure works but build fails at crc32_x86.S 559 560 The easy fix is to pass --disable-assembler to the configure script. 561 562 The configure script determines if assembler code can be used by 563 looking at the configure triplet; there is currently no check if 564 the assembler code can actually actually be built. The x86 assembler 565 code should work on x86 GNU/Linux, *BSDs, Solaris, Darwin, MinGW, 566 Cygwin, and DJGPP. On other x86 systems, there may be problems and 567 the assembler code may need to be disabled with the configure option. 568 569 If you get this error when building for x86-64, you have specified or 570 the configure script has misguessed your architecture. Pass the 571 correct configure triplet using the --build=CPU-COMPANY-SYSTEM option 572 (see INSTALL.generic). 573 574 5754.4. Lots of warnings about symbol visibility 576 577 On some systems where symbol visibility isn't supported, GCC may 578 still accept the visibility options and attributes, which will make 579 configure think that visibility is supported. This will result in 580 many compiler warnings. You can avoid the warnings by forcing the 581 visibility support off by passing gl_cv_cc_visibility=no as an 582 argument to the configure script. This has no effect on the 583 resulting binaries, but fewer warnings looks nicer and may allow 584 using --enable-werror. 585 586 5874.5. "make check" fails 588 589 If the other tests pass but test_scripts.sh fails, then the problem 590 is in the scripts in src/scripts. Comparing the contents of 591 tests/xzgrep_test_output to tests/xzgrep_expected_output might 592 give a good idea about problems in xzgrep. One possibility is that 593 some tools are missing from the current PATH or the tools lack 594 support for some POSIX features. This can happen at least on 595 Solaris where the tools in /bin may be ancient but good enough 596 tools are available in /usr/xpg4/bin or /usr/xpg6/bin. One fix 597 for this problem is described in section 3.2 of this file. 598 599 If tests other than test_scripts.sh fail, a likely reason is that 600 libtool links the test programs against an installed version of 601 liblzma instead of the version that was just built. This is 602 obviously a bug which seems to happen on some platforms. 603 A workaround is to uninstall the old liblzma versions first. 604 605 If the problem isn't any of those described above, then it's likely 606 a bug in XZ Utils or in the compiler. See the platform-specific 607 notes in this file for possible known problems. Please report 608 a bug if you cannot solve the problem. See README for contact 609 information. 610 611 6124.6. liblzma.so (or similar) not found when running xz 613 614 If you installed the package with "make install" and get an error 615 about liblzma.so (or a similarly named file) being missing, try 616 running "ldconfig" to update the run-time linker cache (if your 617 operating system has such a command). 618 619