BUILD.txt

   1 Building Dinit
   2 =-=-=-=-=-=-=-
   3
   4 Building Dinit should be a straight-forward process. It requires GNU make and a C++11 compiler
   5 (GCC version 4.9 and later, or Clang ~5.0 and later, should be fine)
   6
   7 Edit the "mconfig" file to choose appropriate values for the configuration variables defined
   8 within. In particular:
   9
  10   CXX : should be set to the name of the C++ compiler (and link driver)
  11   CXXOPTS :  are options passed to the compiler during compilation (see note for GCC below)
  12   LDFLAGS :  are any extra flags required for linking; should not normally be needed
  13              (FreeBSD requires -lrt).
  14
  15 Suitable defaults for a number of systems are provided. Note that the "eg++" or "clang++" package
  16 must be installed on OpenBSD as the default "g++" compiler is too old. Clang is part of the base
  17 system in recent releases.
  18
  19 Then, change into the "src" directory, and run "make" (or "gmake" if the system make is not
  20 GNU make, such as on most BSD systems):
  21
  22     cd src
  23     make
  24
  25 If everything goes smoothly this will build dinit, dinitctl, and optionally the shutdown
  26 utility. Use "make install" to install; you can specify an alternate installation by
  27 setting the "DESTDIR" variable, eg "make DESTDIR=/tmp/temporary-install-path install".
  28
  29
  30 Running test suite
  31 =-=-=-=-=-=-=-=-=-
  32
  33 Build the "check" target in order to run the test suite:
  34
  35     make check
  36
  37 The standard mconfig options enable various sanitizers during build of the tests. On Linux you may
  38 see an error such as the following:
  39
  40     make[3]: Leaving directory '/home/davmac/workspace/dinit/src/tests/cptests'
  41     ./tests
  42     ==25332==ERROR: AddressSanitizer failed to allocate 0xdfff0001000 (15392894357504) bytes at
  43     address 2008fff7000 (errno: 12)
  44     ==25332==ReserveShadowMemoryRange failed while trying to map 0xdfff0001000 bytes. Perhaps
  45     you're using ulimit -v
  46     make[2]: *** [Makefile:12: run-tests] Aborted
  47
  48 If you get this, either disable the address sanitizer or make sure you have overcommit enabled:
  49
  50     echo 1 > /proc/sys/vm/overcommit_memory
  51
  52 Any test failures will abort the test suite run immediately.
  53
  54 In addition to the standard test suite, there is experimental support for fuzzing the control
  55 protocol handling using LLVM/clang's fuzzer (libFuzzer). Change to the `src/tests/cptests`
  56 directory and build the "fuzz" target:
  57
  58     make fuzz
  59
  60 Then create a "corpus" directory and run the fuzzer:
  61
  62     mkdir corpus
  63     ./fuzz corpus
  64
  65 This will auto-generate test data as it finds input which triggers new execution paths. Check
  66 libFuzzer documentation for further details.
  67
  68
  69 Special note for GCC/Libstdc++
  70 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  71
  72 (Note: the issue discussed here has apparently been resolved in recent GCC versions).
  73
  74 GCC 5.x onwards includes a "dual ABI" in its standard library implementation, aka Libstdc++.
  75 Compiling against the newer (C++11 and later) ABI can be achieved by adding
  76 -D_GLIBCXX_USE_CXX11_ABI=1 to the compiler command line; this uses a non-standard language
  77 extension to differently mangle symbol names in order to link against the new ABI versions.
  78
  79 (Some systems may be configured to build with the new ABI by default, and in that case you
  80 build against the old ABI using D_GLIBCXX_USE_CXX11_ABI=1).
  81
  82 This is problematic for several reasons. First, it prevents linking against the new ABI with
  83 other compilers that do not understand the language extension (LLVM i.e. clang++ does so
  84 in recent versions, so this is perhaps no longer much of a problem in practice). Secondly,
  85 some aspects of library behavior are ABI-dependent but cannot be changed using the ABI
  86 macro; in particular, exceptions thrown as a result of failed I/O operations are, in GCC
  87 versions 5.x and 6.x, always "old ABI" exceptions which cannot be caught by code compiled
  88 against the new ABI, and in GCC version 7.x they are always "new ABI" exceptions which cannot
  89 be caught by code compiled against the old ABI. Since the one library object now supposedly
  90 houses both ABIs, this means that at least one of the two ABIs is always broken.
  91
  92 A blog post describing the dual ABI mechanism can be found here:
  93
  94     https://developers.redhat.com/blog/2015/02/05/gcc5-and-the-c11-abi/
  95
  96 The bug regarding the issue with catching other-ABI exceptions is here:
  97
  98     https://gcc.gnu.org/bugzilla/show_bug.cgi?id=66145
  99
 100 Since Dinit is affected by this bug, the unfortunate possibility exists to break Dinit by
 101 upgrading GCC. If you have libstdc++ corresponding to GCC 5.x or 6.x, you *must* build with
 102 the old ABI, but Dinit will be broken if you upgrade to GCC 7. If you have libstdc++ from
 103 GCC 7, you *must* build with the new ABI. If the wrong ABI is used, Dinit may still run
 104 successfully but any attempt to load a non-existing service, for example, will cause Dinit
 105 to crash.