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. Use the UCRT variant
  55     unless you have a good reason to why you still need to use MSVCRT.
  56
  57     MSVCRT is old. 32-bit builds of XZ Utils with MSVCRT should run on
  58     Windows 2000 and later (even Windows 95 should still be possible
  59     with trivial edits to the source code). However, MSVCRT doesn't
  60     support the UTF-8 code page. Under Windows 10 version 1903 and
  61     later, the command line tools of XZ Utils 5.6.3 and later use the
  62     UTF-8 code page. If the command line tools are built against MSVCRT
  63     and used on Win10 v1903 or later, non-ASCII characters may be
  64     displayed incorrectly. Otherwise the tools should still function
  65     correctly, so it's mostly a cosmetic issue.
  66
  67     UCRT is included in Windows 10, and it's possible to install UCRT
  68     on Windows XP and later. UCRT supports the UTF-8 code page. UCRT is
  69     the preferred choice if out-of-the-box compatibility with Windows
  70     versions older than 10 is not required. Visual Studio 2015 and
  71     later produce binaries that use UCRT.
  72
  73     If you want to build liblzma.dll for use with your application,
  74     it's recommended to use the same CRT for all components (the UTF-8
  75     code page issue only affects the command line tools, not liblzma).
  76     If this isn't possible, see the file liblzma-crt-mixing.txt.
  77
  78
  79 3. CMake
  80 --------
  81
  82     CMake is used for selecting build options and generating makefiles.
  83     It can also be used to extract archives, including .tar.xz and .7z.
  84
  85     Download a CMake binary package (.zip) from its homepage:
  86
  87         https://cmake.org/download/
  88
  89     Extract it to, for example, C:\devel\cmake so that the executables
  90     end up in C:\devel\cmake\bin. Avoid spaces and other special
  91     characters in the path.
  92
  93
  94 4. MinGW-w64 toolchains
  95 -----------------------
  96
  97     There are a few choices of prebuilt toolchains listed on
  98     the MinGW-w64 homepage:
  99
 100         https://www.mingw-w64.org/downloads/
 101
 102     These instructions list one GCC-based version and one
 103     Clang/LLVM-based version. Both include mingw32-make too.
 104
 105
 106 4.1. MinGW-w64 with GCC
 107
 108     For GCC, download appropriate packages from Mingw-builds depending
 109     on if you want to build 32-bit or 64-bit x86 version of XZ Utils
 110     and if the XZ Utils binaries should link against MSVCRT or UCRT
 111     (use 64-bit UCRT if possible):
 112
 113         https://github.com/niXman/mingw-builds-binaries/releases
 114
 115         i686-*-release-win32-*-msvcrt-*.7z    32-bit, uses MSVCRT (old)
 116         i686-*-release-win32-*-ucrt-*.7z      32-bit, uses UCRT (new)
 117         x86_64-*-release-win32-*-msvcrt-*.7z  64-bit, uses MSVCRT (old)
 118         x86_64-*-release-win32-*-ucrt-*.7z    64-bit, uses UCRT (new)
 119
 120     Extract it, for example, to C:\devel so that the executables are
 121     in C:\devel\mingw32\bin or C:\devel\mingw64\bin. To extract,
 122     you can install 7-Zip from <https://7-zip.org/> or use CMake
 123     on the command line:
 124
 125         set PATH=C:\devel\cmake\bin;%PATH%
 126         c:
 127         cd \devel
 128         cmake -E tar xf x86_64-13.1.0-release-win32-seh-ucrt-rt_v11-rev1.7z
 129
 130     Then skip to the section "Building XZ Utils".
 131
 132
 133 4.2. MinGW-w64 with Clang/LLVM
 134
 135     For Clang/LLVM, download an appropriate package from LLVM-MinGW
 136     (use 64-bit UCRT if possible):
 137
 138         https://github.com/mstorsjo/llvm-mingw/releases
 139
 140         llvm-mingw-*-msvcrt-i686.zip          32-bit, uses MSVCRT (old)
 141         llvm-mingw-*-ucrt-i686.zip            32-bit, uses UCRT (new)
 142         llvm-mingw-*-msvcrt-x86_64.zip        64-bit, uses MSVCRT (old)
 143         llvm-mingw-*-ucrt-x86_64.zip          64-bit, uses UCRT (new)
 144
 145     Extract it, for example, to C:\devel so that the executables end up
 146     in a directory like C:\devel\llvm-mingw-20230919-ucrt-x86_64\bin.
 147
 148
 149 5. Building XZ Utils
 150 --------------------
 151
 152     For a simple builds, you can use the included build-with-cmake.bat
 153     which takes these arguments:
 154
 155     %1 = Path to CMake's bin directory. Example:
 156          c:\devel\cmake\bin
 157
 158     %2 = Path to MinGW-w64's bin directory. Example:
 159          c:\devel\mingw64\bin
 160
 161     %3 = ON or OFF: Set to ON to build liblzma.dll or OFF for
 162          static liblzma.a. With OFF, the *.exe files won't
 163          depend on liblzma.dll.
 164
 165     Example:
 166
 167         build-with-cmake C:\devel\cmake\bin C:\devel\mingw64\bin ON
 168
 169     If successful, the "build" directory should then contain:
 170
 171         liblzma.dll     liblzma compression library
 172         liblzma.def     DEF file for creating an import library
 173         xz.exe          xz command line tool
 174         xzdec.exe       Decompression-only tool (smaller than xz.exe)
 175         lzmadec.exe     Decompression-only tool for legacy .lzma files
 176         lzmainfo.exe    Shows header info of legacy .lzma files
 177
 178     Ignore the other files. :-)
 179
 180
 181 5.1. Advanced build options
 182
 183     For 32-bit x86 builds, adding -msse2 to CFLAGS improves
 184     compression speed a little (but not decompression speed).
 185     There is no runtime detection for SSE2 support. It is
 186     recommended to use 64-bit version when possible.
 187
 188     It's possible to omit features from the build to reduce code size.
 189     There are several CMake configuration options available. One may
 190     change from CMAKE_BUILD_TYPE=Release to =MinSizeRel as well but
 191     it makes the code slower.
 192
 193     If building for multiple targets, keep only one toolchain in PATH
 194     at a time.
 195
 196
 197 6. Creating an import library for MSVC / Visual Studio
 198 ------------------------------------------------------
 199
 200     To link against liblzma.dll, you need to create an import library
 201     first. You need the "lib" command from MSVC and liblzma.def. Here
 202     is the command that works on 32-bit x86:
 203
 204         lib /def:liblzma.def /out:liblzma.lib /machine:ix86
 205
 206     On x86-64, the /machine argument has to be changed:
 207
 208         lib /def:liblzma.def /out:liblzma.lib /machine:x64
 209
 210     IMPORTANT: See also the file liblzma-crt-mixing.txt.
 211