Debian Codegraph @

cmake/tribits/doc/guides/users_guide/TribitsUsersGuide.rst

raw
1 =================================
2 TriBITS Users Guide and Reference
3 =================================
4
5 :Author: Roscoe A. Bartlett ([email protected])
6 :Date: |date|
7 :Version: .. include:: ../TribitsGitVersion.txt
8
9 .. |date| date::
10
11 :Abstract: This document describes the usage of TriBITS to build, test, and deploy complex software. The primary audience are those individuals who develop on a software project which uses TriBITS as the framework for the project's CMake build system. The overall structure of a TriBITS project is described including all of the various project- and package-specific files that TriBITS requires or can use and what order these files are processed. It also contains detailed reference information on all of the various TriBITS macros and functions directly used in a TriBITS project's CMakeLists.txt files. Many other topics of interest to a TriBITS project developer and architect are discussed as well.
12
13 .. sectnum::
14 :depth: 2
15
16 .. Above, the depth of the TOC is set to just 2 because I don't want the
17 .. TriBITS function/macro names to have section numbers appearing before them.
18 .. Also, some of them are long and I don't want them to go off the page of the
19 .. PDF document.
20
21 .. Sections in this document use the underlines:
22 ..
23 .. Level-1 ==================
24 .. Level-2 ------------------
25 .. Level-3 ++++++++++++++++++
26 .. Level-4 ..................
27
28 .. contents::
29
30
31 Introduction
32 =============
33
34 This document describes the usage of the TriBITS (Tribal Build, Integration,
35 Test System) to develop software projects. An initial overview of TriBITS is
36 provided in the `TriBITS Overview`_ document which contains the big picture
37 and provides a high-level road map to what TriBITS provides. This particular
38 document, however, describes the details on how to use the TriBITS system to
39 create a CMake build system for a set of compiled software packages. Also
40 described are an extended set of tools and processes to create a complete
41 software development, testing, and deployment environment consistent with
42 modern agile software development best practices.
43
44 TriBITS is a fairly extensive framework that is built on top of the
45 open-source CMake/CTest/CPack/CDash system (which in itself is a very
46 extensive system of software and tools). The most important thing to remember
47 is that a software project that uses TriBITS is really just a CMake project.
48 TriBITS makes no attempt to hide that fact either from the TriBITS project
49 developers or from the users that need to configure and build the software.
50 Therefore, to make effective usage of TriBITS, one must learn the basics of
51 CMake (both as a developer and as a user). In particular, CMake is a
52 Turning-complete programming language with local variables, global variables, macros, functions, targets, commands, and other
53 features. One needs to understand how to define and use variables, macros,
54 and functions in CMake. One needs to know how to debug CMakeLists.txt files
55 and CMake code in general (i.e. using ``message()`` print statements). One
56 needs to understand how CMake defines and uses targets for various qualities
57 like libraries, executables, etc. Without this basic understanding of CMake,
58 one will have trouble resolving problems when they occur.
59
60 The remainder of this documented is structured as follows. First, there is
61 some additional `Background`_ material provided. Then, a detailed
62 specification of `TriBITS Project Structure`_ is given which lists and defines
63 all of the files that a TriBITS project contains and how they are processed.
64 This is followed up by short descriptions of `Example TriBITS Projects`_ that
65 are provided with the TriBITS source tree that are used throughout this
66 document. The topic of `Package Dependencies and Enable/Disable Logic`_ is
67 then discussed which is the backbone of the TriBITS system. An overview of
68 the foundations for `TriBITS Automated Testing`_ is then given. The topic of
69 TriBITS `Multi-Repository Support`_ is examined next. `Development
70 Workflows`_ using TriBITS is then explored. This is followed by a set of
71 detailed `Howtos`_. Later some `Miscellaneous Topics`_ are presented that
72 don't fit well into other sections. Then the main bulk of the detailed
73 reference material for TriBITS is given in the section `TriBITS Detailed
74 Reference Documentation`_. Finally, several bits of information are provided
75 in the `Appendix`_.
76
77
78 .. include:: ../TribitsGuidesBody.rst
79
80
81 .. include:: TribitsCoreDetailedReference.rst
82
83
84 .. include:: ../TribitsGuidesReferences.rst
85
86
87 .. include:: ../TribitsFAQ.rst
88
89
90 Appendix
91 ========
92
93 .. include:: ../TribitsCMakeLanguageOverviewAndGotchas.rst
94
95 .. include:: ../TribitsHistory.rst
96
97 .. include:: ../TribitsPackageNotCMakePackage.rst
98
99 .. include:: ../TribitsDesignConsiderations.rst
100
101 .. include:: ../TribitsToolsDocumentation.rst
102
103
104 .. ***
105 .. *** Extra References
106 .. ***
107
108 .. _tribits_read_all_project_deps_files_create_deps_graph(): TribitsMaintainersGuide.html#tribits-read-all-project-deps-files-create-deps-graph
109
110 .. _${PACKAGE_NAME}_LIB_DEFINED_DEPENDENCIES: TribitsMaintainersGuide.html#package-name-lib-enabled-dependencies
111
112 .. _${PACKAGE_NAME}_TEST_DEFINED_DEPENDENCIES: TribitsMaintainersGuide.html#package-name-test-enabled-dependencies