README.win32

   1 Tor Lillqvist <tml@iki.fi>
   2 Hans Breuer <hans@breuer.org>
   3
   4 Note that this document is not really maintained in a serious
   5 fashion. Lots of information here might be misleading or outdated. You
   6 have been warned.
   7
   8 General
   9 =======
  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 http://www.gtk.org/download-windows.html . 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 in involved.
  16
  17 To build GLib on Win32, you can use either gcc ("mingw") or the
  18 Microsoft compiler and tools. For the latter, MSVC6 and later have
  19 been used successfully. Also the Digital Mars C/C++ compiler has
  20 reportedly been used.
  21
  22 You can also cross-compile GLib for Windows from Linux using the
  23 cross-compiling mingw packages for your distro.
  24
  25 Note that to just *use* GLib on Windows, there is no need to build it
  26 yourself.
  27
  28 On Windows setting up a correct build environment can be quite a task,
  29 especially if you are used to just typing `meson; ninja` on Linux,
  30 and expect things to work as smoothly on Windows.
  31
  32 The following preprocessor macros are to be used for conditional
  33 compilation related to Win32 in GLib-using code:
  34
  35 - G_OS_WIN32 is defined when compiling for native Win32, without
  36   any POSIX emulation, other than to the extent provided by the
  37   bundled Microsoft C library (msvcr*.dll).
  38
  39 - G_WITH_CYGWIN is defined if compiling for the Cygwin
  40   environment. Note that G_OS_WIN32 is *not* defined in that case, as
  41   Cygwin is supposed to behave like Unix. G_OS_UNIX *is* defined by a GLib
  42   for Cygwin.
  43
  44 - G_PLATFORM_WIN32 is defined when either G_OS_WIN32 or G_WITH_CYGWIN
  45   is defined.
  46
  47 These macros are defined in glibconfig.h, and are thus available in
  48 all source files that include <glib.h>.
  49
  50 Additionally, there are the compiler-specific macros:
  51 - __GNUC__ is defined when using gcc
  52 - _MSC_VER is defined when using the Microsoft compiler
  53 - __DMC__ is defined when using the Digital Mars C/C++ compiler
  54
  55 G_OS_WIN32 implies using the Microsoft C runtime, normally
  56 msvcrt.dll. GLib is not known to work with the older crtdll.dll
  57 runtime, or the static Microsoft C runtime libraries libc.lib and
  58 libcmt.lib. It apparently does work with the debugging version of
  59 msvcrt.dll, msvcrtd.dll. If compiled with Microsoft compilers newer
  60 than MSVC6, it also works with their compiler-specific runtimes, like
  61 msvcr70.dll or msvcr80.dll. Please note that it's non totally clear if
  62 you would be allowed by the license to distrubute a GLib linked to
  63 msvcr70.dll or msvcr80.dll, as those are not part of the operating
  64 system, but of the MSVC product. msvcrt.dll is part of Windows.
  65
  66 For people using Visual Studio 2005 or later:
  67
  68 If you are building GLib-based libraries or applications, or GLib itself
  69 and you see a C4819 error (or warning, before C4819 is treated as an error
  70 in msvc_recommended_pragmas.h), please be advised that this error/warning should
  71 not be disregarded, as this likely means portions of the build is not being
  72 done correctly, as this is an issue of Visual Studio running on CJK (East Asian)
  73 locales.  This is an issue that also affects builds of other projects, such as
  74 QT, Firefox, LibreOffice/OpenOffice, Pango and GTK+, along with many other projects.
  75
  76 To overcome this problem, please set your system's locale setting for non-Unicode to
  77 English (United States), reboot, and restart the build, and the code should build
  78 normally.  See also this GNOME Wiki page [1] that gives a bit further info on this.
  79
  80 In Visual Studio 2015 and later, the /utf-8 option is provided, which is set by the
  81 latest Meson releases when building GLib, and can be used in other project files
  82 that uses GLib to avoid the need of setting your system's locale setting for
  83 non-Unicode and the subsequent requirement to restart the system.
  84
  85 Building software that use GLib or GTK+
  86 =======================================
  87
  88 Building software that just *uses* GLib or GTK+ also require to have
  89 the right compiler set up the right way. If you intend to use gcc,
  90 follow the relevant instructions below in that case, too.
  91
  92 Tor uses gcc with the -mms-bitfields flag which means that in order to
  93 use the prebuilt DLLs (especially of GTK+), if you compile your code
  94 with gcc, you *must* also use that flag. This flag means that the
  95 struct layout rules are identical to those used by MSVC. This is
  96 essential if the same DLLs are to be usable both from gcc- and
  97 MSVC-compiled code. Such compatibility is desirable.
  98
  99 When using the prebuilt GLib DLLs that use msvcrt.dll from code that
 100 uses other C runtimes like for example msvcr70.dll, one should note
 101 that one cannot use such GLib API that take or returns file
 102 descriptors. On Windows, a file descriptor (the small integer as
 103 returned by open() and handled by related functions, and included in
 104 the FILE struct) is an index into a table local to the C runtime
 105 DLL. A file descriptor in one C runtime DLL does not have the same
 106 meaning in another C runtime DLL.
 107
 108 Building GLib
 109 =============
 110
 111 Again, first decide whether you really want to do this.
 112
 113 Before building GLib you must also have a GNU gettext-runtime
 114 developer package. Get prebuilt binaries of gettext-runtime from
 115 http://www.gtk.org/download-windows.html .
 116
 117 Building with Visual Studio
 118 ===========================
 119
 120 Meson is now the supported method of building GLib using Visual Studio.
 121
 122 Note that you will need a libintl implementation, zlib, and libFFI, and
 123 optionally PCRE1, which should preferably be built with the same compiler
 124 that is now being used to build GLib.  Ensure that their headers, .lib's
 125 and DLLs can be found in the paths specified by the INCLUDE, LIB and PATH
 126 envvars.  The Meson build process will pull in a copy of the ZLib and the
 127 libFFI sources if they cannot be found, and will build an in-source copy
 128 of PCRE1 if PCRE1 cannt be found.
 129
 130 One can also refer to the following page for building the dependencies:
 131
 132 https://wiki.gnome.org/Projects/GTK%2B/Win32/MSVCCompilationOfGTKStack
 133
 134 You will also need the following items:
 135 -Python 3.6.x, you need the 32-bit version if you are building GLib
 136  as a 32-bit/x86 build, or the amd64/x64 version for building 64-bit/x86-64
 137  builds.  You will then need to install or update Meson by using pip.
 138 -The Ninja build tool, required for Visual Studio 2008, 2012 and 2013 builds,
 139  and optional for 2010, 2015 and 2017 builds, where Visual Studio projects
 140  can be generated instead of the Ninja build files.
 141 -GIT for Windows is highly recommended, in the case where some required
 142  dependencies are not found, and Meson makes use of GIT to download
 143  the sources to build in the build process.
 144
 145 To do a build using Meson, do the following:
 146
 147 -Open a Visual Studio (or SDK) command prompt that matches the Visual Studio
 148  version and build platform (Win32/x86, x64, etc.) that will be used in all
 149  the following steps.
 150
 151 -Create an empty directory/folder for the build.  It needs to be in the same
 152  drive as where your GLib sources are located (i.e. $(GLIB_SRCDIR)).  cd into
 153  that directory/folder.
 154
 155 -Setup your PATH envvar:
 156
 157    set PATH=%PATH%;$(PYTHON_INSTALL_DIR);$(NINJA_DIR)
 158
 159  where PYTHON_INSTALL_DIR is where Python 3.6.x+ is installed to, and NINJA_DIR
 160  is where your ninja executable can be found.  The NINJA_DIR can be omitted if one
 161  passes --backend=vs to the Meson configuration line, for Visual Studio 2010, 2015
 162  and 2017 builds.
 163
 164 -Configure the build using Meson:
 165
 166     python $(PYTHON_INSTALL_DIR)\scripts\meson.py $(GLIB_SRCDIR) --buildtype=$(build_configuration) --prefix=$(INSTALL_PREFIX) [--backend=vs]
 167
 168  Please see the Meson docs for an explanation for --buildtype, the path passed for
 169  --prefix need not to be on the same drive as where the build is carried out, but
 170  it is recommended to use forward slashes for this path.  The --backend=vs can be
 171  used if the Visual Studio project generator is preferred over using Ninja, for
 172  Visual Studio 2010, 2015 and 2017 builds.
 173
 174 -Build, test and install the build:
 175  Run ninja (and ninja test and ninja install) or open the generated Visual Studio
 176  projects to compile, test and install the build.
 177
 178 Note that if building the sources with Visual Studio 2008, note the following
 179 additional items:
 180
 181 -You need to run the following lines from your build directory, to embed the manifests
 182  that are generated during the build, assuming the built binaries are installed
 183  to $(PREFIX), after a successful build/installation:
 184
 185 for /r %f in (*.dll.manifest) do if exist $(PREFIX)\bin\%~nf mt /manifest %f $(PREFIX)\bin\%~nf;2
 186 for /r %f in (*.exe.manifest) do if exist $(PREFIX)\bin\%~nf mt /manifest %f $(PREFIX)\bin\%~nf;1
 187
 188 -If building for amd64/x86_64/x64, sometimes the compilation of sources may seem to hang, which
 189  is caused by an optimization issue in the 2008 x64 compiler.  You need to use Task Manager to
 190  remove all running instances of cl.exe, which will cause the build process to terminate.  Update
 191  the build flags of the sources that hang on compilation by changing its "/O2" flag to "/O1"
 192  in build.ninja, and  retry the build, where things should continue to build normally.  At the
 193  time of writing, this is needed for compiling glib/gtestutils.c,  gio/gsettings.c,
 194  gio/gsettingsschema.c and gio/tests/gsubprocess-testprog.c