9d57fbc7bd7a333228f374f98365be34b99c6041
[wimlib] / README.WINDOWS
1
2                                   INTRODUCTION
3
4 wimlib is free and open source software that is available on both UNIX-like
5 systems and Windows.  This file provides additional information specifically
6 about the Windows version of wimlib and the command line tool "wimlib-imagex"
7 that is distributed with it.  It does not obsolete the generic README.txt, which
8 you should read too.
9
10                               WINDOWS DISTRIBUTION
11
12 The Windows distribution of wimlib is a ZIP file containing the following items:
13
14   * wimlib-imagex.exe, a command-line tool to deal with WIM (.wim), split WIM
15     (.swm), and ESD (.esd) files that is inspired by Microsoft's ImageX and
16     DISM.  This is a ready-to-run executable and not an installer.
17
18   * Very short batch scripts (e.g. wimapply.cmd) which are shortcuts to the
19     corresponding wimlib-imagex commands (e.g. `wimlib-imagex apply').
20
21   * The documentation, including this file, the generic README.txt, and
22     PDF documentation for wimlib-imagex in the 'doc' directory.
23
24   * The library itself (libwim-15.dll).  The C header wimlib.h is not
25     included; download the source if you want it.
26
27   * License files for all software included.  These are all free software
28     licenses.  COPYING.txt is the main license, and it refers to
29     COPYING.GPLv3.txt and COPYING.LGPLv3.txt.  The other licenses are for
30     third-party software included in the library.
31
32 Note that there are separate ZIP files for 32-bit (i686) and 64-bit (x86_64)
33 binaries.  They are both fully supported, but you should prefer the 64-bit
34 binaries when possible as they can be noticeably faster.
35
36                                  WIMLIB-IMAGEX
37
38 wimlib-imagex supports most features of Microsoft's ImageX as well as some
39 features that are supported by DISM but not by ImageX.  wimlib-imagex also
40 supports some features that neither ImageX nor DISM support.  Some of the
41 advantages of wimlib-imagex compared to ImageX and DISM are:
42
43   * wimlib-imagex provides "extract" and "update" commands which allow
44     you to quickly work with WIM images without mounting them.
45
46   * wimlib-imagex provides an easy-to-use "optimize" command which removes
47     wasted space from a WIM file and optionally recompresses it with stronger
48     compression.
49
50   * wimlib includes advanced implementations of all compression algorithms used
51     in WIM files.  They usually outperform and outcompress their Microsoft
52     equivalents.
53
54   * wimlib-imagex supports solid WIM files and LZMS compression, for example as
55     used in ESD (.esd) files.  (These are partially supported by recent DISM
56     versions but not by ImageX.)
57
58   * wimlib-imagex supports imaging a live Windows system.  Just use the
59     --snapshot option.
60
61   * In many cases, wimlib-imagex has simpler command-line syntax than either
62     ImageX or DISM.
63
64   * Whenever possible, wimlib-imagex includes improved documentation and
65     informational output compared to Microsoft's software.
66
67   * wimlib and wimlib-imagex are free software, so you can modify and/or audit
68     the source code.
69
70 However, some limitations of wimlib-imagex compared to ImageX and DISM are:
71
72   * On Windows, wimlib-imagex does not support mounting WIM images.
73
74   * wimlib-imagex has no awareness of Windows "packages".
75
76                                 ADDITIONAL NOTES
77
78 It's recommended to use wimlib-imagex in scripts to avoid having to
79 interactively enter commands.  However, note that wimlib-imagex is largely just
80 a command-line front-end for wimlib, and it's possible to use wimlib's API in
81 other front-ends or applications.  Currently there is no official graphical user
82 interface available for wimlib or wimlib-imagex.  However, an unofficial, beta,
83 Windows-only graphical user interface that provides a thin wrapper around
84 wimlib-imagex can be downloaded at
85 http://reboot.pro/files/file/485-wimlib-imagex-command-line-compiler/.
86
87                               BUILDING FROM SOURCE
88
89 As with other open source software, advanced users may choose to build wimlib
90 from source, potentially with customizations.  Although wimlib's build system is
91 designed for UNIX-like systems and is easiest to use on Linux, it's possible to
92 build Windows binaries on Windows using Cygwin with MinGW.  To do this, follow
93 the instructions below.  For the sake of example, I'll assume you are building a
94 64-bit version of wimlib v1.10.0.
95
96 Run the Cygwin installer, available from https://www.cygwin.com/setup-x86.exe.
97 When you get to the package selection screen, choose the following additional
98 packages from category "Devel":
99
100     - make
101     - mingw64-x86_64-binutils
102     - mingw64-x86_64-gcc-g++
103     - mingw64-x86_64-libxml2
104     - mingw64-x86_64-pkg-config
105     - mingw64-x86_64-winpthreads
106
107 Download wimlib's source code from https://wimlib.net/downloads/wimlib-1.10.0.tar.gz.
108
109 Start a Cygwin terminal and run the following commands:
110
111     cd /cygdrive/c/Users/example/Downloads # (or wherever you downloaded the source to)
112     tar xf wimlib-1.10.0.tar.gz
113     cd wimlib-1.10.0
114     ./configure --host=x86_64-w64-mingw32
115     make
116
117 If successful, the new binaries "libwim-15.dll" and "wimlib-imagex.exe" will
118 have been produced in the .libs directory.
119
120 By default the binaries are built with debug symbols.  If desired, you can use
121 x86_64-w64-mingw32-strip to strip them.
122
123 libwim-15.dll will be linked to several other DLLs which you will need as well:
124
125     - libwinpthread-1.dll
126     - libxml2-2.dll, which also requires:
127         - iconv.dll
128         - liblzma-5.dll
129         - zlib1.dll
130
131 These DLLs can be found in "C:\cygwin\usr\x86_64-w64-mingw32\sys-root\mingw\bin"
132 and must be placed alongside libwim-15.dll for it to run portably.  (In the
133 official binary release, these third-party libraries are linked to libwim-15.dll
134 statically rather than dynamically --- or are unnecessary, in the case of
135 libxml2's dependencies.)
136
137 Building 32-bit binaries is very similar, but you'll need to replace "x86_64"
138 with "i686" everywhere in the above instructions, and libwim-15.dll will also
139 depend on libgcc_s_sjlj-1.dll.  Note that you can build both 32-bit and 64-bit
140 binaries from the same Cygwin installation, provided that you install both the
141 mingw64-i686-* and mingw64-x86_64-* packages; and you can run the Cygwin setup
142 program to install more packages at any time.