From 184cbbcfd7f3d1d0f45d592f33bb99c670b2c7e8 Mon Sep 17 00:00:00 2001 From: Nirbheek Chauhan Date: Tue, 27 Aug 2019 03:06:44 +0530 Subject: [PATCH] README.win32: Update and convert to markdown --- README.win32 | 195 +----------------------------------------------- README.win32.md | 182 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 183 insertions(+), 194 deletions(-) create mode 100644 README.win32.md diff --git a/README.win32 b/README.win32 index b7bce104b..2a31029f9 100644 --- a/README.win32 +++ b/README.win32 @@ -1,194 +1 @@ -Tor Lillqvist -Hans Breuer - -Note that this document is not really maintained in a serious -fashion. Lots of information here might be misleading or outdated. You -have been warned. - -General -======= - -For prebuilt binaries (DLLs and EXEs) and developer packages (headers, -import libraries) of GLib, Pango, GTK+ etc for Windows, go to -http://www.gtk.org/download-windows.html . They are for "native" -Windows meaning they use the Win32 API and Microsoft C runtime library -only. No POSIX (Unix) emulation layer like Cygwin in involved. - -To build GLib on Win32, you can use either gcc ("mingw") or the -Microsoft compiler and tools. For the latter, MSVC6 and later have -been used successfully. Also the Digital Mars C/C++ compiler has -reportedly been used. - -You can also cross-compile GLib for Windows from Linux using the -cross-compiling mingw packages for your distro. - -Note that to just *use* GLib on Windows, there is no need to build it -yourself. - -On Windows setting up a correct build environment can be quite a task, -especially if you are used to just typing `meson; ninja` on Linux, -and expect things to work as smoothly on Windows. - -The following preprocessor macros are to be used for conditional -compilation related to Win32 in GLib-using code: - -- G_OS_WIN32 is defined when compiling for native Win32, without - any POSIX emulation, other than to the extent provided by the - bundled Microsoft C library (msvcr*.dll). - -- G_WITH_CYGWIN is defined if compiling for the Cygwin - environment. Note that G_OS_WIN32 is *not* defined in that case, as - Cygwin is supposed to behave like Unix. G_OS_UNIX *is* defined by a GLib - for Cygwin. - -- G_PLATFORM_WIN32 is defined when either G_OS_WIN32 or G_WITH_CYGWIN - is defined. - -These macros are defined in glibconfig.h, and are thus available in -all source files that include . - -Additionally, there are the compiler-specific macros: -- __GNUC__ is defined when using gcc -- _MSC_VER is defined when using the Microsoft compiler -- __DMC__ is defined when using the Digital Mars C/C++ compiler - -G_OS_WIN32 implies using the Microsoft C runtime, normally -msvcrt.dll. GLib is not known to work with the older crtdll.dll -runtime, or the static Microsoft C runtime libraries libc.lib and -libcmt.lib. It apparently does work with the debugging version of -msvcrt.dll, msvcrtd.dll. If compiled with Microsoft compilers newer -than MSVC6, it also works with their compiler-specific runtimes, like -msvcr70.dll or msvcr80.dll. Please note that it's non totally clear if -you would be allowed by the license to distrubute a GLib linked to -msvcr70.dll or msvcr80.dll, as those are not part of the operating -system, but of the MSVC product. msvcrt.dll is part of Windows. - -For people using Visual Studio 2005 or later: - -If you are building GLib-based libraries or applications, or GLib itself -and you see a C4819 error (or warning, before C4819 is treated as an error -in msvc_recommended_pragmas.h), please be advised that this error/warning should -not be disregarded, as this likely means portions of the build is not being -done correctly, as this is an issue of Visual Studio running on CJK (East Asian) -locales. This is an issue that also affects builds of other projects, such as -QT, Firefox, LibreOffice/OpenOffice, Pango and GTK+, along with many other projects. - -To overcome this problem, please set your system's locale setting for non-Unicode to -English (United States), reboot, and restart the build, and the code should build -normally. See also this GNOME Wiki page [1] that gives a bit further info on this. - -In Visual Studio 2015 and later, the /utf-8 option is provided, which is set by the -latest Meson releases when building GLib, and can be used in other project files -that uses GLib to avoid the need of setting your system's locale setting for -non-Unicode and the subsequent requirement to restart the system. - -Building software that use GLib or GTK+ -======================================= - -Building software that just *uses* GLib or GTK+ also require to have -the right compiler set up the right way. If you intend to use gcc, -follow the relevant instructions below in that case, too. - -Tor uses gcc with the -mms-bitfields flag which means that in order to -use the prebuilt DLLs (especially of GTK+), if you compile your code -with gcc, you *must* also use that flag. This flag means that the -struct layout rules are identical to those used by MSVC. This is -essential if the same DLLs are to be usable both from gcc- and -MSVC-compiled code. Such compatibility is desirable. - -When using the prebuilt GLib DLLs that use msvcrt.dll from code that -uses other C runtimes like for example msvcr70.dll, one should note -that one cannot use such GLib API that take or returns file -descriptors. On Windows, a file descriptor (the small integer as -returned by open() and handled by related functions, and included in -the FILE struct) is an index into a table local to the C runtime -DLL. A file descriptor in one C runtime DLL does not have the same -meaning in another C runtime DLL. - -Building GLib -============= - -Again, first decide whether you really want to do this. - -Before building GLib you must also have a GNU gettext-runtime -developer package. Get prebuilt binaries of gettext-runtime from -http://www.gtk.org/download-windows.html . - -Building with Visual Studio -=========================== - -Meson is now the supported method of building GLib using Visual Studio. - -Note that you will need a libintl implementation, zlib, and libFFI, and -optionally PCRE1, which should preferably be built with the same compiler -that is now being used to build GLib. Ensure that their headers, .lib's -and DLLs can be found in the paths specified by the INCLUDE, LIB and PATH -envvars. The Meson build process will pull in a copy of the ZLib and the -libFFI sources if they cannot be found, and will build an in-source copy -of PCRE1 if PCRE1 cannt be found. - -One can also refer to the following page for building the dependencies: - -https://wiki.gnome.org/Projects/GTK%2B/Win32/MSVCCompilationOfGTKStack - -You will also need the following items: --Python 3.6.x, you need the 32-bit version if you are building GLib - as a 32-bit/x86 build, or the amd64/x64 version for building 64-bit/x86-64 - builds. You will then need to install or update Meson by using pip. --The Ninja build tool, required for Visual Studio 2008, 2012 and 2013 builds, - and optional for 2010, 2015 and 2017 builds, where Visual Studio projects - can be generated instead of the Ninja build files. --GIT for Windows is highly recommended, in the case where some required - dependencies are not found, and Meson makes use of GIT to download - the sources to build in the build process. - -To do a build using Meson, do the following: - --Open a Visual Studio (or SDK) command prompt that matches the Visual Studio - version and build platform (Win32/x86, x64, etc.) that will be used in all - the following steps. - --Create an empty directory/folder for the build. It needs to be in the same - drive as where your GLib sources are located (i.e. $(GLIB_SRCDIR)). cd into - that directory/folder. - --Setup your PATH envvar: - - set PATH=%PATH%;$(PYTHON_INSTALL_DIR);$(NINJA_DIR) - - where PYTHON_INSTALL_DIR is where Python 3.6.x+ is installed to, and NINJA_DIR - is where your ninja executable can be found. The NINJA_DIR can be omitted if one - passes --backend=vs to the Meson configuration line, for Visual Studio 2010, 2015 - and 2017 builds. - --Configure the build using Meson: - - python $(PYTHON_INSTALL_DIR)\scripts\meson.py $(GLIB_SRCDIR) --buildtype=$(build_configuration) --prefix=$(INSTALL_PREFIX) [--backend=vs] - - Please see the Meson docs for an explanation for --buildtype, the path passed for - --prefix need not to be on the same drive as where the build is carried out, but - it is recommended to use forward slashes for this path. The --backend=vs can be - used if the Visual Studio project generator is preferred over using Ninja, for - Visual Studio 2010, 2015 and 2017 builds. - --Build, test and install the build: - Run ninja (and ninja test and ninja install) or open the generated Visual Studio - projects to compile, test and install the build. - -Note that if building the sources with Visual Studio 2008, note the following -additional items: - --You need to run the following lines from your build directory, to embed the manifests - that are generated during the build, assuming the built binaries are installed - to $(PREFIX), after a successful build/installation: - -for /r %f in (*.dll.manifest) do if exist $(PREFIX)\bin\%~nf mt /manifest %f $(PREFIX)\bin\%~nf;2 -for /r %f in (*.exe.manifest) do if exist $(PREFIX)\bin\%~nf mt /manifest %f $(PREFIX)\bin\%~nf;1 - --If building for amd64/x86_64/x64, sometimes the compilation of sources may seem to hang, which - is caused by an optimization issue in the 2008 x64 compiler. You need to use Task Manager to - remove all running instances of cl.exe, which will cause the build process to terminate. Update - the build flags of the sources that hang on compilation by changing its "/O2" flag to "/O1" - in build.ninja, and retry the build, where things should continue to build normally. At the - time of writing, this is needed for compiling glib/gtestutils.c, gio/gsettings.c, - gio/gsettingsschema.c and gio/tests/gsubprocess-testprog.c +See README.win32.md diff --git a/README.win32.md b/README.win32.md new file mode 100644 index 000000000..2925d3ddf --- /dev/null +++ b/README.win32.md @@ -0,0 +1,182 @@ +Chun-wei Fan `` +Philip Withnall `` +Nirbheek Chauhan `` + +This document was last updated in 2019. You're reading this in the future, and +lots of information might be misleading or outdated in your age. You have been +warned. + +# General + +For prebuilt binaries (DLLs and EXEs) and developer packages (headers, +import libraries) of GLib, Pango, GTK+ etc for Windows, go to +https://www.gtk.org/download/windows.php . They are for "native" +Windows meaning they use the Win32 API and Microsoft C runtime library +only. No POSIX (Unix) emulation layer like Cygwin is involved. + +To build GLib on Win32, you can use either GCC ("MinGW") or the Microsoft +Visual Studio toolchain. For the latter, Visual Studio 2015 and later are +recommended. For older Visual Studio versions, see below. + +You can also cross-compile GLib for Windows from Linux using the +cross-compiling mingw packages for your distro. + +Note that to just *use* GLib on Windows, there is no need to build it +yourself. + +On Windows setting up a correct build environment is very similar to typing +`meson; ninja` like on Linux. + +The following preprocessor macros are to be used for conditional +compilation related to Win32 in GLib-using code: + +- `G_OS_WIN32` is defined when compiling for native Win32, without + any POSIX emulation, other than to the extent provided by the + bundled Microsoft C library. + +- `G_WITH_CYGWIN` is defined if compiling for the Cygwin + environment. Note that `G_OS_WIN32` is *not* defined in that case, as + Cygwin is supposed to behave like Unix. `G_OS_UNIX` *is* defined by a GLib + for Cygwin. + +- `G_PLATFORM_WIN32` is defined when either `G_OS_WIN32` or `G_WITH_CYGWIN` + is defined. + +These macros are defined in `glibconfig.h`, and are thus available in +all source files that include ``. + +Additionally, there are the compiler-specific macros: +- `__GNUC__` is defined when using GCC or Clang +- `__clang__` is defined when using Clang or Clang-CL +- `_MSC_VER` is defined when using MSVC or Clang-CL + +`G_OS_WIN32` implies using the Microsoft C runtime, which used to be +`msvcrt.dll` and is now the [Universal CRT](https://docs.microsoft.com/en-us/cpp/c-runtime-library/crt-library-features?view=vs-2015) +when building with Visual Studio. When using the MinGW-GCC toolchain, the CRT +in use depends on the settings used while the toolchain was built. We highly +recommend [using the Universal CRT when building with +MinGW](https://mingwpy.github.io/ucrt.html) too. + +GLib is not actively tested with the static versions of the UCRT, but if you +need to use those, patches are welcome. + +# Building software that use GLib or GTK+ + +Building software that just *uses* GLib or GTK+ also require to have +the right compiler set up the right way. If you intend to use MinGW-GCC, +follow the relevant instructions below in that case, too. + +You should link to GLib using the `-mms-bitfields` GCC flag. This flag means +that the struct layout rules are identical to those used by MSVC. This is +essential if the same DLLs are to be usable both from gcc- and MSVC-compiled +code. + +## Cross-CRT issues + +You should take care that the DLLs that your code links to are using the same +C runtime library. Not doing so can and likely will lead to panics and crashes +**unless** you're very careful while passing objects allocated by a library +linked with one CRT to a library linked to another CRT, or (more commonly) not +doing that at all. + +If you *do* pass CRT objects across CRT boundaries, do not file any issues +about whatever happens next. + +To give an example, opening a `FILE` handle created by one CRT cannot be +understood by any other CRT, and will lead to an access violation. You also +cannot allocate memory in one CRT and free it using another. + +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), +but in theory if you're **very very** careful, you can make things work. Again, +please do not come to us for help if you choose to do this. + +# Building GLib + +You can build GLib with MinGW-GCC, MSVC, or (experimentally) with Clang-CL. + +For all compilers, you will need the following: + +- Install Python 3.6.x or newer, either 32-bit or 64-bit. We recommend enabling + the option to add it to your `PATH`. +- [Install Meson](https://mesonbuild.com/Getting-meson.html) +- Install the [Ninja build tool](https://github.com/ninja-build/ninja/releases), which can also be + installed with `pip3`. You can skip this step if you want to generate Visual + Studio project files. +- [git for Windows](https://gitforwindows.org/) is required, since Meson makes + use of git to download dependencies using subprojects. + +## Building with MinGW-GCC + +Open your MSYS or [MSYS2](https://www.msys2.org/) shell where you have the +MinGW-GCC toolchain installed, and build GLib [like any other Meson +project](https://mesonbuild.com/Quick-guide.html#compiling-a-meson-project). + +## Building with Visual Studio 2015 or newer + +Meson is now the only supported method of building GLib using Visual Studio. + +To do a build using Meson, do the following: + +- Open a Visual Studio (or SDK) command prompt that matches the Visual Studio + version and build platform (Win32/x86, x64, etc.) that will be used in all + the following steps. + +- Create an empty directory/folder for the build inside your GLib sources + directory, say, `_builddir`, and `cd` into it. + +- Set up the build using Meson: + +```cmd +> meson .. --buildtype= --prefix= [--backend=vs] +``` + + Please see [the Meson docs](https://mesonbuild.com/Builtin-options.html#core-options) + for an explanation for `--buildtype`. + + The path passed for `--prefix` need not to be on the same drive as where the + build is carried out, but it is recommended to use forward slashes for this + path. The `--backend=vs` option can be used if the Visual Studio project + generator is preferred over using Ninja. + +- Build, test and install the build: + Run `ninja` to build, `meson test` to test and `meson install` to install the + build. If you used `--backend=vs`, instead of running `ninja`, you need to + use `msbuild` or you can open the generated solution in Visual Studio. + +## Building with old versions of Visual Studio + +The steps are the same as above, with the following notes about issues that you might face. + +### C4819 build errors + +If you are building GLib-based libraries or applications, or GLib itself +and you see a `C4819` error (or warning, before `C4819` is treated as an error +in `msvc_recommended_pragmas.h`), please be advised that this error/warning should +not be disregarded, as this likely means portions of the build are not being +done correctly, as this is an issue of Visual Studio running on CJK (East Asian) +locales. This is an issue that also affects builds of other projects, such as +QT, Firefox, LibreOffice/OpenOffice, Pango and GTK, along with many other projects. + +To overcome this problem, please set your system's locale setting for non-Unicode to +English (United States), reboot, and restart the build, and the code should build +normally. + +### Visual Studio 2008 hacks + +- You need to run the following lines from your build directory, to embed the + manifests that are generated during the build, assuming the built binaries + are installed to `$(PREFIX)`, after a successful build/installation: + +```cmd +> for /r %f in (*.dll.manifest) do if exist $(PREFIX)\bin\%~nf mt /manifest %f $(PREFIX)\bin\%~nf;2 +> for /r %f in (*.exe.manifest) do if exist $(PREFIX)\bin\%~nf mt /manifest %f $(PREFIX)\bin\%~nf;1 +``` + + +- If building for amd64/x86_64/x64, sometimes the compilation of sources may seem to hang, which + is caused by an optimization issue in the 2008 x64 compiler. You need to use Task Manager to + remove all running instances of `cl.exe`, which will cause the build process to terminate. Update + the build flags of the sources that hang on compilation by changing its `"/O2"` flag to `"/O1"` + in `build.ninja`, and retry the build, where things should continue to build normally. At the + time of writing, this is needed for compiling `glib/gtestutils.c`, `gio/gsettings.c`, + `gio/gsettingsschema.c` and `gio/tests/gsubprocess-testprog.c`