1 |
schorsch |
1.1 |
Building and Installing Radiance with SCons |
2 |
|
|
------------------------------------------- |
3 |
|
|
|
4 |
|
|
This file describes how to build and install Radiance using the SCons |
5 |
schorsch |
1.6 |
based build system, an alternative to the traditional makeall script |
6 |
|
|
explained in the README file. |
7 |
schorsch |
1.1 |
|
8 |
|
|
|
9 |
|
|
Requirements |
10 |
|
|
------------ |
11 |
|
|
|
12 |
|
|
Please make sure that you have dowloaded and unpacked BOTH the Radiance |
13 |
schorsch |
1.3 |
source package AND the archive with the auxiliary support files. |
14 |
|
|
Crucial parts of the system will be missing if you only have one of |
15 |
|
|
them, and SCons will be unable to build the software. |
16 |
schorsch |
1.1 |
|
17 |
|
|
SCons is a platform-independent software configuration and build system |
18 |
|
|
written in Python. If SCons and Python are not already installed on your |
19 |
|
|
system, then you need to download and install them first. |
20 |
schorsch |
1.6 |
At the time of this writing, all versions of SCons work with Python 2.7. |
21 |
|
|
SCons versions from 3.0 up also work with Python 3.x, even if the |
22 |
|
|
documentation may still say otherwise. |
23 |
schorsch |
1.1 |
|
24 |
|
|
Python: http://www.python.org/ |
25 |
|
|
SCons: http://www.scons.org/ |
26 |
|
|
|
27 |
schorsch |
1.2 |
For many systems, precompiled packages are available, such as Installer |
28 |
schorsch |
1.1 |
files for Windows. Most Linux distributions already come with Python |
29 |
|
|
installed and ready to use. |
30 |
|
|
|
31 |
schorsch |
1.4 |
SCons *may* use a libtiff already installed on your system. On posix |
32 |
|
|
systems it usually does. Otherwise the executables requiring it are |
33 |
|
|
not built. |
34 |
schorsch |
1.1 |
|
35 |
schorsch |
1.5 |
On Windows, Radiance gets built with MS Visual Studio if present, the |
36 |
schorsch |
1.6 |
free (of cost) community editions are sufficient. |
37 |
|
|
Warning: when VS 2015 came out, the new "universal CRT" from Windows 10, |
38 |
|
|
which was used at the time, had a bug that corrupts data in text pipes. |
39 |
|
|
(Technically, the UCRT is now part of the OS instead of the compiler, |
40 |
|
|
so you need to make sure you have a fixed version of the CRT SDK.) |
41 |
|
|
Since VS 2017, the "universal CRT" bug is fixed and everyting works fine. |
42 |
schorsch |
1.5 |
|
43 |
schorsch |
1.1 |
|
44 |
|
|
Building |
45 |
|
|
-------- |
46 |
|
|
|
47 |
|
|
For building Radiance, go to the "ray" directory (where this file |
48 |
|
|
resides) in a console window and type: |
49 |
|
|
|
50 |
|
|
$> scons build |
51 |
|
|
|
52 |
|
|
or just |
53 |
|
|
|
54 |
|
|
$> scons |
55 |
|
|
|
56 |
|
|
The Scons program will find the necessary information, display a |
57 |
schorsch |
1.6 |
copyright message for you to acknowledge (once), and proceed to build |
58 |
|
|
the software. |
59 |
schorsch |
1.1 |
|
60 |
schorsch |
1.6 |
On Windows, the distribution includes a file named "scons.bat", in |
61 |
|
|
case the SCons script is not on the system execution path. You may |
62 |
|
|
need to change this file to point to your actual Python installation. |
63 |
schorsch |
1.1 |
|
64 |
schorsch |
1.6 |
All build products are stored under "ray/scbuild/<platform>/", where |
65 |
|
|
they are then available for testing and installation. |
66 |
|
|
|
67 |
|
|
|
68 |
|
|
Configuration |
69 |
|
|
------------- |
70 |
schorsch |
1.1 |
|
71 |
|
|
In the subdirectory "ray/platform/" there are a number of configuration |
72 |
|
|
files for various build environments. In this context, a "platform" is a |
73 |
schorsch |
1.6 |
specific combination of operating system, Memory model (32 or 64 bit), |
74 |
|
|
and build tools (eg. compiler). |
75 |
schorsch |
1.1 |
On unix based systems, the compiler usually doesn't make much of a |
76 |
|
|
difference, but on Windows, there are seperate build environments for |
77 |
schorsch |
1.4 |
toolkits like MingW. |
78 |
schorsch |
1.1 |
|
79 |
|
|
The file "ray/platform/README" explains the settings that can be |
80 |
|
|
configured in those files, and how to create a new one, if you use a |
81 |
|
|
platform that isn't supported yet. |
82 |
|
|
|
83 |
|
|
|
84 |
|
|
Options |
85 |
|
|
------- |
86 |
|
|
|
87 |
|
|
You can add the following command line options when invoking Scons. |
88 |
|
|
The directories given here will override those specified in the |
89 |
|
|
configuration file. |
90 |
|
|
|
91 |
schorsch |
1.6 |
RAD_BASEDIR=<directory> |
92 |
|
|
The base directory for the installation |
93 |
|
|
(Default read from config file, depending on platform) |
94 |
|
|
|
95 |
schorsch |
1.1 |
RAD_BINDIR=<directory> |
96 |
schorsch |
1.6 |
Install executables here |
97 |
|
|
(Default read from config file, usually relative to RAD_BASEDIR) |
98 |
schorsch |
1.1 |
|
99 |
|
|
RAD_MANDIR=<directory> |
100 |
schorsch |
1.6 |
Install man pages here |
101 |
|
|
(Default read from config file, usually relative to RAD_BASEDIR) |
102 |
schorsch |
1.1 |
|
103 |
|
|
RAD_RLIBDIR=<directory> |
104 |
schorsch |
1.6 |
Install support files here |
105 |
|
|
(Default read from config file, usually relative to RAD_BASEDIR) |
106 |
schorsch |
1.1 |
|
107 |
|
|
RAD_DEBUG=1|0 |
108 |
schorsch |
1.6 |
1: Build a debug version |
109 |
|
|
0: Build a production version (default) |
110 |
schorsch |
1.1 |
|
111 |
|
|
SKIP=1|0 |
112 |
schorsch |
1.6 |
1: Skip display of License terms |
113 |
|
|
0: Don't skip (default) |
114 |
schorsch |
1.1 |
|
115 |
schorsch |
1.7 |
PMAP_OOC=1|0 |
116 |
|
|
This is not yet available on Windows |
117 |
|
|
1: Build Photon-Maps with Out-of-core Octree (default on unix) |
118 |
|
|
0: Build Photon-Maps with In-core KD-Tree (hard set on Windows) |
119 |
|
|
|
120 |
schorsch |
1.6 |
MSVC_VERSION=12.0|13.0|14.1 |
121 |
|
|
This is only relevant for building with VC on Windows. |
122 |
|
|
"12.0" for Visual C/C++ 2013. |
123 |
|
|
"13.0" for Visual C/C++ 2015 (watch out for CRT bug). |
124 |
|
|
"14.1" for Visual C/C++ 2017 with up-to-date service packs as of |
125 |
|
|
this writing. |
126 |
|
|
By default, SCons will select the C/C++ toolset from the most recent |
127 |
|
|
installed VC version. If it doesn't select the one you want, you can |
128 |
|
|
supply an invalid value (eg. 'xxx') and it will print out a list |
129 |
|
|
of the versions that it found to be available. |
130 |
|
|
|
131 |
|
|
SCons will remember the values given with those options, for each |
132 |
|
|
platform seperately. You don't need to supply them again each time when |
133 |
|
|
you run repeated builds and installs, but only when something changes. |
134 |
schorsch |
1.1 |
|
135 |
|
|
Invoking SCons with the -H flag will display informtion about many other |
136 |
|
|
options, but you won't normally need any of those. |
137 |
|
|
|
138 |
|
|
|
139 |
|
|
Testing |
140 |
|
|
------- |
141 |
|
|
|
142 |
|
|
Radiance comes with a (still very incomplete) test suite, which can be |
143 |
|
|
run by invoking |
144 |
|
|
|
145 |
|
|
$> scons test |
146 |
|
|
|
147 |
|
|
This executes a series of tests, each indicating success or failure. |
148 |
schorsch |
1.6 |
|
149 |
|
|
Testing via SCons will use the Radiance binaries in the |
150 |
|
|
"ray/scbuild/<platform>/bin" directory, where they are located after |
151 |
|
|
building but before installing, and the support files in "ray/lib/" |
152 |
|
|
or elsewhere in the source tree. |
153 |
|
|
However, it will not trigger a (re-)build if any of those files are out |
154 |
|
|
of date or missing. Instead, it will complain about failed tests because |
155 |
|
|
of missing executables and other files. You need to manually invoke |
156 |
|
|
building and testing runs one after the other to ensure that everything |
157 |
schorsch |
1.1 |
is where it should be. |
158 |
|
|
|
159 |
|
|
Users (that means you!) are invited to contribute more test cases. |
160 |
|
|
The goal is that eventually (almost) all Radiance functionality can be |
161 |
|
|
tested for compliance with the specification and/or expected results. |
162 |
|
|
|
163 |
|
|
See the file "ray/test/README.txt" for details about the testing framework |
164 |
|
|
and instructions on how to contribute test cases. |
165 |
|
|
|
166 |
|
|
|
167 |
|
|
Installation |
168 |
|
|
------------ |
169 |
|
|
|
170 |
schorsch |
1.6 |
At the begin of each run, SCons will print the currently configured |
171 |
|
|
installations directories to the console, even when it won't actually |
172 |
|
|
install anything. You can use this to verify that you're about to |
173 |
|
|
install in the right location. If uncertain, just start another build |
174 |
|
|
run (possibly resulting just in a "`build' is up to date." message) while |
175 |
|
|
supplying eg. a new "RAD_BASEDIR=..." parameter to verify the output. |
176 |
|
|
If the path configuration seems botched up, just remove the file |
177 |
|
|
"ray/scbuild/<platform>/install_paths.py" and start from scratch. |
178 |
|
|
|
179 |
|
|
The default installation directory structure is as follows: |
180 |
|
|
Base: <> # default depending on platform |
181 |
|
|
Binaries: <>/bin |
182 |
|
|
Library: <>/share/lib |
183 |
|
|
Manpages: <>/share/man |
184 |
|
|
If you keep this structure, make sure to set the PATH, RAYPATH, and |
185 |
|
|
MANPATH environment variables accordingly. |
186 |
|
|
|
187 |
schorsch |
1.1 |
The software will be installed into the directories given either in the |
188 |
schorsch |
1.2 |
configuration file or through command options, by invoking |
189 |
schorsch |
1.1 |
|
190 |
|
|
$> scons install |
191 |
|
|
|
192 |
|
|
To do this you need write permission in the target directories. |
193 |
|
|
Any files that are not present or not up to date will be (re-)built |
194 |
|
|
before being installed. |
195 |
|
|
|
196 |
|
|
You can install parts of the software by specifying one of three special |
197 |
|
|
targets: |
198 |
|
|
|
199 |
|
|
$> scons bininstall # only executable files |
200 |
|
|
$> scons rlibinstall # only support files |
201 |
|
|
$> scons maninstall # only manual pages |
202 |
|
|
|
203 |
|
|
|
204 |
|
|
Cleanup |
205 |
|
|
------- |
206 |
|
|
|
207 |
|
|
To save disk space on your system, or in preparation of a fresh build |
208 |
|
|
with different settings, you can clean up the source tree by invoking |
209 |
|
|
|
210 |
schorsch |
1.2 |
$> scons -c |
211 |
schorsch |
1.1 |
|
212 |
|
|
This will delete all the generated object files, libraries, and |
213 |
schorsch |
1.6 |
executables below the respective "ray/scbuild/<platform>/" subdirectory. |
214 |
schorsch |
1.1 |
|
215 |
|
|
|