diff --git a/docs/supported-platforms.md b/docs/supported-platforms.md new file mode 100644 index 000000000..fbda4266c --- /dev/null +++ b/docs/supported-platforms.md @@ -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). diff --git a/docs/toolchain-requirements.md b/docs/toolchain-requirements.md new file mode 100644 index 000000000..fe5804a7c --- /dev/null +++ b/docs/toolchain-requirements.md @@ -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 `` (or `` +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. +