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
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:
- 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
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)
--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:
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
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.
git://wimlib.net / wimlib / blobdiff