luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-04-28 10:06:53 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'compiler-toolchain-reqs' into 'main'

Browse Source 
docs: Add compiler and toolchain requirements from the wiki

See merge request GNOME/glib!2664
This commit is contained in:
Philip Withnall 2022-05-18 07:57:46 +00:00
commit 25d2925f3f
2 changed files with 263 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

95
docs/supported-platforms.md Normal file
View File

@ -0,0 +1,95 @@
Supported platforms
===
GLib’s approach to portability is that we only support systems that we can test.
That means that either a large number of GLib developers are regularly using
GLib on a particular system, or we have regular builds of GLib on that system.
Minimum versions
---
* macOS: minimum version OS X 10.7 (we
[don’t support universal binaries](https://bugzilla.gnome.org/show_bug.cgi?id=780238);
some features (like notification support)
[require OS X 10.9](https://bugzilla.gnome.org/show_bug.cgi?id=747146)
* Windows:
[minimum version is Windows 8](https://gitlab.gnome.org/GNOME/glib/-/merge_requests/1970),
minimum build chain is Visual Studio 2012
* Static builds are only supported with MinGW-based toolchains (cf
[this comment](https://gitlab.gnome.org/GNOME/glib/-/merge_requests/2384#note_1336662))
* Android: [minimum NDK version 15](https://gitlab.gnome.org/GNOME/glib/issues/1113)
* Linux: glibc newer than 2.5 (if using glibc; other forms of libc are supported)
Tested platforms
---
GLib is regularly built on at least the following systems:
* GNOME OS Nightly: https://os.gnome.org/
* Fedora: http://koji.fedoraproject.org/koji/packageinfo?packageID=382
* Ubuntu: http://packages.ubuntu.com/source/glib2.0
* Debian: https://packages.debian.org/experimental/libglib2.0-0
* FreeBSD: https://wiki.gnome.org/Projects/Jhbuild/FreeBSD
* openSUSE: https://build.opensuse.org/package/show/GNOME:Factory/glib2
* CI runners, https://gitlab.gnome.org/GNOME/glib/blob/main/.gitlab-ci.yml:
* Fedora (34, https://gitlab.gnome.org/GNOME/glib/-/blob/main/.gitlab-ci/fedora.Dockerfile)
* Debian (Bullseye, https://gitlab.gnome.org/GNOME/glib/-/blob/main/.gitlab-ci/debian-stable.Dockerfile)
* Windows (MinGW64)
* Windows (msys2-mingw32)
* Windows (Visual Studio 2017, and a static linking version)
* Android (NDK r23b, API 31, arm64, https://gitlab.gnome.org/GNOME/glib/-/blob/main/.gitlab-ci/android-ndk.sh)
* FreeBSD (12 and 13)
* macOS
If other platforms are to be supported, we need to set up regular CI testing for
them. Please contact us if you want to help.
Policy and rationale
---
Due to their position in the market, we consider supporting GNU/Linux, Windows
and macOS to be the highest priorities and we will go out of our way to
accommodate these systems, even in places that they are contravening standards.
In general, we are open to the idea of supporting any Free Software UNIX-like
system with good POSIX compliance. We are always interested in receiving
patches that improve our POSIX compliance — if there is a good POSIX equivalent
for a platform-specific API that we’re using, then all other things equal, we
prefer the POSIX one.
We may use a non-POSIX API available on one or more of our supported systems in
the case that it provides some advantage over the POSIX equivalent (such as the
case with `pipe2()` solving the `O_CLOEXEC` race). In these cases, we will try
to provide a fallback to the pure POSIX approach. If we’ve used a
system-specific API without providing a fallback to a largely-equivalent POSIX
API then it is likely a mistake, and we’re happy to receive a patch to fix it.
We are not interested in supporting other systems if it involves adding code
paths that we cannot test. Specifically, this means that we will reject patches
that introduce platform-specific `#ifdef` sections in the code unless we are
actively doing builds of GLib on this platform (ie: see the lists above). We’ve
historically accepted such patches from users of these systems on an ad hoc
basis, but it created an unsustainable situation. Patches that fix
platform-specific build issues in such a way that the code is improved in the
general case are of course welcome.
Although we aim to support all systems with good POSIX compliance, we are not
interested in adhering to “pure POSIX and nothing else”. If we need to add a
feature and we can provide good support on all of the platforms that we support
(above), we will not hold back for other systems. We will always try to provide
a fallback to a POSIX-specified approach, if possible, or to simply replace a
given functionality with a no-op, but even this may not be possible in cases of
critical functionality.
Specific notes
---
Note that we currently depend on a number of features specified in POSIX, but
listed as optional:
* [`CLOCK_MONOTONIC`](http://pubs.opengroup.org/onlinepubs/009695399/functions/clock_gettime.html)
is expected to be present and working
* [`pthread_condattr_setclock()`](http://pubs.opengroup.org/onlinepubs/7999959899/functions/pthread_condattr_setclock.html)
is expected to be present and working
Also see [toolchain requirements](./toolchain-requirements.md).

168
docs/toolchain-requirements.md Normal file
View File

@ -0,0 +1,168 @@
Toolchain/Compiler requirements
===
GLib requires a toolchain that supports C99.
GLib contains some fall back code that allows supporting toolchains that are not
fully C99-compatible.
GLib makes some assumptions about features of the C library and C preprocessor,
compiler and linker that may go beyond what C99 mandates. We will use features
beyond C99 if they are substantially useful and if they are supported in a wide
range of compilers.
In general, we are primarily interested in supporting these four compilers:
* GCC on *nix
* Clang (LLVM)
* MSVC
* mingw32-w64
This is in keeping with our goal of primarily targetting GNU/Linux, Windows and
Mac OS, along with Free Software POSIX-compliant operating systems. See
[Supported platforms](./supported-platforms.md) for a bit more information and
rationale about that.
In particular, we are interested in MSVC because, although there are other
compilers which target Windows, they do not output debugging information that is
compatible with MSVC. In interest of usability, we want users of GLib to be
able to debug GLib along with their own code while using MSVC as their
development environment.
At any given time, GLib may work with mingw32 (from mingw.org) but it is not
specifically supported. Politics aside, it seems that mingw.org is mostly
dormant and, at this point, all of the big distributions have switched over to
mingw32-w64. In several cases, mingw.org has been missing APIs that we’ve
wanted to use and upstream has not been responsive about adding them.
GLib will attempt to remain compatible with other compilers, but some ‘extra
features’ are assumed. Those are detailed below.
GLib additionally requires Python 3 to build.
Varargs macros
---
_Not a hard requirement._
GLib can work with either C99 or GNU style varargs macros.
Symbol visibility control
---
_Not a hard requirement._
When available, GLib uses `__attribute__((visibility("hidden")))` and the
`-fvisibility=hidden` compiler option to control symbol visibility, and the
`-Bsymbolic-functions` linker flag.
Builtin atomic operations
---
_Not a hard requirement._
GLib will fall back to using a mutex-based implementation if atomic builtins are
not available.
C99 printf and positional parameters
---
_Not a hard requirement._
GLib can be built with an included printf implementation (from GNUlib) if the
system printf is deficient.
Constructors and destructors
---
_Hard requirement._
GLib can work with pragma-based, as well as with attribute-based constructor
support. There is a fallback for MSVC using a `DllMain()` instead.
`va_list` pass-by-reference
---
_Hard requirement._
GLib depends on the ability to pass-by-reference a `va_list`, as mandated in
C99 § 7.15: “It is permitted to create a pointer to a `va_list` and pass that
pointer to another function, in which case the original function may make
further use of the original list after the other function returns.”
Support for `static inline`
---
_Hard requirement._
GLib depends on implementation of the `inline` keyword as described by
C99 § 6.7.4.
GLib further assumes that functions appearing in header files and marked
`static inline`, but not used in a particular compilation unit will:
* not generate warnings about being unused
* not be emitted in the compiler’s output
It is possible that a compiler adheres to C99 § 6.7.4 but not to GLib’s further
assumptions. Such compilers may produce large numbers of warnings or large
executables when compiling GLib or programs based on GLib.
Support for `alloca()`
---
_Hard requirement._
Your compiler must support `alloca()`, defined in `<alloca.h>` (or `<malloc.h>`
on Windows) and it must accept a non-constant argument.
(C11) support for type redefinition
---
**This requirement has been temporarily suspended (on account of OpenBSD
carrying an old version of gcc) but it will probably return in the future.**
Your compiler must allow “a typedef name [to] be redefined to denote the same
type as it currently does”, as per C11 §6.7, item 3.
‘Big’ enums
---
_Hard requirement._
Some of our enum types use `1<<31` as a value. We also use negative values in
enums. We rely on the compiler to choose a suitable storage size for the enum
that can accommodate this.
Selected C99 features
---
_Hard requirement._
Starting with GLib 2.52 and GTK+ 3.90, we will be using the following C99
features where appropriate:
* Compound literals
* Designated initializers
* Mixed declarations
Function pointer conversions
---
_Hard requirement._
GLib heavily relies on the ability to convert a function pointer to a `void*`
and back again losslessly. Any platform or compiler which doesn’t support this
cannot be used to compile GLib or code which uses GLib. This precludes use of
the `-pedantic` GCC flag with GLib.
`stdint.h`
---
_Hard requirement since GLib 2.67.x._
GLib [requires a C99 `stdint.h`](https://gitlab.gnome.org/GNOME/glib/-/merge_requests/1675)
with all the usual sized integer types (`int8_t`, `uint64_t` and so on),
believed to be supported by all relevant Unix platforms/compilers, as well as
Microsoft compilers since MSVC 2013.