Project

General

Profile

Using CMake » History » Version 6

Roman Tabulov, 06/25/2010 08:45 AM

1 1 Pieter Libin
h1. Using CMake
2
3 4 Anonymous
{{toc}}
4
5 1 Pieter Libin
In this example we are going to see how to use CMake to compile a very simple Wt project where you have a *source* directory with all your files
6
and a *build* directory to generate your application.
7
8 5 Roman Tabulov
If you don't care where your files are located or you are looking for an even simpler example you can go [[Frequently_Asked_Questions#Q-How-do-I-build-my-newly-written-Hello-World-application]].
9 1 Pieter Libin
10
11
h4. Directory Structure 
12
13
Before starting make sure that your project main directory (In this example the main directory is called main) looks like this:
14
15
<pre>
16
main
17
|
18
+--source..................you have all your files here
19 4 Anonymous
<pre>
20 1 Pieter Libin
    |
21
    + -- CMakeLists.txt .. a text file where we will write CMake commands (empty) 
22 4 Anonymous
</pre>
23 1 Pieter Libin
+--build.................. build directory (initially, this directory is empty)
24
+--CMakeLists.txt ........ a text file where we will write CMake commands (empty)
25
</pre>
26
27
28
h4. CMakeLists.txt in the main directory 
29
30
These are the contents of the CMakeLists.txt file that you should write on the main directory
31
32
<pre>
33
CMAKE_MINIMUM_REQUIRED(VERSION 2.6)
34
35
PROJECT(WT_EXAMPLE)
36
37
SET (WT_CONNECTOR "wtfcgi" CACHE STRING "Connector used (wthttp or wtfcgi)")
38
39
ADD_SUBDIRECTORY(source)
40
</pre>
41
42
* The first two instructions are self descriptive. CMAKE_MINIMUM_REQUIRED checks that you have the indicated version. If you don't include this instruction in your CMakeLists.txt you will be able to continue but you will see a warning message. The second option, PROJECT, simply assigns a name to your CMake project.
43
44
* The third instruction is a bit more interesting. SET allows to create variables inside a CMake script. In this case we are creating a variable named WT_CONNECTOR that is going to contain a string value that by default is going to be "wtfcgi". The syntax used here is:
45
46
<pre>
47
SET(VARIABLE_NAME default_value CACHE type "help message")
48
</pre>
49
50
* The CACHE options allows to save the value. Next time you run ccmake (as you will see later) the variable will contain the last value that you entered.
51
52
* The last instruction in this CMake script is ADD_SUBDIRECTORY. This instruction will delegate the execution of the script to the subdirectory enclosed in parenthesis. 
53
54
The syntax is:
55
56
<pre> ADD_SUBDIRECTORY(subdir)</pre>
57
58
You need to make sure that there is a CMakeLists.txt file in the subdirectory that you are referencing, so that sub CMakeLists.txt will be executed.
59
60
In our example as we have one subdirectory (source) we will have a correspondant CMakeLists.txt file in there.
61
62
63
h4. CMakeLists.txt in the source directory 
64
65
This is an example of the CMakeLists.txt file that goes in the source directory
66
67
<pre>
68
SET(WT_PROJECT_SOURCE
69
File1.h
70
File1.cpp
71
File2.h
72
File2.cpp
73
Main.C
74
)
75
76
SET(WT_PROJECT_TARGET wt_project.wt)
77
78
ADD_EXECUTABLE(${WT_PROJECT_TARGET} ${WT_PROJECT_SOURCE})
79
80
TARGET_LINK_LIBRARIES(${WT_PROJECT_TARGET} ${WT_CONNECTOR} wt)
81
82
INCLUDE_DIRECTORIES(/usr/local/include/Wt)
83
</pre>
84
85
Let's break this down:
86
87
88
h5. Variables in a CMake script 
89
90
WT_PROJECT_SOURCE and WT_PROJECT_TARGET are two variables and you can change the names as you like as long as you make sure that you change them everywhere in your script.
91
92
93
h5. SET instruction 
94
95
The CMake SET instruction allows to associate any number of strings with a CMake variable. The syntax is:
96
97
<pre>
98
SET(CMAKE_VARIABLE string1 string2 ... stringN)
99
</pre>
100
101
In our example we have two SET instructions. The first one is allowing us to associate all our source file names with WT_PROJECT_SOURCE. The second SET instruction is associating the string wt_project.wt with WT_PROJECT_TARGET.
102
103
104
h5. ADD_EXECUTABLE instruction 
105
106
The ADD_EXECUTABLE instruction configures the executable file you are about to compile. The syntax is:
107
108
<pre>
109
ADD_EXECUTABLE(EXECUTABLE_NAME file1 file2 ... fileN)
110
</pre>
111
112
However given that we have our source list in the variable WT_PROJECT_SOURCE, we can write:
113
114
<pre>
115
ADD_EXECUTABLE(EXECUTABLE_NAME ${WT_PROJECT_SOURCE})
116
</pre>
117
118
In this case we see the way CMake variables can be used. Every time that you want to refer to any variable contents you just need to use the ${} syntax around the variable name.
119
120
121
h5. TARGET_LINK_LIBRARIES instruction 
122
123
The TARGET_LINK_LIBRARIES instruction allows to link our executable file with the depending libraries. The syntax is:
124
<pre>
125
TARGET_LINK_LIBRARIES(EXECUTABLE_NAME lib1 lib2 ... libN)
126
</pre>
127
128
In our case we need to make sure that the our executable links to  Wt (wt library) and one of the connectors (wthttp library or wtfcgi library). In our example, the connector name is stored in the variable WT_CONNECTOR.
129
130
131
h5. INCLUDE_DIRECTORIES instruction 
132
133
The INCLUDE_DIRECTORIES instruction adds the given directories to those searched by the compiler for include files. The syntax is:
134
<pre>
135
INCLUDE_DIRECTORIES(dir1 dir2 ... dirN)
136
</pre>
137
138
For the sake of the example, I have added the directory /usr/local/include/Wt. This is where all the Wt header files live in my Ubuntu installation. However this might not be the case for you and you might want to decipher where these files are in your system. The general solution for this is to use 
139
140
TODO: Talk about FIND_PACKAGE
141
142
143
h4. Project files/Makefiles generation 
144
145
Once you are finished editing the source/CMakeLists.txt file you should go to the build directory and type:
146
<pre>cmake ..</pre>
147
148
149
You will see the initial CCMake screen on your terminal console:
150
151
<pre>
152 4 Anonymous
<pre>
153 1 Pieter Libin
                                                     Page 0 of 1
154
 EMPTY CACHE
155 4 Anonymous
</pre>
156 1 Pieter Libin
157
158
EMPTY CACHE:
159
Press [enter] to edit option                         CMake Version 2.6 - patch 4
160
Press [c] to configure
161
Press [h] for help         Press [q] to quit without generating
162
Press [t] to toggle advanced mode (Currently Off)
163
</pre>
164
165
Here you need to run the configuration option by pressing *[c]*
166
167
This will take you to the next screen:
168
169
<pre>
170 4 Anonymous
<pre>
171 1 Pieter Libin
                                                     Page 1 of 1
172
 CMAKE_BUILD_TYPE                                                         
173
 CMAKE_INSTALL_PREFIX             /usr/local                                   
174
 WT_CONNECTOR                     wtfcgi                                       
175 4 Anonymous
</pre>
176 1 Pieter Libin
177 4 Anonymous
178 1 Pieter Libin
CMAKE_BUILD_TYPE: Choose the type of build, options are: None(CMAKE_CXX_FLAGS or
179
Press [enter] to edit option                         CMake Version 2.6 - patch 4
180
Press [c] to configure
181
Press [h] for help         Press [q] to quit without generating
182
Press [t] to toggle advanced mode (Currently Off)
183
</pre>
184
185
At this point, you need to define the type of build (CMAKE_BUILD_TYPE) you are going to do. Options are:
186
187
* Debug
188
* Release
189
* RelWithDebInfo
190
* MinSizeRel
191
192
Next we see that the variable WT_CONNECTOR that was defined in the main directory CMakeLists.txt file appears. As stated before, options for this variable are:
193
194
* wthttp (Wt connector)
195
* wtfcgi (FastCGI connector)
196
197
Once you are set this properties, for instance selecting Debug and wtfcgi respectively, you need to configure again (by pressing *[c]*).  This time an aditional option *[g]* appears: 
198
199
<pre>
200 4 Anonymous
<pre>
201 1 Pieter Libin
                                                     Page 1 of 1
202
 CMAKE_BUILD_TYPE                 Debug                                        
203
 CMAKE_INSTALL_PREFIX             /usr/local                                   
204
 WT_CONNECTOR                     wtfcgi                                       
205 4 Anonymous
</pre>
206
207 1 Pieter Libin
208
209
CMAKE_BUILD_TYPE: Choose the type of build, options are: None(CMAKE_CXX_FLAGS or
210
Press [enter] to edit option                         CMake Version 2.6 - patch 4
211
Press [c] to configure     Press [g] to generate and exit
212
Press [h] for help         Press [q] to quit without generating
213
Press [t] to toggle advanced mode (Currently Off)
214
</pre>
215
216
At this point you press [g] to generate your project. This step takes care of the files that need to be generated in order to compile your project on the platform you are working on. For example if you were working on Visual Studio under Windows, then the project and solution files would be generated. On Linux you will see that there is a set of Makefiles that you will use to compile your project.
217
218
After pressing [g] you will end up in the build directory again. This time we just do a regular *make*. The output should be something similar to this:
219
cg
220
<pre>
221
make
222
[ 50%] Building CXX object src/CMakeFiles/App.wt.dir/App.cpp.o
223
[100%] Building CXX object src/CMakeFiles/App.wt.dir/Main.C.o
224
Linking CXX executable App.wt
225
[100%] Built target App.wt
226
</pre>
227
228
Now your application is ready to go. To execute your application you need to follow the guidelines for the case where you are using the built-in Wt server or any FastCGI supporting web server.
229
230
231
h4. Summary 
232
233
Well that is basically it. I hope this had been helpful to understand a little bit more what CMake is about. As this is the first version of this document please feel free to make any comments, suggestion, or corrections.
234
235
If you want to learn more about the different instructions that CMake offers I advise you to visit:
236
237
* Pau Garcia's CMake slides (http://www.elpauer.org/stuff/learning_cmake.pdf)
238
* The CMake documentation webpage (http://www.cmake.org/cmake/help/cmake2.6docs.html)
239 6 Roman Tabulov
* CMake with Eclipse (http://www.cmake.org/Wiki/CMake:Eclipse_UNIX_Tutorial)