wimlib-imagex: Include WIMBoot options in usage printout
[wimlib] / README
1                                   INTRODUCTION
2
3 This is wimlib version 1.6.2 (March 2014).  wimlib is a C library for
4 creating, modifying, extracting, and mounting files in the Windows Imaging
5 Format (WIM files).  These files are normally created using the ImageX
6 (imagex.exe) or Dism (Dism.exe) utilities on Windows, but wimlib is distributed
7 with a free implementation of ImageX called "wimlib-imagex" for both UNIX-like
8 systems and Windows.
9
10                                   INSTALLATION
11
12 To install wimlib and wimlib-imagex on Windows you simply need to download and
13 extract the ZIP file containing the latest binaries from the SourceForge page
14 (http://sourceforge.net/projects/wimlib/), which you may have already done.
15
16 To install wimlib and wimlib-imagex on UNIX-like systems (with Linux being the
17 primary supported and tested platform), you must compile the source code, which
18 is also available at http://sourceforge.net/projects/wimlib/.  Alternatively,
19 check if a package has been prepared for your Linux distribution.  Example files
20 for Debian and RPM packaging are in the debian/ and rpm/ directories.
21
22                                     WIM FILES
23
24 A Windows Imaging (WIM) file is an archive designed primarily for archiving
25 Windows filesystems.  However, it can be used on other platforms as well, with
26 some limitations.  Like some other archive formats such as ZIP, files in WIM
27 archives may be compressed.  WIM files support multiple compression formats,
28 including LZX, XPRESS, and LZMS.  All these formats are supported by wimlib.
29
30 A WIM file consists of one or more "images".  Each image is an independent
31 top-level directory structure and is logically separate from all other images in
32 the WIM.  Each image has a name as well as a 1-based index in the WIM file.  To
33 save space, WIM archives automatically combine all duplicate files across all
34 images.
35
36 A WIM file may be either stand-alone or split into multiple parts.  Split WIMs
37 are read-only and cannot be modified.
38
39 Since version 1.6.0, wimlib also supports ESD (.esd) files, except when
40 encrypted.  These are still WIM files but they use a newer version of the file
41 format.
42
43                              IMAGEX IMPLEMENTATION
44
45 wimlib itself is a C library, and it provides a documented public API (See:
46 http://wimlib.sourceforge.net) for other programs to use.  However, it is also
47 distributed with a command-line program called "wimlib-imagex" that uses this
48 library to implement an imaging tool similar to Microsoft's ImageX.
49 wimlib-imagex supports almost all the capabilities of Microsoft's ImageX as well
50 as additional capabilities.  wimlib-imagex works on both UNIX-like systems and
51 Windows, although some features differ between the platforms.
52
53 Run `wimlib-imagex' with no arguments to see an overview of the available
54 commands and their syntax.  For additional documentation:
55
56   * If you have installed wimlib-imagex on a UNIX-like system, you will find
57     further documentation in the man pages; run `man wimlib-imagex' to get
58     started.
59
60   * If you have downloaded the Windows binary distribution, you will find the
61     documentation for wimlib-imagex in PDF format in the "doc" directory,
62     ready for viewing with any PDF viewer.  Please note that although the PDF
63     files are converted from UNIX-style "man pages", they do document
64     Windows-specific behavior when appropriate.
65
66                                 COMPRESSION RATIO
67
68 wimlib (and wimlib-imagex) can create XPRESS, LZX, or LZMS compressed WIM
69 archives.  wimlib includes its own compression codecs and does not use the
70 compression API available on some versions of Windows.  The below table provides
71 the results (file size, in bytes, and time to create, in seconds) of capturing a
72 WIM containing an x86 Windows PE image, using various compression types and
73 options.  When applicable, the results with the equivalent Microsoft
74 implementation in WIMGAPI, which is the library used by ImageX and Dism, are
75 included.
76
77   ===========================================================================
78   | Compression type       ||  wimlib (v1.6.1)       |  WIMGAPI (Windows 8) |
79   ===========================================================================
80   | None             [1]   ||  531,979,435 in 18s    |  531,980,333 in 24s  |
81   | XPRESS           [2]   ||  207,369,912 in 22s    |  209,886,010 in 39s  |
82   | LZX (quick)      [3]   ||  194,876,901 in 29s    |  N/A                 |
83   | LZX (normal)     [4]   ||  187,962,713 in 158s   |  188,163,523 in 125s |
84   | LZX (slow)       [5]   ||  186,913,423 in 358s   |  N/A                 |
85   | LZMS (non-solid) [6]   ||  176,880,594 in 182s   |  N/A                 |
86   | LZMS (solid)     [7]   ||  136,507,304 in 494s   |  126,735,608 in 623s |
87   ===========================================================================
88
89 Notes:
90    [1] '--compress=none' for wimlib-imagex;
91        '/compress none' or no option for ImageX.
92
93    [2] '--compress=fast' or '--compress=XPRESS' for wimlib-imagex;
94        '/compress fast' or no option for ImageX.
95        Compression chunk size is 32768 (the default for XPRESS).
96
97    [3] No compression option specified to wimlib-imagex; no known equivalent for
98        WIMGAPI (ImageX uses XPRESS compression if no option specified).
99        Compression chunk size is 32768 (the default for LZX).
100
101    [4] '--compress=maximum' or '--compress=LZX' for wimlib-imagex;
102        '/compress maximum' for ImageX.
103        Compression chunk size is 32768 (the default for LZX).
104
105    [5] '--compress=maximum --compress-slow' for wimlib-imagex;
106        no known equivalent for WIMGAPI.
107        Compression chunk size is 32768 (the default for LZX).
108
109    [6] '--compress=recovery' or '--compress=LZMS' for wimlib-imagex;
110        no known way to create the equivalent with WIMGAPI.
111        Compression chunk size is 131072 (the default for LZMS).  Note: this
112        compression type is not generally recommended due to its limited
113        compatibility with the MS implementations.
114
115    [7] '--compress=recovery --solid' or '--compress=LZMS --solid' for
116        wimlib-imagex; WIMCreateFile with WIM_COMPRESSION_LZMS and flag
117        0x20000000 for WIMGAPI.  Compression chunk size in packed resources is
118        33554432 for wimlib, 67108864 for WIMGAPI.  Note: this compression type
119        is not generally recommended due to its limited compatibility with the MS
120        implementations.  Also, due to the large chunk size, wimlib uses about
121        500MB of memory per thread when compressing in this format.
122
123 The above timings were done on Windows 8 (x86) so that side-by-side comparisons
124 with the Microsoft implementation would be possible; however, wimlib may have
125 even better performance on other operating systems such as Linux.  The system
126 had 2 CPUs and 2 GiB of memory available.  All times were done with the page
127 cache warmed, so the times primarily measure the performance of the compression
128 algorithms and not the time to read data from disk, which presumably is similar
129 in each implementation.
130
131 Below are results for compressing the Canterbury corpus using wimlib (v1.6.1),
132 WIMGAPI (Windows 8), and some other formats/programs, including the archive size
133 only.  Note that the Canterbury corpus includes no duplicate files or hard
134 links, which WIM handles better than most other formats by storing only distinct
135 data streams.
136
137      =================================================
138      | Format                         | Size (bytes) |
139      =================================================
140      | tar                            | 2,826,240    |
141      | WIM (WIMGAPI, None)            | 2,814,278    |
142      | WIM (wimlib, None)             | 2,813,856    |
143      | WIM (WIMGAPI, XPRESS)          | 825,410      |
144      | WIM (wimlib, XPRESS)           | 792,024      |
145      | tar.gz (gzip, default)         | 738,796      |
146      | ZIP (Info-ZIP, default)        | 735,334      |
147      | tar.gz (gzip, -9)              | 733,971      |
148      | ZIP (Info-ZIP, -9)             | 732,297      |
149      | WIM (wimlib, LZX quick)        | 722,196      |
150      | WIM (WIMGAPI, LZX)             | 651,766      |
151      | WIM (wimlib, LZX normal)       | 639,464      |
152      | WIM (wimlib, LZX slow)         | 633,144      |
153      | WIM (wimlib, LZMS non-solid)   | 590,252      |
154      | tar.bz2 (bzip, default)        | 565,008      |
155      | tar.bz2 (bzip, -9)             | 565,008      |
156      | WIM (wimlib, LZMS solid)       | 534,218      |
157      | WIM (wimlib, LZMS solid, slow) | 529,904      |
158      | WIM (WIMGAPI, LZMS solid)      | 521,232      |
159      | tar.xz (xz, default)           | 486,916      |
160      | tar.xz (xz, -9)                | 486,904      |
161      | 7z  (7-zip, default)           | 484,700      |
162      | 7z  (7-zip, -9)                | 483,239      |
163      =================================================
164
165                                   NTFS SUPPORT
166
167 WIM images may contain data, such as alternate data streams and
168 compression/encryption flags, that are best represented on the NTFS filesystem
169 used on Windows.  Also, WIM images may contain security descriptors which are
170 specific to Windows and cannot be represented on other operating systems.
171 wimlib handles this NTFS-specific or Windows-specific data in a
172 platform-dependent way:
173
174   * In the Windows version of wimlib and wimlib-imagex, NTFS-specific and
175     Windows-specific data are supported natively.
176
177   * In the UNIX version of wimlib and wimlib-imagex, NTFS-specific and
178     Windows-specific data are ordinarily ignored; however, there is also special
179     support for capturing and extracting images directly to/from unmounted NTFS
180     volumes.  This was made possible with the help of libntfs-3g from the
181     NTFS-3g project.
182
183 For both platforms the code for NTFS capture and extraction is complete enough
184 that it is possible to apply an image from the "install.wim" contained in recent
185 Windows installation media (Vista, Windows 7, or Windows 8) directly to a NTFS
186 filesystem, and then boot Windows from it after preparing the Boot Configuration
187 Data.  In addition, a Windows installation can be captured (or backed up) into a
188 WIM file, and then re-applied later.
189
190                                    WINDOWS PE
191
192 A major use for wimlib and wimlib-imagex is to create customized images of
193 Windows PE, the Windows Preinstallation Environment, on either UNIX-like systems
194 or Windows without having to rely on Microsoft's software and its restrictions
195 and limitations.
196
197 Windows PE is a lightweight version of Windows that can run entirely from memory
198 and can be used to install Windows from local media or a network drive or
199 perform maintenance.  It is the operating system that runs when you boot from
200 the Windows installation media.
201
202 You can find Windows PE on the installation DVD for Windows Vista, Windows 7, or
203 Windows 8, in the file `sources/boot.wim'.  Windows PE can also be found in the
204 Windows Automated Installation Kit (WAIK), which is free to download from
205 Microsoft, inside the `WinPE.cab' file, which you can extract natively on
206 Windows, or on UNIX-like systems if you install either the `cabextract' or
207 `p7zip' programs.
208
209 In addition, Windows installations and recovery partitions frequently contain a
210 WIM containing an image of the Windows Recovery Environment, which is similar to
211 Windows PE.
212
213 A shell script `mkwinpeimg' is distributed with wimlib on UNIX-like systems to
214 ease the process of creating and customizing a bootable Windows PE image.
215
216                                   DEPENDENCIES
217
218 This section documents the dependencies of wimlib and the programs distributed
219 with it, when building for a UNIX-like system from source.  If you have
220 downloaded the Windows binary distribution of wimlib and wimlib-imagex then all
221 dependencies were already included and this section is irrelevant.
222
223 * libxml2 (required)
224         This is a commonly used free library to read and write XML files.  You
225         likely already have it installed as a dependency for some other program.
226         For more information see http://xmlsoft.org/.
227
228 * libfuse (optional but highly recommended)
229         Unless configured with --without-fuse, wimlib requires a non-ancient
230         version of libfuse to be installed.  Most Linux distributions already
231         include this, but make sure you have the libfuse package installed, and
232         also libfuse-dev if your distribution distributes header files
233         separately.  FUSE also requires a kernel module.  If the kernel module
234         is available it will automatically be loaded if you try to mount a WIM
235         file.  For more information see http://fuse.sourceforge.net/.  FUSE is
236         also available for FreeBSD.
237
238 * libntfs-3g (optional but highly recommended)
239         Unless configured with --without-ntfs-3g, wimlib requires the library
240         and headers for libntfs-3g version 2011-4-12 or later to be installed.
241         Versions dated 2010-3-6 and earlier do not work because they are missing
242         the header xattrs.h (and the file xattrs.c, which contains functions we
243         need).  libntfs-3g version 2013-1-13 is compatible only with wimlib
244         1.2.4 and later.
245
246 * OpenSSL / libcrypto (optional)
247         wimlib can use the SHA1 message digest code from OpenSSL instead of
248         compiling in yet another SHA1 implementation. (See LICENSE section.)
249
250 * cdrkit (optional)
251 * mtools (optional)
252 * syslinux (optional)
253 * cabextract (optional)
254         The `mkwinpeimg' shell script will look for several other programs
255         depending on what options are given to it.  Depending on your Linux
256         distribution, you may already have these programs installed, or they may
257         be in the software repository.  Making an ISO filesystem requires
258         `mkisofs' from `cdrkit' (http://www.cdrkit.org).  Making a disk image
259         requires `mtools' (http://www.gnu.org/software/mtools) and `syslinux'
260         (http://www.syslinux.org).  Retrieving files from the Windows Automated
261         Installation Kit requires `cabextract' (http://www.cabextract.org.uk).
262
263                                  CONFIGURATION
264
265 This section documents the most important options that may be passed to the
266 "configure" script when building from source:
267
268 --without-ntfs-3g
269         If libntfs-3g is not available or is not version 2011-4-12 or later,
270         wimlib can be built without it, in which case it will not be possible to
271         apply or capture images directly to/from NTFS volumes.
272
273 --without-fuse
274         If libfuse or the FUSE kernel module is not available, wimlib can be
275         compiled with --without-fuse.  This will remove the ability to mount and
276         unmount WIM files.
277
278 --without-libcrypto
279         Build in functions for SHA1 rather than using external SHA1 functions
280         from libcrypto (part of OpenSSL).  The default is to use libcrypto if it
281         is found on the system.
282
283 --enable-xattr, --disable-xattr
284         Enable or disable support for the extended-attributes interface to NTFS
285         alternate data streams in mounted WIMs.  To support these, wimlib
286         requires that the setxattr() function and the attr/xattr.h header are
287         available.  The default is to autodetect whether support is possible.
288
289 --disable-multithreaded-compression
290         By default, data will be compressed using multiple threads when writing
291         a WIM, unless only 1 processor is detected.  Specify this option to
292         disable support for this.
293
294 --enable-ssse3-sha1
295         Use a very fast assembly language implementation of SHA1 from Intel.
296         Only use this if the build target supports the SSSE3 instructions.
297
298 --disable-error-messages
299         Save some space by removing all error messages from the library.
300
301 --disable-assertions
302         Remove assertions included by default.
303
304                                   PORTABILITY
305
306 wimlib has primarily been tested on Linux and Windows (primarily Windows 7, but
307 also Windows XP and Windows 8).
308
309 wimlib may work on FreeBSD and Mac OS X.  However, this is not well tested.  If
310 you do not have libntfs-3g 2011-4-12 or later available, you must configure
311 wimlib with --without-ntfs-3g.  On FreeBSD, before mounting a WIM you need to
312 load the POSIX message queue module (run `kldload mqueuefs').
313
314 The code has primarily been tested on x86 and x86_64 CPUs, but it's written to
315 be portable to other architectures and I've also tested it on ARM.  However,
316 although the code is written to correctly deal with endianness, it has not yet
317 actually been tested on a big-endian architecture.
318
319                                    REFERENCES
320
321 The WIM file format is partially specified in a document that can be found in
322 the Microsoft Download Center.  However, this document really only provides an
323 overview of the format and is not a formal specification.
324
325 With regards to the supported compression formats:
326
327 - Microsoft has official documentation for XPRESS that is of reasonable quality.
328 - Microsoft has official documentation for LZX but it contains errors.
329 - There does not seem to be any official documentation for LZMS, so my comments
330   and code in src/lzms-decompress.c may in fact be the best documentation
331   available for this particular compression format.
332
333 The code in ntfs-3g_apply.c and ntfs-3g_capture.c uses the NTFS-3g library,
334 which is a library for reading and writing to NTFS filesystems (the filesystem
335 used by recent versions of Windows).  See
336 http://www.tuxera.com/community/ntfs-3g-download/ for more information.
337
338 The LZX decompressor (lzx-decompress.c) was originally based on code from the
339 cabextract project (http://www.cabextract.org.uk) but has been rewritten.
340
341 The LZX compressor (lzx-compress.c) was originally based on code written by
342 Matthew Russotto (www.russotto.net/chm/) but has been rewritten.  It now uses
343 suffix array construction code from divsufsort
344 (https://code.google.com/p/libdivsufsort/) and algorithms from 7-Zip as well as
345 several published papers.
346
347 lz_hash.c contains a hash-table-based LZ77 matchfinder that is based on code
348 from zlib but has been rewritten.  This code is applicable to XPRESS, LZX, and
349 LZMS, all of which are partly based on LZ77 compression.
350
351 A limited number of other free programs can handle some parts of the WIM
352 file format:
353
354   * 7-zip is able to extract and create WIMs (as well as files in many
355     other archive formats).  However, wimlib is designed specifically to handle
356     WIM files and provides features previously only available in Microsoft's
357     implementation, such as the ability to mount WIMs read-write as well as
358     read-only, the ability to create LZX or XPRESS compressed WIMs, and the
359     correct handling of security descriptors and hard links.
360   * ImagePyX (https://github.com/maxpat78/ImagePyX) is a Python program that
361     provides similar capabilities to wimlib-imagex.  One thing to note, though,
362     is that it does not support compression and decompression by itself, but
363     instead relies on external native code, such as the codecs from wimlib.
364
365 A very early version of wimlib is being used to deploy Windows 7 from the
366 Ultimate Deployment Appliance.  For more information see
367 http://www.ultimatedeployment.org/.
368
369 If you are looking for a UNIX archive format that provides features similar to
370 WIM, I recommend you take a look at SquashFS (http://squashfs.sourceforge.net/).
371
372                                     LICENSE
373
374 As of version 1.0.0, wimlib and all programs and scripts distributed with it are
375 released under the GNU GPL version 3.0 or later.  See COPYING for details.
376 Some individual source files are also released under more permissive licenses.
377
378 wimlib is independently developed and does not contain any code, data, or files
379 copyrighted by Microsoft.  It is not known to be affected by any patents.
380
381 On UNIX-like systems, if you do not want wimlib to be dynamically linked with
382 libcrypto (OpenSSL), configure with --without-libcrypto.  This replaces the SHA1
383 implementation with built-in code and there will be no difference in
384 functionality.
385
386                                    DISCLAIMER
387
388 wimlib comes with no warranty whatsoever.  Please submit a bug report (to
389 ebiggers3@gmail.com) if you find a bug in wimlib and/or wimlib-imagex.
390
391 Be aware that some parts of the WIM file format are poorly documented or even
392 completely undocumented, so I've just had to do the best I can to read and write
393 WIMs that appear to be compatible with Microsoft's software.