annotate Sphinx/source/faq/compiling.rst @ 1113:a588960a72e5 default tip

spelling
author Alain Mazy <am@orthanc.team>
date Mon, 28 Oct 2024 09:23:08 +0100
parents 1316bc62b5d5
children
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
481
4f076a3b9934 unanswered-forum.rst
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
6 .. toctree::
4f076a3b9934 unanswered-forum.rst
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
7 :hidden:
4f076a3b9934 unanswered-forum.rst
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
8
4f076a3b9934 unanswered-forum.rst
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
9 compiling-old.rst
4f076a3b9934 unanswered-forum.rst
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
10
4f076a3b9934 unanswered-forum.rst
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 360
diff changeset
11
42
a52f1dc48ebc GNU/Linux
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 41
diff changeset
12 Under GNU/Linux
a52f1dc48ebc GNU/Linux
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 41
diff changeset
13 ---------------
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
14
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
15 * Orthanc >= 0.7.1: See the `build instructions
991
1316bc62b5d5 migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 481
diff changeset
16 <https://orthanc.uclouvain.be/hg/orthanc/file/default/LinuxCompilation.txt>`_
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
17 inside the source package.
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
18 * Orthanc <= 0.7.0: See the :ref:`compiling-old`.
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
19
262
3391edf37359 note for packagers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 86
diff changeset
20 **Note for packagers:** As explained :ref:`below on this page
3391edf37359 note for packagers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 86
diff changeset
21 <compiling-infrastructure>`, the CMake scripts of Orthanc and its
3391edf37359 note for packagers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 86
diff changeset
22 associated plugins may have to download the source code of third-party
3391edf37359 note for packagers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 86
diff changeset
23 dependencies. This is an undesirable feature if packaging Orthanc for
3391edf37359 note for packagers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 86
diff changeset
24 some GNU/Linux distribution, as network connections are forbidden in
3391edf37359 note for packagers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 86
diff changeset
25 such situations to enable reproducible builds. To prevent the CMake
3391edf37359 note for packagers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 86
diff changeset
26 scripts to download from Internet, package maintainers can manually
3391edf37359 note for packagers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 86
diff changeset
27 download third-party dependencies by themselves (by checking what is
3391edf37359 note for packagers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 86
diff changeset
28 downloaded by CMake during a fresh build), then put them in a
3391edf37359 note for packagers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 86
diff changeset
29 subfolder named ``ThirdPartyDownloads/`` in the same folder as the
3391edf37359 note for packagers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 86
diff changeset
30 ``CMakeLists.txt`` file of the project. If the third-party packages
3391edf37359 note for packagers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 86
diff changeset
31 are already in that subfolder, the CMake script will not try and
3391edf37359 note for packagers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 86
diff changeset
32 download them from Internet.
3391edf37359 note for packagers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 86
diff changeset
33
3391edf37359 note for packagers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 86
diff changeset
34
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
35 Under Microsoft Windows
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
36 -----------------------
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
37
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
38 See the `build instructions for Windows
991
1316bc62b5d5 migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 481
diff changeset
39 <https://orthanc.uclouvain.be/hg/orthanc/file/default/INSTALL>`_ inside
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
40 the source package.
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 Under OS X
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 mainline of Orthanc can compile under Apple OS X, with the XCode
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
46 compiler, since June 24th, 2014. See the `build instructions for
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
47 Darwin
991
1316bc62b5d5 migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 481
diff changeset
48 <https://orthanc.uclouvain.be/hg/orthanc/file/default/DarwinCompilation.txt>`_
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
49 inside the source package.
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
50
41
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
51 Performance warning
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
52 -------------------
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
53
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
54 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
55 ``-DCMAKE_BUILD_TYPE=Release`` when invoking ``cmake``. Indeed, by
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
56 default, `run-time debug assertions
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
57 <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
58 are enabled, which can seriously impact performance, especially if
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
59 your Orthanc server stores a lot of DICOM instances.
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
60
1c8aaaea72b2 runtime assertions
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 25
diff changeset
61
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
62
262
3391edf37359 note for packagers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 86
diff changeset
63 .. _compiling-infrastructure:
3391edf37359 note for packagers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 86
diff changeset
64
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
65 Please explain the build infrastructure
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
66 ---------------------------------------
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
67
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
68 The build infrastructure of Orthanc is based upon `CMake
25
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 0
diff changeset
69 <https://cmake.org/>`_. The build scripts are designed to embed all
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
70 the third-party dependencies directly inside the Orthanc
42
a52f1dc48ebc GNU/Linux
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 41
diff changeset
71 executable. This is the meaning of the ``-DSTATIC_BUILD=ON`` option,
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
72 as described in the `INSTALL
991
1316bc62b5d5 migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 481
diff changeset
73 <https://orthanc.uclouvain.be/hg/orthanc/file/default/INSTALL>`_ file of Orthanc.
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
74
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
75 Such a static linking is very desirable under Windows, since the
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
76 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
77 straightforward installation procedure (just download the Windows
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
78 binaries and execute them), which eases the setup of the development
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
79 machines (no external library is to be manually installed, everything
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
80 is downloaded during the build configuration), and which avoids the
25
669ea65ba7fb fix links
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 0
diff changeset
81 `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
82 this makes our build infrastructure rather complex.
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 Static linking is not as desirable under GNU/Linux than under
a52f1dc48ebc GNU/Linux
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 41
diff changeset
85 Windows. GNU/Linux prefers software that dynamically links against the
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
86 system-wide libraries: This is explained by the fact that whenever a
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
87 third-party dependency benefits from a bugfix, any software that is
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
88 linked against it also immediately benefits from this fix. This also
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
89 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
90 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
91 option whenever possible.
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
92
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
93 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
94 unavailable or incompatible with Orthanc, depending on your GNU/Linux
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
95 distribution. Some CMake options have thus been introduced to force
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
96 the static linking against some individual third-party
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
97 dependencies. Here are the most useful:
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
98
42
a52f1dc48ebc GNU/Linux
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 41
diff changeset
99 * ``-DUSE_SYSTEM_DCMTK=OFF`` to statically link against DCMTK.
a52f1dc48ebc GNU/Linux
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 41
diff changeset
100 * ``-DUSE_SYSTEM_JSONCPP=OFF`` to statically link against JsonCpp.
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
101
86
329bcab46f5e contributing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 42
diff changeset
102 You will also have to set the ``-DALLOW_DOWNLOADS=ON`` to explicitely
329bcab46f5e contributing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 42
diff changeset
103 allow the CMake script to download the source code of any required
329bcab46f5e contributing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 42
diff changeset
104 dependency. The source code of all these dependencies is self-hosted
329bcab46f5e contributing
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 42
diff changeset
105 on the Web server running our official homepage.
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
106
42
a52f1dc48ebc GNU/Linux
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 41
diff changeset
107 Please also note that the option ``-DSTANDALONE_BUILD=ON`` must be
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
108 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
109 another computer. This option will embed all the external resource
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
110 files (notably Orthanc Explorer) into the resulting executable. If
42
a52f1dc48ebc GNU/Linux
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 41
diff changeset
111 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
112 source directories.
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
113
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
114
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
115 Missing ``uuid-dev`` package
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
116 ----------------------------
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
117
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
118 Orthanc might fail to compile, complaining about missing ``uuid-dev`` package.
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
119
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
120 This problem seems to occur when fist building Orthanc without the
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
121 ``uuid-dev`` package installed, then installing ``uuid-dev``, then
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
122 rebuilding Orthanc. It seems that the build scripts do not update the
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
123 cached variable about the presence of ``uuid-dev``.
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
124
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
125 To solve this problem, `as reported
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
126 <https://groups.google.com/d/msg/orthanc-users/hQYulBBvJvs/S1Pm125o59gJ>`_
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
127 by Peter Somlo, it is necessary to entirely remove the build directory
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
128 (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
129 directory.