[glib: 1/4] docs: Add compiler and toolchain requirements from the wiki

[Philip Withnall <pwithnall src gnome org>]

commit aa60b45ff8f233ff78a2a25973ceaa6d68aaa9c8
Author: Philip Withnall <pwithnall endlessos org>
Date:   Tue May 17 22:43:50 2022 +0100

    docs: Add compiler and toolchain requirements from the wiki
    
    These files are Markdown-ified versions of the following wiki pages:
     * https://wiki.gnome.org/Projects/GLib/CompilerRequirements
     * https://wiki.gnome.org/Projects/GLib/SupportedPlatforms
    
    Keeping the files in version control with the rest of the documentation
    means they should be easier to find, and easier to remember to keep up
    to date.
    
    They have not been modified other than to change to Markdown and tweak
    the formatting. Content updates to them will be done in future commits.
    
    Signed-off-by: Philip Withnall <pwithnall endlessos org>

 docs/supported-platforms.md    |  95 +++++++++++++++++++++++
 docs/toolchain-requirements.md | 168 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 263 insertions(+)
---
diff --git a/docs/supported-platforms.md b/docs/supported-platforms.md
new file mode 100644
index 0000000000..bf9dcd8abf
--- /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
+---
+
+ * Mac OS: minimum version OS X 10.7 (we don’t support universal binaries: see
+   https://bugzilla.gnome.org/show_bug.cgi?id=780238); some features (like
+   notification support) require OS X 10.9 (see
+   https://bugzilla.gnome.org/show_bug.cgi?id=747146)
+ * Windows: minimum version is Windows 8 (see
+   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, see 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/master/.gitlab-ci.yml:
+  * Fedora (31, https://gitlab.gnome.org/GNOME/glib/-/blob/master/.gitlab-ci/fedora.Dockerfile)
+  * Debian (Buster, https://gitlab.gnome.org/GNOME/glib/-/blob/master/.gitlab-ci/debian-stable.Dockerfile)
+  * Windows (MinGW64)
+  * Windows (msys2-mingw32)
+  * Windows (Visual Studio 2017)
+  * Android (NDK r17b, API 21+28, arm64, 
https://gitlab.gnome.org/GNOME/glib/-/blob/master/.gitlab-ci/android-download-ndk.sh)
+  * FreeBSD (11 and 12)
+  * 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 Mac OS 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 0000000000..fe5804a7c7
--- /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 `<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.
+