design.rst 8.0KB

il y a 5 ans
il y a 5 ans
il y a 5 ans
il y a 5 ans
il y a 5 ans
il y a 5 ans
il y a 5 ans
il y a 5 ans
il y a 5 ans
il y a 5 ans
il y a 5 ans
il y a 5 ans
il y a 5 ans
il y a 5 ans
il y a 5 ans
il y a 5 ans
il y a 5 ans
il y a 5 ans
il y a 5 ans
il y a 5 ans
il y a 5 ans
il y a 5 ans
il y a 5 ans
il y a 5 ans
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201
  1. ``dds`` Design and Rationale
  2. ############################
  3. ``dds`` has been designed from the very beginning as an extremely opinionated
  4. hybrid *build system* and *package manager*. Unlike most build systems however,
  5. ``dds`` has a strong focus on a particular aspect of software development: C and
  6. C++ libraries.
  7. This may sound pointless, right? Libraries are useless unless we can use them
  8. to build applications!
  9. Indeed, applications *are* essential, and ``dds`` is able to build those as
  10. well.
  11. Another design decision is that ``dds`` is built to be driven by automated
  12. tools as well as humans. ``dds`` is not designed to entirely replace existing
  13. build systems and package management solutions. Rather, it is designed to be
  14. easy to integrate *with* existing systems and tools.
  15. Background
  16. **********
  17. I'm going to say something somewhat controversial: C and C++ don't need
  18. "package management." At least, not *generalized* "package management." C++
  19. needs *library* "package management."
  20. The C and C++ compilation model is inherently *more complex* than almost any
  21. other language in use today. This isn't to say "bad," but rather than it is
  22. built to meet extremely high and strange demands. It also comes with a large
  23. burden of *legacy*. Meeting both of these requirements simultaneously presents
  24. incredible implementation challenges.
  25. Despite the vast amount of work put into build systems and tooling, virtually
  26. all developers are using them *incorrectly* and/or *dangerously* without
  27. realizing it, and we seem to be still a great distance from a unified library
  28. package distribution and consumption mechanism.
  29. Tabula Rasa
  30. ***********
  31. ``dds`` attempts to break from the pattern of legacy demands and strange usage
  32. demands in a few ways. The major differences between ``dds`` and other build
  33. systems like CMake, Meson, build2, SCons, MSBuild, etc. is that of *tradeoffs*.
  34. If you opt-in to have your library built by ``dds``, you forgoe
  35. *customizability* in favor of *simplicity* and *ease*.
  36. ``dds`` takes a look at what is needed to build and develop *libraries* and
  37. optimizes for that use case. It is also built with a very strong, very
  38. opinionated idea of *how* libraries should be constructed and used. These
  39. prescriptions are not at all arbitrary, though. They are built upon the
  40. observations of the strengths and weaknesses of build systems in use throughout
  41. industry and community.
  42. There is some ambiguity on the term "build system." It can mean one of two
  43. things:
  44. 1. A *proper noun* "Build System," such as CMake, Meson, Autotools, or even
  45. Gulp, WebPack, and Mix. These are specific tools that have been developed
  46. for the implementation of the second definition:
  47. 2. A general noun "build system" refers to the particular start-to-finish
  48. process through which a specific piece of software is mapped from its raw
  49. *inputs* (source code, resource libraries, toolchains) to the outputs
  50. (applications, appliances, libraries, or web sites).
  51. For example, LLVM and Blender both use the CMake "Build System," but their
  52. "build system" is not the same. The "build system" for each is wildly
  53. different, despite both using the same underlying "Build System."
  54. ``dds`` takes a massive divergence at this point. One project using ``dds`` as
  55. their build system has a nearly identical build process to every other project
  56. using ``dds``. Simply running ``dds build`` should be enough
  57. to build *any* ``dds`` project.
  58. In order to reach this uniformity and simplicity, ``dds`` drops almost all
  59. aspects of project-by-project customizability. Instead, ``dds`` affords the
  60. developer a contract:
  61. If you play by the rules, you get to play in this space.
  62. .. _design.rules:
  63. The Rules
  64. *********
  65. We've talked an awful lot about the "rules" and "restrictions" that ``dds``
  66. imposes, but what are they?
  67. .. _design.rules.not-apps:
  68. ``dds`` Is not Made for Complex Applications
  69. ============================================
  70. Alright, this one isn't a "rule" as much as a recommendation: If you are
  71. building an application that *needs* some build process functionality that
  72. ``dds`` does not provide, ``dds`` is only open to changes that do not
  73. violate any of the other existing rules.
  74. .. note::
  75. **However:** If you are a *library* author and you find that ``dds``
  76. cannot correctly build your library without violating other rules, we may
  77. have to take a look. This is certainly not to say it will allow arbitrary
  78. customization features to permit the rules to be bent arbitrarily: Read
  79. on.
  80. ``dds`` *does* contain functionality for building applications, but they must
  81. also play by the rules.
  82. If you want to build a complex application with ``dds`` that uses lots of
  83. platform-specific sources, code generation, and conditional components, a good
  84. option is to use an external build script that prepares the project tree before
  85. invoking ``dds``.
  86. .. _design.rules.change:
  87. *Your Code* Should Be Changed Before ``dds`` Should Be Changed
  88. ==============================================================
  89. The wording of this rule means that the onus is on the developer to meet the
  90. expectations that ``dds`` prescribes in order to make the build work.
  91. If your project meets all the requirements outlined in this document but you
  92. still find trouble in making your build work, or if you *cannot* see *any*
  93. possible way for your project to be built by ``dds`` regardless of what changes
  94. you make, then it this is grounds for change in ``dds``, either in clarifying
  95. the rules or tweaking ``dds`` functionality
  96. .. _design.rules.layout:
  97. Library Projects Must Meet the Layout Requirements
  98. ==================================================
  99. This is a very concrete requirement. ``dds`` prescribes a particular project
  100. structure layout with minimal differing options. ``dds`` prescribes the
  101. `Pitchfork`_ layout requirements.
  102. .. note::
  103. These prescriptions are not as draconian as they may sound upon first
  104. reading. Refer to the :doc:`guide/packages` page for more information.
  105. .. _Pitchfork: https://api.csswg.org/bikeshed/?force=1&url=https://raw.githubusercontent.com/vector-of-bool/pitchfork/develop/data/spec.bs
  106. .. _design.rules.no-cond-compile:
  107. A Library Build Must Successfully Compile All Source Files
  108. ==========================================================
  109. Almost all Build Systems have a concept of *conditionally* adding a source file
  110. to a build. ``dds`` elides this feature in place of relying on in-source
  111. conditional compilation.
  112. .. _design.rules.no-lazy-code-gen:
  113. All Code Must Be in Place Before Building
  114. =========================================
  115. ``dds`` does not provide code-generation functionality. Instead, any generated
  116. code should be generated by separate build steps before ``dds`` is executed.
  117. .. _design.rules.one-binary-per-src:
  118. All Compilable Files in a ``src/`` Directory Must Link Together
  119. ===============================================================
  120. As part of the prescribed project layout, the ``src/`` project directory
  121. contains source files. ``dds`` requires that *all* source files in a given
  122. ``src/`` directory should link together cleanly. Practically, this means that
  123. every ``src/`` directory must correspond to *exactly* one library.
  124. .. _design.rules.include:
  125. No Arbitrary ``#include`` Directories
  126. =====================================
  127. Only ``src/`` and ``include/`` will ever be used as the basis for header
  128. resolution while building a project, so all ``#include`` directives should be
  129. relative to those directories. Refer to :ref:`pkg.source-root`.
  130. .. _design.rules.uniform-compile:
  131. All Files Compile with the Same Options
  132. =======================================
  133. When DDS compiles a project, every source file will be compiled with an
  134. identical set of options. Additionally, when DDS compiles a dependency tree,
  135. every library in that dependency tree will be compiled with an identical set of
  136. options. Refer to the :doc:`guide/toolchains` page for more information.
  137. Currently, the only exception to this rules is for flags that control compiler
  138. warnings: Dependencies will be compiled without adding any warnings flags,
  139. while the main project will be compiled with warnings enabled by default.