-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathbuildtips.html
270 lines (253 loc) · 9.35 KB
/
buildtips.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
<html>
<head>
<link rel="stylesheet" type="text/css" href="regina.css">
<title>Building Regina on Different Systems</title>
</head>
<body bgcolor="#FFFFFF" text="#000000"
link="#0000EE" vlink="#551A8B" alink="#FF0000">
<h1><a name="contents">Building Regina on Different Systems</a></h1>
<p>
<table class="contentswrapper" cellspacing=0>
<tbody>
<tr><td valign="top">
<table class="contents" cellspacing=0><tbody>
<tr><td><a href="#linux">GNU/Linux</a></td></tr>
<tr><td><a href="#macosx">Mac</a></td></tr>
<tr><td><a href="#windows">Windows</a></td></tr>
<tr><td><a href="#cluster">Cluster environments</a></td></tr>
<tr><td><a href="#highdim">Supporting dimensions 9–15</a></td></tr>
<tr><td><a href="#linking">Compiling Regina into your software</a></td></tr>
<tr><td><a href="index.html">Back to main page ...</a></td></tr>
</tbody></table>
</td></tr>
</tbody>
</table>
</p>
<p>
This page offers tips and tricks for building Regina successfully on
various operating systems.
</p>
<p>
As always, it is
<b>much simpler to download and install a ready-made package</b> if you can.
Check out the
<a href="index.html#download">Regina download tables</a>
and see if your distribution is supported.
</p>
<p>
Please also see the page on <a href="source.html">building from sources</a>,
which lists the system requirements and gives a general overview of the
build process.
</p>
<p>
If these tips do not work for you, please mail the authors
(including your <tt>CMakeCache.txt</tt> if possible) so that we can
update the build scripts (and this page) to reflect systems like yours.
</p>
<h2><a name="linux">GNU/Linux</a></h2>
<p>
Regina can be installed anywhere (it does not
need to live directly beneath <tt>/usr</tt> as in the past).
The default is to install in <tt>/usr/local</tt>, though you can change this
if you like by passing the argument <tt>CMAKE_INSTALL_PREFIX</tt> to cmake:
</p>
<div class="example"><p>
<tt>example$ cmake -DCMAKE_INSTALL_PREFIX=/home/bab/software ..</tt>
</p></div>
<p>
If you run a 64-bit version of linux (the <tt>x86_64</tt> or
<tt>amd64</tt> architectures) and you use an RPM-based distribution
(such as Fedora, Mandriva or SuSE),
you may wish to set <tt>LIB_SUFFIX</tt>:
</p>
<div class="example"><p>
<tt>example$ cmake -DLIB_SUFFIX=64 ..</tt>
</p></div>
<p>
This ensures that Regina's libraries are installed in a 64-bit directory
such as <tt>/usr/local/lib64/</tt>.
</p>
<p>
Debian-based distributions (such as Debian or Ubuntu) do not use special
directory names for 64-bit systems, and you should
<b>not set <tt>LIB_SUFFIX</tt></b> on such machines.
</p>
<h2><a name="macosx">Mac</a></h2>
<p>
The macOS build has evolved to remove the need for
software environments such as
<a href="http://www.macports.org/">MacPorts</a> or
<a href="http://finkproject.org/">Fink</a>
(and indeed,
the macOS binaries here on the Regina website were built on a system
without any such environment installed at all).
The current situation is as follows:
<ul>
<li>To build a standalone app bundle (like the one here on the Regina
website), you will need to build Regina in Xcode. Regina's git source
tree includes a full Xcode project, but this is heavily tailored to the
developer's personal setup and so it may need some work to build on your
machine.
<li>Alternatively, you can have a full unix-like installation (with programs
in <tt>/usr/local/bin/</tt>, libraries in <tt>/usr/local/lib/</tt>
data in <tt>/usr/local/share/regina/</tt> and so on).
<b>This is the much simpler option</b>, and it is supported
out-of-the-box; read on for details.
</ul>
<p>
For a full unix-like installation, assuming you already have
an environment like
<a href="http://www.macports.org/">MacPorts</a> or
<a href="http://finkproject.org/">Fink</a> installed,
you may need to pass additional arguments to cmake:
<ul>
<li>If you wish to use the system python installation (or some other
python installation) instead of MacPorts' or Fink's, set
<tt>Python_EXECUTABLE</tt> to the python interpreter
(e.g., <tt>/usr/bin/python3</tt>).</li>
<li>If you want to change the installation prefix from the
default <tt>/usr/local</tt>, set <tt>CMAKE_INSTALL_PREFIX</tt>.
This controls where the application bundle will appear when you run
<tt>make install</tt>.</li>
<li>If you have downloaded Qt separately (not via MacPorts/Fink), you
need to tell Regina where to find it. Set <tt>CMAKE_PREFIX_PATH</tt> to the
relevant Qt directory containing <tt>include/</tt>, <tt>lib/</tt> and so on.
For a typical Qt installation, this looks something like
<tt>.../Qt/6.4.0/macos</tt>.</li>
<li>You do <b>not</b> need to set <tt>REGINA_INSTALL_TYPE</tt> to <tt>XDG</tt>,
since this is now the default (and indeed the only valid option) on macOS.</li>
</ul>
</p>
<p>
A complete example of a cmake line that uses the Qt and Python from MacPorts,
and installs Regina in the default location <tt>/usr/local/</tt>:
</p>
<div class="example">
<p>
<tt>example$ cmake -DPython_EXECUTABLE=/opt/local/bin/python3.11 ..</tt>
</p>
</div>
<p>
A complete example that uses the system Python and a
prebuilt Qt from the Qt website,
and installs Regina in a custom location beneath the user's home directory:
</p>
<div class="example">
<p>
<tt>example$ cmake -DPython_EXECUTABLE=/usr/bin/python3
-DCMAKE_INSTALL_PREFIX=/Users/bab/software
-DCMAKE_PREFIX_PATH=/Users/bab/Qt/6.4.0/macos
..</tt>
</p>
</div>
<h2><a name="windows">Windows</a></h2>
<p>
Building Regina under Windows is possible but extremely messy.
If you are working with Regina's sources, we highly recommend that
you do this under GNU/Linux or macOS.
</p>
<p>
If you really need to get a Windows build running, please mail the
authors for assistance.
Alternatively, you can look in
<a href="https://github.com/regina-normal/aux/tree/master/packaging/windows">Regina's packaging repository</a>
to get some idea of what the Regina developer has been doing to build
the Windows binaries that you see here on the Regina website.
</p>
<h2><a name="cluster">Cluster environments</a></h2>
<p>
If you plan to use Regina in a high-performance computing environment
such as a university cluster,
you should set <tt>REGINA_INSTALL_TYPE</tt> to <tt>HPC</tt>.
This will disable the graphical user interface, and will ensure that
Regina's python module is installed alongside Regina (and not in
the system python <tt>site-packages</tt> directory).
</p>
<div class="example"><p>
<tt>example$ cmake -DREGINA_INSTALL_TYPE=HPC ..</tt>
</p></div>
<p>
You will almost certainly not have root access
to the cluster, which means you will need to install Regina beneath your
home directory. You do this by creating a top-level install directory
(say <tt>/home/bab/software</tt>) and then passing it as the install prefix
to cmake:
</p>
<div class="example"><p>
<tt>example$ cmake -DREGINA_INSTALL_TYPE=HPC
-DCMAKE_INSTALL_PREFIX=/home/bab/software ..</tt>
</p></div>
<p>
Regina will now install its various components in the subdirectories
<tt>/home/bab/software/bin</tt>,
<tt>/home/bab/software/lib</tt>,
<tt>/home/bab/software/share</tt> and so on.
If you set <tt>REGINA_INSTALL_TYPE=HPC</tt> as described above, Regina
will install its Python module in
<tt>/home/bab/software/lib/regina/python</tt>.
</p>
<p>
You should pass an <b>absolute path</b> as your install prefix
(not <tt>~/software</tt> or <tt>../software</tt>, for instance).
It is best if this is not the directory in which
you unpacked Regina's sources, since otherwise you may find it hard to
untangle sources from binaries later on.
</p>
<h2><a name="highdim">Supporting dimensions 9–15</a></h2>
<p>
Regina's <i>source code</i> supports triangulations of all dimensions
≤ 15.
However, supporting higher dimensions come with some overhead
(particularly for Python users), and so Regina's ready-made packages
and default builds only support dimensions 2–8.
</p>
<p>
If you need support for dimensions 9–15, you can build Regina
yourself with the <tt>HIGHDIM</tt> flag set to <tt>1</tt>. You should
see the effect in the CMake output:
</p>
<div class="example"><p>
<tt>example$ cmake -DHIGHDIM=1 ..<br>
-- The C compiler identification is AppleClang 13.0.0.13000029<br>
...<br>
-- Detecting CXX compile features - done<br>
-- <b>Dimensions 9-15: enabled</b><br>
-- Regina install type: XDG<br>
...</tt>
</p></div>
<h2><a name="linking">Compiling Regina into your software</h2>
<p>
Once Regina is built and installed, you may wish to compile it
into your own C++ programs. The helper script <tt>regina-engine-config</tt>
gives you all of the necessary compiler and linker options for doing this.
You can find this script with the other programs in
<tt><i>prefix</i>/bin</tt>, where <tt><i>prefix</i></tt> is your
installation prefix.
</p>
<p>
To obtain a full set of compiler options:
</p>
<div class="example"><p>
<tt>example$ regina-engine-config --cflags</tt>
</p></div>
<p>
To obtain a full set of linker options:
</p>
<div class="example"><p>
<tt>example$ regina-engine-config --libs</tt>
</p></div>
<p>
You can use this script directly on the command-line (or in your
Makefile). So, for instance, to compile the program <tt>myprog.cpp</tt>
against Regina:
</p>
<div class="example"><p>
<tt>example$ g++ myprog.cpp `regina-engine-config --cflags --libs`
-o myprog</tt>
</p></div>
<p class="return">
<a href="index.html"><img src="regina.svg" alt="Back to main page ..."
border="0" width="32" height="32" align="middle"></a>
<a href="index.html">Back to main page ...</a></p>
</body>
</html>