X-Git-Url: https://wimlib.net/git/?a=blobdiff_plain;f=README;h=6715a1f669d9b1223e8fa69327ab0652bef76bae;hb=HEAD;hp=ebae1722fa140817a744a26bca3a83b343ec9169;hpb=9bec19341aac9190cd0bd80a6937b02d923dd566;p=wimlib diff --git a/README b/README deleted file mode 100644 index ebae1722..00000000 --- a/README +++ /dev/null @@ -1,329 +0,0 @@ - INTRODUCTION - -This is wimlib version 1.5.2 (November 2013). 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 two compression formats: LZX and -XPRESS *. Both 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. - -* Note: The Windows 8 WIMGAPI apparently adds a third format, LZMS, but it is - not documented and is incompatible with ImageX and Dism. It is unclear if - this new format is actually being used for anything. - - 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 or LZX 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. - - 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 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 specified in a document that can be found in the -Microsoft Download Center. There is a similar document that specifies the LZX -compression format, and a document that specifies the XPRESS compression format. -However, many parts of these formats are poorly documented, and some parts have -no documentation whatsoever. Some particularly poorly documented parts of the -formats have had comments added in various places in the library code. Please -see the code and/or ask me if you have any questions about the WIM file format -as it exists in reality and not as it exists in Microsoft's poorly written -documentation. - -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. - -lzx-decompress.c, the code to decompress WIM file resources that are compressed -using LZX compression, was originally based on code from the cabextract project -(http://www.cabextract.org.uk) but has been rewritten. - -lzx-compress.c, the code to compress WIM file resources using LZX compression, -was originally based on code written by Matthew Russotto (www.russotto.net/chm/) -but has been rewritten. - -lz77.c, the code to find LZ77 matches (used for both XPRESS and LZX -compression), is based on code from zlib but has been rewritten. - -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 - imagex.exe, 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/. - -You can see the documentation about Microsoft's version of ImageX at -http://technet.microsoft.com/en-us/library/cc749447(v=ws.10).aspx, so you can -see how it compares to wimlib-imagex. - -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. Use Microsoft's `imagex.exe' if you -want to make sure your WIM files are made "correctly" (but beware: Microsoft's -version contains some bugs). - -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.