X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=README;h=196ed0596f1a5bea11dde8624d10b2a65e487648;hp=6b4b174d5f23742cc4b48a02817e5e18bb40e9f2;hb=HEAD;hpb=94f8de6d411d58a0eb2e472cc1b984f195eb2447 diff --git a/README b/README deleted file mode 100644 index 6b4b174d..00000000 --- a/README +++ /dev/null @@ -1,387 +0,0 @@ - INTRODUCTION - -This is wimlib version 1.7.4 (January 2015). wimlib is a C library for -creating, modifying, extracting, and mounting files in the Windows Imaging -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, 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 -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. - -Since version 1.6.0, wimlib also supports ESD (.esd) files, except when -encrypted. These are still WIM files but they use a newer version of the file -format. - - 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 files. -wimlib includes its own compression codecs and does not use the compression API -available on some versions of Windows. - -I have gradually been improving the compression codecs in wimlib. For XPRESS -and LZX, they now usually outperform and outcompress the equivalent Microsoft -implementations. Although results will vary depending on the data being -compressed, in the table below I present the results for a common use case: -compressing an x86 Windows PE image. Each row displays the compression type, -the size of the resulting WIM file in bytes, and how many seconds it took to -create the file. When applicable, the results with the equivalent Microsoft -implementation in WIMGAPI is included. - - ============================================================================= - | Compression || wimlib (v1.7.4) | WIMGAPI (Windows 8.1) | - ============================================================================= - | None [1] || 361,314,224 in 2.4s | 361,315,338 in 4.5s | - | XPRESS [2] || 138,218,750 in 3.0s | 140,457,436 in 6.0s | - | XPRESS (slow) [3] || 135,173,511 in 8.9s | N/A | - | LZX (quick) [4] || 130,332,007 in 4.1s | N/A | - | LZX (normal) [5] || 126,714,807 in 12.5s | 127,293,240 in 19.2s | - | LZX (slow) [6] || 126,150,743 in 20.5s | N/A | - | LZMS (non-solid) [7] || 121,909,792 in 11.9s | N/A | - | LZMS (solid) [8] || 93,650,936 in 45.0s | 88,771,192 in 109.2 | - | "WIMBoot" [9] || 167,023,719 in 3.5s | 169,109,211 in 10.4s | - | "WIMBoot" (slow) [10] || 165,027,583 in 7.9s | N/A | - ============================================================================= - -Notes: - [1] '--compress=none' for wimlib-imagex; '/compress:none' for DISM. - - [2] '--compress=XPRESS' for wimlib-imagex; '/compress:fast' for DISM. - Compression chunk size defaults to 32768 bytes in both cases. - - [3] '--compress=XPRESS:80' for wimlib-imagex; no known equivalent for DISM. - Compression chunk size defaults to 32768 bytes. - - [4] '--compress=LZX:20' for wimlib-imagex; no known equivalent for DISM. - Compression chunk size defaults to 32768 bytes. - - [5] '--compress=LZX' or '--compress=LZX:50' or no option for wimlib-imagex; - '/compress:maximum' for DISM. - Compression chunk size defaults to 32768 bytes in both cases. - - [6] '--compress=LZX:100' for wimlib-imagex; no known equivalent for DISM. - Compression chunk size defaults to 32768 bytes. - - [7] '--compress=LZMS' for wimlib-imagex; no known equivalent for DISM. - Compression chunk size defaults to 131072 bytes. - - [8] '--solid' for wimlib-imagex. Should be '/compress:recovery' for DISM, - but only works for /Export-Image, not /Capture-Image. Compression chunk - size in solid blocks defaults to 33554432 for wimlib, 67108864 for DISM. - - [9] '--wimboot' for wimlib-imagex; '/wimboot' for DISM. - This is really XPRESS compression with 4096 byte chunks, so the same as - '--compress=XPRESS --chunk-size=4096'. - - [10] '--wimboot --compress=XPRESS:80' for wimlib-imagex; - no known equivalent for DISM. - Same format as [9], but trying harder to get a good compression ratio. - -Note: wimlib-imagex's --compress option also accepts the "fast", "maximum", and -"recovery" aliases for XPRESS, LZX, and LZMS, respectively. - -Testing environment: - - - 64 bit binaries - - Windows 8.1 virtual machine running on Linux with VT-x - - 4 CPUs and 4 GiB memory given to virtual machine - - SSD-backed virtual disk - - All tests done with page cache warmed - -The compression ratio provided by wimlib is also competitive with commonly used -archive formats. Below are file sizes that result when the Canterbury corpus is -compressed with wimlib (v1.7.2), WIMGAPI (Windows 8.1), and some other -formats/programs: - - ===================================================== - | Format | Size (bytes) | - ===================================================== - | tar | 2,826,240 | - | WIM (WIMGAPI, None) | 2,814,254 | - | WIM (wimlib, None) | 2,814,216 | - | WIM (WIMGAPI, XPRESS) | 825,536 | - | WIM (wimlib, XPRESS) | 790,016 | - | tar.gz (gzip, default) | 738,796 | - | ZIP (Info-ZIP, default) | 735,334 | - | tar.gz (gzip, -9) | 733,971 | - | ZIP (Info-ZIP, -9) | 732,297 | - | WIM (wimlib, LZX quick) | 704,006 | - | WIM (WIMGAPI, LZX) | 651,866 | - | WIM (wimlib, LZX normal) | 632,614 | - | WIM (wimlib, LZX slow) | 625,050 | - | WIM (wimlib, LZMS non-solid) | 581,960 | - | tar.bz2 (bzip, default) | 565,008 | - | tar.bz2 (bzip, -9) | 565,008 | - | WIM (wimlib, LZX solid) | 532,700 | - | WIM (wimlib, LZMS solid) | 525,990 | - | WIM (wimlib, LZX solid, slow) | 525,140 | - | WIM (wimlib, LZMS solid, slow) | 523,728 | - | WIM (WIMGAPI, LZMS solid) | 521,366 | - | WIM (wimlib, LZX solid, very slow) | 520,832 | - | tar.xz (xz, default) | 486,916 | - | tar.xz (xz, -9) | 486,904 | - | 7z (7-zip, default) | 484,700 | - | 7z (7-zip, -9) | 483,239 | - ===================================================== - -Note: WIM does even better on directory trees containing duplicate files, which -the Canterbury corpus doesn't have. - - 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 an 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 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 SHA-1 message digest implementation from libcrypto - (usually provided by OpenSSL) instead of compiling in yet another SHA-1 - implementation. - -* 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 - capture or apply WIM images directly from/to NTFS volumes. - - The default is --with-ntfs-3g when building for any UNIX-like system, - and --without-ntfs-3g when building for Windows. - ---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. - - The default is --with-fuse when building for Linux, and --without-fuse - otherwise. - ---without-libcrypto - Build in functions for SHA-1 rather than using external SHA-1 functions - from libcrypto (usually provided by OpenSSL). - - The default is to use libcrypto if it is found on your system. - - PORTABILITY - -wimlib works on both UNIX-like systems (Linux, Mac OS X, FreeBSD, etc.) and -Windows (XP and later). - -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. - -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. It has been -tested on the ARM architecture. - -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. 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 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. - -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 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 - instead relies on external native code, such as the codecs from wimlib. - -If you are looking for an archive format that provides features similar to WIM -but was designed primarily for UNIX, you may want to consider SquashFS -(http://squashfs.sourceforge.net/). However, you may find that wimlib works -surprisingly well on UNIX. It will store hard links and symbolic links, and it -has optional support for storing UNIX owners, groups, modes, and special files -such as device nodes and FIFOs. Actually, I use it to back up my own files on -Linux! - - LICENSE AND DISCLAIMER - -See COPYING for information about the license. - -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. - -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.