1. Meson build system for Dinit
  2. =-=-=-=-=-=-=-=-=-=-=-=-=-=-
  3. Buidling Dinit via Meson
  4. =-=-=-=-=-=-=-=-=-=-=-=-
  5. Building Dinit is possible via two build systems: Meson and Make (makefiles).
  6. This file contains instructions for building Dinit using Meson.
  7. Bulding dinit via Meson requires Meson 0.56.0 or later and a C++11 compiler
  8. (GCC version 4.9 or later, or Clang ~5.0 or later, should be fine).
  9. <!> Special notes about building Dinit via Meson
  10. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  11. Please keep in mind:
  12. 1. The Meson build system for Dinit is an experimental way to build Dinit.
  13. It may not work flawlessly in all cases. Please report bugs at
  15. 2. The primary build system is based on "make" (it requires GNU Make). It is documented in
  16. the file BUILD. It is currently recommended as it is less likely to cause issues. However,
  17. the Meson-based build has been proven to work for straight-forward builds that follow this
  18. guide.
  19. The meson-based build system has the following limitations:
  20. 1. Sanitizers cannot be enabled only for tests, as they are by default in a Make-based build.
  21. 2. Test output from unit tests is inhibited. The logs must be inspected manually after test
  22. execution.
  23. Short version
  24. =-=-=-=-=-=-=
  25. Run "meson setup builddir && meson compile -C builddir". Your system type will
  26. hopefully be detected automatically and appropriate configuration chosen, and Dinit
  27. will be built. Skip to "Installation".
  28. If this fails, if you want to run the tests, or if you are cross-compiling, read the "long
  29. version" instructions.
  30. Long version
  31. =-=-=-=-=-=-
  32. In general Meson will correctly determine the configuration required to build Dinit automatically.
  33. First prepare the "build directory":
  34. meson setup builddir/
  35. This command configures a "build directory" in "builddir/". You can choose another name if
  36. desired, but don't use a directory that is part of the Dinit source tree such as build/ or src/.
  37. The "meson setup" command will prepare to build Dinit including the dinit daemon, dinitctl utility
  38. and the shutdown/reboot/halt utilities by default. Tests will not be built. If you wish to change
  39. the build options, see the next section.
  40. Once "meson setup" has completed successfully, you can compile Dinit with:
  41. meson compile -C builddir
  42. Custom build options
  43. =-=-=-=-=-=-=-=-=-=-
  44. Dinit should generally build with no additional options, however if desired or necessary custom
  45. options can be passed via the "meson setup" command line:
  46. meson setup -Doption=value builddir/
  47. It is also possible to modify the original "meson_options.txt" file and set values there.
  48. Custom options:
  49. shutdown-prefix : Name prefix for "shutdown", "halt" and "reboot"
  50. commands (if they are built).
  51. This affects both the output, and what command dinit
  52. will execute as part of system shutdown. If you want
  53. to install Dinit alongside another init system with
  54. its own shutdown/halt/reboot commands, set
  55. this (for eg. to "dinit-").
  56. Available values : any string
  57. Default value : (empty)
  58. build-shutdown : Whether to build the "shutdown" (and "halt" etc) utilities.
  59. These are only useful if dinit is the system init
  60. (i.e. the PID 1 process). You probably don't want
  61. this unless building for Linux.
  62. Available values : enabled, disabled, auto
  63. Default value : auto
  64. dinit-control-socket-path : Default full path to the control socket, for when
  65. Dinit runs as system service manager.
  66. Available values : any filesystem path
  67. Default value : /run/dinitctl
  68. unit-tests : Build and run unit tests. See "Running the test suite", below.
  69. Available values: true, false
  70. Default value : false
  71. igr-tests : Build and run integration tests. See "Running the test suite", below.
  72. Available values : true, false
  73. Default value : false
  74. fuzzer : Build Dinit's fuzzer tests (using LLVM's Libfuzzer). See "Running
  75. fuzzer", below.
  76. Available values : true, false
  77. Default value : false
  78. use-utmpx : Whether to build support for manipulating the
  79. utmp/utmpx database via the related POSIX functions.
  80. This may be required (along with appropriate service
  81. configuration) for utilities like "who" to work
  82. correctly (the service configuration items "inittab-id"
  83. and "inittab-line" have no effect if this is disabled).
  84. If not set to any value, support is enabled for certain
  85. systems automatically and disabled for all others.
  86. Available values : enabled, disabled, auto
  87. Default value : auto
  88. use-initgroups : Whether to initialize supplementary groups for run-as services. The C
  89. API for this is not in POSIX, but is in practice supported on just
  90. about every relevant system, so it is enabled by default. If it is
  91. not supported on yours, you can explicitly disable it.
  92. Available values : true, false
  93. Default value : true
  94. dinit-sbindir : Default full path to the dinit executables. Note that Dinit doesn't
  95. use Meson's "sbindir" option; see "Why we use another option for
  96. sbindir?", below.
  97. Available values : any filesystem path
  98. Default value : /sbin
  99. man-pages : Build Dinit's man pages.
  100. Available values : true, false
  101. Default value : true
  102. default-auto-restart : Enable/disable auto-restart for services by default.
  103. Available values : true, false
  104. Default value : true
  105. default-start-timeout : Default start-timeout for services.
  106. Specifies the time in seconds allowed for the service to start. If
  107. the service takes longer than this, service startup will be cancelled
  108. (service processes will be signalled to cause termination). The
  109. default if unspecified is 60 seconds. (The value can be overridden
  110. for individual services via the service description).
  111. Available values : any positive integer
  112. Default value : 60
  113. default-stop-timeout : Default stop-timeout for services by default.
  114. Specifies the time in seconds allowed for the service to stop. If the
  115. service takes longer than this, its process group is sent a SIGKILL
  116. signal which should cause it to terminate immediately. The default if
  117. unspecified is 10 seconds. (The value can be overridden for
  118. individual services via the service description).
  119. Available values : any positive integer
  120. Default value : 10
  121. support-cgroups : Enable Cgroups support.
  122. Available values : enabled, disabled, auto
  123. Default value : auto
  124. build-shutdown : Whether to build the shutdown/reboot/halt utilities.
  125. Available values : enabled, disabled, auto
  126. Default value : auto
  127. Running the test suite
  128. =-=-=-=-=-=-=-=-=-=-=-
  129. Enable the "unit-tests" option to run the unit tests:
  130. meson setup -Dunit-tests=true builddir/
  131. In Dinit's make build system -fsanitize is usually enabled for unit tests. The meson build system
  132. doesn't support this, but you can opt to enable sanitizers for the entire build (including Dinit
  133. binaries) if you choose:
  134. meson setup -Db_sanitize='address,undefined' builddir/
  135. Enable "igr-tests" to run the integration tests:
  136. meson setup -Digr-tests=true builddir/
  137. (The integration tests are more fragile than the unit tests, but give a
  138. better indication that Dinit will actually work correctly on your system).
  139. Finally, compile Dinit and run tests:
  140. meson compile -C builddir
  141. meson test -C builddir
  142. The test status will be reported. The test logs will be available in
  143. "builddir/meson-logs/testlog.txt".
  144. Installation
  145. =-=-=-=-=-=-
  146. You can install Dinit via this command:
  147. meson install -C builddir
  148. If you want to install to an alternate root (eg for packaging purposes),
  149. specify that root via DESTDIR:
  150. DESTDIR=/tmp/temporary-install-path meson install -C builddir
  151. The dinit executable will be put in "dinit-sbindir" option value (by default /sbin)
  152. (or rather, in $DESTDIR/sbin), which may not be on the path for normal users.
  153. Consider making a symbolic link to /usr/sbin/dinit.
  154. Running the fuzzer
  155. =-=-=-=-=-=-=-=-=-
  156. In addition to the standard test suite, there is experimental support for
  157. fuzzing the control protocol handling using LLVM/clang's fuzzer (libFuzzer).
  158. Enable the "fuzzer" option to build the fuzzer:
  159. meson setup -Dfuzzer=true builddir
  160. Then change current directory to builddir/src/tests/cptests/, create a "corpus" directory and run
  161. the fuzzer:
  162. mkdir corpus
  163. ./fuzz corpus
  164. This will auto-generate test data as it finds input which triggers new execution paths. Check
  165. libFuzzer documentation for further details.
  166. Why do we use another option for sbindir?
  167. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  168. Old versions of Meson force "sbindir" to be prefixed by the "prefix" property (eg /usr, resulting
  169. in /usr/sbin). For Dinit it is normal to use /sbin as the destination for executables, so the
  170. Meson build system for Dinit uses "dinit-sbindir" instead of the default "sbindir". (The
  171. underlying issue has been fixed in Meson 0.62.0, but for now Dinit continues to use the alternate
  172. setting to retain backwards compatibility with earlier versions of Meson).
  173. Some notes
  174. =-=-=-=-=-
  175. 1. Dinit uses a "custom" buildtype with "'optimization=s', 'debug=false'"
  176. (-Os, no debug) by default.
  177. 2. To build with debug symbols, use "meson setup -Ddebug=true builddir" or
  178. a buildtype with "debug=true"
  179. 3. To enable LTO, use "meson setup -Db_lto=true builddir".