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 MinGW + MSYS, 140 MinGW-w64 + MSYS, and Cygwin. There is windows/build.bash to 141 ease packaging XZ Utils with MinGW(-w64) + MSYS into a 142 redistributable .zip or .7z file. See windows/INSTALL-Windows.txt 143 for more information. 144 145 It may be possible to build liblzma with other toolchains too, but 146 that will probably require writing a separate makefile. Building 147 the command line tools with non-GNU toolchains will be harder than 148 building only liblzma. 149 150 Starting with XZ Utils 5.2.0, building liblzma (not the whole 151 XZ Utils) should work with MSVC 2013 update 2 or later using 152 windows/config.h. No project files or makefiles are included yet, 153 so the build process isn't as convenient yet as it could be. 154 155 Even if liblzma is built with MinGW(-w64), the resulting DLL can 156 be used by other compilers and linkers, including MSVC. See 157 windows/README-Windows.txt for details. 158 159 1601.2.8. DOS 161 162 There is an experimental Makefile in the "dos" directory to build 163 XZ Utils on DOS using DJGPP. Support for long file names (LFN) is 164 needed. See dos/README for more information. 165 166 GNU Autotools based build hasn't been tried on DOS. If you try, I 167 would like to hear if it worked. 168 169 1701.3. Adding support for new platforms 171 172 If you have written patches to make XZ Utils to work on previously 173 unsupported platform, please send the patches to me! I will consider 174 including them to the official version. It's nice to minimize the 175 need of third-party patching. 176 177 One exception: Don't request or send patches to change the whole 178 source package to C89. I find C99 substantially nicer to write and 179 maintain. However, the public library headers must be in C89 to 180 avoid frustrating those who maintain programs, which are strictly 181 in C89 or C++. 182 183 1842. configure options 185-------------------- 186 187 In most cases, the defaults are what you want. Many of the options 188 below are useful only when building a size-optimized version of 189 liblzma or command line tools. 190 191 --enable-encoders=LIST 192 --disable-encoders 193 Specify a comma-separated LIST of filter encoders to 194 build. See "./configure --help" for exact list of 195 available filter encoders. The default is to build all 196 supported encoders. 197 198 If LIST is empty or --disable-encoders is used, no filter 199 encoders will be built and also the code shared between 200 encoders will be omitted. 201 202 Disabling encoders will remove some symbols from the 203 liblzma ABI, so this option should be used only when it 204 is known to not cause problems. 205 206 --enable-decoders=LIST 207 --disable-decoders 208 This is like --enable-encoders but for decoders. The 209 default is to build all supported decoders. 210 211 --enable-match-finders=LIST 212 liblzma includes two categories of match finders: 213 hash chains and binary trees. Hash chains (hc3 and hc4) 214 are quite fast but they don't provide the best compression 215 ratio. Binary trees (bt2, bt3 and bt4) give excellent 216 compression ratio, but they are slower and need more 217 memory than hash chains. 218 219 You need to enable at least one match finder to build the 220 LZMA1 or LZMA2 filter encoders. Usually hash chains are 221 used only in the fast mode, while binary trees are used to 222 when the best compression ratio is wanted. 223 224 The default is to build all the match finders if LZMA1 225 or LZMA2 filter encoders are being built. 226 227 --enable-checks=LIST 228 liblzma support multiple integrity checks. CRC32 is 229 mandatory, and cannot be omitted. See "./configure --help" 230 for exact list of available integrity check types. 231 232 liblzma and the command line tools can decompress files 233 which use unsupported integrity check type, but naturally 234 the file integrity cannot be verified in that case. 235 236 Disabling integrity checks may remove some symbols from 237 the liblzma ABI, so this option should be used only when 238 it is known to not cause problems. 239 240 --disable-xz 241 --disable-xzdec 242 --disable-lzmadec 243 --disable-lzmainfo 244 Don't build and install the command line tool mentioned 245 in the option name. 246 247 NOTE: Disabling xz will skip some tests in "make check". 248 249 NOTE: If xzdec is disabled and lzmadec is left enabled, 250 a dangling man page symlink lzmadec.1 -> xzdec.1 is 251 created. 252 253 --disable-lzma-links 254 Don't create symlinks for LZMA Utils compatibility. 255 This includes lzma, unlzma, and lzcat. If scripts are 256 installed, also lzdiff, lzcmp, lzgrep, lzegrep, lzfgrep, 257 lzmore, and lzless will be omitted if this option is used. 258 259 --disable-scripts 260 Don't install the scripts xzdiff, xzgrep, xzmore, xzless, 261 and their symlinks. 262 263 --disable-doc 264 Don't install the documentation files to $docdir 265 (often /usr/doc/xz or /usr/local/doc/xz). Man pages 266 will still be installed. The $docdir can be changed 267 with --docdir=DIR. 268 269 --disable-assembler 270 liblzma includes some assembler optimizations. Currently 271 there is only assembler code for CRC32 and CRC64 for 272 32-bit x86. 273 274 All the assembler code in liblzma is position-independent 275 code, which is suitable for use in shared libraries and 276 position-independent executables. So far only i386 277 instructions are used, but the code is optimized for i686 278 class CPUs. If you are compiling liblzma exclusively for 279 pre-i686 systems, you may want to disable the assembler 280 code. 281 282 --enable-unaligned-access 283 Allow liblzma to use unaligned memory access for 16-bit 284 and 32-bit loads and stores. This should be enabled only 285 when the hardware supports this, i.e. when unaligned 286 access is fast. Some operating system kernels emulate 287 unaligned access, which is extremely slow. This option 288 shouldn't be used on systems that rely on such emulation. 289 290 Unaligned access is enabled by default on x86, x86-64, 291 and big endian PowerPC. 292 293 --enable-small 294 Reduce the size of liblzma by selecting smaller but 295 semantically equivalent version of some functions, and 296 omit precomputed lookup tables. This option tends to 297 make liblzma slightly slower. 298 299 Note that while omitting the precomputed tables makes 300 liblzma smaller on disk, the tables are still needed at 301 run time, and need to be computed at startup. This also 302 means that the RAM holding the tables won't be shared 303 between applications linked against shared liblzma. 304 305 This option doesn't modify CFLAGS to tell the compiler 306 to optimize for size. You need to add -Os or equivalent 307 flag(s) to CFLAGS manually. 308 309 --enable-assume-ram=SIZE 310 On the most common operating systems, XZ Utils is able to 311 detect the amount of physical memory on the system. This 312 information is used by the options --memlimit-compress, 313 --memlimit-decompress, and --memlimit when setting the 314 limit to a percentage of total RAM. 315 316 On some systems, there is no code to detect the amount of 317 RAM though. Using --enable-assume-ram one can set how much 318 memory to assume on these systems. SIZE is given as MiB. 319 The default is 128 MiB. 320 321 Feel free to send patches to add support for detecting 322 the amount of RAM on the operating system you use. See 323 src/common/tuklib_physmem.c for details. 324 325 --enable-threads=METHOD 326 Threading support is enabled by default so normally there 327 is no need to specify this option. 328 329 Supported values for METHOD: 330 331 yes Autodetect the threading method. If none 332 is found, configure will give an error. 333 334 posix Use POSIX pthreads. This is the default 335 except on Windows outside Cygwin. 336 337 win95 Use Windows 95 compatible threads. This 338 is compatible with Windows XP and later 339 too. This is the default for 32-bit x86 340 Windows builds. The `win95' threading is 341 incompatible with --enable-small. 342 343 vista Use Windows Vista compatible threads. The 344 resulting binaries won't run on Windows XP 345 or older. This is the default for Windows 346 excluding 32-bit x86 builds (that is, on 347 x86-64 the default is `vista'). 348 349 no Disable threading support. This is the 350 same as using --disable-threads. 351 NOTE: If combined with --enable-small, the 352 resulting liblzma won't be thread safe, 353 that is, if a multi-threaded application 354 calls any liblzma functions from more than 355 one thread, something bad may happen. 356 357 --enable-symbol-versions 358 Use symbol versioning for liblzma. This is enabled by 359 default on GNU/Linux, other GNU-based systems, and 360 FreeBSD. 361 362 --enable-debug 363 This enables the assert() macro and possibly some other 364 run-time consistency checks. It makes the code slower, so 365 you normally don't want to have this enabled. 366 367 --enable-werror 368 If building with GCC, make all compiler warnings an error, 369 that abort the compilation. This may help catching bugs, 370 and should work on most systems. This has no effect on the 371 resulting binaries. 372 373 3742.1. Static vs. dynamic linking of liblzma 375 376 On 32-bit x86, linking against static liblzma can give a minor 377 speed improvement. Static libraries on x86 are usually compiled as 378 position-dependent code (non-PIC) and shared libraries are built as 379 position-independent code (PIC). PIC wastes one register, which can 380 make the code slightly slower compared to a non-PIC version. (Note 381 that this doesn't apply to x86-64.) 382 383 If you want to link xz against static liblzma, the simplest way 384 is to pass --disable-shared to configure. If you want also shared 385 liblzma, run configure again and run "make install" only for 386 src/liblzma. 387 388 3892.2. Optimizing xzdec and lzmadec 390 391 xzdec and lzmadec are intended to be relatively small instead of 392 optimizing for the best speed. Thus, it is a good idea to build 393 xzdec and lzmadec separately: 394 395 - To link the tools against static liblzma, pass --disable-shared 396 to configure. 397 398 - To select somewhat size-optimized variant of some things in 399 liblzma, pass --enable-small to configure. 400 401 - Tell the compiler to optimize for size instead of speed. 402 E.g. with GCC, put -Os into CFLAGS. 403 404 - xzdec and lzmadec will never use multithreading capabilities of 405 liblzma. You can avoid dependency on libpthread by passing 406 --disable-threads to configure. 407 408 - There are and will be no translated messages for xzdec and 409 lzmadec, so it is fine to pass also --disable-nls to configure. 410 411 - Only decoder code is needed, so you can speed up the build 412 slightly by passing --disable-encoders to configure. This 413 shouldn't affect the final size of the executables though, 414 because the linker is able to omit the encoder code anyway. 415 416 If you have no use for xzdec or lzmadec, you can disable them with 417 --disable-xzdec and --disable-lzmadec. 418 419 4203. xzgrep and other scripts 421--------------------------- 422 4233.1. Dependencies 424 425 POSIX shell (sh) and bunch of other standard POSIX tools are required 426 to run the scripts. The configure script tries to find a POSIX 427 compliant sh, but if it fails, you can force the shell by passing 428 gl_cv_posix_shell=/path/to/posix-sh as an argument to the configure 429 script. 430 431 xzdiff (xzcmp/lzdiff/lzcmp) may use mktemp if it is available. As 432 a fallback xzdiff will use mkdir to securely create a temporary 433 directory. Having mktemp available is still recommended since the 434 mkdir fallback method isn't as robust as mktemp is. The original 435 mktemp can be found from <http://www.mktemp.org/>. On GNU, most will 436 use the mktemp program from GNU coreutils instead of the original 437 implementation. Both mktemp versions are fine. 438 439 In addition to using xz to decompress .xz files, xzgrep and xzdiff 440 use gzip, bzip2, and lzop to support .gz, bz2, and .lzo files. 441 442 4433.2. PATH 444 445 The scripts assume that the required tools (standard POSIX utilities, 446 mktemp, and xz) are in PATH; the scripts don't set the PATH themselves. 447 Some people like this while some think this is a bug. Those in the 448 latter group can easily patch the scripts before running the configure 449 script by taking advantage of a placeholder line in the scripts. 450 451 For example, to make the scripts prefix /usr/bin:/bin to PATH: 452 453 perl -pi -e 's|^#SET_PATH.*$|PATH=/usr/bin:/bin:\$PATH|' \ 454 src/scripts/xz*.in 455 456 4574. Troubleshooting 458------------------ 459 4604.1. "No C99 compiler was found." 461 462 You need a C99 compiler to build XZ Utils. If the configure script 463 cannot find a C99 compiler and you think you have such a compiler 464 installed, set the compiler command by passing CC=/path/to/c99 as 465 an argument to the configure script. 466 467 If you get this error even when you think your compiler supports C99, 468 you can override the test by passing ac_cv_prog_cc_c99= as an argument 469 to the configure script. The test for C99 compiler is not perfect (and 470 it is not as easy to make it perfect as it sounds), so sometimes this 471 may be needed. You will get a compile error if your compiler doesn't 472 support enough C99. 473 474 4754.2. "No POSIX conforming shell (sh) was found." 476 477 xzgrep and other scripts need a shell that (roughly) conforms 478 to POSIX. The configure script tries to find such a shell. If 479 it fails, you can force the shell to be used by passing 480 gl_cv_posix_shell=/path/to/posix-sh as an argument to the configure 481 script. Alternatively you can omit the installation of scripts and 482 this error by passing --disable-scripts to configure. 483 484 4854.3. configure works but build fails at crc32_x86.S 486 487 The easy fix is to pass --disable-assembler to the configure script. 488 489 The configure script determines if assembler code can be used by 490 looking at the configure triplet; there is currently no check if 491 the assembler code can actually actually be built. The x86 assembler 492 code should work on x86 GNU/Linux, *BSDs, Solaris, Darwin, MinGW, 493 Cygwin, and DJGPP. On other x86 systems, there may be problems and 494 the assembler code may need to be disabled with the configure option. 495 496 If you get this error when building for x86-64, you have specified or 497 the configure script has misguessed your architecture. Pass the 498 correct configure triplet using the --build=CPU-COMPANY-SYSTEM option 499 (see INSTALL.generic). 500 501 5024.4. Lots of warnings about symbol visibility 503 504 On some systems where symbol visibility isn't supported, GCC may 505 still accept the visibility options and attributes, which will make 506 configure think that visibility is supported. This will result in 507 many compiler warnings. You can avoid the warnings by forcing the 508 visibility support off by passing gl_cv_cc_visibility=no as an 509 argument to the configure script. This has no effect on the 510 resulting binaries, but fewer warnings looks nicer and may allow 511 using --enable-werror. 512 513 5144.5. "make check" fails 515 516 If the other tests pass but test_scripts.sh fails, then the problem 517 is in the scripts in src/scripts. Comparing the contents of 518 tests/xzgrep_test_output to tests/xzgrep_expected_output might 519 give a good idea about problems in xzgrep. One possibility is that 520 some tools are missing from the current PATH or the tools lack 521 support for some POSIX features. This can happen at least on 522 Solaris where the tools in /bin may be ancient but good enough 523 tools are available in /usr/xpg4/bin or /usr/xpg6/bin. One fix 524 for this problem is described in section 3.2 of this file. 525 526 If tests other than test_scripts.sh fail, a likely reason is that 527 libtool links the test programs against an installed version of 528 liblzma instead of the version that was just built. This is 529 obviously a bug which seems to happen on some platforms. 530 A workaround is to uninstall the old liblzma versions first. 531 532 If the problem isn't any of those described above, then it's likely 533 a bug in XZ Utils or in the compiler. See the platform-specific 534 notes in this file for possible known problems. Please report 535 a bug if you cannot solve the problem. See README for contact 536 information. 537 538 5394.6. liblzma.so (or similar) not found when running xz 540 541 If you installed the package with "make install" and get an error 542 about liblzma.so (or a similarly named file) being missing, try 543 running "ldconfig" to update the run-time linker cache (if your 544 operating system has such a command). 545 546