mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-02-04 18:26:19 +01:00
Merge branch 'compiler-toolchain-reqs' into 'main'
docs: Add compiler and toolchain requirements from the wiki See merge request GNOME/glib!2664
This commit is contained in:
Philip Withnall
commit
25d2925f3f
95
docs/supported-platforms.md
Normal file
95
docs/supported-platforms.md
Normal 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
168
docs/toolchain-requirements.md
Normal 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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user