windows/INSTALL-MinGW-w64_with_CMake.txt

   1
   2 Building XZ Utils on Windows using MinGW-w64 and CMake
   3 ======================================================
   4
   5     1. Introduction
   6        1.1. Licensing considerations
   7     2. MSVCRT or UCRT
   8     3. CMake
   9     4. MinGW-w64 toolchains
  10        4.1. MinGW-w64 with GCC
  11        4.2. MinGW-w64 with Clang/LLVM
  12     5. Building XZ Utils
  13        5.1. Advanced build options
  14     6. Creating an import library for MSVC / Visual Studio
  15
  16
  17 1. Introduction
  18 ---------------
  19
  20     This document explains how to build XZ Utils using MinGW-w64,
  21     GCC or Clang/LLVM, CMake, and GNU make (mingw32-make) natively
  22     on Windows. The resulting XZ Utils library and executable files
  23     will only depend on DLLs that are included in Windows.
  24
  25     The build tools can be extracted into separate directories and used
  26     directly from there and deleted when no longer needed. There are no
  27     installers to run for these and no configuration needed.
  28
  29     These instructions don't apply to Cygwin. XZ Utils can be built
  30     under Cygwin in the same way as many other packages.
  31
  32
  33 1.1. Licensing considerations
  34
  35     Parts of MinGW-w64 runtime are statically linked into the binaries
  36     being built. The file COPYING.MinGW-w64-runtime.txt in MinGW-w64
  37     contains the license notices that apply to some parts of the
  38     runtime. The notices must be distributed alongside the binaries
  39     that have been built with MinGW-w64.
  40
  41     MinGW-w64 includes getopt_long(). The GNU getopt_long() (LGPLv2.1)
  42     included in XZ Utils isn't used when building with MinGW-w64.
  43
  44     The code from XZ Utils that ends up liblzma.dll and the *.exe files
  45     is under the BSD Zero Clause License (0BSD) which doesn't require
  46     any copyright or license notices to be included when distributing
  47     the binaries. See the file COPYING in the parent directory.
  48
  49
  50 2. MSVCRT or UCRT
  51 -----------------
  52
  53     Both GCC and Clang/LLVM based MinGW-w64 toolchains come in MSVCRT
  54     and Universal C runtime (UCRT) variants. MSVCRT is the old one.
  55     32-bit builds of XZ Utils with MSVCRT should run on Windows 2000
  56     and later (even Windows 95 should still be possible with trivial
  57     edits to the source code).
  58
  59     UCRT is included in Windows 10, and it's possible to install UCRT
  60     on Windows XP and later. UCRT might be the preferred choice if
  61     out-of-the-box compatibility with Windows versions older than 10
  62     is not required. Visual Studio 2015 and later produce binaries
  63     that use UCRT.
  64
  65     If you want to build liblzma.dll for use with your application,
  66     it's recommended to use the same CRT for all components. If this
  67     isn't possible, see the file liblzma-crt-mixing.txt.
  68
  69     If you only need the command line tools, the choice of CRT isn't
  70     important, at least for now.
  71
  72
  73 3. CMake
  74 --------
  75
  76     CMake is used for selecting build options and generating makefiles.
  77     It can also be used to extract archives, including .tar.xz and .7z.
  78
  79     Download a CMake binary package (.zip) from its homepage:
  80
  81         https://cmake.org/download/
  82
  83     Extract it to, for example, C:\devel\cmake so that the executables
  84     end up in C:\devel\cmake\bin. Avoid spaces and other special
  85     characters in the path.
  86
  87
  88 4. MinGW-w64 toolchains
  89 -----------------------
  90
  91     There are a few choices of prebuilt toolchains listed on
  92     the MinGW-w64 homepage:
  93
  94         https://www.mingw-w64.org/downloads/
  95
  96     These instructions list one GCC-based version and one
  97     Clang/LLVM-based version. Both include mingw32-make too.
  98
  99
 100 4.1. MinGW-w64 with GCC
 101
 102     For GCC, download appropriate packages from Mingw-builds depending
 103     on if you want to build 32-bit or 64-bit x86 version of XZ Utils
 104     and if the XZ Utils binaries should link against MSVCRT or UCRT:
 105
 106         https://github.com/niXman/mingw-builds-binaries/releases
 107
 108         i686-*-release-win32-*-msvcrt-*.7z    32-bit, uses MSVCRT (old)
 109         i686-*-release-win32-*-ucrt-*.7z      32-bit, uses UCRT (new)
 110         x86_64-*-release-win32-*-msvcrt-*.7z  64-bit, uses MSVCRT (old)
 111         x86_64-*-release-win32-*-ucrt-*.7z    64-bit, uses UCRT (new)
 112
 113     Extract it, for example, to C:\devel so that the executables are
 114     in C:\devel\mingw32\bin or C:\devel\mingw64\bin. To extract,
 115     you can install 7-Zip from <https://7-zip.org/> or use CMake
 116     on the command line:
 117
 118         set PATH=C:\devel\cmake\bin;%PATH%
 119         c:
 120         cd \devel
 121         cmake -E tar xf x86_64-13.1.0-release-win32-seh-ucrt-rt_v11-rev1.7z
 122
 123     Then skip to the section "Building XZ Utils".
 124
 125
 126 4.2. MinGW-w64 with Clang/LLVM
 127
 128     For Clang/LLVM, download an appropriate package from LLVM-MinGW:
 129
 130         https://github.com/mstorsjo/llvm-mingw/releases
 131
 132         llvm-mingw-*-msvcrt-i686.zip          32-bit, uses MSVCRT (old)
 133         llvm-mingw-*-ucrt-i686.zip            32-bit, uses UCRT (new)
 134         llvm-mingw-*-msvcrt-x86_64.zip        64-bit, uses MSVCRT (old)
 135         llvm-mingw-*-ucrt-x86_64.zip          64-bit, uses UCRT (new)
 136
 137     Extract it, for example, to C:\devel so that the executables end up
 138     in a directory like C:\devel\llvm-mingw-20230919-ucrt-x86_64\bin.
 139
 140
 141 5. Building XZ Utils
 142 --------------------
 143
 144     For a simple builds, you can use the included build-with-cmake.bat
 145     which takes these arguments:
 146
 147     %1 = Path to CMake's bin directory. Example:
 148          c:\devel\cmake\bin
 149
 150     %2 = Path to MinGW-w64's bin directory. Example:
 151          c:\devel\mingw64\bin
 152
 153     %3 = ON or OFF: Set to ON to build liblzma.dll or OFF for
 154          static liblzma.a. With OFF, the *.exe files won't
 155          depend on liblzma.dll.
 156
 157     Example:
 158
 159         build-with-cmake C:\devel\cmake\bin C:\devel\mingw64\bin ON
 160
 161     If successful, the "build" directory should then contain:
 162
 163         liblzma.dll     liblzma compression library
 164         liblzma.def     DEF file for creating an import library
 165         xz.exe          xz command line tool
 166         xzdec.exe       Decompression-only tool (smaller than xz.exe)
 167         lzmadec.exe     Decompression-only tool for legacy .lzma files
 168         lzmainfo.exe    Shows header info of legacy .lzma files
 169
 170     Ignore the other files. :-)
 171
 172
 173 5.1. Advanced build options
 174
 175     For 32-bit x86 builds, adding -msse2 to CFLAGS improves
 176     compression speed a little (but not decompression speed).
 177     There is no runtime detection for SSE2 support. It is
 178     recommended to use 64-bit version when possible.
 179
 180     It's possible to omit features from the build to reduce code size.
 181     There are several CMake configuration options available. One may
 182     change from CMAKE_BUILD_TYPE=Release to =MinSizeRel as well but
 183     it makes the code slower.
 184
 185     If building for multiple targets, keep only one toolchain in PATH
 186     at a time.
 187
 188
 189 6. Creating an import library for MSVC / Visual Studio
 190 ------------------------------------------------------
 191
 192     To link against liblzma.dll, you need to create an import library
 193     first. You need the "lib" command from MSVC and liblzma.def. Here
 194     is the command that works on 32-bit x86:
 195
 196         lib /def:liblzma.def /out:liblzma.lib /machine:ix86
 197
 198     On x86-64, the /machine argument has to be changed:
 199
 200         lib /def:liblzma.def /out:liblzma.lib /machine:x64
 201
 202     IMPORTANT: See also the file liblzma-crt-mixing.txt.
 203