X-Git-Url: https://wimlib.net/git/?a=blobdiff_plain;f=README;h=95f990d9cf0d5a9e1c5f0ac811b8e58eade35b51;hb=df4b628740bef19eb067459d02a789fbf8d3a479;hp=2a171888a438eb96511ced9b53b074121e18a443;hpb=29b2d3d6b0f9f30c9e119714c34598a51fb71d6a;p=wimlib diff --git a/README b/README index 2a171888..95f990d9 100644 --- a/README +++ b/README @@ -1,17 +1,16 @@ INTRODUCTION -This is wimlib version 1.7.1-BETA (June 2014). wimlib is a C library for +This is wimlib version 1.7.2-BETA (August 2014). wimlib is a C library for creating, modifying, extracting, and mounting files in the Windows Imaging -Format (WIM files). These files are normally created using the ImageX -(imagex.exe) or Dism (Dism.exe) utilities on Windows, but wimlib is distributed -with a free implementation of ImageX called "wimlib-imagex" for both UNIX-like -systems and Windows. +Format (WIM files). wimlib and its command-line frontend 'wimlib-imagex' +provide a free and cross-platform alternative to Microsoft's WIMGAPI, ImageX, +and DISM. INSTALLATION -To install wimlib and wimlib-imagex on Windows you simply need to download and -extract the ZIP file containing the latest binaries from the SourceForge page -(http://sourceforge.net/projects/wimlib/), which you may have already done. +To install wimlib and wimlib-imagex on Windows, simply download and extract the +ZIP file containing the latest binaries from the SourceForge page +(http://sourceforge.net/projects/wimlib/). You probably have already done this! To install wimlib and wimlib-imagex on UNIX-like systems (with Linux being the primary supported and tested platform), you must compile the source code, which @@ -79,18 +78,18 @@ create the file. When applicable, the results with the equivalent Microsoft implementation in WIMGAPI is included. ============================================================================= - | Compression || wimlib (v1.7.1) | WIMGAPI (Windows 8.1) | + | Compression || wimlib (v1.7.2-BETA) | WIMGAPI (Windows 8.1) | ============================================================================= - | None [1] || 361,182,560 in 3.7s | 361,183,674 in 4.4s | - | XPRESS [2] || 138,349,798 in 5.8s | 140,416,657 in 6.8s | - | XPRESS (slow) [3] || 135,234,072 in 19.5s | N/A | - | LZX (quick) [4] || 131,816,279 in 6.7s | N/A | - | LZX (normal) [5] || 126,808,347 in 28.3s | 127,259,566 in 31.4s | - | LZX (slow) [6] || 126,199,523 in 61.4s | N/A | - | LZMS (non-solid) [7] || 122,083,126 in 30.4s | N/A | - | LZMS (solid) [8] || 93,752,206 in 84.3s | 88,742,238 in 156.1s | - | "WIMBoot" [9] || 167,039,787 in 7.6s | 169,051,718 in 14.9s | - | "WIMBoot" (slow) [10] || 165,141,503 in 15.8s | N/A | + | None [1] || 361,404,682 in 3.4s | 361,364,994 in 4.2s | + | XPRESS [2] || 138,398,747 in 4.2s | 140,468,002 in 5.1s | + | XPRESS (slow) [3] || 135,284,950 in 10.3s | N/A | + | LZX (quick) [4] || 131,861,913 in 4.7s | N/A | + | LZX (normal) [5] || 126,855,247 in 14.9s | 127,301,774 in 18.2s | + | LZX (slow) [6] || 126,245,561 in 32.1s | N/A | + | LZMS (non-solid) [7] || 122,126,328 in 16.4s | N/A | + | LZMS (solid) [8] || 93,795,440 in 47.4s | 88,789,426 in 96.8s | + | "WIMBoot" [9] || 167,121,495 in 5.3s | 169,124,968 in 9.3s | + | "WIMBoot" (slow) [10] || 165,219,818 in 9.4s | N/A | ============================================================================= Notes: @@ -134,7 +133,7 @@ Testing environment: - 64 bit binaries - Windows 8.1 virtual machine running on Linux with VT-x - - 2 CPUs and 2 GiB memory given to virtual machine + - 4 CPUs and 4 GiB memory given to virtual machine - SSD-backed virtual disk - All tests done with page cache warmed @@ -233,31 +232,34 @@ downloaded the Windows binary distribution of wimlib and wimlib-imagex then all dependencies were already included and this section is irrelevant. * libxml2 (required) - This is a commonly used free library to read and write XML files. You - likely already have it installed as a dependency for some other program. - For more information see http://xmlsoft.org/. - -* libfuse (optional but highly recommended) - Unless configured with --without-fuse, wimlib requires a non-ancient - version of libfuse to be installed. Most Linux distributions already - include this, but make sure you have the libfuse package installed, and - also libfuse-dev if your distribution distributes header files - separately. FUSE also requires a kernel module. If the kernel module - is available it will automatically be loaded if you try to mount a WIM - file. For more information see http://fuse.sourceforge.net/. FUSE is - also available for FreeBSD. - -* libntfs-3g (optional but highly recommended) - Unless configured with --without-ntfs-3g, wimlib requires the library - and headers for libntfs-3g version 2011-4-12 or later to be installed. - Versions dated 2010-3-6 and earlier do not work because they are missing - the header xattrs.h (and the file xattrs.c, which contains functions we - need). libntfs-3g version 2013-1-13 is compatible only with wimlib - 1.2.4 and later. + This is a commonly used free library to read and write XML documents. + Almost all Linux distributions should include this; however, you may + need to install the header files, which might be in a package named + "libxml2-dev" or similar. For more information see http://xmlsoft.org/. + +* libfuse (optional but recommended) + Unless configured --without-fuse, wimlib requires a non-ancient version + of libfuse. Most Linux distributions already include this, but make + sure you have the libfuse package installed, and also libfuse-dev if + your distribution distributes header files separately. FUSE also + requires a kernel module. If the kernel module is available it should + automatically be loaded if you try to mount a WIM image. For more + information see http://fuse.sourceforge.net/. + +* libattr (optional but recommended) + Unless configured --without-fuse, wimlib also requires libattr. Almost + all Linux distributions should include this; however, you may need to + install the header files, which might be in a package named "attr-dev", + "libattr1-dev", or similar. + +* libntfs-3g (optional but recommended) + Unless configured --without-ntfs-3g, wimlib requires the library and + headers for libntfs-3g version 2011-4-12 or later to be installed. * OpenSSL / libcrypto (optional) - wimlib can use the SHA1 message digest code from OpenSSL instead of - compiling in yet another SHA1 implementation. (See LICENSE section.) + wimlib can use the SHA-1 message digest implementation from libcrypto + (usually provided by OpenSSL) instead of compiling in yet another SHA-1 + implementation. * cdrkit (optional) * mtools (optional) @@ -280,76 +282,70 @@ This section documents the most important options that may be passed to the --without-ntfs-3g If libntfs-3g is not available or is not version 2011-4-12 or later, wimlib can be built without it, in which case it will not be possible to - apply or capture images directly to/from NTFS volumes. + capture or apply WIM images directly from/to NTFS volumes. ---without-fuse - If libfuse or the FUSE kernel module is not available, wimlib can be - compiled with --without-fuse. This will remove the ability to mount and - unmount WIM files. - ---without-libcrypto - Build in functions for SHA1 rather than using external SHA1 functions - from libcrypto (part of OpenSSL). The default is to use libcrypto if it - is found on the system. + The default is --with-ntfs-3g when building for any UNIX-like system, + and --without-ntfs-3g when building for Windows. ---disable-multithreaded-compression - By default, data will be compressed using multiple threads when writing - a WIM, unless only 1 processor is detected. Specify this option to - disable support for this. +--without-fuse + The --without-fuse option completely disables support for mounting WIM + images. This removes dependencies on libfuse, librt, and libattr. The + wimmount, wimmountrw, and wimunmount commands will not work. ---enable-ssse3-sha1 - Use a very fast assembly language implementation of SHA1 from Intel. - Only use this if the build target supports the SSSE3 instructions. + The default is --with-fuse when building for Linux, and --without-fuse + otherwise. ---disable-error-messages - Save some space by removing all error messages from the library. +--without-libcrypto + Build in functions for SHA-1 rather than using external SHA-1 functions + from libcrypto (usually provided by OpenSSL). ---disable-assertions - Remove assertions included by default. + The default is to use libcrypto if it is found on your system. PORTABILITY -wimlib has primarily been tested on Linux and Windows (primarily Windows 7, but -also Windows XP and Windows 8). +wimlib works on both UNIX-like systems (Linux, Mac OS X, FreeBSD, etc.) and +Windows (XP and later). -wimlib may work on FreeBSD and Mac OS X. However, this is not well tested. If -you do not have libntfs-3g 2011-4-12 or later available, you must configure -wimlib with --without-ntfs-3g. On FreeBSD, before mounting a WIM you need to -load the POSIX message queue module (run `kldload mqueuefs'). +As much code as possible is shared among all supported platforms, but there +necessarily are some differences in what features are supported on each platform +and how they are implemented. Most notable is that file tree scanning and +extraction are implemented separately for Windows, UNIX, and UNIX (NTFS-3g +mode), to ensure a fast and feature-rich implementation of each platform/mode. -The code has primarily been tested on x86 and x86_64 CPUs, but it's written to -be portable to other architectures and I've also tested it on ARM. However, -although the code is written to correctly deal with endianness, it has not yet -actually been tested on a big-endian architecture. +wimlib is mainly used on x86 and x86_64 CPUs, but it should also work on a +number of other GCC-supported 32-bit or 64-bit architectures. No assumptions +are made about endianness, but some code assumes that unaligned memory accesses +are supported and relatively efficient. + +Currently, gcc and clang are the only supported compilers. A few nonstandard +extensions are used in the code. REFERENCES The WIM file format is partially specified in a document that can be found in the Microsoft Download Center. However, this document really only provides an -overview of the format and is not a formal specification. +overview of the format and is not a formal specification. It also does not +cover later extensions of the format, such as solid blocks. With regards to the supported compression formats: - Microsoft has official documentation for XPRESS that is of reasonable quality. -- Microsoft has official documentation for LZX but it contains errors. +- Microsoft has official documentation for LZX, but in two different documents, + neither of which is completely applicable to its use in the WIM format, and + the first of which contains multiple errors. - There does not seem to be any official documentation for LZMS, so my comments and code in src/lzms-decompress.c may in fact be the best documentation available for this particular compression format. +The algorithms used by wimlib's compression and decompression codecs are +inspired by a variety of sources, including open source projects and computer +science papers. + The code in ntfs-3g_apply.c and ntfs-3g_capture.c uses the NTFS-3g library, which is a library for reading and writing to NTFS filesystems (the filesystem used by recent versions of Windows). See http://www.tuxera.com/community/ntfs-3g-download/ for more information. -The LZX decompressor (lzx-decompress.c) was originally based on code from the -cabextract project (http://www.cabextract.org.uk). The LZX compressor -(lzx-compress.c) was originally based on code written by Matthew Russotto -(www.russotto.net/chm/). However I have since rewritten and made many -improvements to both the decompressor and compressor. - -lz_binary_trees.c contains LZ77 match-finding code that uses binary trees. It -is based on code from liblzma but I have since rewritten it. - A limited number of other free programs can handle some parts of the WIM file format: @@ -357,8 +353,9 @@ file format: other archive formats). However, wimlib is designed specifically to handle WIM files and provides features previously only available in Microsoft's implementation, such as the ability to mount WIMs read-write as well as - read-only, the ability to create compressed WIMs, and the correct handling - of security descriptors and hard links. + read-only, the ability to create compressed WIMs, the correct handling of + security descriptors and hard links, support for LZMS compression, and + support for solid archives. * ImagePyX (https://github.com/maxpat78/ImagePyX) is a Python program that provides similar capabilities to wimlib-imagex. One thing to note, though, is that it does not support compression and decompression by itself, but @@ -386,7 +383,3 @@ functionality. wimlib comes with no warranty whatsoever. Please submit a bug report (to ebiggers3@gmail.com) if you find a bug in wimlib and/or wimlib-imagex. - -Be aware that some parts of the WIM file format are poorly documented or even -completely undocumented, so I've just had to do the best I can to read and write -WIMs that appear to be compatible with Microsoft's software.