windows/README

   1
   2 XZ Utils on Windows
   3 ===================
   4
   5 Introduction
   6
   7     This document explains how to build XZ Utils for Microsoft Windows
   8     using MinGW (Minimalist GNU for Windows).
   9
  10     This is currently experimental and has got very little testing.
  11     No ABI stability is promised for liblzma.dll.
  12
  13
  14 Why MinGW
  15
  16     XZ Utils code is C99. It should be possible to compile at least
  17     liblzma using any C99 compiler. Compiling the command line tools may
  18     need a little extra work to get them built on new systems, because
  19     they use some features that aren't standardized in POSIX.
  20
  21     MinGW is free software. MinGW runtime provides some functions that
  22     made porting the command line tools easier. Most(?) of the MinGW
  23     runtime, which gets linked into the resulting binaries, is in the
  24     public domain.
  25
  26     While most C compilers nowadays support C99 well enough (including
  27     most compilers for Windows), MSVC doesn't. It seems that Microsoft
  28     has no plans to ever support C99. Thus, it is not possible to build
  29     XZ Utils using MSVC without doing a lot of work to convert the code.
  30     Using prebuilt liblzma from MSVC is possible though, since the
  31     liblzma API headers are in C89 and contain some non-standard extra
  32     hacks required by MSVC.
  33
  34
  35 Getting and Installing MinGW
  36
  37     You can download MinGW for 32-bit Windows from Sourceforge:
  38
  39         http://sourceforge.net/project/showfiles.php?group_id=2435
  40
  41     It is enough to pick Automated MinGW Installer and MSYS Base System.
  42     Using the automated installer, select at least runtime, w32api,
  43     core compiler, and MinGW make. From MSYS you actually need only
  44     certain tools, but it is easiest to just install the whole MSYS.
  45
  46     To build for x86-64 version of Windows, you can download a snapshot
  47     of MinGW targeting for 64-bit Windows:
  48
  49         http://sourceforge.net/project/showfiles.php?group_id=202880
  50
  51     You can use the 32-bit MSYS also for 64-bit build, since we don't
  52     link against anything in MSYS, just use the tools from it. You may
  53     use the make tool from 32-bit MinGW (mingw32-make.exe) although
  54     probably the make.exe from MSYS works too.
  55
  56     Naturally you can pick the components manually, for example to try
  57     the latest available GCC. It is also possible to use a cross-compiler
  58     to build Windows binaries for example on GNU/Linux, or use Wine to
  59     run the Windows binaries. However, these instructions focus on
  60     building on Windows.
  61
  62
  63 Building for 32-bit Windows
  64
  65     Add MinGW and MSYS to PATH (adjust if you installed to non-default
  66     location):
  67
  68         C:\>set PATH=C:\MinGW\bin;C:\MSYS\1.0\bin;%PATH%
  69
  70     Then it should be enough to just run mingw32-make in this directory:
  71
  72         C:\xz-5.x.x\windows>mingw32-make
  73
  74
  75 Building for 64-bit Windows
  76
  77     For 64-bit build the PATH has to point to 64-bit MinGW:
  78
  79         C:\>set PATH=C:\MinGW64\bin;C:\MSYS\1.0\bin;%PATH%
  80
  81     You need to pass W64=1 to mingw32-make (or make if you don't have
  82     mingw32-make):
  83
  84         C:\xz-5.x.x\windows>mingw32-make W64=1
  85
  86
  87 Additional Make Flags and Targets
  88
  89     You may want to try some additional optimizations, which may or
  90     may not make the code faster (and may or may not hit possible
  91     compiler bugs more easily):
  92
  93         mingw32-make CFLAGS="-O3 -fomit-frame-pointer -funroll-loops"
  94
  95     If you want to enable assertions (the assert() macro), use DEBUG=1.
  96     You may want to disable optimizations too if you plan to actually
  97     debug the code. Never use DEBUG=1 for production builds!
  98
  99         mingw32-make DEBUG=1 CFLAGS="-g -O0"
 100
 101     By default, liblzma is built as a DLL and the command line tools
 102     linked dynamically against that liblzma.dll. To build static
 103     versions instead, use STATIC=1:
 104
 105         mingw32-make STATIC=1
 106
 107     TODO: Static build is not implemented yet.
 108
 109     To copy the built binaries and required headers into a clean
 110     directory, use the pkg target:
 111
 112         mingw32-make pkg
 113
 114     It first removes a possibly existing pkg directory, and then
 115     recreates it with the required files.
 116
 117     TODO: The pkg target doesn't copy any license or other copyright
 118     related information into the pkg directory.
 119
 120
 121 Creating an Import Library for MSVC
 122
 123     The included Makefile creates import library liblzma.a which works
 124     only(?) with MinGW. To use liblzma.dll for MSVC, you need to create
 125     liblzma.lib using the lib command from MSVC:
 126
 127         lib /def:liblzma.def /out:liblzma.lib /machine:ix86
 128
 129     On x86-64, the /machine argument has to naturally be changed:
 130
 131         lib /def:liblzma.def /out:liblzma.lib /machine:x64
 132
 133
 134 To Do
 135
 136     - Test Win64 support and add instructions about getting x86-64
 137       version of MinGW.
 138
 139     - Static liblzma and statically linked command line tools
 140
 141     - Creating the import library for other compilers/linkers
 142
 143     - Building with other compilers for Windows
 144
 145     - liblzma currently uses cdecl. Would stdcall be more compatible?
 146
 147     - Support building more size-optimized liblzma (the HAVE_SMALL
 148       define and other things that are needed)
 149
 150     - Support selecting which parts of liblzma to build to make the
 151       library even smaller.
 152
 153     - Use the configure script on Windows just like it is used on all
 154       the other systems?
 155
 156
 157 Bugs
 158
 159     Report bugs to <lasse.collin@tukaani.org> (in English or Finnish).
 160
 161     Take into account that I don't have MSVC and I cannot very easily
 162     test anything on Windows. As of writing, I have tried MinGW and the
 163     resulting binaries only under 32-bit Wine.
 164