Debian Codegraph @

cmake/tribits/doc/tutorial/src/TribitsTutorial_ProjectStructure.rst

raw
1 =====================================
2 A HelloWorld TriBITS Project
3 =====================================
4
5 :Author: Joe Frye ([email protected])
6 :Date: |date|
7
8 .. |date| date::
9
10 .. sectnum::
11 :depth: 2
12
13 .. Sections in this document use the underlines:
14 ..
15 .. Level-1 ==================
16 .. Level-2 ------------------
17 .. Level-3 ++++++++++++++++++
18 .. Level-4 ..................
19
20 .. contents::
21
22
23 Introduction
24 =============
25
26 This tutorial is designed to give you a basic overveiw of the
27 structure of a TriBITS project at a high level. See the tutorial on
28 TriBITS Example Project for more detail and concrete examples. TriBITS
29 defines a few structural units hat are then put together to form a
30 tribits project. In this tutorial we will discuss what each of these
31 unts are, and how to assemble them to create a tribits project. One
32 key advantage of TriBITS is that once a project is using TriBITS, it
33 is east for another project to use the packages defined in another
34 TriBITS project.
35
36
37 TriBITS Packages
38 =================
39
40 The simplest way to think of a package is as a collection of source
41 files being built into one (or more, but ideally one) library or
42 executable and a set of tests. If you have componetns of your project
43 that fit this description then consider making into a package. A
44 package does not have to build just one library or executable and if
45 there are targets that are always built together then make them all
46 part of the same package.
47
48 The goal of a tribits package is straight forward. Take some source
49 files and build a target and the tests for that target. This will be
50 the main function of the CMakeLists.txt file in top level package
51 directory. In that CmakeLists.txt file you need to tell tribits which
52 source files to use to build each target and which targets to build.
53 You will also need to define any dependencies this package may have on
54 other packages in the project.
55
56 In order top define a package, you must have the following files
57 defined::
58
59
60
61 TriBITS Projects
62 ================
63
64 A tribits project is just a collection of Tribits packages, there is
65 no limit to how many packages a project can contain but it must
66 contain at least one. A project can include packages that are defined
67 in the same repository as the project or it can use packages from
68 TriBITS repositories (see below for more detail). Source files and
69 build targets cannot be specified at the project level, that must be
70 done in a package. Once you have Tribits packages defined then you can
71 put them together in a Tribits project. In order to do this you need
72 to define some things at the project level such as packages your
73 project wishes to use and where to find them, any TPL dependencies you
74 may have, Project name and other project options, and the current
75 version of the project.
76
77 In order top define a project, you must have the following files
78 defined::
79
80 CTestConfig.cmake
81 PackagesList.cmake
82 ProjectName.cmake
83 TPLsList.cmake
84 Version.cmake
85
86
87 TriBITS Sub-packages
88 =====================
89
90 Similar to the way a TriBITS project contains packages that can
91 optionally be turned on and off, a package can defein subpackages that
92 can be optionally enabled. Subpackages allow for a finer level of
93 control over dependencies as each subpackage can define it's own
94 dependencies. A subpackage cannot have subpackages of it's own.
95
96 In order top define a subpackage, you must have the following files
97 defined::
98
99
100 TriBITS Repositories
101 =====================
102
103 A TriBITS repository is a collection of TriBITS packages. Like a
104 project a repository must define which packages it contains, any TPL
105 dependenecies, and options. Dependencies between packages are still
106 defined by the package. A TriBITS project can also be used as a
107 TriBITS repository for another TriBITS project.
108
109 In order top define a tribits repository, you must have the following
110 files defined::
111
112 TriBITS TPLS
113 ============
114
115 A TPL is software that your project depends on that is not built by
116 your project. You will have to tell TriBITS which TPLs to find and
117 how/where to look for them.
118
119
120 Summary
121 ========
122
123 The basic unit of a TriBITS build system is the TriBITS package where
124 source files are identified and targets are built. Tribits has a
125 standard way to handle dependencies within packages and will
126 automatically enable/disable all appropriate packages for a specified
127 configuration. A TriBITS project is made up of one or more TriBITS
128 packages that is either defined in the project's repo or in a TriBITS
129 repository. This document is intended to be brief and give just a
130 high level summary of the structure of a TriBITS project. Please see
131 the tutorial on converting a project to TriBITS or the TriBITS Example
132 Project tutorial for much more detail and examples.