5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
5 роки тому
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546
  1. .. highlight:: js
  2. Toolchains
  3. ##########
  4. One of the core components of ``dds`` is that of the *toolchain*. A toolchain
  5. encompasses the environment used to build and link source code, including, but
  6. not limited to:
  7. #. The executable binaries that constitute the language implementation:
  8. Compilers, linkers, and archive managers.
  9. #. The configuration of those tools, including most options given to those
  10. tools when they are invoked.
  11. #. The set of preprocessor macros and language features that are active during
  12. compilation.
  13. When a build is run, every file in the entire tree (including dependencies)
  14. will be compiled, archived, and linked using the same toolchain.
  15. This page provides an introduction on how one can make use of toolchains most
  16. effectively in your project.
  17. .. note::
  18. **IMPORTANT**: ``dds`` will *not* automatically load the Visual C++
  19. environment. To use Visual C++, ``dds`` must be executed from the
  20. appropriate environment in order for the Visual C++ toolchain executables
  21. and files to be available.
  22. Passing a Toolchain
  23. *******************
  24. In ``dds``, the default format of a toolchain is that of a single JSON5 file
  25. that describes the entire toolchain. When running a build for a project, the
  26. ``dds`` executable will look in a few locations for a default toolchain, and
  27. generate an error if no default toolchain file is found (Refer to
  28. :ref:`toolchains.default`). A different toolchain can be provided by passing
  29. the toolchain file for the ``--toolchain`` (or ``-t``) option on the command
  30. line::
  31. $ dds build -t my-toolchain.json5
  32. Alternatively, you can pass the name of a built-in toolchain. See below.
  33. .. _toolchains.builtin:
  34. Built-in Toolchains
  35. *******************
  36. For convenience, ``dds`` includes several built-in toolchains that can be
  37. accessed in the ``--toolchain`` command-line option using a colon ``:``
  38. prefix::
  39. $ dds build -t :gcc
  40. ``dds`` will treat the leading colon (``:``) as a name for a built-in
  41. toolchain (this means that a toolchain's filepath may not begin with a colon).
  42. There are several built-in toolchains that may be specified:
  43. ``:gcc``
  44. Uses the default ``gcc`` and ``g++`` executables, linkers, and options
  45. thereof.
  46. ``:gcc-N`` (for some integer ``N``)
  47. Equivalent to ``:gcc``, but uses the ``gcc-N`` and ``g++-N`` executables.
  48. ``:clang``
  49. Equivalent to ``:gcc``, but uses the ``clang`` and ``clang++`` executables.
  50. ``:clang-N`` (for some integer ``N``)
  51. Equivalent to ``:clang``, but uses the ``clang-N`` and ``clang++-N``
  52. executables.
  53. ``:msvc``
  54. Compiles and links using the Visual C++ toolchain.
  55. The following pseudo-toolchains are also available:
  56. ``:debug:XYZ``
  57. Uses built-in toolchain ``:XYZ``, but generates debugging information.
  58. ``:ccache:XYZ``
  59. Uses built-in toolchain ``:XYZ``, but prefixes all compile commands with
  60. ``ccache``.
  61. ``:c++UV:XYZ`` (for two integers ``UV``)
  62. Sets the C++ version to ``C++UV`` and uses the ``:XYZ`` toolchain.
  63. .. _toolchains.default:
  64. Providing a Default Toolchain File
  65. **********************************
  66. If you do not wish to provide a new toolchain for every individual project,
  67. and the built-in toolchains do not suit your needs, you can write a toolchain
  68. file to one of a few predefined paths, and ``dds`` will find and use it for the
  69. build. The following directories are searched, in order:
  70. #. ``$pwd/`` - If the working directory contains a toolchain file, it will be
  71. used as the default.
  72. #. ``$dds_config_dir/`` - Searches for a toolchain file in ``dds``'s user-local
  73. configuration directory (see below).
  74. #. ``$user_home/`` - Searches for a toolchain file at the root of the current
  75. user's home directory. (``$HOME`` on Unix-like systems, and ``$PROFILE`` on
  76. Windows.)
  77. In each directory, it will search for ``toolchain.json5``, ``toolchain.jsonc``,
  78. or ``toolchain.json``.
  79. The ``$dds_user_config`` directory is the ``dds`` subdirectory of the
  80. user-local configuration directory.
  81. The user-local config directory is ``$XDG_CONFIG_DIR`` or ``~/.config`` on
  82. Linux, ``~/Library/Preferences`` on macOS, and ``~/AppData/Roaming`` on
  83. Windows.
  84. Toolchain Definitions
  85. *********************
  86. Besides using the built-in toolchains, it is likely that you'll soon want to
  87. customize a toolchain further. Further customization must be done with a
  88. file that contains the toolchain definition. The most basic toolchain file is
  89. simply one line:
  90. .. code-block::
  91. {
  92. compiler_id: "<compiler-id>"
  93. }
  94. where ``<compiler-id>`` is one of the known ``compiler_id`` options (See the
  95. toolchain option reference). ``dds`` will infer common suitable defaults for
  96. the remaining options based on the value of ``compiler_id``.
  97. For example, if you specify ``gnu``, then ``dds`` will assume ``gcc`` to be the
  98. C compiler, ``g++`` to be the C++ compiler, and ``ar`` to be the library
  99. archiving tool.
  100. If you know that your compiler executable has a different name, you can
  101. specify them with additional options:
  102. .. code-block::
  103. {
  104. compiler_id: 'gnu',
  105. c_compiler: 'gcc-9',
  106. cxx_compiler: 'g++-9',
  107. }
  108. ``dds`` will continue to infer other options based on the ``compiler_id``, but
  109. will use the provided executable names when compiling files for the respective
  110. languages.
  111. To specify compilation flags, the ``flags`` option can be used:
  112. .. code-block::
  113. {
  114. // [...]
  115. flags: '-fsanitize=address -fno-inline',
  116. }
  117. .. note::
  118. Use ``warning_flags`` to specify options regarding compiler warnings.
  119. Flags for linking executables can be specified with ``link_flags``:
  120. .. code-block::
  121. {
  122. // [...]
  123. link_flags: '-fsanitize=address -fPIE'
  124. }
  125. .. _toolchains.opt-ref:
  126. Toolchain Option Reference
  127. **************************
  128. Understanding Flags and Shell Parsing
  129. -------------------------------------
  130. Many of the ``dds`` toolchain parameters accept argument lists or shell-string
  131. lists. If such an option is given a single string, then that string is split
  132. using the syntax of a POSIX shell command parser. It accepts both single ``'``
  133. and double ``"`` quote characters as argument delimiters.
  134. If an option is given a list of strings instead, then each string in that
  135. array is treated as a full command line argument and is passed as such.
  136. For example, this sample with ``flags``::
  137. {
  138. flags: "-fsanitize=address -fPIC"
  139. }
  140. is equivalent to this one::
  141. {
  142. flags: ["-fsanitize=address", "-fPIC"]
  143. }
  144. Despite splitting strings as-if they were shell commands, ``dds`` does nothing
  145. else shell-like. It does not expand environment variables, nor does it expand
  146. globs and wildcards.
  147. ``compiler_id``
  148. ---------------
  149. Specify the identity of the compiler. This option is used to infer many other
  150. facts about the toolchain. If specifying the full toolchain with the command
  151. templates, this option is not required.
  152. Valid values are:
  153. ``gnu``
  154. For GCC
  155. ``clang``
  156. For LLVM/Clang
  157. ``msvc``
  158. For Microsoft Visual C++
  159. ``c_compiler`` and ``cxx_compiler``
  160. -----------------------------------
  161. Names/paths of the C and C++ compilers, respectively. Defaults will be inferred
  162. from ``compiler_id``.
  163. ``c_version`` and ``cxx_version``
  164. ---------------------------------
  165. Specify the language versions for C and C++, respectively. By default, ``dds``
  166. will not set any language version. Using this option requires that the
  167. ``compiler_id`` be specified. Setting this value will cause the corresponding
  168. language-version flag to be passed to the compiler.
  169. Valid ``c_version`` values are:
  170. - ``c89``
  171. - ``c99``
  172. - ``c11``
  173. - ``c18``
  174. Valid ``cxx_version`` values are:
  175. - ``c++98``
  176. - ``c++03``
  177. - ``c++11``
  178. - ``c++14``
  179. - ``c++17``
  180. - ``c++20``
  181. .. warning::
  182. ``dds`` will not do any "smarts" to infer the exact option to pass to have
  183. the required effect. If you ask for ``c++20`` from ``gcc 4.8``, ``dds``
  184. will simply pass ``-std=c++20`` with no questions asked. If you need
  185. finer-grained control, use the ``c_flags`` and ``cxx_flags`` options.
  186. ``warning_flags``
  187. -----------------
  188. Provide *additional* compiler flags that should be used to enable warnings. This
  189. option is stored separately from ``flags``, as these options may be
  190. enabled/disabled separately depending on how ``dds`` is invoked.
  191. .. note::
  192. If ``compiler_id`` is provided, a default set of warning flags will be
  193. provided when warnings are enabled.
  194. Adding flags to this toolchain option will *append* flags to the basis
  195. warning flag list rather than overwrite them.
  196. .. seealso::
  197. Refer to :ref:`toolchains.opts.base_warning_flags` for more information.
  198. ``flags``, ``c_flags``, and ``cxx_flags``
  199. -----------------------------------------
  200. Specify *additional* compiler options, possibly per-language.
  201. ``link_flags``
  202. --------------
  203. Specify *additional* link options to use when linking executables.
  204. .. note::
  205. ``dds`` does not invoke the linker directly, but instead invokes the
  206. compiler with the appropriate flags to perform linking. If you need to pass
  207. flags directly to the linker, you will need to use the compiler's options to
  208. direct flags through to the linker. On GNU-style, this is
  209. ``-Wl,<linker-option>``. With MSVC, a separate flag ``/LINK`` must be
  210. specified, and all following options are passed to the underlying
  211. ``link.exe``.
  212. ``optimize``
  213. ------------
  214. Boolean option (``true`` or ``false``) to enable/disable optimizations. Default
  215. is ``false``.
  216. ``debug``
  217. ---------
  218. Bool or string. Default is ``false``. If ``true`` or ``"embedded"``, generates
  219. debug information embedded in the compiled binaries. If ``"split"``, generates
  220. debug information in a separate file from the binaries.
  221. .. note::
  222. ``"split"`` with GCC requires that the compiler support the
  223. ``-gsplit-dwarf`` option.
  224. ``runtime``
  225. -----------
  226. Select the language runtime/standard library options. Must be an object, and supports two keys:
  227. ``static``
  228. A boolean. If ``true``, the runtime and standard libraries will be
  229. static-linked into the generated binaries. If ``false``, they will be
  230. dynamically linked. Default is ``true`` with MSVC, and ``false`` with GCC
  231. and Clang.
  232. ``debug``
  233. A boolean. If ``true``, the debug versions of the runtime and standard
  234. library will be compiled and linked into the generated binaries. If
  235. ``false``, the default libraries will be used.
  236. **On MSVC** the default value depends on the top-level ``/debug`` option: If
  237. ``/debug`` is not ``false``, then ``/runtime/debug`` defaults to ``true``.
  238. **On GCC and Clang** the default value is ``false``.
  239. .. note::
  240. On GNU-like compilers, ``static`` does not generate a static executable, it
  241. only statically links the runtime and standard library. To generate a static
  242. executable, the ``-static`` option should be added to ``link_flags``.
  243. .. note::
  244. On GNU and Clang, setting ``/runtime/debug`` to ``true`` will compile all
  245. files with the ``_GLIBCXX_DEBUG`` and ``_LIBCPP_DEBUG=1`` preprocessor
  246. definitions set. **Translation units compiled with these macros are
  247. definitively ABI-incompatible with TUs that have been compiled without these
  248. options!!**
  249. If you link to a static or dynamic library that has not been compiled with
  250. the same runtime settings, generated programs will likely crash.
  251. ``compiler_launcher``
  252. ---------------------
  253. Provide a command prefix that should be used on all compiler executions.
  254. e.g. ``ccache``.
  255. ``advanced``
  256. ------------
  257. A nested object that contains advanced toolchain options. Refer to section on
  258. advanced toolchain options.
  259. Advanced Options Reference
  260. **************************
  261. The options below are probably not good to tweak unless you *really* know what
  262. you are doing. Their values will be inferred from ``compiler_id``.
  263. Command Templates
  264. -----------------
  265. Many of the below options take the form of command-line templates. These are
  266. templates from which ``dds`` will create a command-line for a subprocess,
  267. possibly by combining them together.
  268. Each command template allows some set of placeholders. Each instance of the
  269. placeholder string will be replaced in the final command line. Refer to each
  270. respective option for more information.
  271. ``deps_mode``
  272. -------------
  273. Specify the way in which ``dds`` should track compilation dependencies. One
  274. of ``gnu``, ``msvc``, or ``none``.
  275. .. note::
  276. If ``none``, then dependency tracking will be disabled entirely. This will
  277. prevent ``dds`` from tracking interdependencies of source files, and
  278. inhibits incremental compilation.
  279. ``c_compile_file`` and ``cxx_compile_file``
  280. -------------------------------------------
  281. Override the *command template* that is used to compile source files.
  282. This template expects three placeholders:
  283. - ``[in]`` is the path to the file that will be compiled.
  284. - ``[out]`` is the path to the object file that will be generated.
  285. - ``[flags]`` is the placeholder of the compilation flags. This placeholder
  286. must not be attached to any other arguments. The compilation flag argument
  287. list will be inserted in place of ``[flags]``.
  288. Defaults::
  289. {
  290. // On GNU-like compilers (GCC, Clang):
  291. c_compile_file: "<compiler> -fPIC -pthread [flags] -c [in] -o[out]",
  292. cxx_compile_file: "<compiler> -fPIC -pthread [flags] -c [in] -o[out]",
  293. // On MSVC:
  294. c_compile_file: "cl.exe /nologo /permissive- [flags] /c [in] /Fo[out]",
  295. cxx_compile_file: "cl.exe /EHsc /nologo /permissive- [flags] /c [in] /Fo[out]",
  296. }
  297. ``create_archive``
  298. ------------------
  299. Override the *command template* that is used to generate static library archive
  300. files.
  301. This template expects two placeholders:
  302. - ``[in]`` is the a placeholder for the list of inputs. It must not be attached
  303. to any other arguments. The list of input paths will be inserted in place of
  304. ``[in]``.
  305. - ``[out]`` is the placeholder for the output path for the static library
  306. archive.
  307. Defaults::
  308. {
  309. // On GNU-like:
  310. create_archive: "ar rcs [out] [in]",
  311. // On MSVC:
  312. create_archive: "lib /nologo /OUT:[out] [in]",
  313. }
  314. ``link_executable``
  315. -------------------
  316. Override the *command template* that is used to link executables.
  317. This template expects the same placeholders as ``create_archive``, but
  318. ``[out]`` is a placeholder for the executable file rather than a static
  319. library.
  320. Defaults::
  321. {
  322. // For GNU-like:
  323. link_executable: "<compiler> -fPIC [in] -pthread -o[out] [flags]",
  324. // For MSVC:
  325. link_executable: "cl.exe /nologo /EHsc [in] /Fe[out]",
  326. }
  327. ``include_template`` and ``external_include_template``
  328. ------------------------------------------------------
  329. Override the *command template* for the flags to specify a header search path.
  330. ``external_include_template`` will be used to specify the include search path
  331. for a directory that is "external" (i.e. does not live within the main project).
  332. For each directory added to the ``#include`` search path, this argument
  333. template is instantiated in the ``[flags]`` for the compilation.
  334. This template expects only a single placeholder: ``[path]``, which will be
  335. replaced with the path to the directory to be added to the search path.
  336. On MSVC, this defaults to ``/I [path]``. On GNU-like, ``-isystem [path]`` is
  337. used for ``external_include_template`` and ``-I [path]`` for
  338. ``include_template``.
  339. ``define_template``
  340. -------------------
  341. Override the *command template* for the flags to set a preprocessor definition.
  342. This template expects only a single placeholder: ``[def]``, which is the
  343. preprocessor macro definition argument.
  344. On MSVC, this defaults to ``/D [def]``. On GNU-like compilers, this is
  345. ``-D [def]``.
  346. ``tty_flags``
  347. -------------
  348. Supply additional flags when compiling/linking that will only be applied if
  349. standard output is an ANSI-capable terminal.
  350. On GNU and Clang this will be ``-fdiagnostics-color`` by default.
  351. ``obj_prefix``, ``obj_suffix``, ``archive_prefix``, ``archive_suffix``, ``exe_prefix``, and ``exe_suffix``
  352. ----------------------------------------------------------------------------------------------------------
  353. Set the filename prefixes and suffixes for object files, library archive files,
  354. and executable files, respectively.
  355. .. _toolchains.opts.base_warning_flags:
  356. ``base_warning_flags``
  357. ----------------------
  358. When you compile your project and request warning flags, ``dds`` will
  359. concatenate the warning flags from this option with the flags provided by
  360. ``warning_flags``. This option is "advanced," because it provides a set of
  361. defaults based on the ``compiler_id``.
  362. On GNU-like compilers, the base warning flags are ``-Wall -Wextra -Wpedantic
  363. -Wconversion``. On MSVC the default flag is ``/W4``.
  364. For example, if you set ``warning_flags`` to ``"-Werror"`` on a GNU-like
  365. compiler, the resulting command line will contain ``-Wall -Wextra -Wpedantic
  366. -Wconversion -Werror``.