1. Meson build system for Dinit
  2. =-=-=-=-=-=-=-=-=-=-=-=-=-=-
  3. <!> Special notes about building Dinit via Meson
  4. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  5. Please keep in mind:
  6. 1. Meson build system for Dinit is an experimental way to build Dinit.
  7. it might have some bugs. Please report bugs on
  8. 2. Meson build system for Dinit is "extra" part. The main build system is GNU Make.
  9. This means that the feature is first tested on Make. There may also be delays
  10. in adding new Dinit's features to Meson builds.
  11. 3. If you found some bugs in Meson builds, Please also test it on GNU make builds.
  12. Buidling Dinit via Meson
  13. =-=-=-=-=-=-=-=-=-=-=-=-
  14. Buidling Dinit is available via two "Build system": meson & make.
  15. This file contains instructions for building Dinit using meson.
  16. Bulding dinit via meson requires "meson" (0.47.0 or later) and a C++11 compiler
  17. (GCC version 4.9 and later, or Clang ~5.0 and later, should be fine).
  18. Short version
  19. =-=-=-=-=-=-=
  20. Run "meson setup builddir && meson compile -C builddir". Your system type will
  21. hopefully be detected automatically and appropriate configuration chosen, and Dinit
  22. will be built. Continue reading instructions at "Running the test suite" or skip
  23. straight to "Installation".
  24. If this fails, or if you are cross-compiling, read the "long version" instructions.
  25. Long version
  26. =-=-=-=-=-=-
  27. Meson configures all you need to build Dinit. It detects your OS, detects your
  28. compiler & sets something based on your system information.
  29. By Default no action is required & meson configures everything needed to build Dinit.
  30. Note that the "eg++" or "clang++" package must be installed on OpenBSD
  31. as the default "g++" compiler is too old. Clang is a part of the base system
  32. in recent releases.
  33. In Meson you need to prepare the "build directory". simply just type:
  34. meson setup builddir/
  35. This command configures "build directory" in builddir/. You can set desired
  36. directory (but we suggest don't use dinit's directory such as build/ & src/ or ...
  37. as "build dir"). If everything goes smoothly this will prepare everything to
  38. build dinit, dinitctl and optionaly the shutdown/reboot/halt utilitys by default.
  39. Everything is ready! you can compile Dinit with
  40. meson compile -C builddir
  41. This command builds the dinit, dinitctl and optionaly the shutdown/reboot/halt
  42. utilitys by default. Note: on Mesons older than 0.54, you need to use
  43. "ninja -C builddir" instead of "meson compile -C builddir".
  44. Dinit's custom options
  45. =-=-=-=-=-=-=-=-=-=-=-
  46. Dinit should generally build with no additional options, all required
  47. options/flags will be added automatically. Custom options can be passed
  48. with command line:
  49. meson setup -Doption=value builddir/
  50. or users can modify original "meson_options.txt" and set values.
  51. Custom options:
  52. shutdown-prefix : Name prefix for "shutdown", "halt" and "reboot"
  53. commands (if they are built).
  54. This affects both the output, and what command dinit
  55. will execute as part of system shutdown. If you want
  56. to install Dinit alongside another init system with
  57. its own shutdown/halt/reboot commands, set
  58. this (for eg. to "dinit-").
  59. Available values : everything you want!
  60. Default value : (empty)
  61. build-shutdown : Whether to build the "shutdown" (and "halt" etc) utilities.
  62. These are only useful if dinit is the system init
  63. (i.e. the PID 1 process). You probably don't want
  64. this unless building for Linux.
  65. Available values : enabled, disabled, auto
  66. Default value : auto
  67. dinit-control-socket-path : Default full path to the control socket, for when
  68. Dinit runs as system service manager.
  69. Available values : anywhere you want!
  70. Default value : /run/dinitctl
  71. unit-tests : Building Unit tests. see "Running test suite", below.
  72. Available values: true, false
  73. Default value : false
  74. igr-tests : Building Integration tests. see "Running test suite", below.
  75. Available values : true, false
  76. Default value : false
  77. fuzzer : Building LLVM's Libfuzzer for Dinit. see "Running fuzzer", below.
  78. Available values : true, false
  79. Default value : false
  80. use-utmpx : Whether to build support for manipulating the
  81. utmp/utmpx database via the related POSIX functions.
  82. This may be required (along with appropriate service
  83. configuration) for utilities like "who" to work
  84. correctly (the service configuration items "inittab-id"
  85. and "inittab-line" have no effect if this is disabled).
  86. If not set to any value, support is enabled for certain
  87. systems automatically and disabled for all others.
  88. Available values : enabled, disabled, auto
  89. Default value : auto
  90. dinit-sbindir : Default full path to the dinit executables.
  91. For some reasons Dinit dont follow Meson's default
  92. sbindir option. see "Why we use another option
  93. for sbindir?", below.
  94. Available values : anywhere you want!
  95. Default value : /sbin
  96. man-pages : Building Dinit's man-pages.
  97. Available values : true, false
  98. Default value : true
  99. support-cgroups : Enable Cgroups supprot.
  100. Available values : enabled, disabled, auto
  101. Default value : auto
  102. build-shutdown : Building shutdown/reboot/halt or not.
  103. Available values : enabled, disabled, auto
  104. Default value : auto
  105. Running test suite
  106. =-=-=-=-=-=-=-=-=-
  107. Enable "unit-tests" option to run the test suite:
  108. meson setup -Dunit-tests=true builddir/
  109. In Dinit's make build system -fsanitize enabled for unit tests but in meson
  110. it's not enabled. so if you need that use this option in meson setup step:
  111. meson setup -Db_sanitizes='address,undefined' builddir/
  112. Note: Unlike Dinit's make build system, This flag enables sanitizers for
  113. entire build.
  114. Enable "igr-tests" to run the integration tests:
  115. meson setup -Digr-tests=true builddir/
  116. (The integration tests are more fragile than the unit tests, but give a
  117. better indication that Dinit will actually work correctly on your system).
  118. Finally compile Dinit with "meson compile -C builddir" and run tests via:
  119. meson test -C builddir
  120. Then Meson report test status. All test logs available at
  121. "builddir/meson-logs/testlog.txt".
  122. Installation
  123. =-=-=-=-=-=-
  124. You can install dinit via this command:
  125. meson install -C builddir
  126. If you want to install to an alternate root (eg for packaging purposes),
  127. specify that root via DESTDIR:
  128. DESTDIR=/tmp/temporary-install-path meson install -C builddir
  129. The dinit executable will be put in "dinit-sbindir" option value (by default /sbin)
  130. (or rather, in $DESTDIR/sbin), which may not be on the path for normal users.
  131. Consider making a symbolic link to /usr/sbin/dinit.
  132. Running fuzzer
  133. =-=-=-=-=-=-=-
  134. In addition to the standard test suite, there is experimental support for
  135. fuzzing the control protocol handling using LLVM/clang's fuzzer (libFuzzer).
  136. Enable "fuzzer" option to build fuzzer:
  137. meson setup -Dfuzzer=true builddir
  138. Then changing current directory to Your builddir (eg builddir)/src/tests/cptests/,
  139. create a "corpus" directory and run the fuzzer:
  140. mkdir corpus
  141. ./fuzz corpus
  142. This will auto-generate test data as it finds input which triggers new
  143. execution paths. Check libFuzzer documentation for further details.
  144. Why we use another option for sbindir?
  145. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  146. For some reasons, Old Mesons force sbindir will prefixed by Meson's prefix
  147. (eg /usr + sbin) but Dinit project use /sbin by default as sbindir.
  148. in Newer Mesons that fixes this thing but we target Mesons's 0.47.0 as
  149. minimum version. So we use "dinit-sbindir" instead of default "sbindir".
  150. Some notes
  151. =-=-=-=-=-
  152. 1. Dinit use "custom" buildtype with "'optimization=s', 'debug=false'"
  153. (-Os, no debug) by default.
  154. 2. For building with debug symbols, use "meson setup -Ddebug=true builddir" or
  155. a buildtype with "debug=true"
  156. 3. For enabling LTO, use "meson setup -Db_lto=true builddir" command.
  157. Special note for GCC/Libstdc++
  158. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  159. (Note: the issue discussed here has apparently been resolved in recent GCC versions).
  160. GCC 5.x onwards includes a "dual ABI" in its standard library implementation, aka Libstdc++.
  161. Compiling against the newer (C++11 and later) ABI can be achieved by adding
  162. -D_GLIBCXX_USE_CXX11_ABI=1 to the compiler command line; this uses a non-standard language
  163. extension to differently mangle symbol names in order to link against the new ABI versions.
  164. (Some systems may be configured to build with the new ABI by default, and in that
  165. case you build against the old ABI using -D_GLIBCXX_USE_CXX11_ABI=0).
  166. This is problematic for several reasons. First, it prevents linking against the
  167. new ABI with other compilers that do not understand the language extension
  168. (LLVM i.e. clang++ does so in recent versions, so this is perhaps no longer
  169. much of a problem in practice). Secondly, some aspects of library behaviour are
  170. ABI-dependent but cannot be changed using the ABI macro; in particular, exceptions
  171. thrown as a result of failed I/O operations are, in GCC versions 5.x and 6.x, always
  172. "old ABI" exceptions which cannot be caught by code compiled against the new ABI, and
  173. in GCC version 7.x they are always "new ABI" exceptions which cannot be caught by
  174. code compiled against the old ABI. Since the one library object now supposedly
  175. houses both ABIs, this means that at least one of the two ABIs is always broken.
  176. A blog post describing the dual ABI mechanism can be found here:
  178. The bug regarding the issue with catching other-ABI exceptions is here:
  180. Since Dinit is affected by this bug, the unfortunate possibility exists to break
  181. Dinit by upgrading GCC. If you have libstdc++ corresponding to GCC 5.x or 6.x,
  182. you *must* build with the old ABI, but Dinit will be broken if you upgrade to GCC 7.
  183. If you have libstdc++ from GCC 7, you *must* build with the new ABI. If the wrong
  184. ABI is used, Dinit may still run successfully but any attempt to load a non-existing
  185. service, for example, will cause Dinit to crash.