BUILD

   1 Building Dinit
   2 =-=-=-=-=-=-=-
   3
   4 Building Dinit should be a straight-forward process. It requires GNU make.
   5
   6 Edit the "mconfig" file to choose appropriate values for the configuration variables defined
   7 within. In particular:
   8
   9   CXX : should be set to the name of the C++ compiler (and linker)
  10   CXXOPTS :  are options passed to the compiler during compilation (see note for GCC below)
  11   EXTRA_LIBS : are any extra libraries required for linking; should not normally be needed.
  12
  13 Defaults for Linux and OpenBSD are provided. Note that the "eg++" or "clang++" package must
  14 be installed on OpenBSD as the default "g++" compiler is too old. Clang is part of the base
  15 system in recent releases.
  16
  17 Then, change into the "src" directory, and run "make" (or "gmake" if the system make is not
  18 GNU make, such as on most BSD systems):
  19
  20     cd src
  21     make
  22
  23 If everything goes smoothly this will build dinit, dinitctl, and optionally the shutdown
  24 utility. Use "make install" to install; you can specify an alternate installation by
  25 setting the "DESTDIR" variable, eg "make DESTDIR=/tmp/temporary-install-path install".
  26
  27
  28 Special note for GCC/Libstdc++
  29 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  30
  31 GCC 5.x onwards includes a "dual ABI" in its standard library implementation, aka Libstdc++.
  32 Compiling against the newer (C++11 and later) ABI can be achieved by adding
  33 -D_GLIBCXX_USE_CXX11_ABI=1 to the compiler command line; this uses a non-standard language
  34 extension to differently mangle symbol names in order to link against the new ABI versions.
  35
  36 (Some systems may be configured to build with the new ABI by default, and in that case you
  37 build against the old ABI using D_GLIBCXX_USE_CXX11_ABI=1).
  38
  39 This is problematic for several reasons. First, it prevents linking against the new ABI with
  40 other compilers that do not understand the language extension (LLVM i.e. clang++ does so
  41 in recent versions, so this is perhaps no longer much of a problem in practice). Secondly,
  42 some aspects of library behavior are ABI-dependent but cannot be changed using the ABI
  43 macro; in particular, exceptions thrown as a result of failed I/O operations are, in GCC
  44 versions 5.x and 6.x, always "old ABI" exceptions which cannot be caught by code compiled
  45 against the new ABI, and in GCC version 7.x they are always "new ABI" exceptions which cannot
  46 be caught by code compiled against the old ABI. Since the one library object now supposedly
  47 houses both ABIs, this means that at least one of the two ABIs is always broken.
  48
  49 A blog post describing the dual ABI mechanism can be found here:
  50
  51     https://developers.redhat.com/blog/2015/02/05/gcc5-and-the-c11-abi/
  52
  53 The bug regarding the issue with catching other-ABI exceptions is here:
  54
  55     https://gcc.gnu.org/bugzilla/show_bug.cgi?id=66145
  56
  57 Since Dinit is affected by this bug, the unfortunate possibility exists to break Dinit by
  58 upgrading GCC. If you have libstdc++ corresponding to GCC 5.x or 6.x, you *must* build with
  59 the old ABI, but Dinit will be broken if you upgrade to GCC 7. If you have libstdc++ from
  60 GCC 7, you *must* build with the new ABI. If the wrong ABI is used, Dinit may still run
  61 successfully but any attempt to load a non-existing service, for example, will cause Dinit
  62 to crash.