Debian Codegraph @

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

raw
1 =====================================
2 Convert your project to use TriBITS
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 Introduction
23 ============
24
25 This document will help you convert your project that is currently
26 being built with cmake to build with Tribits instead. I will be
27 introducing a subset of tribits features in the hopes of keeping this
28 document easy to follow. There is a wealth of detailed documentation
29 for tribits. Once you have some ecperience with Tribits, I recommend
30 that you use the "TriBITS Developers Guide" as a reference. Tribits
31 is desigend to take advantage of modularity in projects and excels at
32 managing complex dependencies between software packages. Tribits
33 projects should be structured a certain in order to work best. For the
34 purposes of this tutorial, the most basic unit of Tribits is a Tribits
35 package. A Tribits project is a collection of Tribits packages.
36 (This is not the whole story but for now just consider packages and
37 projects)
38
39
40 TriBITS Packages
41 ================
42
43 The first thing to do when converting a project to tribits is to think
44 about the structure of the project and to figure out the best way to
45 break it into packages. In this section, I hope to give you a better
46 idea of what exactly constitutes a tribits package and give you some
47 guidelines on how to split them up. Once you have your project
48 building with Tribits, you will be able to build different
49 configurations by simply turning packages on or off.
50
51 Identify your packages
52 ----------------------
53
54 The simplest way to think of a package is as a collection of source
55 files being built into one (or more, but ideally one) library or
56 executable and a set of tests. If you have componetns of your project
57 that fit this description then consider making into a package. A
58 package does not have to build just one library or executable and if
59 there are targets that are always built together then make them all
60 part of the same package. For example consider the following
61 situations where you are building 3 different libraries.
62
63 examples
64 ~~~~~~~~
65
66 if libA libB, and liC do not depend on each other and it makes sense
67 to build them separately, then make them each their own package.
68
69 libA ==> libB ==> libC
70 libA depends on libB which depends on libC.
71 Again consider making them all their own packages
72
73 libA <==> libB ==> libC
74
75 libA and libB depend on each other and libB depends on libC. Make two
76 packages, one that builds A and B, and one that builds C
77
78
79 Components of a Tribits Package
80 -------------------------------
81
82 The goal of a tribits package is straight forward. Take some source
83 files and build a target and the tests for that target. This will
84 probably be the main function of the CMakeLists.txt file in top level
85 package directory. In that CmakeLists.txt file you need to have a few
86 commands if you follow this list, you will be well on your way to a
87 Tribits package.
88
89 1. tribits_package(<package_name>) - must be called before you add any
90 targets you want to build in this package. It is a good idea to
91 make it the first line in the top level CMakLists.txt file
92 #. Add subdirectories
93 #. Identify your source files
94 #. Add targets to be built using tribits_add_library(),
95 tribits_add_executable(), and tribits_add_test()
96 #. tribits_package_postprocess() - do not add any new targets or
97 include new directories after this command. This should be the
98 last line in the file
99
100 You will also need to define any dependencies this package may have on
101 other packages in the project. This is done in a File called
102 Dependencies.camke in a cmake directory. All that is required in this
103 file is a call to tribits_package_define_dependencies(). Even if the
104 package does not depend on another you still need to have this.
105
106
107 Example of simple package CMakeLists.txt files
108 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
109
110 Here is a simple example of a CMakelists.txt file for the top level of
111 a package. In this example the targets are being specified in this
112 top level file::
113
114 #
115 # A) Define the package
116 #
117 tribits_package( ExamplePackageName )
118
119 #
120 # B) Set up package-specific options
121 #
122 set(example_srcs example.cpp)
123 set(example_headers example.h)
124
125 #
126 # C) Add the libraries, tests, and examples
127 #
128 tribits_add_library(library_name SOURCES ${example_srcs} HEADERS ${example_headers})
129
130 #
131 # D) Do standard post processing
132 #
133 tribits_package_postprocess()
134
135 You may have source files grouped together into files used to build
136 the target(s) and files used to build tests of the targets. Suppose
137 you have a src/ directory and a test/ directory. Then you may want
138 your top level file to just include those subdirectories and let the
139 CMakeLists.txt in each subdirectory do B) and C) from the above
140 example. So you would have something like::
141
142 #
143 # A) Define the package
144 #
145 tribits_package( SimpleCxx ENABLE_SHADOWING_WARNINGS CLEANED )
146
147 #
148 # B) Add the libraries, tests, and examples
149 #
150 add_subdirectory(src)
151 tribits_add_test_directories(test)
152
153 #
154 # C) Do standard post processing
155 #
156 tribits_package_postprocess()
157
158 In this case you would also have a CMakeLists.txt file in the src/
159 directory that looks like. Note there are no calls to
160 tribits_package() or tribits_package_postprocess() in this lower level
161 CMakeLists file. These functions must be called in the top level
162 CMakLists file but not in any others ::
163
164 #
165 # A) Set up package-specific options
166 #
167 set(example_srcs example.cpp)
168 set(example_headers example.h)
169
170 #
171 # B) Add the libraries, tests, and examples
172 #
173 tribits_add_library(library_name SOURCES ${example_srcs} HEADERS ${example_headers})
174
175
176 Examples of Dependencies.cmake files
177 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
178
179 In Addition to the CMakeLists files described above, you will also
180 need to tell Tribits about the dependencies this package has on other
181 packages. This is done through a call to
182 tribits_package_define_dependencies() in a package's
183 Dependencies.camke file. If there are no dependencies then this file
184 will contain a call to tribits_package_define_dependencies() with no
185 arguments::
186
187 # Dependencies.camke
188 tribits_package_define_dependencies()
189
190 Suppose this package has an optional and a required dependency on
191 other packagages then the call would look something like::
192
193 tribits_package_define_dependencies(
194 LIB_REQUIRED_TPLS name_of_required_package
195 LIB_OPTIONAL_TPLS name_of_otional_package
196 )
197
198
199 Linking libraries
200 -----------------
201
202 If you are building more than one target in a package you may be
203 accustomed to calling target_link_library() to tell camke to build the
204 target against some library. If the library is being built in the
205 same package as your target, you do not need to do this because
206 Tribits will automatically link against any libraries built in the same
207 package. Additionally you do not need to do this for targets built in
208 other packages because tribits will link against any libraries built
209 in packages that the current package depends on. If you are calling
210 target_link_library() then it is either redundant, or it indicates
211 there is a dependency that needs to be defined in the
212 Dependencies.camke file of your package.
213
214
215 TriBITS Projects
216 ================
217
218 A tribits project is a collection of Tribits packages. If you have
219 Tribits packages defined then you can put them together in a Tribits
220 project. In order to do this you need to define some things at the
221 project level. The top level project will have a CMakeLists file as
222 well as a few .camke files to define packages that are in the project,
223 TPLs that he project may depend on, software version, and other
224 project information. In the tribits project directory you need to
225 have the following files:
226
227 1. *CMakeLists.txt* - top level CMakeLists for the project. here you
228 will initialize your Tribits project, define which packages will be
229 built by default, and define some setting for your project
230 #. *PackagesList.cmake* - Tells tribits which packages are part of
231 this project and where to find them
232 #. *TPLsList.cmke* - Tells tribits which TPLs that packages my depend
233 on and how to find them
234 #. *ProjectName.cmake* - defines the project name and possibly some
235 other project level settings
236 #. *Version.cmake* - set the version of the software being built
237 #. *Package Directories* - A directory for each package that contains
238 everything necessary for a Tribits package described above. Often
239 Projects will have a packages directory that contains all of the
240 individual package directories in the project
241
242 An example directory structure could look like this::
243
244 my_tribits_project/
245 |__CMakeLists.txt
246 |__PackageLists.cmake
247 |__TPLSsList.cmake
248 |__ProjectName.cmake
249 |__Version.cmkae
250 |__packages/
251 |__my_first_tribists_package/
252 | |__CMakeList.txt
253 | |__cmake/
254 | | |__Dependencies.cmake
255 | |__src/
256 | | |__ a bunch of source files
257 | |__test/
258 | |__ more source files to build tests
259 |
260 |__my_second_tribists_package/
261 |__CMakeList.txt
262 |__cmake/
263 | |__Dependencies.cmake
264 |__src/
265 | |__ a bunch of source files
266 |__test/
267 |__ more source files to build tests
268
269 next we will go over what each of the project level cmake files need
270 to contain and some of the option you may want to use for your project
271
272 ProjectName.cmake
273 -----------------
274
275 This file simply needs to set the variable PROJECT_NAME. For
276 example::
277
278 set(PROJECT_NAME Your_Project_Name)
279
280 you may also want to do other stuff in here (ask Ross What?/why?)
281
282
283 PackageList.cmake
284 -----------------
285
286 Here you will define all of the packages in the project with a name, a
287 location, and some options. This is done with a call to
288 tribits_repository_define_packages(). For example::
289
290 tribits_repository_define_packages(
291 TriBitsPackageA packages/package_a PT
292 TribitsPackageB packages/package_b PT
293 )
294
295 Each line will contain information about one package. The foirst
296 entry is the name of the package, the second is the path to the
297 package, and the third is for package classification. Package
298 classifications you can specify are:
299
300 Testing category (Required)
301
302 - *PT (Primary Tested)* - The code is the highest priority to keep
303 working. This package package is essential to developer
304 productivity and would adversly effect customers if broken.
305 - *ST (Secondary Tested)* - This code is very important to the project
306 but will not necessarily halt development if it breaks. Consider
307 making a package as ST if it depends on difficult to install TPLs or
308 TPLs that are not available no all development platforms.
309 - *EX (Experimental)* - This code is unstable and difficult to
310 maintain. It is not portible or not important enough to be tested
311 at the same level as other code
312
313 Package Maturity (Defaults to UM) (ask Ross what this is? to include?)
314 - EP
315 - RS
316 - PG
317 - PM
318 - GRS
319 - GPG
320 - GPM
321 - UM
322
323 In this file you may also choose to call
324 tribits_disable_package_on_platforms() if you have packages that you
325 know will not work on certain platform and you want to disable them on
326 those platforms::
327
328 tribits_disable_package_on_platforms(package_name
329 platform_0 platform_1 ...
330 )
331
332 This will cause package_name to be disabled by default on platform_0,
333 platform_1, ...
334
335
336 TPLsList.cmake
337 --------------
338
339 Here you will define all of the tpls in the project. The function
340 call is very similar to defining packages above. You do this by
341 calling tribits_repository_define_tpls() with a name, a path to a tpl
342 cmake find module, and a classification for each tpl. For example::
343
344 tribits_repository_define_tpls(
345 MPI "${${PROJECT_NAME}_TRIBITS_DIR}/core/std_tpls/FindTPLMPI.cmake" PT
346 SomeTplA "cmake/tpls/" PT
347 SomeTplB "cmkae/tpls/" PT
348 )
349
350 In this example you can see a path to the tribits findTPLMPI.camke
351 module which will find mpi on the system as well as examples of relative
352 paths to a directory where the project has defined some cmkae find
353 modules for the required TPLs. Each line will contain information
354 about one tpl. The first entry is the name of the tpl, the second is
355 the path to the tpl find module, and the third is for tpl
356 classification. Tpl classifications you can specify are:
357
358 Testing category (Required)
359
360 - *PT (Primary Tested)* - This tpl is essential to developer
361 productivity and would adversly effect customers if broken.
362 - *ST (Secondary Tested)* - This tpl is important to the project but
363 mat be difficult to install or the TPL is not available no all
364 development platforms.
365 - *EX (Experimental)* - TPL is experimental, unstable and/or difficult to
366 maintain.
367
368 The recommendation is to list all TPLs as "PT"
369
370
371 Version.cmake
372 -------------
373
374 This file just contains version information for the code example::
375
376 set(${REPOSITORY_NAME}_VERSION 1.1)
377 set(${REPOSITORY_NAME}_MAJOR_VERSION 01)
378 set(${REPOSITORY_NAME}_MAJOR_MINOR_VERSION 010100)
379 set(${REPOSITORY_NAME}_VERSION_STRING "1.1 (Dev)")
380 set(${REPOSITORY_NAME}_ENABLE_DEVELOPMENT_MODE_DEFAULT ON) # Change to 'OFF' for a release
381
382 CMakeList.txt
383 -------------
384
385 Here you will tell tribits some basic information it need to build as
386 atribits project. You need to specify where Tribits is located on the
387 system (many projects choose to snapshot tribits into their
388 repository) You will also be able to specify if packages are turned
389 on/off by default. Here is the order of commandsthat you should have
390 in this project level CMakeLists file:
391
392 1. cmake_minimum_version() - set the minimum version of cmake required
393 for this project o build. If you try and run with a lower version
394 then there will be an error. You cannot specify a version lower than
395 3.23.0
396 #. Include ProjectName.cmake and call project() with argument PROJECT_NAME
397 #. specify the directory to tribits and include TriBITS.cmake
398 #. specify which packages are turned on/off by default
399 #. call tribits_project()
400
401 Here is an example of a project CMakeLists::
402
403 # Define your minimum CMake version
404 cmake_minimum_required(VERSION 3.23.0 FATAL_ERROR)
405
406 # Define your project name and set up major project options
407 include("${CMAKE_CURRENT_SOURCE_DIR}/ProjectName.cmake")
408 project(${PROJECT_NAME} NONE)
409
410 # Pull in the TriBITS system and execute
411 set(${PROJECT_NAME}_TRIBITS_DIR
412 "${CMAKE_CURRENT_LIST_DIR}/../.." CACHE STRING
413 "TriBITS base directory (default assumes in TriBITS source tree)")
414 include("${${PROJECT_NAME}_TRIBITS_DIR}/TriBITS.cmake")
415
416 # Do all of the processing for this Tribits project
417 tribits_project()
418
419
420
421 TriBITS Repositories
422 --------------------
423
424 In the simplest case your project will use packages that are in the
425 same repository as your project but his does not have to be the case.
426 Packages may be defined in a TriBITS repository that can then be used
427 by your project by adding the extra repositories in a file
428 "<projectDir>/cmake/ExtraRepositoriesList.cmake" which sets up the
429 repositories with a call to::
430
431 tribits_project_define_extra_repositories()
432
433 such as ::
434
435 tribits_project_define_extra_repositories(
436 <REPO_NAME> <REPO_DIR> <REPO_VCTYPE> <REPO_URL> <REPO_PACKSTAT> <REPO_CLASSIFICATION>
437 ...
438 )
439
440 where each line is one repo and
441
442 - **REPO_NAME** is the name of the repo
443
444 - **REPO_DIR** is the relative path to the repo (assumed to be
445 ./REPO_NAME/ if it is blank)
446
447 - **REPO_VCTYPE** the type of version control used for this repo (must
448 be: "GIT", "SVN", or "")
449
450 - **REPO_URL** the url to the repo (can be "". if REPO_VCTYPE is ""
451 then this must be "")
452
453 - **REPO_PACKSTAT** indicates if this is a TriBITS repository with
454 packages or not. "NOPACKAGES" means this repo does not contain
455 TriBITS packages. "HASPACKAGES, PRE" means this repo does have
456 packages and you would like them to be processed before the packages
457 listed by your project because packages in your project depend on
458 the packages in this repo. "HASPACKAGES, POST" means this repo has
459 packages and you would like for them to be processed after the
460 packages listed in your project because the packages in this repo
461 depend on the packages in your project
462
463 - **REPO_CLASSIFICATION** indicates when this repo should be included
464 for testing must be: "Continuous", "Nightly", or "Experimental"
465