Debian Codegraph @

cmake/tribits/doc/tutorial/src/TribitsTutorial_HelloWorld.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 The Simplest HelloWorld project
24 ================================
25
26 This short tutorial will walk you through setting up a basic
27 HelloWorld project built by TriBITS to intdroduce basic concepts in
28 TriBITS. To begin you will need cmake and TriBITS installed on your
29 machine. You will also need a working c and c++ compiler.
30
31 **Before you begin make sure you have:**
32 - CMake installed
33 - Tribits installed
34 - C compiler
35 - C++ compiler
36
37 Initial Setup
38 -------------------
39
40 TriBITS projects have a specific structure ie a project is a
41 collection of packages. Packages may or may not depend on other
42 packages, and may or may not be required. For this example we will be
43 creating a project that has just one package, the "HelloPackage"
44 package. First lets create all the directories for our project. We
45 will need a top level directory for the project which I will call
46 tribits_hello_world. We need a directory for the "HelloPackage"
47 package. We will also need a directory for the build which I call
48 "build". Under the hello_package_dir also create the directories
49 "cmake" and "src"
50
51 You should have the following directories::
52
53 tribits_hello_world/
54 tribits_hello_wolrd/build
55 tribits_hello_world/hello_package_dir
56 tribits_hello_world/hello_package_dir/cmake
57 tribits_hello_world/hello_package_dir/src
58
59 $ tree
60 .
61 |__ tribits_hello_world
62 |__ build
63 |__ hello_package_dir
64 |__ cmake
65 |__ src
66
67
68 Create a TriBITS package
69 ------------------------
70
71 Any TriBITS package needs to have at least 3 files.
72
73 - a top level CMakeLists file
74 - a file that track package dependencies
75 - source files
76
77
78 First lets create a single source file which is the classic
79 HelloWorld.cpp. Just copy this to HelloWorld.cpp in the src
80 directory::
81
82 #include <iostream>
83
84 int main()
85 {
86 std::cout << "Hello World!\n";
87 return 0;
88
89 }
90
91 Second lets create the package dependencies file which should be
92 placed in the cmake directory. Copy the below text into a file called
93 Dependencies.cmake::
94
95
96 tribits_package_define_dependencies()
97
98
99 In this case the package we are creating has no dependencies but we
100 still need this file. The lack of arguments to the
101 tribits_package_define_dependencies() call reflects that this package
102 does not have dependencies. The last and most interesting file we
103 will create in the package directory is the CMakeLists.txt file. Copy
104 the following into CMakeLists.txt::
105
106 tribits_package(HelloPackage)
107
108 tribits_add_executable(Hello-Executable-Name NOEXEPREFIX SOURCES
109 src/HelloWorld.cpp INSTALLABLE)
110
111 tribits_package_postprocess()
112
113 **tribits_package(HelloPackage)** Sets up a TriBITS package with the
114 name "HelloPackage"
115
116 **tribits_add_executable(Hello-Executable-Name NOEXEPREFIX SOURCES src/HelloWorld.cpp INSTALLABLE)**
117 tells TriBITS that we want to build an executable named
118 "Hello-Executable-Name" from the source file src/HelloWorld.cpp.
119 NOEXEPREFIX and INSTALLABLE are options to tribits_add_executable()
120 that I will not go into right now.
121
122 **tribits_package_postprocess()** Must be at the end of any
123 packages top level CMakeLists file
124
125
126 Create a Tribits Project
127 ------------------------
128
129 Recall that a TriBITS project is made up of TriBITS packages. We have
130 just defeined a package now we will create a project that consists of
131 just that one package. In order to do this we are going to create 4
132 files in the top level directory and they are named:
133
134 - CMakeLists.txt
135 - PackageList.cmake
136 - ProjectName.cmake
137 - TPLsList.cmake
138
139
140 **TPLsList.cmake** this file tells Tribits about TPLs needed for the
141 project. In this case, the package does not depend on any TPLs so
142 this file will be very simple. It should contain just the following
143 single line::
144
145 tribits_repository_define_tpls()
146
147 **ProjectName.cmake** this file sets the name of the project. Some
148 other options can be specified in this file but we will just set the
149 project name. It should contain the following::
150
151 set(PROJECT_NAME TribitsHelloWorld)
152
153 **PackageList.cmake** defines which packages are in the project. We
154 will just need to tell it the name and location of our one package::
155
156 tribits_repository_define_packages(
157 HelloPackage hello_package_dir PT
158 )
159
160 **CMakeLists.txt** This is the most interesting file in this example.
161 Here we will set a minimum cmake version, load some options, and tell
162 cmake that this is a Tribits project. The CMakeLists.txt file should
163 have the following contents::
164
165 # To be safe, define your minimum CMake version
166 cmake_minimum_required(VERSION 3.23.0 FATAL_ERROR)
167
168 # Make CMake set WIN32 with CYGWIN for older CMake versions
169 set(CMAKE_LEGACY_CYGWIN_WIN32 1 CACHE BOOL "" FORCE)
170
171 # Get PROJECT_NAME (must be in file for other parts of system)
172 include(${CMAKE_CURRENT_SOURCE_DIR}/ProjectName.cmake)
173
174 # CMake requires that you declare the CMake project in the top-level file
175 project(${PROJECT_NAME} NONE)
176
177 # This needs to be set to the path to the installation of TriBITS on your machine
178 set(${PROJECT_NAME}_TRIBITS_DIR
179 ${CMAKE_CURRENT_SOURCE_DIR}/cmake/tribits CACHE PATH "TriBITS base
180 directory (default assumes in TriBITS source tree).")
181
182 # Include the TriBITS system
183 include("${${PROJECT_NAME}_TRIBITS_DIR}/TriBITS.cmake")
184
185 # MPI and Fortran are enabled by default, turn them off for this project
186 set(TPL_ENABLE_MPI OFF CACHE BOOL "" FORCE)
187 # Turn off Fortran support by default
188 set(${PROJECT_NAME}_ENABLE_Fortran_DEFAULT OFF)
189
190 # Only one package in this simple project so just enable it :-)
191 set(${PROJECT_NAME}_ENABLE_HelloPackage ON CACHE BOOL "" FORCE)
192
193 # Do all of the processing for this Tribits project
194 tribits_project()
195
196 **${PROJECT_NAME}_TRIBITS_DIR** Make sure you set this to your Tribits
197 Installation path it may not be the same as this path. Now you should
198 have a directory structure that looks like this::
199
200 .
201 |__ CMakeLists.txt
202 |__ PackagesList.cmake
203 |__ ProjectName.cmake
204 |__ TPLsList.cmake
205 |__ build
206 |__ hello_package_dir
207 |__ CMakeLists.txt
208 |__ cmake
209 |__ |__ Dependencies.cmake
210 |__ src
211 |__ HelloWorld.cpp
212
213
214 Build your TriBITS project
215 ----------------------------
216
217 Go to the build directory and type the following to configure your
218 project::
219
220 cmake ../
221
222 The configure step will have created several files inside your build
223 directory, most notably it will have created necessary make files to
224 actually build your project. The other file I will mention here is
225 the CMakeCache.txt which stores information about how the project was
226 configured. To build your project just type::
227
228 make
229
230 you should see::
231
232 [ 50\%] Building CXX object
233 hello_package_dir/CMakeFiles/Hello-Executable-Name.dir/src/HelloWorld.cpp.o
234 [100\%] Linking CXX executable Hello-Executable-Name.exe
235 [100\%] Built target Hello-Executable-Name
236
237 now in build/hello\_package\_dir you will see an executable named
238 "Hello-Executable-Name" and if you run that executable you will see::
239
240 $ ./hello_package_dir/Hello-Executable-Name.exe
241 Hello World!
242
243
244 Adding other targets
245 ======================
246
247 Types of targets
248 ------------------
249
250 Previously we had just one source file and we compiled it into one
251 executable. In addition to executables we may also want to create
252 other targets such as libraries abd tests. In the
253 hello_package_dir/src directory create the following files:
254
255 **hello_world_main.cpp**::
256
257 #include <iostream>
258 #include "hello_world_lib.hpp"
259 int main() {
260 std::cout << HelloWorld::gethelloworld() << "\n";
261 return 0;
262 }
263
264 **hello_world_lib.hpp**::
265
266 #include <string>
267
268 namespace HelloWorld { std::string gethelloworld(); }
269
270 **hello_world\_lib.cpp**::
271
272 #include "hello_world_lib.hpp"
273 std::string HelloWorld::gethelloworld()
274 { return "Hello World!"; }
275
276 **hello_world_unit_tests.cpp**::
277
278 #include <iostream>
279 #include "hello_world_lib.hpp"
280
281 int main() {
282
283 bool success = true;
284
285 const std::string rtn = HelloWorld::gethelloworld();
286 std::cout << "HelloWorld::gethelloworld() = '"<<rtn<<"' == 'Hello World'? ";
287 if (rtn == "Hello World!") {
288 std::cout << "passed\n";
289 }
290 else {
291 std::cout << "FAILED\n";
292 success = false;
293 }
294
295 if (success) {
296 std::cout << "All unit tests passed :-)\n";
297 }
298 else {
299 std::cout << "At least one unit test failed :-(\n";
300 }
301
302 }
303
304 We will use these files to build an executalbe, a library, and tests.
305 Remember in the CMakeLists.txt file for the HelloPackage
306 (hello_package_dir/CMakeList.txt) we have the line::
307
308 tribits_add_executable(Hello-Executable-Name NOEXEPREFIX SOURCES
309 src/HelloWorld.cpp INSTALLABLE)
310
311 lets now modify that line to build an executable of the same name but
312 using hello_world_main.cpp instead of HelloWorld.cpp::
313
314 tribits_add_executable(Hello-Executable-Name NOEXEPREFIX SOURCES
315 src/hello_world_main.cpp INSTALLABLE)
316
317 to create a library we need to call tribits_add_library() and give it
318 a name, headers and sources. add this the CMakeLists.txt::
319
320 tribits_add_library(hello_world_lib HEADERS src/hello_world_lib.hpp
321 SOURCES src/hello_world_lib.cpp)
322
323 we can also add tests. You can add a test based on an executable you
324 have already specified for example::
325
326 tribits_add_test(Hello-Executable-Name NOEXEPREFIX
327 PASS_REGULAR_EXPRESSION "Hello World")
328
329 will run "Hello-Executable-Name" and verify that the output is "Hello
330 World". You can also add a test and an executable att he same
331 time. for example::
332
333 tribits_add_executable_and_test(unit_tests SOURCES
334 src/hello_world_unit_tests.cpp PASS_REGULAR_EXPRESSION "All unit
335 tests passed")
336
337 will create an executable named "unit_tests" from the source file
338 hello_world_unit_tests.cpp. This executable will be used in a test
339 that will be marked as passing if the output of that executable is
340 "All unit tests passed". After making these changes and additions to
341 the CMakeLists.txt file it should read::
342
343 tribits_package(HelloPackage)
344
345 tribits_add_library(hello_world_lib HEADERS src/hello_world_lib.hpp
346 SOURCES src/hello_world_lib.cpp)
347
348 tribits_add_executable(Hello-Executable-Name NOEXEPREFIX SOURCES
349 hello_world_main.cpp INSTALLABLE)
350
351 tribits_add_test(Hello-Executable-Name NOEXEPREFIX
352 PASS_REGULAR_EXPRESSION "Hello World")
353
354 tribits_add_executable_and_test(unit_tests SOURCES
355 hello_world_unit_tests.cpp PASS_REGULAR_EXPRESSION "All unit tests
356 passed")
357
358 tribits_package_postprocess()
359
360 now reconfigure and rebuild in the build directory with::
361
362 cmake ../
363 make
364
365
366 What did we build?
367 ====================
368
369 In the build directory there are many new files created by
370 TriBITS/CMake lets look at a few that are important for understanding
371 how TriBITS is building your project.
372
373 Build Targets
374 ----------------
375
376 In the last section we built a library, an executable, and two tests.
377 Where are they? look in::
378
379 build/hello_package_dir
380
381 among other things you will see::
382
383
384 Hello-Executable-Name.exe
385 HelloPackage_unit_tests.exe
386 libhello_world_lib.a
387
388 by default, TriBITS will place the targets inside a directory with the
389 same name as the package directory. If you have more than one package
390 then the files will be in separate directories::
391
392 build
393 |__ package_one
394 |__ build_target_A
395 |__ build_target_B
396 |__ package_two
397 |__ build_target_C
398 |__ build_target_D
399
400 You can install the built targets to the default location
401 (/usr/local/bin) with::
402
403
404 make install
405
406 You may want to install somewhere other than the default. In this
407 case you want to set a CMamke variable called CMAKE_INSTALL_PREFIX. If
408 this is set then the files will be installed to the directory
409 specified. For example in the top level CMakeLists set this variable
410 to a diecroyr called "Install" in the current source tree::
411
412 set(CMAKE_INSTALL_PREFIX ${CMAKE_CURRENT_SOURCE_DIR}/Install)
413
414 now clear the contents of the build directory and reconfigure, build,
415 and install the project with::
416
417 cmake ../
418 make install
419
420 Now you should see a directory called "Install" in the top level of the
421 project with contents::
422
423 tree
424 .
425 |__ bin
426 | |__ Hello-Executable-Name.exe
427 |__ include
428 | |__ hello_world_lib.hpp
429 |__ lib
430 |__ cmake
431 | |__ TribitsGreetings
432 | |__ TribitsGreetingsConfigVersion.cmake
433 |__ libhello_world_lib.a
434
435
436 Summary
437 ========
438
439 This tutorial has covered the most basic concepts in a TriBITS
440 project. A TriBITS project a collection of TriBITS packages and each
441 package defines its build targets (executables, tests, and libraries)
442 and source files. A package also must define its dependencies. See
443 the TriBITS example project tutarial for a more complicate example of
444 a project and more detail about Tribits packages, TPLs, and
445 dependencies