|
| 1 | +======================================= |
| 2 | +TriBITS Hello World Tutorial |
| 3 | +======================================= |
| 4 | + |
| 5 | +:Author: Roscoe A. Bartlett ( [email protected]), Joe Frye ( [email protected]) |
| 6 | +:Date: |date| |
| 7 | +:Version: .. include:: TribitsGitVersion.txt |
| 8 | + |
| 9 | +.. |date| date:: |
| 10 | + |
| 11 | + |
| 12 | +.. sectnum:: |
| 13 | + :depth: 2 |
| 14 | + |
| 15 | +.. Above, the depth of the TOC is set to just 2 because I don't want the |
| 16 | +.. TriBITS function/macro names to have section numbers appearing before them. |
| 17 | +.. Also, some of them are long and I don't want them to go off the page of the |
| 18 | +.. PDF document. |
| 19 | +
|
| 20 | +.. Sections in this document use the underlines: |
| 21 | +.. |
| 22 | +.. Level-1 ================== |
| 23 | +.. Level-2 ------------------ |
| 24 | +.. Level-3 ++++++++++++++++++ |
| 25 | +.. Level-4 .................. |
| 26 | +
|
| 27 | +.. contents:: |
| 28 | + |
| 29 | +The Simplest HelloWorld project |
| 30 | +=================================== |
| 31 | +This short tutorial will walk you through setting up a basic HelloWorld project |
| 32 | +built by TriBITS to intdroduce the basic concepts in TriBits. To begin you |
| 33 | +will need cmake and TriBITS installed on your machine. You will also need a |
| 34 | +working c and c++ compiler. |
| 35 | + |
| 36 | +TriBITS projects have a specific structure ie a project is a collection of |
| 37 | +packages. For this example we will be creating a project that has just one |
| 38 | +package, the "HelloPackage" package. |
| 39 | + |
| 40 | +Initial Setup |
| 41 | +---------------- |
| 42 | +First lets create all the directories for our project. We will need a top level |
| 43 | +directory for the project which I will call tribits_hello_world. We need a |
| 44 | +directory for the "HelloPackage" package. We will also need a directory for the |
| 45 | +build which I call "build". Under the hello_package_dir also create the directories |
| 46 | +"camke" and "src":: |
| 47 | + |
| 48 | + tribits_hello_world/ |
| 49 | + tribits_hello_wolrd/build |
| 50 | + tribits_hello_world/hello_package_dir |
| 51 | + tribits_hello_world/hello_package_dir/cmake |
| 52 | + tribits_hello_world/hello_package_dir/src |
| 53 | + |
| 54 | + $ tree |
| 55 | + . |
| 56 | + └── tribits_hello_world |
| 57 | + ├── build |
| 58 | + └── hello_package_dir |
| 59 | + ├── cmake |
| 60 | + └── src |
| 61 | + |
| 62 | +Create a TriBITS package |
| 63 | +------------------------- |
| 64 | +The most basic TriBITS package needs to have 3 files. |
| 65 | +* a top level CMakeLists file |
| 66 | +* a source file |
| 67 | +* a file that track package dependencies |
| 68 | + |
| 69 | +First lets create the source file which is the classic HelloWorld.cpp. Just |
| 70 | +copy this to HelloWorld.cpp in the src directory:: |
| 71 | + |
| 72 | + #include <iostream> |
| 73 | + |
| 74 | + int main() |
| 75 | + { |
| 76 | + std::cout << "Hello World!\n"; |
| 77 | + return 0; |
| 78 | + |
| 79 | + } |
| 80 | + |
| 81 | +Second lets create the package dependencies file which should be placed in the |
| 82 | +cmake directory. Copy the below text into a file called Dependencies.cmake:: |
| 83 | + |
| 84 | + TRIBITS_PACKAGE_DEFINE_DEPENDENCIES() |
| 85 | + |
| 86 | +In this case the package we are creating has no dependencies but we still need |
| 87 | +this file. The lack of arguments to the TRIBITS_PACKAGE_DEFINE_DEPENDENCIES() call |
| 88 | +reflects that this package does not have dependencies. The last and most interesting |
| 89 | +file we will create in the package directory is the CMakeLists.txt file. Copy the following |
| 90 | +into CMakeLists.txt:: |
| 91 | + |
| 92 | + TRIBITS_PACKAGE(HelloPackage) |
| 93 | + TRIBITS_ADD_EXECUTABLE(Hello-Executable-Name NOEXEPREFIX SOURCES src/HelloWorld.cpp INSTALLABLE) |
| 94 | + TRIBITS_PACKAGE_POSTPROCESS() |
| 95 | + |
| 96 | + |
| 97 | +**TRIBITS_PACKAGE(HelloPackage)** Sets this up a TriBITS package with the name "HelloPackage" |
| 98 | + |
| 99 | +**TRIBITS_ADD_EXECUTABLE(Hello-Executable-Name NOEXEPREFIX SOURCES src/HelloWorld.cpp INSTALLABLE)** tells |
| 100 | +TriBITS that we want to build an executable named "Hello-Executable-Name" from the source file src/HelloWorld.cpp. |
| 101 | +NOEXEPREFIX and INSTALLABLE are options to TRIBITS_ADD_EXECUTABLE() that I will not go into right now. |
| 102 | + |
| 103 | +**TRIBITS_PACKAGE_POSTPROCESS()** Must be at the end of any packages top level CMakeLists file |
| 104 | + |
| 105 | +**Say some stuff about Tribits packages (here) or at teh top of this section** |
| 106 | + |
| 107 | +Create a Tribits Project |
| 108 | +------------------------- |
| 109 | +Recall that a TriBITS project is made up of TriBITS packages. We have just defeined a package now we will create |
| 110 | +a project that consists of just that one package. In order to do this we are going to create 4 files in the top |
| 111 | +level directory and they are named: |
| 112 | +* CMakeLists.txt |
| 113 | +* PackageList.cmake |
| 114 | +* ProjectName.camke |
| 115 | +* TPLsList.cmake |
| 116 | + |
| 117 | +**TPLsList.camke** this file tells Tribits ablout TPLs needed for the project. In this case, the package does not |
| 118 | +depend on any TPLs so this file will be very simple. It should contain just the following single line:: |
| 119 | + |
| 120 | + TRIBITS_REPOSITORY_DEFINE_TPLS() |
| 121 | + |
| 122 | +**ProjectName.camke** this file sets the name of the project. Some other options can be specified in this file but we |
| 123 | +will just set the project name. It should contain the following:: |
| 124 | + |
| 125 | + SET(PROJECT_NAME TribitsHelloWorld) |
| 126 | + |
| 127 | +**PackageList.cmake** defeines which packages are in the project. We will just need to tell it the name and location |
| 128 | +of our one package:: |
| 129 | + |
| 130 | + TRIBITS_REPOSITORY_DEFINE_PACKAGES( |
| 131 | + HelloPackage hello_package_dir PT |
| 132 | + ) |
| 133 | + |
| 134 | +**CMakeLists.txt** This is the most interesting file in this example. Here we will set a minimum cmake version, load some |
| 135 | +options, and tell cmake that this is a Tribits project. The CMakeLists.txt file should have the following contents:: |
| 136 | + |
| 137 | + # To be safe, define your minimum CMake version |
| 138 | + CMAKE_MINIMUM_REQUIRED(VERSION 2.8.11 FATAL_ERROR) |
| 139 | + |
| 140 | + # Make CMake set WIN32 with CYGWIN for older CMake versions |
| 141 | + SET(CMAKE_LEGACY_CYGWIN_WIN32 1 CACHE BOOL "" FORCE) |
| 142 | + |
| 143 | + # Get PROJECT_NAME (must be in file for other parts of system) |
| 144 | + INCLUDE(${CMAKE_CURRENT_SOURCE_DIR}/ProjectName.cmake) |
| 145 | + |
| 146 | + # CMake requires that you declare the CMake project in the top-level file |
| 147 | + PROJECT(${PROJECT_NAME} NONE) |
| 148 | + |
| 149 | + # This needs to be set to the path to the installation of TriBITS on your machine |
| 150 | + SET(${PROJECT_NAME}_TRIBITS_DIR ${CMAKE_CURRENT_SOURCE_DIR}/cmake/tribits |
| 151 | + CACHE PATH "TriBITS base directory (default assumes in TriBITS source tree).") |
| 152 | + |
| 153 | + # Include the TriBITS system |
| 154 | + INCLUDE("${${PROJECT_NAME}_TRIBITS_DIR}/TriBITS.cmake") |
| 155 | + |
| 156 | + # MPI and Fortran are enabled by defualt, turn them off for this project |
| 157 | + SET(TPL_ENABLE_MPI OFF CACHE BOOL "" FORCE) |
| 158 | + # Turn off Fortran support by default |
| 159 | + SET(${PROJECT_NAME}_ENABLE_Fortran_DEFAULT OFF) |
| 160 | + |
| 161 | + # Only one package in this simple project so just enable it :-) |
| 162 | + SET(${PROJECT_NAME}_ENABLE_HelloPackage ON CACHE BOOL "" FORCE) |
| 163 | + |
| 164 | + # Do all of the processing for this Tribits project |
| 165 | + TRIBITS_PROJECT() |
| 166 | + |
| 167 | +**SET(${PROJECT_NAME}_TRIBITS_DIR ${CMAKE_CURRENT_SOURCE_DIR}/cmake/tribits |
| 168 | + CACHE PATH "TriBITS base directory (default assumes in TriBITS source tree).")** |
| 169 | +Make sure you set this to your Tribits Installation path it may not be the same as |
| 170 | +this path. Now you should have a directory structure that looks like this:: |
| 171 | + |
| 172 | + . |
| 173 | + ├── CMakeLists.txt |
| 174 | + ├── PackagesList.cmake |
| 175 | + ├── ProjectName.cmake |
| 176 | + ├── TPLsList.cmake |
| 177 | + ├── build |
| 178 | + └── hello_package_dir |
| 179 | + ├── CMakeLists.txt |
| 180 | + ├── cmake |
| 181 | + │ └── Dependencies.cmake |
| 182 | + └── src |
| 183 | + └── HelloWorld.cpp |
| 184 | + |
| 185 | + |
| 186 | +Build your TriBITS project |
| 187 | +--------------------------- |
| 188 | +Go to the build directory and type:: |
| 189 | + cmake ../ |
| 190 | + |
| 191 | +You should see something very similar to:: |
| 192 | + |
| 193 | +..literalinclude:: HelloWorldConfigure.output |
| 194 | + |
0 commit comments