-
Notifications
You must be signed in to change notification settings - Fork 109
/
INSTALL
486 lines (382 loc) · 20.8 KB
/
INSTALL
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
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
Introduction
============
This document contains instructions for those who intend to build the Coin
library from source and install it on their system.
It does not contain any information about installing binary distributions of
Coin.
We encourage you to use the CMake build configuration in favor of Autotools as
all development efforts are directed to this path. The Autotools build system
is still maintained but at a significantly lower priority.
The Build Environment
=====================
CMake
-----
Coin uses [CMake](https://cmake.org/download) 3.0 or later for the
configuration, building, and installation procedures. This means you need a
build tool and a C/C++ compiler that is supported by CMake.
On Microsoft Windows platforms, you don't need to install the [Cygwin
environment](www.cygwin.com) or something equivalent anymore to get through the
build procedure. CMake will generate native projects for the build tools like
Ninja, Make, XCode, or Microsoft Visual Studio/MSBuild.
Git
---
To get the sources you need a Git client, [Git](https://www.git-scm.com/download),
[Git GUI clients](https://git-scm.com/downloads/guis), or
[TortoiseGit](https://tortoisegit.org/download) are a good choice.
The Git command `git` need to be available at the command line.
Downloading the compressed sources from the
[Releases](https://github.com/coin3d/coin/releases/) section of the project
won't work as the .git directory is not contained in the zip or tar.gz files
and therefore submodules are not be properly populated.
Instead of doing so you need to clone the repository, e.g. calling
`git clone --recurse-submodules https://github.com/coin3d/coin`.
Boost
-----
Boost C++ libraries are needed (at least version 1.45.0 from
[boost](http://www.boost.org)). Up to now Coin only uses the header only
libraries, so downloading and installing the sources without building is
sufficient. Boost binary packages are provided for Windows on
[sourceforge](https://sourceforge.net/projects/boost/files/boost-binaries/). To
find out how the Visual Studio version is related to the internal numbering have
a look at
[Internal_version_numbering](https://en.wikipedia.org/wiki/Microsoft_Visual_C%2B%2B#Internal_version_numbering).
On Linux prebuilt binaries for your distribution should be provided by the
package manager.
Doxygen
-------
As the generation of the Coin documentation is enabled by default,
[Doxygen](http://www.doxygen.nl/download.html) is required.
NSIS
----
If you intend to generate an installation package of the Coin library on
Windows, [NSIS](https://nsis.sourceforge.io/Download) is required.
XQuartz, OpenMotif
------------------
If you intend to build the Coin library on macOS using X11 an appropriate X11
implementation like XQuartz as well as OpenMotif are required. You may install
the packages via homebrew or macports.
Coin build configuration using CMake
====================================
First you need to find out what generators are supported by CMake on your
platform. The command `cmake --help` on the command line provides you an
extensive list of supported generators. We strongly recommend you to specify
the generator explicitly by using CMake's option `-G` as it makes your build
behave deterministic. E.g., when you install an additional development
environment on Windows or a newer CMake version the default compiler for the
platform selected by CMake may change. Without the generator option CMake will
pick up a different compiler by default. Otherwise CMake always uses the
explicitly specified generator.
For additional configuration options not mentioned on the sample command lines
see "CMake configuration options" on this page.
Linux
-----
(1) git clone --recurse-submodules https://github.com/coin3d/coin coin
(2) cmake -Hcoin -Bcoin_build -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX=/usr/local
-DCMAKE_BUILD_TYPE=Release -DCOIN_BUILD_DOCUMENTATION=OFF
(3) cd coin_build
make
(4) make install
(5) cd cpack.d
cpack --config debian.cmake
cpack --config fedora.cmake
or
(1) git clone --recurse-submodules https://github.com/coin3d/coin coin
(2) cmake -Hcoin -Bcoin_build -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX=/usr/local
-DCMAKE_BUILD_TYPE=Release -DCOIN_BUILD_DOCUMENTATION=OFF
(3) cmake --build coin_build --target all --config Release -- -j4
(4) cmake --build coin_build --target install --config Release -- -j4
(5) cd coin_build/cpack.d
cpack --config debian.cmake
cpack --config fedora.cmake
1. Get the sources using Git clone command
2. Configure the build
If you just want a standard installation (or regenerate the Makefiles using
cached options).
You may omit the generator, then the default generator for the platform is used.
CMake will create the build directory if it does not exist.
Coin uses an Out-of-source build mode, i.e. you must not run the cmake command
directly from the source directory. Instead you need to run it from a separate
build directory, e.g. `coin_build`.
On recent CMake versions (3.13 and later) the option `-H` has been superseded
by `-S`. Or, if available, you can edit all options in a GUI like this
`cmake-gui ./coin`
3. Build the Coin library using the default build tool on the platform
Or, alternatively use the CMake build tool mode.
This uses `coin_build` as build directory, builds the target `all` for the
`Release` configuration and passes `-j4` (parallel building with 4 cores) to
the underlying default build tool (the default build tool on Linux is `make`).
4. Install the Coin library using the default build tool on the platform
Or, alternatively again use the CMake build tool mode. This uses `coin_build`
as build directory, builds the target `install` for the `Release` configuration
and passes `-j4` (parallel building with 4 cores) to the underlying default
build tool (the default build tool on Linux is `make`).
5. Build installation packages of the Coin library (optional)
This uses CPack, a packaging tool from the CMake suite. If something does
not work you may need to add the `--verbose --debug` options to the call to
figure out what went wrong or is missing.
6. Finally when you are done remove the build directory
`rm -rf coin_build`
Windows
-------
(1) git clone --recurse-submodules https://github.com/coin3d/coin coin
(2) cmake -Hcoin -Bcoin_build -G "Visual Studio 2015 Win64" -DCMAKE_INSTALL_PREFIX=C:\Coin3D
-DBOOST_ROOT=C:\Data\Boost-1.56.0 -DCOIN_BUILD_DOCUMENTATION=OFF
(3) cmake --build coin_build --target ALL_BUILD --config Release -- /nologo
/verbosity:minimal /maxcpucount
(4) cmake --build coin_build --target INSTALL --config Release -- /nologo
/verbosity:minimal /maxcpucount
(5) cd coin_build/cpack.d
cpack --config windows.cmake
or
(1) git clone --recurse-submodules https://github.com/coin3d/coin coin
(2) cmake -Hcoin -Bcoin_build -G "Visual Studio 2015 Win64" -DCMAKE_INSTALL_PREFIX=C:\Coin3D
-DBOOST_ROOT=C:\Data\Boost-1.56.0 -DCOIN_BUILD_DOCUMENTATION=OFF
(3) MSBuild /p:Configuration=Release /t:ALL_BUILD Coin.sln /nologo
/verbosity:minimal /maxcpucount
(4) MSBuild /p:Configuration=Release /t:INSTALL Coin.sln /nologo
/verbosity:minimal /maxcpucount
(5) cd coin_build/cpack.d
cpack --config windows.cmake
1. Get the sources using Git clone command
2. Configure the build
If you just want a standard installation (or regenerate the build files using
cached options).
You may omit the generator, then the default generator for the platform is used.
CMake will create the build directory if it does not exist.
Coin uses an Out-of-source build mode, i.e. you must not run the cmake command
directly from the source directory. Instead you need to run it from a separate
build directory, e.g. `coin_build`.
On recent CMake versions (3.13 and later) the option `-H` has been superseded
by `-S`. Or, if available, you can edit all options in a GUI like this
`cmake-gui ./coin`
On Windows the Boost root directory need to be explicitly specified as it
could not be found otherwise.
3. Build the Coin library
Open Coin.sln in the build directory from Microsoft Visual Studio. Build the
`ALL_BUILD` project from the Microsoft Visual Studio solution explorer.
Or, alternatively use the CMake build tool mode.
This uses `coin_build` as build directory, builds the target `ALL_BUILD` for
the `Release` configuration and passes `/nologo /verbosity:minimal /maxcpucount`
(parallel building with maximum number of cores available) to the underlying
default build tool (the default build tool on Windows is `MSBuild`).
Or, directly build the Coin library using the default build tool on the
platform from the command line.
4. Install the Coin Library
Build the `INSTALL` project from the Microsoft Visual Studio solution explorer.
Or, alternatively again use the CMake build tool mode.
This uses `coin_build` as build directory, builds the target `INSTALL` for the
`Release` configuration and passes `/nologo /verbosity:minimal /maxcpucount`
(parallel building with maximum number of cores available) to the underlying
default build tool (the default build tool on Windows is `MSBuild`).
Or, install the Coin library using the default build tool on the platform from
the command line.
5. Build NSIS installation packages of the Coin library (optional)
If something does not work you may need to add the `--verbose --debug` options
to the call to figure out what went wrong or is missing.
6. Finally when you are done remove the build directory
`rmdir /s coin_build`
macOS
-----
(1) git clone --recurse-submodules https://github.com/coin3d/coin coin
(2) cmake -Hcoin -Bcoin_build -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX=/Users/name/Coin3D
-DCOIN_BUILD_DOCUMENTATION=OFF -DCOIN_BUILD_MAC_FRAMEWORK=OFF
(3) cd coin_build
make
(4) sudo make install
(5) cd cpack.d
cpack --config darwin-dmg.cmake
cpack --config darwin-pkg.cmake
or
(1) git clone --recurse-submodules https://github.com/coin3d/coin coin
(2) cmake -Hcoin -Bcoin_build -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX=/Users/name/Coin3D
-DCOIN_BUILD_DOCUMENTATION=OFF -DCOIN_BUILD_MAC_FRAMEWORK=OFF
(3) cmake --build coin_build --target all --config Release -- -j4
(4) sudo cmake --build coin_build --target install --config Release -- -j4
(5) cd coin_build/cpack.d
cpack --config darwin-dmg.cmake
cpack --config darwin-pkg.cmake
1. Get the sources using Git clone command
2. Configure the build
If you just want a standard installation (or regenerate the Makefiles using
cached options).
You may omit the generator, then the default generator for the platform is used.
CMake will create the build directory if it does not exist.
Coin uses an Out-of-source build mode, i.e. you must not run the cmake command
directly from the source directory. Instead you need to run it from a separate
build directory, e.g. `coin_build`.
On recent CMake versions (3.13 and later) the option `-H` has been superseded
by `-S`. Or, if available, you can edit all options in a GUI like this
`cmake-gui ./coin`
3. Build the Coin framework using the default build tool on the platform
Or, alternatively use the CMake build tool mode.
This uses `coin_build` as build directory, builds the target `all` for the
`Release` configuration and passes `-j4` (parallel building with 4 cores) to
the underlying default build tool (the default build tool on Linux is `make`).
4. Install the Coin framework using the default build tool on the platform
Or, alternatively again use the CMake build tool mode.
This uses `coin_build` as build directory, builds the target `install` for the
`Release` configuration and passes `-j4` (parallel building with 4 cores) to
the underlying default build tool (the default build tool on Linux is `make`).
As you are like to install into system locations you need to prefix your
command with sudo.
By default the name of the Coin framework is `Inventor`.
5. Build installation packages of the Coin framework (optional)
This uses CPack a packaging tool from the CMake suite.
If something does not work you may need to add the `--verbose --debug`
options to the call to figure out what went wrong or is missing.
6. Finally when you are done remove the build directory
`rm -rf coin_build`
CMake configuration options
===========================
CMAKE_BUILD_TYPE
Probably the most common types are Debug and Release. The Debug build will
append a `d` to the target library name.
CMAKE_INSTALL_PREFIX
Install path prefix, prepended onto install directories. If set to `/tmp` then
the library will install into `/tmp/lib`. When building and installing Coin as
framework on macOS (e.g. add `-DCOIN_BUILD_MAC_FRAMEWORK=OFF` to the cmake call)
you should set it to either `~/Library/Frameworks`, `/Library/Frameworks`,
`/System/Library/Frameworks`, or `/Network/Library/Frameworks`
CMAKE_PREFIX_PATH
Semicolon separated list of directories specifying installation prefixes to be
searched by CMake `find_package`, `find_library`, `find_...` commands. When
CMake searches for config packages, e.g. for `simage` with
`find_package(simage)`, these directories are searched to find
`<PackageName>Config.cmake` or `<packagename>-config.cmake`. This can be used
to specify non standard installation places for required package information,
e.g. `/opt/local/Boost;/opt/local/Qt5` or
`C:\Data\local\Boost;C:\Data\Qt-5.12.0`.
COIN_BUILD_SHARED_LIBS
Build shared library when ON, static when OFF. Default is ON.
COIN_BUILD_DOCUMENTATION
Build HTML documentation on all platforms when ON, as well as man pages on
platforms other than Windows. Default is OFF. The latest version of the
documentation can always be found on the
[Documentation](https://github.com/coin3d/coin/wiki/Documentation) page of
the wiki.
COIN_BUILD_DOCUMENTATION_MAN
Build Coin man pages when ON on platforms other than Windows. Default is OFF.
COIN_BUILD_DOCUMENTATION_QTHELP
Build QtHelp documentation when ON (requires Qt installation
[https://www.qt.io](https://www.qt.io) ) Default is OFF.
COIN_BUILD_DOCUMENTATION_CHM
Build compressed HTML help manual on Windows platform when ON (requires
Microsoft HTML Help Workshop
[download](https://go.microsoft.com/fwlink/?LinkId=14188)). Default is OFF.
COIN_BUILD_INTERNAL_DOCUMENTATION
Depends on `COIN_BUILD_DOCUMENTATION` to be ON. When OFF (the default) only the
documentation regarding the public API will be built, and warnings for
undocumented entities are turned on. When ON the generated documentation will
include internal classes, which can be useful for Coin developers. Since it is
less common to fully document internal entities, warnings for undocumented
entities are turned off.
COIN_BUILD_MAC_FRAMEWORK
Build Coin as framework when ON, as library when OFF. Default is OFF. On
macOS, the default behavior is to install Coin as a framework so you can
compile/link with it by using the compiler option `-framework Inventor`. If
you want to make a plain installation into
`${CMAKE_INSTALL_PREFIX}/{lib,include}` instead, set this option to OFF.
COIN_BUILD_MAC_X11
Link Coin to the X11 implementation of GL when ON, to OpenGL framework when OFF.
Default is OFF. You need to have OpenMotif and XQuartz installed.
COIN_BUILD_TESTS
Build the provided test cases when ON. Default is ON.
HAVE_MULTIPLE_VERSION
Forces the use of versioned paths for includes and documentation when ON, usual
behavior otherwise.
COIN_BUILD_SINGLE_LIB
Build only one library when ON, multiple when OFF. Default is ON for Windows,
OFF for other platforms.
COIN_BUILD_MSVC_MP
Enable build with multiple processes in Visual Studio. Default is ON. (Only
available when using Visual C++ compiler)
BOOST_ROOT
If you placed your Boost installation into a directory that is not known to
CMake you may need to specify `BOOST ROOT` on the CMake command line, e.g.
`-DBOOST_ROOT=/opt/local/boost-1.56.0` on Linux and
`-DBOOST_ROOT=C:\Data\Boost-1.56.0 on Windows`.
GUI-Toolkit (SoQt, SoWin, SoXt, Quarter) build configuration using CMake
========================================================================
Building the GUI toolkits is very similar to the Coin build commands. To build
a GUI toolkit different from SoQt simply replace `soqt` with `sowin`, `soxt` or
`quarter` as well as `SOQT` with `SOWIN`, `SOXT` or `QUARTER` in the build
commands.
Linux
-----
(1) git clone --recurse-submodules https://github.com/coin3d/soqt soqt
(2) cmake -Hsoqt -Bsoqt_build -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release
-DCMAKE_INSTALL_PREFIX=/usr/local -DCMAKE_PREFIX_PATH="/usr/local"
-DSOQT_BUILD_DOCUMENTATION=OFF
(3) cmake --build soqt_build --target all --config Release -- -j4
(4) cmake --build soqt_build --target install --config Release -- -j4
(5) cd cpack.d
cpack --config debian.cmake
cpack --config fedora.cmake
Windows
-------
(1) git clone --recurse-submodules https://github.com/coin3d/soqt soqt
(2) cmake -Hsoqt -Bsoqt_build -G "Visual Studio 2015" -A x64 -DCMAKE_INSTALL_PREFIX=C:\Coin3D
-DCMAKE_PREFIX_PATH="C:\Coin3D;C:\Qt\5.12.1\msvc2015_64"
-DBOOST_ROOT=C:\Data\Boost-1.56.0 -DSOQT_BUILD_DOCUMENTATION=OFF
(3) cmake --build soqt_build --target ALL_BUILD --config Release -- /nologo
/verbosity:minimal /maxcpucount
(4) cmake --build soqt_build --target INSTALL --config Release -- /nologo
/verbosity:minimal /maxcpucount
(5) cd soqt_build/cpack.d
cpack --config windows.cmake
macOS
-----
(1) git clone --recurse-submodules https://github.com/coin3d/soqt soqt
(2) cmake -Hsoqt -Bsoqt_build -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release
-DCMAKE_INSTALL_PREFIX=/Users/name/Coin3D
-DCMAKE_PREFIX_PATH="/Users/name/Coin3D;/usr/local/Cellar/qt/5.12.1"
-DSOQT_BUILD_DOCUMENTATION=OFF -DSOQT_BUILD_MAC_FRAMEWORK=OFF
(3) cmake --build soqt_build --target all --config Release -- -j4
(4) cmake --build soqt_build --target install --config Release -- -j4
(5) cd cpack.d
cpack --config darwin-dmg.cmake
cpack --config darwin-pkg.cmake
macOS and X11
-------------
To use X11 on macOS you need to provide X11/XQuartz and OpenMotif packages and
build Coin with an additional option `-DCOIN_BUILD_MAC_X11=ON`.
(1) git clone --recurse-submodules https://github.com/coin3d/coin coin
(2) cmake -Hcoin -Bcoin_build -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX=/Users/name/Coin3D
-DCOIN_BUILD_DOCUMENTATION=OFF -DCOIN_BUILD_MAC_FRAMEWORK=OFF
(3) cmake --build coin_build --target all --config Release -- -j4
(4) cmake --build coin_build --target install --config Release -- -j4
(1) git clone --recurse-submodules https://github.com/coin3d/soxt soxt
(2) cmake -Hsoxt -Bsoxt_build -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release
-DCMAKE_INSTALL_PREFIX=/Users/name/Coin3D
-DCMAKE_PREFIX_PATH="/Users/name/Coin3D" -DSOQT_BUILD_DOCUMENTATION=OFF
-DSOXT_BUILD_MAC_FRAMEWORK=OFF
(3) cmake --build soxt_build --target all --config Release -- -j4
(4) cmake --build soxt_build --target install --config Release -- -j4
...
Some build tips
===============
CMake caches the build options and uses these as defaults during subsequent
runs. To clear the cache, delete the file CMakeCache.txt or empty the build
directory completely.
If you build both Debug and Release configurations and don't want to make clean
and reconfigure each time something changes, use a separate build directory for
each type.
When Things Fail
================
If you experience configure/build/install problems beyond what can be resolved
by following the instructions in this file and the relevant README files and the
FAQ, you can ask for help on the [mailing
list](https://groups.google.com/group/coin3d-discuss) (subscription is needed
for posting), or you can contact us per [email](coin-support@coin3d.org) for
technical support.
Before asking, check that the subject hasn't been discussed and resolved already
by looking through the coin-discuss mailing list or at the [Coin issue
tracker](https://github.com/coin3d/coin/issues).
If you decide to send us an email about the problem or add an entry to the issue
tracker, you should include all the information that is relevant to the problem
together with your description.
This includes the terminal output from CMake for the compilation that fails or
at least the entire CMake error message.
A description of the build environment you use may also be helpful, e.g. the
compiler suite and versions of libraries and any system customization that may
be relevant to the problem.