annotate Sphinx/source/faq/compiling.rst @ 247:325dd3901547

ohif
author Sebastien Jodogne <s.jodogne@gmail.com>
date Sun, 19 May 2019 10:08:52 +0200
parents 329bcab46f5e
children 3391edf37359
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
1 .. _compiling:
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
2
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
3 Compiling Orthanc
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
4 =================
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
5
42
a52f1dc48ebc GNU/Linux
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 41
diff changeset
6 Under GNU/Linux
a52f1dc48ebc GNU/Linux
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 41
diff changeset
7 ---------------
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
8
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
9 * Orthanc >= 0.7.1: See the `build instructions
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
10 <https://bitbucket.org/sjodogne/orthanc/src/default/LinuxCompilation.txt>`_
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
11 inside the source package.
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
12 * Orthanc <= 0.7.0: See the :ref:`compiling-old`.
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
13
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
14 Under Microsoft Windows
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
15 -----------------------
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
16
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
17 See the `build instructions for Windows
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
18 <https://bitbucket.org/sjodogne/orthanc/src/default/INSTALL>`_ inside
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
19 the source package.
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
20
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
21 Under OS X
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
22 ----------
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
23
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
24 The mainline of Orthanc can compile under Apple OS X, with the XCode
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
25 compiler, since June 24th, 2014. See the `build instructions for
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
26 Darwin
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
27 <https://bitbucket.org/sjodogne/orthanc/src/default/DarwinCompilation.txt>`_
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
28 inside the source package.
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
29
41
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
30 Performance warning
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
31 -------------------
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
32
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
33 If performance is important to you, make sure to add the option
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
34 ``-DCMAKE_BUILD_TYPE=Release`` when invoking ``cmake``. Indeed, by
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
35 default, `run-time debug assertions
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
36 <https://en.wikipedia.org/wiki/Assertion_(software_development)#Assertions_for_run-time_checking>`_
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
37 are enabled, which can seriously impact performance, especially if
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
38 your Orthanc server stores a lot of DICOM instances.
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
39
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
40
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
41
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
42 Please explain the build infrastructure
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
43 ---------------------------------------
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
44
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
45 The build infrastructure of Orthanc is based upon `CMake
25
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 0
diff changeset
46 <https://cmake.org/>`_. The build scripts are designed to embed all
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
47 the third-party dependencies directly inside the Orthanc
42
a52f1dc48ebc GNU/Linux
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 41
diff changeset
48 executable. This is the meaning of the ``-DSTATIC_BUILD=ON`` option,
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
49 as described in the `INSTALL
25
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 0
diff changeset
50 <https://bitbucket.org/sjodogne/orthanc/src/default/INSTALL>`_ file of Orthanc.
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
51
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
52 Such a static linking is very desirable under Windows, since the
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
53 Orthanc binaries do not depend on any external DLL, which results in a
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
54 straightforward installation procedure (just download the Windows
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
55 binaries and execute them), which eases the setup of the development
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
56 machines (no external library is to be manually installed, everything
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
57 is downloaded during the build configuration), and which avoids the
25
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 0
diff changeset
58 `DLL hell <https://en.wikipedia.org/wiki/Dll_hell>`_. As a downside,
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
59 this makes our build infrastructure rather complex.
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
60
42
a52f1dc48ebc GNU/Linux
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 41
diff changeset
61 Static linking is not as desirable under GNU/Linux than under
a52f1dc48ebc GNU/Linux
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 41
diff changeset
62 Windows. GNU/Linux prefers software that dynamically links against the
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
63 system-wide libraries: This is explained by the fact that whenever a
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
64 third-party dependency benefits from a bugfix, any software that is
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
65 linked against it also immediately benefits from this fix. This also
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
66 reduces the size of the binaries as well as the build time. Under
42
a52f1dc48ebc GNU/Linux
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 41
diff changeset
67 GNU/Linux, it is thus recommended to use the ``-DSTATIC_BUILD=OFF``
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
68 option whenever possible.
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
69
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
70 When the dynamic build is used, some third-party dependencies may be
42
a52f1dc48ebc GNU/Linux
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 41
diff changeset
71 unavailable or incompatible with Orthanc, depending on your GNU/Linux
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
72 distribution. Some CMake options have thus been introduced to force
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
73 the static linking against some individual third-party
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
74 dependencies. Here are the most useful:
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
75
42
a52f1dc48ebc GNU/Linux
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 41
diff changeset
76 * ``-DUSE_SYSTEM_DCMTK=OFF`` to statically link against DCMTK.
a52f1dc48ebc GNU/Linux
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 41
diff changeset
77 * ``-DUSE_SYSTEM_JSONCPP=OFF`` to statically link against JsonCpp.
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
78
86
329bcab46f5e contributing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 42
diff changeset
79 You will also have to set the ``-DALLOW_DOWNLOADS=ON`` to explicitely
329bcab46f5e contributing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 42
diff changeset
80 allow the CMake script to download the source code of any required
329bcab46f5e contributing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 42
diff changeset
81 dependency. The source code of all these dependencies is self-hosted
329bcab46f5e contributing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 42
diff changeset
82 on the Web server running our official homepage.
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
83
42
a52f1dc48ebc GNU/Linux
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 41
diff changeset
84 Please also note that the option ``-DSTANDALONE_BUILD=ON`` must be
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
85 used whenever your plan to move the binaries or to install them on
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
86 another computer. This option will embed all the external resource
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
87 files (notably Orthanc Explorer) into the resulting executable. If
42
a52f1dc48ebc GNU/Linux
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 41
diff changeset
88 this option is set to ``OFF``, the resources will be read from the
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
89 source directories.
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
90
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
91
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
92 Missing ``uuid-dev`` package
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
93 ----------------------------
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
94
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
95 Orthanc might fail to compile, complaining about missing ``uuid-dev`` package.
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
96
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
97 This problem seems to occur when fist building Orthanc without the
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
98 ``uuid-dev`` package installed, then installing ``uuid-dev``, then
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
99 rebuilding Orthanc. It seems that the build scripts do not update the
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
100 cached variable about the presence of ``uuid-dev``.
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
101
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
102 To solve this problem, `as reported
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
103 <https://groups.google.com/d/msg/orthanc-users/hQYulBBvJvs/S1Pm125o59gJ>`_
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
104 by Peter Somlo, it is necessary to entirely remove the build directory
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
105 (e.g. with ``rm -rf Build``) and start again the build from a fresh
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
106 directory.