luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-24 14:36:13 +01:00
Code Issues Packages Projects Releases Wiki Activity

README.win32: Update and convert to markdown

Browse Source
This commit is contained in:
Nirbheek Chauhan 2019-08-27 03:06:44 +05:30
parent 29388470f8
commit 184cbbcfd7
2 changed files with 183 additions and 194 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

195
README.win32
View File

@ -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

182
README.win32.md Normal file
View File

@ -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`