+++ /dev/null
- INTRODUCTION
-
-This is wimlib version 1.6.0 (January 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.
-
- 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 UNIX-like systems (with Linux being the
-primary supported and tested platform), you must compile the source code, which
-is also available at http://sourceforge.net/projects/wimlib/. Alternatively,
-check if a package has been prepared for your Linux distribution. Example files
-for Debian and RPM packaging are in the debian/ and rpm/ directories.
-
- WIM FILES
-
-A Windows Imaging (WIM) file is an archive designed primarily for archiving
-Windows filesystems. However, it can be used on other platforms as well, with
-some limitations. Like some other archive formats such as ZIP, files in WIM
-archives may be compressed. WIM files support multiple compression formats,
-including LZX, XPRESS, and LZMS. All these formats are supported by wimlib.
-
-A WIM file consists of one or more "images". Each image is an independent
-top-level directory structure and is logically separate from all other images in
-the WIM. Each image has a name as well as a 1-based index in the WIM file. To
-save space, WIM archives automatically combine all duplicate files across all
-images.
-
-A WIM file may be either stand-alone or split into multiple parts. Split WIMs
-are read-only and cannot be modified.
-
- IMAGEX IMPLEMENTATION
-
-wimlib itself is a C library, and it provides a documented public API (See:
-http://wimlib.sourceforge.net) for other programs to use. However, it is also
-distributed with a command-line program called "wimlib-imagex" that uses this
-library to implement an imaging tool similar to Microsoft's ImageX.
-wimlib-imagex supports almost all the capabilities of Microsoft's ImageX as well
-as additional capabilities. wimlib-imagex works on both UNIX-like systems and
-Windows, although some features differ between the platforms.
-
-Run `wimlib-imagex' with no arguments to see an overview of the available
-commands and their syntax. For additional documentation:
-
- * If you have installed wimlib-imagex on a UNIX-like system, you will find
- further documentation in the man pages; run `man wimlib-imagex' to get
- started.
-
- * If you have downloaded the Windows binary distribution, you will find the
- documentation for wimlib-imagex in PDF format in the "doc" directory,
- ready for viewing with any PDF viewer. Please note that although the PDF
- files are converted from UNIX-style "man pages", they do document
- Windows-specific behavior when appropriate.
-
- COMPRESSION RATIO
-
-wimlib (and wimlib-imagex) can create XPRESS, LZX, or LZMS compressed WIM archives.
-The following tables compare the compression ratio and performance for creating
-a compressed x86_64 Windows PE image. Note: these timings were done on Windows
-so that the times would be fully comparable; however, wimlib may have even
-better performance on other operating systems such as Linux. Timings were done
-with 2 CPUs available, both of which automatically are used by wimlib for both
-XPRESS and LZX, and also by imagex.exe but apparently only for LZX. Results for
-LZMS compression are excluded because the creation of LZMS compressed WIM
-archives is not yet recommended.
-
- Table 1. WIM size
-
- XPRESS Compression LZX Compression
- wimlib-imagex (v1.5.3): 207,444,390 bytes 188,106,091 bytes
- Microsoft imagex.exe (Windows 7): 209,960,209 bytes 188,224,481 bytes
-
- Table 2. Time to create WIM
-
- XPRESS Compression LZX Compression
- wimlib-imagex (v1.5.3): 73 sec 202 sec
- Microsoft imagex.exe (Windows 7): 90 sec 149 sec
-
-The above LZX data are using explicitly specified maximum compression
-('--compress=maximum') as of wimlib v1.5.3. If `wimlib-imagex capture' or
-`wimlib-imagex capture' is instead run with no '--compress' argument, then a
-faster LZX compressor is used; it will produce results in between those given
-for XPRESS and LZX above.
-
-Note: if the absolute maximum but still compatible (i.e. not changing the
-compression chunk size) LZX compression ratio is desired, `wimlib-imagex
-optimize WIMFILE --recompress --compress-slow' on one of the above
-LZX-compressed WIMs produces a WIM of 187,089,943 bytes in about 400 seconds.
-
- NTFS SUPPORT
-
-WIM images may contain data, such as alternate data streams and
-compression/encryption flags, that are best represented on the NTFS filesystem
-used on Windows. Also, WIM images may contain security descriptors which are
-specific to Windows and cannot be represented on other operating systems.
-wimlib handles this NTFS-specific or Windows-specific data in a
-platform-dependent way:
-
- * In the Windows version of wimlib and wimlib-imagex, NTFS-specific and
- Windows-specific data are supported natively.
-
- * In the UNIX version of wimlib and wimlib-imagex, NTFS-specific and
- Windows-specific data are ordinarily ignored; however, there is also special
- support for capturing and extracting images directly to/from unmounted NTFS
- volumes. This was made possible with the help of libntfs-3g from the
- NTFS-3g project.
-
-For both platforms the code for NTFS capture and extraction is complete enough
-that it is possible to apply an image from the "install.wim" contained in recent
-Windows installation media (Vista, Windows 7, or Windows 8) directly to a NTFS
-filesystem, and then boot Windows from it after preparing the Boot Configuration
-Data. In addition, a Windows installation can be captured (or backed up) into a
-WIM file, and then re-applied later.
-
- WINDOWS PE
-
-A major use for wimlib and wimlib-imagex is to create customized images of
-Windows PE, the Windows Preinstallation Environment, on either UNIX-like systems
-or Windows without having to rely on Microsoft's software and its restrictions
-and limitations.
-
-Windows PE is a lightweight version of Windows that can run entirely from memory
-and can be used to install Windows from local media or a network drive or
-perform maintenance. It is the operating system that runs when you boot from
-the Windows installation media.
-
-You can find Windows PE on the installation DVD for Windows Vista, Windows 7, or
-Windows 8, in the file `sources/boot.wim'. Windows PE can also be found in the
-Windows Automated Installation Kit (WAIK), which is free to download from
-Microsoft, inside the `WinPE.cab' file, which you can extract natively on
-Windows, or on UNIX-like systems if you install either the `cabextract' or
-`p7zip' programs.
-
-In addition, Windows installations and recovery partitions frequently contain a
-WIM containing an image of the Windows Recovery Environment, which is similar to
-Windows PE.
-
-A shell script `mkwinpeimg' is distributed with wimlib on UNIX-like systems to
-ease the process of creating and customizing a bootable Windows PE image.
-
- DEPENDENCIES
-
-This section documents the dependencies of wimlib and the programs distributed
-with it, when building for a UNIX-like system from source. If you have
-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.
-
-* OpenSSL / libcrypto (optional)
- wimlib can use the SHA1 message digest code from OpenSSL instead of
- compiling in yet another SHA1 implementation. (See LICENSE section.)
-
-* cdrkit (optional)
-* mtools (optional)
-* syslinux (optional)
-* cabextract (optional)
- The `mkwinpeimg' shell script will look for several other programs
- depending on what options are given to it. Depending on your Linux
- distribution, you may already have these programs installed, or they may
- be in the software repository. Making an ISO filesystem requires
- `mkisofs' from `cdrkit' (http://www.cdrkit.org). Making a disk image
- requires `mtools' (http://www.gnu.org/software/mtools) and `syslinux'
- (http://www.syslinux.org). Retrieving files from the Windows Automated
- Installation Kit requires `cabextract' (http://www.cabextract.org.uk).
-
- CONFIGURATION
-
-This section documents the most important options that may be passed to the
-"configure" script when building from source:
-
---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.
-
---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.
-
---enable-xattr, --disable-xattr
- Enable or disable support for the extended-attributes interface to NTFS
- alternate data streams in mounted WIMs. To support these, wimlib
- requires that the setxattr() function and the attr/xattr.h header are
- available. The default is to autodetect whether support is possible.
-
---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.
-
---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.
-
---disable-error-messages
- Save some space by removing all error messages from the library.
-
---disable-assertions
- Remove assertions included by default.
-
- PORTABILITY
-
-wimlib has primarily been tested on Linux and Windows (primarily Windows 7, but
-also Windows XP and Windows 8).
-
-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').
-
-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.
-
- 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.
-
-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.
-- 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 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) but has been rewritten.
-
-The LZX compressor (lzx-compress.c) was originally based on code written by
-Matthew Russotto (www.russotto.net/chm/) but has been rewritten. It now uses
-suffix array construction code from divsufsort
-(https://code.google.com/p/libdivsufsort/) and algorithms from 7-Zip as well as
-several published papers.
-
-lz_hash.c contains a hash-table-based LZ77 matchfinder that is based on code
-from zlib but has been rewritten. This code is applicable to XPRESS, LZX, and
-LZMS, all of which are partly based on LZ77 compression.
-
-A limited number of other free programs can handle some parts of the WIM
-file format:
-
- * 7-zip is able to extract and create WIMs (as well as files in many
- 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 LZX or XPRESS compressed WIMs, and the
- correct handling of security descriptors and hard links.
- * 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
- instead relies on external native code, such as the codecs from wimlib.
-
-A very early version of wimlib is being used to deploy Windows 7 from the
-Ultimate Deployment Appliance. For more information see
-http://www.ultimatedeployment.org/.
-
-If you are looking for a UNIX archive format that provides features similar to
-WIM, I recommend you take a look at SquashFS (http://squashfs.sourceforge.net/).
-
- LICENSE
-
-As of version 1.0.0, wimlib and all programs and scripts distributed with it are
-released under the GNU GPL version 3.0 or later.
-
-wimlib is independently developed and does not contain any code, data, or files
-copyrighted by Microsoft. It is not known to be affected by any patents.
-
-On UNIX-like systems, if you do not want wimlib to be dynamically linked with
-libcrypto (OpenSSL), configure with --without-libcrypto. This replaces the SHA1
-implementation with built-in code and there will be no difference in
-functionality.
-
- DISCLAIMER
-
-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.