wimlib.net Git - wimlib/blob - README.WINDOWS.md

   1 # Introduction
   2
   3 wimlib is free and open source software that is available on both UNIX-like
   4 systems and Windows.  This file provides additional information specifically
   5 about the Windows version of wimlib and the command line tool `wimlib-imagex`
   6 that is distributed with it.  It does not obsolete the generic
   7 [README](README.md), which you should read too.
   8
   9 # Windows distribution
  10
  11 The Windows distribution of wimlib is a ZIP file containing the following items:
  12
  13 - `wimlib-imagex.exe`, a command-line tool to deal with WIM (.wim), split WIM
  14   (.swm), and ESD (.esd) files that is inspired by Microsoft's ImageX and DISM.
  15   This is a ready-to-run executable and not an installer.
  16
  17 - Very short batch scripts (e.g. `wimapply.cmd`) which are shortcuts to the
  18   corresponding `wimlib-imagex` commands (e.g. `wimlib-imagex apply`).
  19
  20 - The library itself in DLL format (`libwim-15.dll`).  `wimlib-imagex.exe`
  21   requires this to run.
  22
  23 - The documentation, including this file, the generic README, and PDF
  24   documentation for `wimlib-imagex` in the `doc` folder.
  25
  26 - License files for all software included.  These are all free software
  27   licenses.  `COPYING.txt` is the main license, and it refers to
  28   `COPYING.GPLv3.txt` and `COPYING.LGPLv3.txt`.  The other licenses are for
  29   third-party software included in the library.
  30
  31 - Development files in the `devel` folder.  These are only needed if you are
  32   developing C or C++ applications that use wimlib.
  33
  34 Note that there are separate ZIP files for 32-bit `i686` and 64-bit `x86_64`
  35 binaries.  They are both fully supported, but you should prefer the 64-bit
  36 binaries when possible as they can be noticeably faster.
  37
  38 # wimlib-imagex
  39
  40 `wimlib-imagex` supports most features of Microsoft's ImageX as well as some
  41 features that are supported by DISM but not by ImageX.  wimlib-imagex also
  42 supports some features that neither ImageX nor DISM support.  Some of the
  43 advantages of `wimlib-imagex` compared to ImageX and DISM are:
  44
  45 - `wimlib-imagex` provides "extract" and "update" commands which allow you to
  46   quickly work with WIM images without mounting them.
  47
  48 - `wimlib-imagex` provides an easy-to-use "optimize" command which removes
  49   wasted space from a WIM file and optionally recompresses it with stronger
  50   compression.
  51
  52 - wimlib includes advanced implementations of all compression algorithms used in
  53   WIM files.  They usually outperform and outcompress their Microsoft
  54   equivalents.
  55
  56 - `wimlib-imagex` supports solid WIM files and LZMS compression, for example as
  57   used in ESD (.esd) files.  (These are partially supported by recent DISM
  58   versions but not by ImageX.)
  59
  60 - `wimlib-imagex` supports imaging a live Windows system.  Just use the
  61   `--snapshot` option.
  62
  63 - In many cases, `wimlib-imagex` has simpler command-line syntax than either
  64   ImageX or DISM.
  65
  66 - Whenever possible, `wimlib-imagex` includes improved documentation and
  67   informational output compared to Microsoft's software.
  68
  69 - wimlib and `wimlib-imagex` are free software, so you can modify and/or audit
  70   the source code.
  71
  72 However, some limitations of `wimlib-imagex` compared to ImageX and DISM are:
  73
  74 - On Windows, `wimlib-imagex` does not support mounting WIM images.
  75
  76 - `wimlib-imagex` has no awareness of Windows "packages".
  77
  78 # Additional notes
  79
  80 It's recommended to use `wimlib-imagex` in scripts to avoid having to
  81 interactively enter commands.  However, note that `wimlib-imagex` is largely
  82 just a command-line front-end for wimlib, and it's possible to use wimlib's API
  83 in other front-ends or applications.  Currently there is no official graphical
  84 user interface available for wimlib or `wimlib-imagex`.  However,
  85 [Wimlib-clc](https://reboot.pro/files/file/588-wimlib-clc/) is an unofficial,
  86 Windows-only graphical user interface for `wimlib-imagex`.
  87
  88 # Building from source
  89
  90 As with other open source software, advanced users may choose to build wimlib
  91 from source, potentially with customizations.  Currently, wimlib depends on
  92 MinGW-w64 for its Windows support; Visual Studio is not supported.  The Windows
  93 binaries can be cross-compiled on Linux, or built on Windows using MSYS2 or
  94 Cygwin.  The following instructions show the MSYS2 method.
  95
  96 First, install MSYS2 by running the installer from
  97 [msys2.org](https://www.msys2.org).
  98
  99 Then, open any MSYS2 shell and run the following command:
 100
 101     pacman -Syu --noconfirm
 102
 103 After that, open any MSYS2 shell again and run the following commands:
 104
 105     pacman -Syu --noconfirm git
 106     git clone https://wimlib.net/git/wimlib
 107
 108 Note: By default the git repository will be on the `master` branch, which is the
 109 latest development snapshot.  Optionally, you can check out a specific version,
 110 e.g. `cd wimlib && git checkout v1.14.4`.  For old versions, please refer to the
 111 documentation for that version, as things may have changed.  It is also possible
 112 to use a release tarball (e.g. `wimlib-1.14.4.tar.gz`) instead of the git repo.
 113
 114 Finally, to actually do a build, close the MSYS2 shell you have open, then open
 115 one of the following from the Start menu:
 116
 117 - "MSYS2 MINGW64" - for `x86_64` binaries, built with gcc
 118 - "MSYS2 CLANG64" - for `x86_64` binaries, built with clang
 119 - "MSYS2 MINGW32" - for `i686` binaries, built with gcc
 120 - "MSYS2 CLANG32" - for `i686` binaries, built with clang
 121 - "MSYS2 CLANGARM64" - for ARM64 binaries (EXPERIMENTAL)
 122
 123 (If unsure, use "MSYS2 MINGW64".)  Then run the following commands:
 124
 125     cd wimlib
 126     tools/windows-build.sh --install-prerequisites
 127
 128 The script will automatically download and install the packages needed to build
 129 wimlib in the chosen MSYS2 environment, then build wimlib.  The output will be
 130 in a folder named similarly to `wimlib-1.14.4-windows-x86_64-bin`.  Note that
 131 your "home" folder within MSYS2 is `C:\msys64\home\%USERNAME%` by default.
 132 Therefore, the full path to the output folder will be similar to
 133 `C:\msys64\home\%USERNAME%\wimlib\wimlib-1.14.4-windows-x86_64-bin`.