-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathbuild_page.html
163 lines (161 loc) · 14.8 KB
/
build_page.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
<!-- HTML header for doxygen 1.8.11-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.3"/>
<title>MRtrix: The build process</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="stylesheet.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectlogo"><a href=http://www.mrtrix.org><img alt="Logo" src="logo.png"/></a></td>
<td id="projectalign" style="padding-left: 2em;">
<div id="projectname">Developer documentation</div>
<div id="projectbrief">Version 3.0.3-105-gd3941f44</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.3 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search",'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
$(document).ready(function(){initNavTree('build_page.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div><div class="header">
<div class="headertitle"><div class="title">The build process </div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p ><a class="anchor" id="md_src_doc_build"></a></p>
<p >The procedure used to compile the source code is substantially different from that used in most other open-source software. The most common way to compile a software project relies on the <code>make</code> utility, and the presence of one or several <code>Makefiles</code> describing which files are to compiled and linked, and in what order. The process of generating the <code>Makefiles</code> is often facilitated by other utilities such as <code>autoconf</code> & <code>automake</code>. One disadvantage of this approach is that these <code>Makefiles</code> must be updated every time changes are made to the source code that affect the dependencies and the order of compilation.</p>
<p >In MRtrix, building the software relies on a two-stage process implemented in Python. First, the <code>configure</code> script should be executed to set the relevant architecture-specific variables (see <a class="el" href="configure_page.html">The configure script</a> for details). Next, the <code>build</code> script is executed, and is responsible for resolving all inter-dependencies, then compiling and linking all the relevant files in the correct order. This means that any new files added to the source tree will be compiled if needed (according to the rules set out below), without any further action required. In addition, this script is multi-threaded and will use all available CPU cores simultaneously, significantly reducing the time needed to build the software on modern multi-core systems.</p>
<dl class="section note"><dt>Note</dt><dd>on systems with a large number of cores but comparatively small amount of RAM, the multi-threaded build can run out of memory. In these cases, it may be necessary to reduce the number of threads used by the build script by setting the <code>NUMBER_OF_PROCESSORS</code> environment variable before invoking <code>./build</code>.</dd></dl>
<h1><a class="anchor" id="build_process_usage"></a>
Using the MRtrix build process</h1>
<p >The build scripts used to build MRtrix applications are designed to be easy to use, with no input required from the user. This does mean that developers must follow a few fixed rules when writing software for use with MRtrix.</p>
<ul>
<li>To create a new executable, place the correspondingly named source file in the <code>cmd/</code> folder. For example, if a new application called <code>myapp</code> is to be written, write the corresponding code in the <code>cmd/myapp.cpp</code> source file, and the build script will attempt to generate the executable <code>release/bin/myapp</code> from it. You may want to consult the section <a class="el" href="command_howto.html">Creating a new MRtrix command</a> for information on the contents of a command.</li>
<li>The <code>lib/</code> folder should contain only code destined to be included into the MRtrix shared library. This library is intended to provide more generic image access and manipulation routines. Developers should avoid placing more application-specific routines in this folder.</li>
<li>Code designed for specific applications should be placed in the <code>src/</code> folder. The corresponding code will then be linked directly into the executables that make use of these routines, rather than being included into the more general purpose MRtrix shared library.</li>
<li>Non-inlined function and variable definitions should be placed in appropriately named source files (<code>*.cpp</code>), and the corresponding declarations should be placed in a header file with the same name and the appropriate suffix (<code>*.h</code>). This is essential if the build script is to resolve the correct dependencies and link the correct object files together.</li>
<li>MRtrix headers or any header added by the user must be included within quotes, and any system headers within angled brackets. This is critical for the build system to work out the correct dependencies (see <a class="el" href="command_howto.html#include_path">Header search path</a> for details).</li>
</ul>
<h1><a class="anchor" id="configure_section"></a>
The configure script</h1>
<p >The first step required for building the software is to run the <code>configure</code> script, which tailors various parameters to the specific system that it is run on. This includes checking that a compiler is available and behaves as expected, that other required packages are available (such as Eigen), whether the system is a 64-bit machine, etc. It is also possible to create distinct co-existing configurations, for example to compile either release and debug code. For details, see <a class="el" href="configure_page.html">The configure script</a>.</p>
<h1><a class="anchor" id="build_section"></a>
The build script</h1>
<p >This script is responsible for identifying the targets to be built, resolving all their dependencies, compiling all the necessary object files (if they are out of date), and linking them together in the correct order. This is done by first identifying the desired targets, then building a list of their dependencies, and treating these dependencies themselves as targets to be built first. A target can only be built once all its dependencies are satisfied (i.e. all its required dependencies have been built). At this point, the target is built only if one or more of its dependencies is more recent than it is itself (or if it doesn't yet exist). This is done by looking at the timestamps of the relevant files. In this way, the relevant files are regenerated only when and if required.</p>
<p >The following rules are used for each of these steps:</p>
<h4><a class="anchor" id="autotoc_md0"></a>
Identifying targets to be built</h4>
<p >Specific targets can be specified on the command-line, in which case only their minimum required dependencies will be compiled and/or linked. This is useful to check that changes made to a particular file compile without error, without necessarily re-compiling all other associated files. For example: </p><pre class="fragment">$ ./build release/bin/mrconvert
$ ./build lib/mrtrix.o lib/app.o
</pre><p >If no specific targets are given, the default target list will be generated, consisting of all applications found in the <code>cmd/</code> folder. For example, if the file <code>cmd/my_application.cpp</code> exists, then the corresponding target <code>release/bin/my_application</code> will be included in the default target list.</p>
<h4><a class="anchor" id="autotoc_md1"></a>
Special target: <em>clean</em></h4>
<p >The special target <code>clean</code> can be passed to the <code>build</code> script to remove all system-generated files, including all object files (<code>*.o</code>), all executables (i.e. all files in the <code>release/bin/</code> folder), and the MRtrix shared library.</p>
<h4><a class="anchor" id="autotoc_md2"></a>
Resolving dependencies for executables</h4>
<p >A target is assumed to correspond to an executable if it resides in the <code>release/bin/</code> folder (the default target list consists of all executables). The dependencies for an example executable <code>release/bin/myapp</code> are resolved in the following way:</p>
<ol type="1">
<li>the MRtrix library <code>lib/mrtrix-X_Y_Z.so</code> is added to the list</li>
<li>the object file <code>cmd/myapp.o</code> is added to the list</li>
<li>a list of all local headers included in the source file <code>cmd/myapp.cpp</code> is generated. A header is considered local if it is included using inverted commas rather than angled brackets. For example: <div class="fragment"><div class="line"><span class="comment">// By default, the lib/ & src/ folders are included in the include search path</span></div>
<div class="line"><span class="preprocessor">#include "<a class="code" href="mrtrix_8h.html">mrtrix.h</a>"</span> <span class="comment">// the file lib/mrtrix.h exists, and is considered a local header</span></div>
<div class="line"><span class="preprocessor">#include <iostream></span> <span class="comment">// this file is not considered local</span></div>
<div class="ttc" id="amrtrix_8h_html"><div class="ttname"><a href="mrtrix_8h.html">mrtrix.h</a></div></div>
</div><!-- fragment --></li>
<li>if a corresponding source file is found for any of these headers, its corresponding object file is added to the list. For example, if <code>cmd/myapp.cpp</code> includes the header <code>src/histogram.h</code>, and the file <code>src/histogram.cpp</code> exists, the object file <code>src/histogram.o</code> is added to the list of dependencies. Note that object files in the <code>lib/</code> folder are not added to the list of dependencies, since they should already be included in the MRtrix library (see below).</li>
<li>all headers included in any of the local headers or their corresponding source files are also considered in the same way, recursively until no new dependencies are found. For example, the file <code>src/histogram.cpp</code> might also include the header <code>src/min_max.h</code>. Since the source file <code>src/min_max.cpp</code> exists, the corresponding object file <code>src/min_max.o</code> is added to the list.</li>
</ol>
<h4><a class="anchor" id="autotoc_md3"></a>
Resolving dependencies for object files</h4>
<p >A target is considered to be an object file if its suffix corresponds to the expected suffix for an object file (usually <code>*.o</code>). The dependencies for an example object file <code>lib/mycode.o</code> are resolved as follows:</p>
<ol type="1">
<li>the corresponding source file <code>lib/mycode.cpp</code> is added to the list</li>
<li>a list of all local headers included in the source file <code>lib/mycode.cpp</code> is generated.</li>
<li>the list of local headers is expanded by recursively adding all local headers found within the already included local headers, until no new local headers are found.</li>
<li>these headers are all added to the list of dependencies.</li>
</ol>
<h4><a class="anchor" id="autotoc_md4"></a>
Resolving dependencies for the MRtrix library</h4>
<p >The list of dependencies for the MRtrix library is generated by adding the corresponding object file for each source file found in the <code>lib/</code> folder. For example, if the file <code>lib/image/header.cpp</code> is found in the <code>lib/</code> folder, the object file <code>lib/image/header.o</code> is added to the list of dependencies.</p>
<h4><a class="anchor" id="autotoc_md5"></a>
Build rules for each target type</h4>
<ul>
<li><b>executables:</b> dependencies consist of all relevant object files along with the MRtrix library. These are all linked together to form the executable.</li>
<li><b>object files:</b> dependencies consist of a single source code file, along with all the included headers. The source code file is compiled to form the corresponding object file.</li>
<li><b>MRtrix library</b>: dependencies consist of all the object files found in the <code>lib/</code> folder. These are all linked together to form the shared library.</li>
<li><b>source & header files:</b> these have no dependencies, and require no action. </li>
</ul>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated on Mon Jul 4 2022 08:00:07 for MRtrix by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.3 </li>
</ul>
</div>
</body>
</html>