docs/toolchain-requirements.md

   1 Toolchain/Compiler requirements
   2 ===
   3
   4 GLib requires a toolchain that supports C99.
   5
   6 GLib contains some fall back code that allows supporting toolchains that are not
   7 fully C99-compatible.
   8
   9 GLib makes some assumptions about features of the C library and C preprocessor,
  10 compiler and linker that may go beyond what C99 mandates.  We will use features
  11 beyond C99 if they are substantially useful and if they are supported in a wide
  12 range of compilers.
  13
  14 In general, we are primarily interested in supporting these four compilers:
  15
  16  * GCC on *nix
  17  * Clang (LLVM)
  18  * MSVC
  19  * mingw32-w64
  20
  21 This is in keeping with our goal of primarily targetting GNU/Linux, Windows and
  22 Mac OS, along with Free Software POSIX-compliant operating systems.  See
  23 [Supported platforms](./supported-platforms.md) for a bit more information and
  24 rationale about that.
  25
  26 In particular, we are interested in MSVC because, although there are other
  27 compilers which target Windows, they do not output debugging information that is
  28 compatible with MSVC.  In interest of usability, we want users of GLib to be
  29 able to debug GLib along with their own code while using MSVC as their
  30 development environment.
  31
  32 At any given time, GLib may work with mingw32 (from mingw.org) but it is not
  33 specifically supported.  Politics aside, it seems that mingw.org is mostly
  34 dormant and, at this point, all of the big distributions have switched over to
  35 mingw32-w64.  In several cases, mingw.org has been missing APIs that we’ve
  36 wanted to use and upstream has not been responsive about adding them.
  37
  38 GLib will attempt to remain compatible with other compilers, but some ‘extra
  39 features’ are assumed.  Those are detailed below.
  40
  41 GLib additionally requires Python 3 to build.
  42
  43 C99 Varargs macros
  44 ---
  45
  46 _Hard requirement._
  47
  48 GLib requires C99 ``__VA_ARG__`` support for both C and C++ compilers.
  49
  50 Symbol visibility control
  51 ---
  52
  53 _Not a hard requirement._
  54
  55 When available, GLib uses `__attribute__((visibility("hidden")))` and the
  56 `-fvisibility=hidden` compiler option to control symbol visibility, and the
  57 `-Bsymbolic-functions` linker flag.
  58
  59 Builtin atomic operations
  60 ---
  61
  62 _Not a hard requirement._
  63
  64 GLib will fall back to using a mutex-based implementation if atomic builtins are
  65 not available.
  66
  67 C99 printf and positional parameters
  68 ---
  69
  70 _Not a hard requirement._
  71
  72 GLib can be built with an included printf implementation (from GNUlib) if the
  73 system printf is deficient.
  74
  75 Constructors and destructors
  76 ---
  77
  78 _Hard requirement._
  79
  80 GLib can work with pragma-based, as well as with attribute-based constructor
  81 support. There is a fallback for MSVC using a `DllMain()` instead.
  82
  83 `va_list` pass-by-reference
  84 ---
  85
  86 _Hard requirement._
  87
  88 GLib depends on the ability to pass-by-reference a `va_list`, as mandated in
  89 C99  § 7.15: “It is permitted to create a pointer to a `va_list` and pass that
  90 pointer to another function, in which case the original function may make
  91 further use of the original list after the other function returns.”
  92
  93 Support for `static inline`
  94 ---
  95
  96 _Hard requirement._
  97
  98 GLib depends on implementation of the `inline` keyword as described by
  99 C99 § 6.7.4.
 100
 101 GLib further assumes that functions appearing in header files and marked
 102 `static inline`, but not used in a particular compilation unit will:
 103
 104  * not generate warnings about being unused
 105  * not be emitted in the compiler’s output
 106
 107 It is possible that a compiler adheres to C99 § 6.7.4 but not to GLib’s further
 108 assumptions.  Such compilers may produce large numbers of warnings or large
 109 executables when compiling GLib or programs based on GLib.
 110
 111 Support for `alloca()`
 112 ---
 113
 114 _Hard requirement._
 115
 116 Your compiler must support `alloca()`, defined in `<alloca.h>` (or `<malloc.h>`
 117 on Windows) and it must accept a non-constant argument.
 118
 119 (C11) support for type redefinition
 120 ---
 121
 122 **This requirement has been temporarily suspended (on account of OpenBSD
 123 carrying an old version of gcc) but it will probably return in the future.**
 124
 125 Your compiler must allow “a typedef name [to] be redefined to denote the same
 126 type as it currently does”, as per C11 §6.7, item 3.
 127
 128 ‘Big’ enums
 129 ---
 130
 131 _Hard requirement._
 132
 133 Some of our enum types use `1<<31` as a value. We also use negative values in
 134 enums. We rely on the compiler to choose a suitable storage size for the enum
 135 that can accommodate this.
 136
 137 Selected C99 features
 138 ---
 139
 140 _Hard requirement._
 141
 142 Starting with GLib 2.52 and GTK 3.90, we will be using the following C99
 143 features where appropriate:
 144
 145  * Compound literals
 146  * Designated initializers
 147  * Mixed declarations
 148
 149 Function pointer conversions
 150 ---
 151
 152 _Hard requirement._
 153
 154 GLib heavily relies on the ability to convert a function pointer to a `void*`
 155 and back again losslessly. Any platform or compiler which doesn’t support this
 156 cannot be used to compile GLib or code which uses GLib. This precludes use of
 157 the `-pedantic` GCC flag with GLib.
 158
 159 `stdint.h`
 160 ---
 161
 162 _Hard requirement since GLib 2.67.x._
 163
 164 GLib [requires a C99 `stdint.h`](https://gitlab.gnome.org/GNOME/glib/-/merge_requests/1675)
 165 with all the usual sized integer types (`int8_t`, `uint64_t` and so on),
 166 believed to be supported by all relevant Unix platforms/compilers, as well as
 167 Microsoft compilers since MSVC 2013.
 168