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)
7 On the directly supported operating systems - Linux, OpenBSD, FreeBSD and Darwin (macOS) - a
8 suitable build configuration is provided and should be used automatically. For other systems,
9 or to fine tune or correct the configuration, create and edit the "mconfig" file (start by
10 copying one for a particular OS from the "configs" directory) to choose appropriate values for
11 the configuration variables defined within. In particular:
13 CXX : should be set to the name of the C++ compiler (and link driver)
14 CXXOPTS : are options passed to the compiler during compilation (see note for GCC below)
15 LDFLAGS : are any extra flags required for linking; should not normally be needed
16 (FreeBSD requires -lrt).
18 Note that the "eg++" or "clang++" package must be installed on OpenBSD as the default "g++"
19 compiler is too old. Clang is part of the base system in recent releases.
21 Then, change into the "src" directory, and run "make" (or "gmake" if the system make is not
22 GNU make, such as on most BSD systems):
27 If everything goes smoothly this will build dinit, dinitctl, and optionally the shutdown
28 utility. Use "make install" to install; you can specify an alternate installation by
29 setting the "DESTDIR" variable, eg "make DESTDIR=/tmp/temporary-install-path install".
31 Other configuration variables
32 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=
34 There are a number of other variables you can set in the mconfig file which affect the build:
37 Where the "/sbin" directory is. Executables will be installed here.
39 Where the "man" directory is. Man pages will be installed here.
41 Default full path to the control socket, for when Dinit runs as system service manager.
43 Whether to build the "shutdown" (and "halt" etc) utilities. These are only useful
44 if dinit is the system init (i.e. the PID 1 process). You probably don't want this
45 unless building for Linux.
47 Whether to build support for manipulating the utmp/utmpx database via the related POSIX
48 functions. If not set to any value, support is enabled for certain systems automatically
49 and disabled for all others.
51 Any options to enable run-time sanitizers or additional safety checks. This will be used
52 only when building tests. It can safely be left blank.
57 Build the "check" target in order to run the test suite:
61 The standard mconfig options enable various sanitizers during build of the tests. On Linux you may
62 see an error such as the following:
64 make[3]: Leaving directory '/home/davmac/workspace/dinit/src/tests/cptests'
66 ==25332==ERROR: AddressSanitizer failed to allocate 0xdfff0001000 (15392894357504) bytes at
67 address 2008fff7000 (errno: 12)
68 ==25332==ReserveShadowMemoryRange failed while trying to map 0xdfff0001000 bytes. Perhaps
69 you're using ulimit -v
70 make[2]: *** [Makefile:12: run-tests] Aborted
72 If you get this, either disable the address sanitizer or make sure you have overcommit enabled:
74 echo 1 > /proc/sys/vm/overcommit_memory
76 Any test failures will abort the test suite run immediately.
78 In addition to the standard test suite, there is experimental support for fuzzing the control
79 protocol handling using LLVM/clang's fuzzer (libFuzzer). Change to the `src/tests/cptests`
80 directory and build the "fuzz" target:
84 Then create a "corpus" directory and run the fuzzer:
89 This will auto-generate test data as it finds input which triggers new execution paths. Check
90 libFuzzer documentation for further details.
93 Special note for GCC/Libstdc++
94 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
96 (Note: the issue discussed here has apparently been resolved in recent GCC versions).
98 GCC 5.x onwards includes a "dual ABI" in its standard library implementation, aka Libstdc++.
99 Compiling against the newer (C++11 and later) ABI can be achieved by adding
100 -D_GLIBCXX_USE_CXX11_ABI=1 to the compiler command line; this uses a non-standard language
101 extension to differently mangle symbol names in order to link against the new ABI versions.
103 (Some systems may be configured to build with the new ABI by default, and in that case you
104 build against the old ABI using D_GLIBCXX_USE_CXX11_ABI=1).
106 This is problematic for several reasons. First, it prevents linking against the new ABI with
107 other compilers that do not understand the language extension (LLVM i.e. clang++ does so
108 in recent versions, so this is perhaps no longer much of a problem in practice). Secondly,
109 some aspects of library behavior are ABI-dependent but cannot be changed using the ABI
110 macro; in particular, exceptions thrown as a result of failed I/O operations are, in GCC
111 versions 5.x and 6.x, always "old ABI" exceptions which cannot be caught by code compiled
112 against the new ABI, and in GCC version 7.x they are always "new ABI" exceptions which cannot
113 be caught by code compiled against the old ABI. Since the one library object now supposedly
114 houses both ABIs, this means that at least one of the two ABIs is always broken.
116 A blog post describing the dual ABI mechanism can be found here:
118 https://developers.redhat.com/blog/2015/02/05/gcc5-and-the-c11-abi/
120 The bug regarding the issue with catching other-ABI exceptions is here:
122 https://gcc.gnu.org/bugzilla/show_bug.cgi?id=66145
124 Since Dinit is affected by this bug, the unfortunate possibility exists to break Dinit by
125 upgrading GCC. If you have libstdc++ corresponding to GCC 5.x or 6.x, you *must* build with
126 the old ABI, but Dinit will be broken if you upgrade to GCC 7. If you have libstdc++ from
127 GCC 7, you *must* build with the new ABI. If the wrong ABI is used, Dinit may still run
128 successfully but any attempt to load a non-existing service, for example, will cause Dinit