2
0

BUILD_MESON 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254
  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
  14. https://github.com/davmac314/dinit/issues.
  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/soft-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 : When to automatically restart services.
  103. This controls the default value for the "restart" service setting;
  104. see the dinit-service(5) man page for details.
  105. Available : ALWAYS, ON_FAILURE, NEVER
  106. Default value : ALWAYS
  107. default-start-timeout : Default start-timeout for services.
  108. Specifies the time in seconds allowed for the service to start. If
  109. the service takes longer than this, service startup will be cancelled
  110. (service processes will be signalled to cause termination). The
  111. default if unspecified is 60 seconds. (The value can be overridden
  112. for individual services via the service description).
  113. Available values : any positive integer
  114. Default value : 60
  115. default-stop-timeout : Default stop-timeout for services by default.
  116. Specifies the time in seconds allowed for the service to stop. If the
  117. service takes longer than this, its process group is sent a SIGKILL
  118. signal which should cause it to terminate immediately. The default if
  119. unspecified is 10 seconds. (The value can be overridden for
  120. individual services via the service description).
  121. Available values : any positive integer
  122. Default value : 10
  123. support-cgroups : Enable Cgroups support.
  124. Available values : enabled, disabled, auto
  125. Default value : auto
  126. build-shutdown : Whether to build the shutdown/reboot/halt utilities.
  127. Available values : enabled, disabled, auto
  128. Default value : auto
  129. Running the test suite
  130. =-=-=-=-=-=-=-=-=-=-=-
  131. Enable the "unit-tests" option to run the unit tests:
  132. meson setup -Dunit-tests=true builddir/
  133. In Dinit's make build system -fsanitize is usually enabled for unit tests. The meson build system
  134. doesn't support this, but you can opt to enable sanitizers for the entire build (including Dinit
  135. binaries) if you choose:
  136. meson setup -Db_sanitize='address,undefined' builddir/
  137. Enable "igr-tests" to run the integration tests:
  138. meson setup -Digr-tests=true builddir/
  139. (The integration tests are more fragile than the unit tests, but give a
  140. better indication that Dinit will actually work correctly on your system).
  141. Finally, compile Dinit and run tests:
  142. meson compile -C builddir
  143. meson test -C builddir
  144. The test status will be reported. The test logs will be available in
  145. "builddir/meson-logs/testlog.txt".
  146. Installation
  147. =-=-=-=-=-=-
  148. You can install Dinit via this command:
  149. meson install -C builddir
  150. If you want to install to an alternate root (eg for packaging purposes),
  151. specify that root via DESTDIR:
  152. DESTDIR=/tmp/temporary-install-path meson install -C builddir
  153. The dinit executable will be put in "dinit-sbindir" option value (by default /sbin)
  154. (or rather, in $DESTDIR/sbin), which may not be on the path for normal users.
  155. Consider making a symbolic link to /usr/sbin/dinit.
  156. Running the fuzzer
  157. =-=-=-=-=-=-=-=-=-
  158. In addition to the standard test suite, there is experimental support for
  159. fuzzing the control protocol handling using LLVM/clang's fuzzer (libFuzzer).
  160. Enable the "fuzzer" option to build the fuzzer:
  161. meson setup -Dfuzzer=true builddir
  162. Then change current directory to builddir/src/tests/cptests/, create a "corpus" directory and run
  163. the fuzzer:
  164. mkdir corpus
  165. ./fuzz corpus
  166. This will auto-generate test data as it finds input which triggers new execution paths. Check
  167. libFuzzer documentation for further details.
  168. Why do we use another option for sbindir?
  169. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  170. Old versions of Meson force "sbindir" to be prefixed by the "prefix" property (eg /usr, resulting
  171. in /usr/sbin). For Dinit it is normal to use /sbin as the destination for executables, so the
  172. Meson build system for Dinit uses "dinit-sbindir" instead of the default "sbindir". (The
  173. underlying issue has been fixed in Meson 0.62.0, but for now Dinit continues to use the alternate
  174. setting to retain backwards compatibility with earlier versions of Meson).
  175. Some notes
  176. =-=-=-=-=-
  177. 1. Dinit uses a "custom" buildtype with "'optimization=s', 'debug=false'"
  178. (-Os, no debug) by default.
  179. 2. To build with debug symbols, use "meson setup -Ddebug=true builddir" or
  180. a buildtype with "debug=true"
  181. 3. To enable LTO, use "meson setup -Db_lto=true builddir".