Nie możesz wybrać więcej, niż 25 tematów Tematy muszą się zaczynać od litery lub cyfry, mogą zawierać myślniki ('-') i mogą mieć do 35 znaków.

363 lines
13KB

  1. Packages and Layout
  2. ###################
  3. The units of distribution in ``dds`` are *packages*. A single package consists
  4. of one or more *libraries*. In the simplest case, a package will contain a
  5. single library.
  6. It may be easiest to work from the bottom-up when trying to understand how
  7. ``dds`` understands code.
  8. The layout expected by ``dds`` is based on the `Pitchfork layout`_ (PFL).
  9. ``dds`` does not make use of every provision of the layout document, but the
  10. features it does have are based on PFL.
  11. .. _Pitchfork layout: https://api.csswg.org/bikeshed/?force=1&url=https://raw.githubusercontent.com/vector-of-bool/pitchfork/develop/data/spec.bs
  12. In particular, the following directories are used:
  13. - ``src/``
  14. - ``include/``
  15. - ``libs/``
  16. - ``_build/`` (the default build output directory used by ``dds``).
  17. Note that the ``libs/*/`` directories can contain their own ``src/`` and
  18. ``include/`` directories, the purposes and behaviors of which match those of
  19. their top-level counterparts.
  20. Source Files
  21. ************
  22. The smallest subdivision of code that ``dds`` recognizes is the *source file*,
  23. which is exactly as it sounds: A single file containing some amount of code.
  24. Source files can be grouped on a few axes, the most fundamental of which is
  25. "Is this compiled?"
  26. ``dds`` uses source file extensions to determine whether a source file should
  27. be fed to the compiler. All of the common C and C++ file extensions are
  28. supported:
  29. .. list-table::
  30. - * Compiled as C
  31. * ``.c`` and ``.C``
  32. - * Compiled as C++
  33. * ``.cpp``, ``.c++``, ``.cc``, and ``.cxx``
  34. - * Not compiled
  35. * ``.H``, ``.H++``, ``.h``, ``.h++``, ``.hh``, ``.hpp``, ``.hxx``,
  36. ``.ipp``, ``.inc``, and ``.inl``
  37. If a file's extension is not listed in the table above, ``dds`` will ignore it.
  38. .. note::
  39. Although headers are not compiled, this does not mean they are ignored.
  40. ``dds`` still understands and respects headers, and they are collected
  41. together as part of a *source distribution*.
  42. .. _pkgs.apps-tests:
  43. Applications and Tests
  44. **********************
  45. ``dds`` will recognize certain compilable source files as belonging to
  46. applications and tests, depending on the filenames "stem," which is the part of
  47. the filename not including the outer-most file extension. If a compilable source
  48. filename stem ends with ``.main`` or ``.test``, that source file is assumed to
  49. correspond to an executable to generate. The filename second-inner stem before
  50. the ``.main`` or ``.test`` will be used as the name of the generated executable.
  51. For example:
  52. - Given ``foo.main.cpp``
  53. - The stem is ``foo.main``, whose extension is ``.main``, so we will generate
  54. an application.
  55. - The stem of ``foo.main`` is ``foo``, so the executable will be named
  56. ``foo``.
  57. - Given ``bar.test.cpp``
  58. - The stem is ``bar.test``, whose extension is ``.test``, so we will generate
  59. a test.
  60. - The stem of ``bar.test`` is ``bar``, so will generate an executable named
  61. ``bar``.
  62. - Given ``cat-meow.main.cpp``
  63. - The stem is ``cat-meow.main``, which has extension ``.main``, so it is an
  64. application.
  65. - The stem of ``cat-meow.main`` is ``cat-meow``, so will generate an
  66. executable named ``cat-meow``.
  67. - Given ``cats.musical.test.cpp``
  68. - The stem is ``cats.musical.test``, which has extension ``.test``, so this is
  69. a text executable.
  70. - The stem of ``cats.musical.test`` is ``cats.musical``, so we will generate
  71. an executable named ``cats.musical``.
  72. - Note that the dot in ``cats.musical`` is not significant, as ``dds`` does
  73. strip any further extensions.
  74. .. note::
  75. ``dds`` will automatically append the appropriate filename extension to the
  76. generated executables based on the host and toolchain.
  77. An *application* source file is a source file whose file stem ends with
  78. ``.main``. ``dds`` will assume this source file to contain a program entry
  79. point function and not include it as part of the main library build. Instead,
  80. when ``dds`` is generating applications, the source file will be compiled, and
  81. the resulting object will be linked together with the enclosing library into an
  82. executable.
  83. A *test* source file is a source file whose file stem ends with ``.test``. Like
  84. application sources, a *test* source file is omitted from the main library, and
  85. it will be used to generate tests. The exact behavior of tests is determined by
  86. the ``test_driver`` setting for the package, but the default is that each test
  87. source file will generate a single test executable that is executed by ``dds``
  88. when running unit tests.
  89. The building of tests and applications can be controlled when running
  90. ``dds build``. If tests are built, ``dds`` will automatically execute those
  91. tests in parallel once the executables have been generated.
  92. In any case, the executables are associated with a *library*, and, when those
  93. executables are linked, the associated library (and its dependencies) will be
  94. linked into the final executable. There is no need to manually specify this
  95. linking behavior.
  96. .. _pkg.source-root:
  97. Source Roots
  98. ************
  99. Source files are collected as children of some *source root*. A *source
  100. root* is a single directory that contains some *portable* bundle of source
  101. files. The word "portable" is important: It is what distinguishes the
  102. source root from its child directories.
  103. Portability
  104. ===========
  105. By saying that a source root is "portable", It indicates that the directory
  106. itself can be moved, renamed, or copied without breaking the ``#include``
  107. directives of its children or of the directory's referrers.
  108. As a practical example, let's examine such a directory, which we'll call
  109. ``src/`` for the purposes of this example. Suppose we have a directory named
  110. ``src`` with the following structure:
  111. .. code-block:: text
  112. <path>/src/
  113. animals/
  114. mammal/
  115. mammal.hpp
  116. cat/
  117. cat.hpp
  118. sound.hpp
  119. sound.cpp
  120. dog/
  121. dog.hpp
  122. sound.hpp
  123. sound.cpp
  124. In this example, ``src/`` is a *source root*, but ``src/animals/``,
  125. ``src/animals/cat/``, and ``src/animals/dog/`` are **not** source roots.
  126. While they may be directories that contain source files, they are not "roots."
  127. Suppose now that ``dog.hpp`` contains an ``#include`` directive:
  128. .. code-block:: c++
  129. #include <animals/mammal/mammal.hpp>
  130. or even a third-party user that wants to use our library:
  131. .. code-block:: c++
  132. #include <animals/dog/dog.hpp>
  133. #include <animals/dog/sound.hpp>
  134. In order for any code to compile and resolve these ``#include`` directives, the
  135. ``src/`` directory must be added to their *include search path*.
  136. Because the ``#include`` directives are based on the *portable* source root,
  137. the exact location of ``src/`` is not important to the content of the
  138. consuming source code, and can thus be relocated and renamed as necessary.
  139. Consumers only need to update the path of the *include search path* in a single
  140. location rather than modifying their source code.
  141. .. _pkgs.source-root:
  142. Source Roots in ``dds``
  143. =======================
  144. To avoid ambiguity and aide in portability, the following rules should be
  145. strictly adhered to:
  146. #. Source roots may not contain other source roots.
  147. #. Only source roots will be added to the *include-search-path*.
  148. #. All ``#include``-directives are relative to a source root.
  149. By construction, ``dds`` cannot build a project that has nested source roots,
  150. and it will only ever add source roots to the *include-search-path*.
  151. ``dds`` supports either one or two source roots in a library.
  152. .. _pkgs.lib-roots:
  153. Library Roots
  154. *************
  155. In ``dds``, a *library root* is a directory that contains a ``src/`` directory,
  156. an ``include/`` directory, or both. ``dds`` will treat both directories as
  157. source roots, but behaves differently between the two. The ``src/`` and
  158. ``include/`` directories are themselves *source roots*.
  159. ``dds`` distinguishes between a *public* include-directory, and a *private*
  160. include-directory. When ``dds`` is compiling a library, both its *private* and
  161. its *public* include-paths will be added to the compiler's
  162. *include-search-path*. When a downstream user of a library is compiling against
  163. a library managed by ``dds``, only the *public* include-directory will be
  164. added to the compiler's *include-search-path*. This has the effect that only
  165. the files that are children of the source root that is the *public*
  166. include-directory will be available when compiling consumers.
  167. .. warning::
  168. Because only the *public* include-directory is available when compiling
  169. consumers, it is essential that no headers within the *public*
  170. include-directory attempt to use headers from the *private*
  171. include-directory, as they **will not** be visible.
  172. If both ``src/`` and ``include/`` are present in a library root, then ``dds``
  173. will use ``include/`` as the *public* include-directory and ``src/`` as the
  174. *private* include-directory. If only one of the two is present, then that
  175. directory will be treated as the *public* include-directory, and there will be
  176. no *private* include-directory.
  177. When ``dds`` exports a library, the header files from the *public*
  178. include-directory source root will be collected together and distributed as
  179. that library's header tree. The path to the individual header files relative to
  180. their source root will be retained as part of the library distribution.
  181. ``dds`` will compile every compilable source file that appears in the ``src/``
  182. directory. ``dds`` will not compile compilable source files that appear in the
  183. ``include/`` directory and will issue a warning on each file found.
  184. .. _pkgs.libs:
  185. Libraries
  186. *********
  187. The *library* is a fundamental unit of consumable code, and ``dds`` is
  188. specifically built to work with them. When you are in ``dds``, the library is
  189. the center of everything.
  190. A single *library root* will always correspond to exactly one library. If the
  191. library has any compilable sources then ``dds`` will use those sources to
  192. generate a static library file that is linked into runtime binaries. If a
  193. library contains only headers then ``dds`` will not generate an archive to be
  194. included in downstream binaries, but it will still generate link rules for the
  195. dependencies of a header-only library.
  196. In order for ``dds`` to be able to distribute and interlink libraries, a
  197. ``library.json5`` file must be present at the corresponding library root. The
  198. only required key in a ``library.json5`` file is ``name``:
  199. .. code-block:: js
  200. {
  201. name: 'my-library'
  202. }
  203. .. seealso:: More information is discussed on the :ref:`deps.lib-deps` page
  204. .. _pkgs.pkg-root:
  205. Package Roots
  206. *************
  207. A *package root* is a directory that contains some number of library roots. If
  208. the package root contains a ``src/`` and/or ``include/`` directory then the
  209. package root is itself a library root, and a library is defined at the root of
  210. the package. This is intended to be the most common and simplest method of
  211. creating libraries with ``dds``.
  212. If the package root contains a ``libs/`` directory, then each subdirectory of
  213. the ``libs/`` directory is checked to be a library root. Each direct child of
  214. the ``libs/`` directory that is also a library root is added as a child of the
  215. owning package.
  216. .. _pkgs.pkgs:
  217. Packages
  218. ********
  219. A package is defined by some *package root*, and contains some number of
  220. *libraries*.
  221. The primary distribution format of packages that is used by ``dds`` is the
  222. *source distribution*. Refer to the page :doc:`source-dists`.
  223. Packages are identified by a name/version pair, joined together by an ``@``
  224. symbol. The version of a package must be a semantic version string. Together,
  225. the ``name@version`` string forms the *package ID*, and it must be unique within
  226. a repository or local package cache.
  227. In order for a package to be exported by ``dds`` it must have a
  228. ``package.json5`` file at its package root. Three keys are required to be
  229. present in the ``package.json5`` file: ``name``, ``version``, and ``namespace``:
  230. .. code-block:: js
  231. {
  232. name: 'acme-widgets',
  233. version: '6.7.3',
  234. namespace: 'acme',
  235. }
  236. ``version`` must be a valid semantic version string.
  237. .. note::
  238. The ``namespace`` key is arbitrary, and not necessarily associated with
  239. any C++ ``namespace``.
  240. .. seealso::
  241. The purpose of ``namespace``, as well as additional options in this file,
  242. are described in the :ref:`deps.pkg-deps` page
  243. .. _pkgs.naming-reqs:
  244. Naming Requirements
  245. ===================
  246. Package names aren't a complete free-for-all. Package names must follow a set
  247. of specific rules:
  248. - Package names may consist of a subset of ASCII including lowercase
  249. characters, digits, underscores (``_``), hyphens (``-``), and periods
  250. (``.``).
  251. .. note::
  252. Different filesystems differ in their handling of filenames. Some platforms
  253. perform unicode and case normalization, which can significantly confuse tools
  254. that don't use the same normalization rules. Different platforms have
  255. different filename limitations and allowable characters. This set of
  256. characters is valid on most currently popular filesystems.
  257. - Package names must begin with an alphabetic character
  258. - Package names must end with an alphanumeric character (letter or digit).
  259. - Package names may not contain adjacent punctuation characters.