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