-
Notifications
You must be signed in to change notification settings - Fork 0
/
BuildingWithCMake.html
286 lines (243 loc) · 23.5 KB
/
BuildingWithCMake.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
<!DOCTYPE html>
<html lang="en" data-content_root="./">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Building with CMake</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="_static/bootstrap-sphinx.css?v=fadd4351" />
<link rel="stylesheet" type="text/css" href="_static/custom.css?v=77160d70" />
<script src="_static/documentation_options.js?v=a8da1a53"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="CMake Guidelines" href="CMakeBestPractices.html" />
<link rel="prev" title="Building on OS X" href="BuildingOnOSX.html" />
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-59110517-1', 'auto');
ga('send', 'pageview');
</script>
</head><body>
<div id="navbar" class="navbar navbar-default ">
<div class="container">
<div class="navbar-header">
<!-- .btn-navbar is used as the toggle for collapsed navbar content -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="http://www.mantidproject.org">
</a>
<span class="navbar-text navbar-version pull-left"><b>main</b></span>
</div>
<div class="collapse navbar-collapse nav-collapse">
<ul class="nav navbar-nav">
<li class="divider-vertical"></li>
<li><a href="index.html">Home</a></li>
<li><a href="https://download.mantidproject.org">Download</a></li>
<li><a href="https://docs.mantidproject.org">User Documentation</a></li>
<li><a href="http://www.mantidproject.org/contact">Contact Us</a></li>
</ul>
<form class="navbar-form navbar-right" action="search.html" method="get">
<div class="form-group">
<input type="text" name="q" class="form-control" placeholder="Search" />
</div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<p>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="nav-item nav-item-0"><a href="index.html">Documentation</a> »</li>
<li class="nav-item nav-item-this"><a href="">Building with CMake</a></li>
</ul>
</div> </p>
</div>
<div class="container">
<div class="row">
<div class="body col-md-12 content" role="main">
<section id="building-with-cmake">
<span id="buildingwithcmake"></span><h1>Building with CMake<a class="headerlink" href="#building-with-cmake" title="Link to this heading">¶</a></h1>
<nav class="contents local" id="contents">
<ul class="simple">
<li><p><a class="reference internal" href="#environment" id="id3">Environment</a></p></li>
<li><p><a class="reference internal" href="#ccache" id="id4">CCache</a></p>
<ul>
<li><p><a class="reference internal" href="#network-drives" id="id5">Network Drives</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#configuring-your-build" id="id6">Configuring your build</a></p>
<ul>
<li><p><a class="reference internal" href="#cmake-generators" id="id7">CMake generators</a></p></li>
<li><p><a class="reference internal" href="#from-the-command-line" id="id8">From the command line</a></p></li>
<li><p><a class="reference internal" href="#from-the-cmake-gui" id="id9">From the CMake gui</a></p></li>
<li><p><a class="reference internal" href="#data-files-location" id="id10">Data Files Location</a></p></li>
<li><p><a class="reference internal" href="#with-qt-creator" id="id11">With Qt Creator</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#building-and-working-with-cmake" id="id12">Building and working with CMake</a></p></li>
<li><p><a class="reference internal" href="#caveats-and-known-issues" id="id13">Caveats and Known Issues</a></p></li>
<li><p><a class="reference internal" href="#tips" id="id14">Tips</a></p></li>
<li><p><a class="reference internal" href="#build-system-customisation-using-cmake-variables" id="id15">Build system customisation using CMake variables</a></p></li>
</ul>
</nav>
<p>CMake is the build system for the entirety of Mantid (Framework, MantidQt and MantidWorkbench). It is used to generate native build files for your platform, which can be Makefiles (for use with make, nmake or jom) for command line builds or project/solution files for an IDE (e.g. Visual Studio, Eclipse, Qt Creator, XCode).
For a “how is it used version” of this guide, see the <a class="reference external" href="https://github.com/mantidproject/mantid/blob/main/buildconfig/Jenkins/Conda/build">build script</a> used on the build servers.</p>
<section id="environment">
<h2><a class="toc-backref" href="#id3" role="doc-backlink">Environment</a><a class="headerlink" href="#environment" title="Link to this heading">¶</a></h2>
<p>The <a class="reference internal" href="GettingStarted/GettingStarted.html#gettingstarted"><span class="std std-ref">getting started</span></a> page describes how to set up your environment to build Mantid. Follow those instructions and install the Mantid dependencies first.</p>
<p>Also, if you use the <a class="reference external" href="https://ninja-build.org/">Ninja</a> generator then the executable is called <code class="docutils literal notranslate"><span class="pre">ninja-build</span></code> on many systems (e.g. RHEL) rather than <code class="docutils literal notranslate"><span class="pre">ninja</span></code>.</p>
</section>
<section id="ccache">
<h2><a class="toc-backref" href="#id4" role="doc-backlink">CCache</a><a class="headerlink" href="#ccache" title="Link to this heading">¶</a></h2>
<p>Mantid is configured to use the <a class="reference external" href="https://ccache.samba.org/">ccache</a> tool if it is available.
It is highly recommended that this be used on Linux/macOS systems, and Windows when using a Ninja generator.
CCache is installed within your conda environment, and CMake is configured to automatically use it when building.</p>
<p>With your conda environment activated, run <code class="docutils literal notranslate"><span class="pre">ccache</span> <span class="pre">--max-size=20G</span></code> to increase the size of the cache.</p>
<p>If you’re build with <code class="docutils literal notranslate"><span class="pre">ccache</span></code> exhibits warnings that are not usually present then try setting the <code class="docutils literal notranslate"><span class="pre">ccache</span> <span class="pre">--set-config=run_second_cpp="true"</span></code> config option (or set <code class="docutils literal notranslate"><span class="pre">CCACHE_CPP2=yes</span></code> environment variable on older versions).</p>
<section id="network-drives">
<h3><a class="toc-backref" href="#id5" role="doc-backlink">Network Drives</a><a class="headerlink" href="#network-drives" title="Link to this heading">¶</a></h3>
<p>The default location for the cache directory is <code class="docutils literal notranslate"><span class="pre">$HOME/.ccache</span></code> on Linux/macOS, and <code class="docutils literal notranslate"><span class="pre">$HOME/AppData/Roaming/ccache</span></code> on Windows. If your home directory is on a network-mounted drive, the location of this cache can be moved to provide the best performance. On newer versions of <code class="docutils literal notranslate"><span class="pre">ccache</span></code> run <code class="docutils literal notranslate"><span class="pre">ccache</span> <span class="pre">--set-config=cache_dir=PATH_TO_CACHE</span></code>. Older versions (<3.2) do not allow this and must fall back to setting the <code class="docutils literal notranslate"><span class="pre">CCACHE_DIR</span></code> environment variable in your shell profile.</p>
</section>
</section>
<section id="configuring-your-build">
<h2><a class="toc-backref" href="#id6" role="doc-backlink">Configuring your build</a><a class="headerlink" href="#configuring-your-build" title="Link to this heading">¶</a></h2>
<p>CMake encourages the use of ‘out of source’ builds. This means that all generated files are placed in a separate directory structure to the source files. This separation makes a full clean easier (you just delete everything) and means that you can have different types of build (Release, Debug, different compiler versions, etc.) in separate places (Note that for Visual Studio & XCode, you can still select the type of build from within the IDE).</p>
<section id="cmake-generators">
<h3><a class="toc-backref" href="#id7" role="doc-backlink">CMake generators</a><a class="headerlink" href="#cmake-generators" title="Link to this heading">¶</a></h3>
<p>CMake has a <a class="reference external" href="https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html">variety of generators available</a>.
It is suggested that one select the generator that is most appropriate for the IDE/toolchain being used.
On linux, there is a large benefit to selecting the <code class="docutils literal notranslate"><span class="pre">-GNinja</span></code> generator as it is faster at evaluating what targets to rebuild.
Using an <a class="reference external" href="https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#extra-generators">extra generator</a> will, for example, configure qtcreator files with <a class="reference external" href="https://ninja-build.org/">ninja</a> as the underlying build tool.</p>
</section>
<section id="from-the-command-line">
<h3><a class="toc-backref" href="#id8" role="doc-backlink">From the command line</a><a class="headerlink" href="#from-the-command-line" title="Link to this heading">¶</a></h3>
<ul class="simple">
<li><p>If wanting an out of source build, create the directory you want to build in and <code class="docutils literal notranslate"><span class="pre">cd</span></code> into it. Alternatively, you can specify the build and source directories separately by running <code class="docutils literal notranslate"><span class="pre">cmake</span> <span class="pre">-B</span> <span class="pre">/path/to/build</span> <span class="pre">-S</span> <span class="pre">/path/to/source</span></code>.</p></li>
<li><p>On Windows, you may need to be in a Visual Studio Command Prompt.</p></li>
<li><p>Run <code class="docutils literal notranslate"><span class="pre">cmake</span> <span class="pre">/path/to/Mantid</span></code>, or to <code class="docutils literal notranslate"><span class="pre">/path/to/Mantid/Framework</span></code> if you only want a build of the Framework (typically not recommended, but possible nonetheless). This will generate build files using the default generator for your platform (e.g. Unix Makefiles on Linux).</p></li>
<li><p>If you want to use a specific generator (run <code class="docutils literal notranslate"><span class="pre">cmake</span> <span class="pre">--help</span></code> for a list of available generators for your platform), use the <code class="docutils literal notranslate"><span class="pre">-G</span></code> option, e.g. <code class="docutils literal notranslate"><span class="pre">cmake</span> <span class="pre">-G"NMake</span> <span class="pre">Makefiles"</span> <span class="pre">/path/to/Mantid</span></code>.</p></li>
<li><p>If you want to set the build type (e.g. Release, Debug) you can run cmake with the <code class="docutils literal notranslate"><span class="pre">-i</span></code> option or by passing the argument <code class="docutils literal notranslate"><span class="pre">-DCMAKE_BUILD_TYPE=RelWithDebIfo</span></code> to cmake. The default is Release.</p></li>
<li><p>Please note that the executable is called <code class="docutils literal notranslate"><span class="pre">cmake3</span></code> on Red Hat 7 / CentOS7.</p></li>
<li><p>On Red Hat 7 / CentOS7 mantid uses <a class="reference external" href="https://www.softwarecollections.org/en/scls/rhscl/devtoolset-7/">devtoolset-7</a>. This means that you need to wrap your initial <code class="docutils literal notranslate"><span class="pre">cmake</span></code> command as <code class="docutils literal notranslate"><span class="pre">scl</span> <span class="pre">enable</span> <span class="pre">devtoolset-7</span> <span class="pre">"cmake3</span> <span class="pre">/path/to/source"</span></code>. Following build commands do not need this.</p></li>
</ul>
</section>
<section id="from-the-cmake-gui">
<h3><a class="toc-backref" href="#id9" role="doc-backlink">From the CMake gui</a><a class="headerlink" href="#from-the-cmake-gui" title="Link to this heading">¶</a></h3>
<ul class="simple">
<li><p>The cmake gui is available from, e.g., the Windows Program menu or the command line executable <code class="docutils literal notranslate"><span class="pre">cmake-gui</span></code>.</p></li>
<li><p>Start it and click the “Browse Source” button to point to <code class="docutils literal notranslate"><span class="pre">/path/to/Mantid</span></code>.</p></li>
<li><p>Click “Browse Build” and point to the directory you want to build into - it’s recommended that you create a new directory for this (see above), though it can be the same as the source directory.</p></li>
<li><p>Click “Configure” down near the bottom of the window.</p></li>
<li><p>A new window will appear asking which ‘Generator’ you want to use:</p>
<ul>
<li><p>Linux/Mac developers should choose <code class="docutils literal notranslate"><span class="pre">Ninja</span></code></p></li>
<li><p>Windows developers should choose <code class="docutils literal notranslate"><span class="pre">Visual</span> <span class="pre">Studio</span> <span class="pre">16</span> <span class="pre">2019</span></code> and in the _Optional platform for generator_ box select <code class="docutils literal notranslate"><span class="pre">x64</span></code>. If you see errors related to HDF5 then you have most likely selected the wrong platform.</p></li>
</ul>
</li>
<li><p>Wait a while….</p></li>
<li><p>You will be presented with a list of options in red that can in principle be changed. You probably don’t want to change anything.</p></li>
<li><p>Click “Configure” again and wait….</p></li>
<li><p>Finally, click “Generate”. This will create the build files, e.g. for a Visual Studio build there will be a <code class="docutils literal notranslate"><span class="pre">Mantid.sln</span></code> in the directory you selected as your build directory.</p></li>
</ul>
</section>
<section id="data-files-location">
<h3><a class="toc-backref" href="#id10" role="doc-backlink">Data Files Location</a><a class="headerlink" href="#data-files-location" title="Link to this heading">¶</a></h3>
<p>Mantid used the CMake ExternalData system for managing testing data. See <a class="reference internal" href="DataFilesForTesting.html#datafilesfortesting"><span class="std std-ref">Data Files for Testing</span></a> for further instructions.</p>
</section>
<section id="with-qt-creator">
<h3><a class="toc-backref" href="#id11" role="doc-backlink">With Qt Creator</a><a class="headerlink" href="#with-qt-creator" title="Link to this heading">¶</a></h3>
<p><a class="reference external" href="http://qt.nokia.com/products/developer-tools/">Qt Creator</a> has some really nice features (it’s cross-platform, you can directly open Qt Designer within it, you can highlight a Qt type and go directly to it’s help page, it knows about Qt types when debugging….).
The nice feature in this context is that it has CMake support built in. So you can just open the project by pointing to the main CMakeLists file and then run CMake all within the IDE itself.</p>
</section>
</section>
<section id="building-and-working-with-cmake">
<h2><a class="toc-backref" href="#id12" role="doc-backlink">Building and working with CMake</a><a class="headerlink" href="#building-and-working-with-cmake" title="Link to this heading">¶</a></h2>
<p>Building from IDE:</p>
<ul class="simple">
<li><p>Windows using Visual studio: Use the <code class="docutils literal notranslate"><span class="pre">visual-studio.bat</span></code> generated in the build directory to start the IDE. This sets up the environment correctly.</p></li>
<li><p>Otherwise start your IDE and point to or import the generated solution/project files</p></li>
</ul>
<p>Command line: run <code class="docutils literal notranslate"><span class="pre">make</span></code>, <code class="docutils literal notranslate"><span class="pre">nmake</span></code> or <code class="docutils literal notranslate"><span class="pre">jom</span></code> to build the whole of Mantid (sub-targets are available - run <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">help</span></code> to see them).</p>
<p>Working with CMake:</p>
<ul class="simple">
<li><p>You should typically never have to run CMake manually again (unless you want to create a new, separate build) - it will be run automatically if one of the CMake input files changes.</p></li>
<li><p>It should be rare that you will need to edit the CMake build (<code class="docutils literal notranslate"><span class="pre">CMakeLists.txt</span></code>) files. The most common occurrence will be when you add a new file. This must be added to the corresponding CMakeLists file, e.g. if you add a file to Kernel, edit <code class="docutils literal notranslate"><span class="pre">Mantid/Framework/Kernel/CMakeLists.txt</span></code> to add the source, header and test files to the long lists of filepaths at the top of the file.</p></li>
<li><p>The class maker utility (<a class="reference internal" href="ToolsOverview.html#toolsoverview"><span class="std std-ref">Tools Overview</span></a>) can edit the <code class="docutils literal notranslate"><span class="pre">CMakeList.txt</span></code> for you automatically</p></li>
<li><p>There are similar places in the Qt projects for ui files and files that need moc-ing.</p></li>
<li><p>If you add a new dependency, that will need to be added (this is less straightforward - do ask for help).</p></li>
<li><p>Cache variables can be added via the CMake Gui or by running <code class="docutils literal notranslate"><span class="pre">ccmake</span></code>.</p></li>
</ul>
</section>
<section id="caveats-and-known-issues">
<h2><a class="toc-backref" href="#id13" role="doc-backlink">Caveats and Known Issues</a><a class="headerlink" href="#caveats-and-known-issues" title="Link to this heading">¶</a></h2>
<ul class="simple">
<li><p>For Visual Studio & XCode, the libraries and executable are put into <code class="docutils literal notranslate"><span class="pre">Mantid/bin/Release</span></code>, <code class="docutils literal notranslate"><span class="pre">Debug</span></code>, etc.</p></li>
<li><p>There is a known issue with using source control with Eclipse on an out of source build. Set the cache variable <code class="docutils literal notranslate"><span class="pre">ECLIPSE_CDT4_GENERATE_SOURCE_PROJECT</span></code> to true and CMake will generate a set of ‘dummy’ project files within the source tree so that you can import that project and use it for source control actions.</p></li>
</ul>
</section>
<section id="tips">
<h2><a class="toc-backref" href="#id14" role="doc-backlink">Tips</a><a class="headerlink" href="#tips" title="Link to this heading">¶</a></h2>
<ul class="simple">
<li><p>Running unit test executables directly with the CMake-generated <code class="docutils literal notranslate"><span class="pre">Mantid.properties</span></code> file will lead to a bunch of logging output to the console. You are encouraged to use CTest instead, which suppresses this output automatically. Otherwise, adding the line <code class="docutils literal notranslate"><span class="pre">logging.channels.consoleChannel.class</span> <span class="pre">=</span> <span class="pre">NullChannel</span></code> to your Mantid.user.properties file will turn if off.</p></li>
<li><p>If you have more than one gcc and want to build with a version other than the default (e.g. on RedHat), setting CC & CXX environment variables is one way to make it so.</p></li>
</ul>
</section>
<section id="build-system-customisation-using-cmake-variables">
<h2><a class="toc-backref" href="#id15" role="doc-backlink">Build system customisation using CMake variables</a><a class="headerlink" href="#build-system-customisation-using-cmake-variables" title="Link to this heading">¶</a></h2>
<p>The Mantid CMake build can be configured using several ENABLE_XXX variables, for instance ENABLE_DOCS, ENABLE_WORKBENCH and ENABLE_OPENGL
A full list of these variables, with a description, can be viewed in the CMake GUI after the project has been configured.</p>
<p>Component builds of mantid can be performed using the <cite>MANTID_FRAMEWORK_LIB</cite>, <cite>MANTID_QT_LIB</cite> and <cite>ENABLE_WORKBENCH</cite> cmake variables.
For instance, we can build just the framework element using,</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>cmake<span class="w"> </span><span class="se">\</span>
-DMANTID_FRAMEWORK_LIB<span class="o">=</span>BUILD<span class="w"> </span><span class="se">\</span>
-DMANTID_QT_LIB<span class="o">=</span>OFF<span class="w"> </span><span class="se">\</span>
-DENABLE_WORKBENCH<span class="o">=</span>OFF<span class="w"> </span><span class="se">\</span>
-GNinja<span class="w"> </span><span class="se">\</span>
../
</pre></div>
</div>
<p>and likewise a mantidqt only build with,</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>cmake<span class="w"> </span><span class="se">\</span>
-DMANTID_FRAMEWORK_LIB<span class="o">=</span>SYSTEM<span class="w"> </span><span class="se">\</span>
-DMANTID_QT_LIB<span class="o">=</span>BUILD<span class="w"> </span><span class="se">\</span>
-DENABLE_WORKBENCH<span class="o">=</span>OFF<span class="w"> </span><span class="se">\</span>
-GNinja<span class="w"> </span><span class="se">\</span>
../
</pre></div>
</div>
<p>Specifying <cite>MANTID_FRAMEWORK_LIB=SYSTEM</cite> requires that we have installed the Framework and its cmake config files somewhere on the CMAKE_PREFIX_PATH.
This will enable the framework to be found using <cite>find_package(MantidFramework)</cite>.</p>
</section>
</section>
</div>
</div>
</div>
<footer class="footer">
<div class="container">
<ul class="nav navbar-nav" style=" float: right;">
<li>
<a href="BuildingOnOSX.html" title="Previous Chapter: Building on OS X"><span class="glyphicon glyphicon-chevron-left visible-sm"></span><span class="hidden-sm hidden-tablet">« Building on OS X</span>
</a>
</li>
<li>
<a href="CMakeBestPractices.html" title="Next Chapter: CMake Guidelines"><span class="glyphicon glyphicon-chevron-right visible-sm"></span><span class="hidden-sm hidden-tablet">CMake Guidelines »</span>
</a>
</li>
<li><a href="#">Back to top</a></li>
</ul>
<p>
</p>
</div>
</footer>
</body>
</html>