README.win32.md

   1 Chun-wei Fan `<fanc999@yahoo.com.tw>`
   2 Philip Withnall `<withnall@endlessm.com>`
   3 Nirbheek Chauhan `<nirbheek@centricular.com>`
   4
   5 This document was last updated in 2019. You're reading this in the future, and
   6 lots of information might be misleading or outdated in your age. You have been
   7 warned.
   8
   9 # General
  10
  11 For prebuilt binaries (DLLs and EXEs) and developer packages (headers,
  12 import libraries) of GLib, Pango, GTK+ etc for Windows, go to
  13 https://www.gtk.org/download/windows.php . They are for "native"
  14 Windows meaning they use the Win32 API and Microsoft C runtime library
  15 only. No POSIX (Unix) emulation layer like Cygwin is involved.
  16
  17 To build GLib on Win32, you can use either GCC ("MinGW") or the Microsoft
  18 Visual Studio toolchain. For the latter, Visual Studio 2015 and later are
  19 recommended. For older Visual Studio versions, see below.
  20
  21 You can also cross-compile GLib for Windows from Linux using the
  22 cross-compiling mingw packages for your distro.
  23
  24 Note that to just *use* GLib on Windows, there is no need to build it
  25 yourself.
  26
  27 On Windows setting up a correct build environment is very similar to typing
  28 `meson; ninja` like on Linux.
  29
  30 The following preprocessor macros are to be used for conditional
  31 compilation related to Win32 in GLib-using code:
  32
  33 - `G_OS_WIN32` is defined when compiling for native Win32, without
  34   any POSIX emulation, other than to the extent provided by the
  35   bundled Microsoft C library.
  36
  37 - `G_WITH_CYGWIN` is defined if compiling for the Cygwin
  38   environment. Note that `G_OS_WIN32` is *not* defined in that case, as
  39   Cygwin is supposed to behave like Unix. `G_OS_UNIX` *is* defined by a GLib
  40   for Cygwin.
  41
  42 - `G_PLATFORM_WIN32` is defined when either `G_OS_WIN32` or `G_WITH_CYGWIN`
  43   is defined.
  44
  45 These macros are defined in `glibconfig.h`, and are thus available in
  46 all source files that include `<glib.h>`.
  47
  48 Additionally, there are the compiler-specific macros:
  49 - `__GNUC__` is defined when using GCC or Clang
  50 - `__clang__` is defined when using Clang or Clang-CL
  51 - `_MSC_VER` is defined when using MSVC or Clang-CL
  52
  53 `G_OS_WIN32` implies using the Microsoft C runtime, which used to be
  54 `msvcrt.dll` and is now the [Universal CRT](https://docs.microsoft.com/en-us/cpp/c-runtime-library/crt-library-features?view=vs-2015)
  55 when building with Visual Studio. When using the MinGW-GCC toolchain, the CRT
  56 in use depends on the settings used while the toolchain was built. We highly
  57 recommend [using the Universal CRT when building with
  58 MinGW](https://mingwpy.github.io/ucrt.html) too.
  59
  60 GLib is not actively tested with the static versions of the UCRT, but if you
  61 need to use those, patches are welcome.
  62
  63 # Building software that use GLib or GTK+
  64
  65 Building software that just *uses* GLib or GTK+ also require to have
  66 the right compiler set up the right way. If you intend to use MinGW-GCC,
  67 follow the relevant instructions below in that case, too.
  68
  69 You should link to GLib using the `-mms-bitfields` GCC flag. This flag means
  70 that the struct layout rules are identical to those used by MSVC. This is
  71 essential if the same DLLs are to be usable both from gcc- and MSVC-compiled
  72 code.
  73
  74 ## Cross-CRT issues
  75
  76 You should take care that the DLLs that your code links to are using the same
  77 C runtime library. Not doing so can and likely will lead to panics and crashes
  78 **unless** you're very careful while passing objects allocated by a library
  79 linked with one CRT to a library linked to another CRT, or (more commonly) not
  80 doing that at all.
  81
  82 If you *do* pass CRT objects across CRT boundaries, do not file any issues
  83 about whatever happens next.
  84
  85 To give an example, opening a `FILE` handle created by one CRT cannot be
  86 understood by any other CRT, and will lead to an access violation. You also
  87 cannot allocate memory in one CRT and free it using another.
  88
  89 There are [many other cases where you must not allow objects to cross CRT boundaries](https://docs.microsoft.com/en-us/cpp/c-runtime-library/potential-errors-passing-crt-objects-across-dll-boundaries?view=vs-2019),
  90 but in theory if you're **very very** careful, you can make things work. Again,
  91 please do not come to us for help if you choose to do this.
  92
  93 # Building GLib
  94
  95 You can build GLib with MinGW-GCC, MSVC, or (experimentally) with Clang-CL.
  96
  97 For all compilers, you will need the following:
  98
  99 - Install Python 3.6.x or newer, either 32-bit or 64-bit. We recommend enabling
 100   the option to add it to your `PATH`.
 101 - [Install Meson](https://mesonbuild.com/Getting-meson.html)
 102 - Install the [Ninja build tool](https://github.com/ninja-build/ninja/releases), which can also be
 103   installed with `pip3`. You can skip this step if you want to generate Visual
 104   Studio project files.
 105 - [git for Windows](https://gitforwindows.org/) is required, since Meson makes
 106   use of git to download dependencies using subprojects.
 107
 108 ## Building with MinGW-GCC
 109
 110 Open your MSYS or [MSYS2](https://www.msys2.org/) shell where you have the
 111 MinGW-GCC toolchain installed, and build GLib [like any other Meson
 112 project](https://mesonbuild.com/Quick-guide.html#compiling-a-meson-project).
 113
 114 ## Building with Visual Studio 2015 or newer
 115
 116 Meson is now the only supported method of building GLib using Visual Studio.
 117
 118 To do a build using Meson, do the following:
 119
 120 - Open a Visual Studio (or SDK) command prompt that matches the Visual Studio
 121   version and build platform (Win32/x86, x64, etc.) that will be used in all
 122   the following steps.
 123
 124 - Create an empty directory/folder for the build inside your GLib sources
 125   directory, say, `_builddir`, and `cd` into it.
 126
 127 - Set up the build using Meson:
 128
 129 ```cmd
 130 > meson .. --buildtype=<release|debug|debugoptimized> --prefix=<path> [--backend=vs]
 131 ```
 132
 133  Please see [the Meson docs](https://mesonbuild.com/Builtin-options.html#core-options)
 134  for an explanation for `--buildtype`.
 135
 136  The path passed for `--prefix` need not to be on the same drive as where the
 137  build is carried out, but it is recommended to use forward slashes for this
 138  path.  The `--backend=vs` option can be used if the Visual Studio project
 139  generator is preferred over using Ninja.
 140
 141 - Build, test and install the build:
 142   Run `ninja` to build, `meson test` to test and `meson install` to install the
 143   build. If you used `--backend=vs`, instead of running `ninja`, you need to
 144   use `msbuild` or you can open the generated solution in Visual Studio.
 145
 146 ## Building with old versions of Visual Studio
 147
 148 The steps are the same as above, with the following notes about issues that you might face.
 149
 150 ### C4819 build errors
 151
 152 If you are building GLib-based libraries or applications, or GLib itself
 153 and you see a `C4819` error (or warning, before `C4819` is treated as an error
 154 in `msvc_recommended_pragmas.h`), please be advised that this error/warning should
 155 not be disregarded, as this likely means portions of the build are not being
 156 done correctly, as this is an issue of Visual Studio running on CJK (East Asian)
 157 locales.  This is an issue that also affects builds of other projects, such as
 158 QT, Firefox, LibreOffice/OpenOffice, Pango and GTK, along with many other projects.
 159
 160 To overcome this problem, please set your system's locale setting for non-Unicode to
 161 English (United States), reboot, and restart the build, and the code should build
 162 normally.
 163
 164 ### Visual Studio 2008 hacks
 165
 166 - You need to run the following lines from your build directory, to embed the
 167   manifests that are generated during the build, assuming the built binaries
 168   are installed to `$(PREFIX)`, after a successful build/installation:
 169
 170 ```cmd
 171 > for /r %f in (*.dll.manifest) do if exist $(PREFIX)\bin\%~nf mt /manifest %f $(PREFIX)\bin\%~nf;2
 172 > for /r %f in (*.exe.manifest) do if exist $(PREFIX)\bin\%~nf mt /manifest %f $(PREFIX)\bin\%~nf;1
 173 ```
 174
 175
 176 - If building for amd64/x86_64/x64, sometimes the compilation of sources may seem to hang, which
 177   is caused by an optimization issue in the 2008 x64 compiler.  You need to use Task Manager to
 178   remove all running instances of `cl.exe`, which will cause the build process to terminate.  Update
 179   the build flags of the sources that hang on compilation by changing its `"/O2"` flag to `"/O1"`
 180   in `build.ninja`, and retry the build, where things should continue to build normally.  At the
 181   time of writing, this is needed for compiling `glib/gtestutils.c`, `gio/gsettings.c`,
 182   `gio/gsettingsschema.c` and `gio/tests/gsubprocess-testprog.c`