| 2 |
|
------------------------------------------- |
| 3 |
|
|
| 4 |
|
This file describes how to build and install Radiance using the SCons |
| 5 |
< |
based build system (an alternative to the traditional makeall script |
| 6 |
< |
explained in the README file). |
| 5 |
> |
based build system, an alternative to the traditional makeall script |
| 6 |
> |
explained in the README file. |
| 7 |
|
|
| 8 |
|
|
| 9 |
|
Requirements |
| 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 |
+ |
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 |
|
|
| 24 |
|
Python: http://www.python.org/ |
| 25 |
|
SCons: http://www.scons.org/ |
| 28 |
|
files for Windows. Most Linux distributions already come with Python |
| 29 |
|
installed and ready to use. |
| 30 |
|
|
| 31 |
< |
SCons *may* use a libtiff already installed on your system. However, if |
| 32 |
< |
it doesn't find one, it will build its own from sources included with |
| 33 |
< |
Radiance. |
| 31 |
> |
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 |
|
|
| 35 |
+ |
On Windows, Radiance gets built with MS Visual Studio if present, the |
| 36 |
+ |
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 |
|
|
| 43 |
+ |
|
| 44 |
|
Building |
| 45 |
|
-------- |
| 46 |
|
|
| 54 |
|
$> scons |
| 55 |
|
|
| 56 |
|
The Scons program will find the necessary information, display a |
| 57 |
< |
copyright message for you to acknowledge, and proceed to build the |
| 58 |
< |
software. |
| 57 |
> |
copyright message for you to acknowledge (once), and proceed to build |
| 58 |
> |
the software. |
| 59 |
|
|
| 60 |
+ |
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 |
|
|
| 64 |
< |
Configuring |
| 65 |
< |
----------- |
| 64 |
> |
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 |
+ |
|
| 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 |
< |
specific combination of operating system and build tools (eg. compiler). |
| 73 |
> |
specific combination of operating system, Memory model (32 or 64 bit), |
| 74 |
> |
and build tools (eg. compiler). |
| 75 |
|
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 |
< |
toolkits like Cygwin or MingW. |
| 77 |
> |
toolkits like MingW. |
| 78 |
|
|
| 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 |
| 88 |
|
The directories given here will override those specified in the |
| 89 |
|
configuration file. |
| 90 |
|
|
| 91 |
+ |
RAD_BASEDIR=<directory> |
| 92 |
+ |
The base directory for the installation |
| 93 |
+ |
(Default read from config file, depending on platform) |
| 94 |
+ |
|
| 95 |
|
RAD_BINDIR=<directory> |
| 96 |
< |
Install executables here |
| 97 |
< |
(Default read from config file) |
| 96 |
> |
Install executables here |
| 97 |
> |
(Default read from config file, usually relative to RAD_BASEDIR) |
| 98 |
|
|
| 99 |
|
RAD_MANDIR=<directory> |
| 100 |
< |
Install man pages here |
| 101 |
< |
(Default read from config file) |
| 100 |
> |
Install man pages here |
| 101 |
> |
(Default read from config file, usually relative to RAD_BASEDIR) |
| 102 |
|
|
| 103 |
|
RAD_RLIBDIR=<directory> |
| 104 |
< |
Install support files here |
| 105 |
< |
(Default read from config file) |
| 104 |
> |
Install support files here |
| 105 |
> |
(Default read from config file, usually relative to RAD_BASEDIR) |
| 106 |
|
|
| 107 |
|
RAD_DEBUG=1|0 |
| 108 |
< |
1: Build a debug version |
| 109 |
< |
0: Build a production version (default) |
| 108 |
> |
1: Build a debug version |
| 109 |
> |
0: Build a production version (default) |
| 110 |
|
|
| 111 |
|
SKIP=1|0 |
| 112 |
< |
1: Skip display of License terms |
| 113 |
< |
0: Don't skip (default) |
| 112 |
> |
1: Skip display of License terms |
| 113 |
> |
0: Don't skip (default) |
| 114 |
|
|
| 115 |
< |
SCons will remember the values given with those options. You don't need |
| 116 |
< |
to supply them again each time when you run repeated builds and |
| 117 |
< |
installs, but only when something changes. |
| 115 |
> |
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 |
+ |
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 |
+ |
|
| 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 |
|
|
| 145 |
|
$> scons test |
| 146 |
|
|
| 147 |
|
This executes a series of tests, each indicating success or failure. |
| 148 |
< |
Testing will use the Radiance binaries in the "ray/bin/" directory, and the |
| 149 |
< |
support files in "ray/lib/", where they are located after building but |
| 150 |
< |
before installing. However, it will not trigger a (re-)build if any of |
| 151 |
< |
those files are out of date or missing (instead, it will complain about |
| 152 |
< |
failed tests because of missing executables etc.). You need to manually |
| 153 |
< |
invoke building and testing after each other to ensure that everything |
| 148 |
> |
|
| 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 |
|
is where it should be. |
| 158 |
|
|
| 159 |
|
Users (that means you!) are invited to contribute more test cases. |
| 167 |
|
Installation |
| 168 |
|
------------ |
| 169 |
|
|
| 170 |
+ |
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 |
|
The software will be installed into the directories given either in the |
| 188 |
|
configuration file or through command options, by invoking |
| 189 |
|
|
| 210 |
|
$> scons -c |
| 211 |
|
|
| 212 |
|
This will delete all the generated object files, libraries, and |
| 213 |
< |
executables in and below the "ray/src/" subdirectory. |
| 213 |
> |
executables below the respective "ray/scbuild/<platform>/" subdirectory. |
| 214 |
|
|
| 215 |
|
|
