[glib: 1/3] README.win32: Update and convert to markdown

[Nirbheek Chauhan <nirbheekc src gnome org>]

commit 184cbbcfd7f3d1d0f45d592f33bb99c670b2c7e8
Author: Nirbheek Chauhan <nirbheek centricular com>
Date:   Tue Aug 27 03:06:44 2019 +0530

    README.win32: Update and convert to markdown

 README.win32    | 195 +-------------------------------------------------------
 README.win32.md | 182 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 183 insertions(+), 194 deletions(-)
---
diff --git a/README.win32 b/README.win32
index b7bce104b..2a31029f9 100644
--- a/README.win32
+++ b/README.win32
@@ -1,194 +1 @@
-Tor Lillqvist <tml iki fi>
-Hans Breuer <hans breuer org>
-
-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 <glib.h>.
-
-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 `<fanc999 yahoo com tw>`
+Philip Withnall `<withnall endlessm com>`
+Nirbheek Chauhan `<nirbheek centricular com>`
+
+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 `<glib.h>`.
+
+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=<release|debug|debugoptimized> --prefix=<path> [--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`