1 |
Building and Installing Radiance with SCons |
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). |
7 |
|
8 |
|
9 |
Requirements |
10 |
------------ |
11 |
|
12 |
Please make sure that you have dowloaded and unpacked BOTH the Radiance |
13 |
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 |
|
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 |
|
21 |
Python: http://www.python.org/ |
22 |
SCons: http://www.scons.org/ |
23 |
|
24 |
For many systems, precompiled packages are available, such as Installer |
25 |
files for Windows. Most Linux distributions already come with Python |
26 |
installed and ready to use. |
27 |
|
28 |
SCons *may* use a libtiff already installed on your system. However, if |
29 |
it doesn't find one, it will build its own from sources included with |
30 |
Radiance. |
31 |
|
32 |
|
33 |
Building |
34 |
-------- |
35 |
|
36 |
For building Radiance, go to the "ray" directory (where this file |
37 |
resides) in a console window and type: |
38 |
|
39 |
$> scons build |
40 |
|
41 |
or just |
42 |
|
43 |
$> scons |
44 |
|
45 |
The Scons program will find the necessary information, display a |
46 |
copyright message for you to acknowledge, and proceed to build the |
47 |
software. |
48 |
|
49 |
|
50 |
Configuring |
51 |
----------- |
52 |
|
53 |
In the subdirectory "ray/platform/" there are a number of configuration |
54 |
files for various build environments. In this context, a "platform" is a |
55 |
specific combination of operating system and build tools (eg. compiler). |
56 |
On unix based systems, the compiler usually doesn't make much of a |
57 |
difference, but on Windows, there are seperate build environments for |
58 |
toolkits like Cygwin or MingW. |
59 |
|
60 |
The file "ray/platform/README" explains the settings that can be |
61 |
configured in those files, and how to create a new one, if you use a |
62 |
platform that isn't supported yet. |
63 |
|
64 |
|
65 |
Options |
66 |
------- |
67 |
|
68 |
You can add the following command line options when invoking Scons. |
69 |
The directories given here will override those specified in the |
70 |
configuration file. |
71 |
|
72 |
RAD_BINDIR=<directory> |
73 |
Install executables here |
74 |
(Default read from config file) |
75 |
|
76 |
RAD_MANDIR=<directory> |
77 |
Install man pages here |
78 |
(Default read from config file) |
79 |
|
80 |
RAD_RLIBDIR=<directory> |
81 |
Install support files here |
82 |
(Default read from config file) |
83 |
|
84 |
RAD_DEBUG=1|0 |
85 |
1: Build a debug version |
86 |
0: Build a production version (default) |
87 |
|
88 |
SKIP=1|0 |
89 |
1: Skip display of License terms |
90 |
0: Don't skip (default) |
91 |
|
92 |
SCons will remember the values given with those options. You don't need |
93 |
to supply them again each time when you run repeated builds and |
94 |
installs, but only when something changes. |
95 |
|
96 |
Invoking SCons with the -H flag will display informtion about many other |
97 |
options, but you won't normally need any of those. |
98 |
|
99 |
|
100 |
Testing |
101 |
------- |
102 |
|
103 |
Radiance comes with a (still very incomplete) test suite, which can be |
104 |
run by invoking |
105 |
|
106 |
$> scons test |
107 |
|
108 |
This executes a series of tests, each indicating success or failure. |
109 |
Testing will use the Radiance binaries in the "ray/bin/" directory, and the |
110 |
support files in "ray/lib/", where they are located after building but |
111 |
before installing. However, it will not trigger a (re-)build if any of |
112 |
those files are out of date or missing (instead, it will complain about |
113 |
failed tests because of missing executables etc.). You need to manually |
114 |
invoke building and testing after each other to ensure that everything |
115 |
is where it should be. |
116 |
|
117 |
Users (that means you!) are invited to contribute more test cases. |
118 |
The goal is that eventually (almost) all Radiance functionality can be |
119 |
tested for compliance with the specification and/or expected results. |
120 |
|
121 |
See the file "ray/test/README.txt" for details about the testing framework |
122 |
and instructions on how to contribute test cases. |
123 |
|
124 |
|
125 |
Installation |
126 |
------------ |
127 |
|
128 |
The software will be installed into the directories given either in the |
129 |
configuration file or through command options, by invoking |
130 |
|
131 |
$> scons install |
132 |
|
133 |
To do this you need write permission in the target directories. |
134 |
Any files that are not present or not up to date will be (re-)built |
135 |
before being installed. |
136 |
|
137 |
You can install parts of the software by specifying one of three special |
138 |
targets: |
139 |
|
140 |
$> scons bininstall # only executable files |
141 |
$> scons rlibinstall # only support files |
142 |
$> scons maninstall # only manual pages |
143 |
|
144 |
|
145 |
Cleanup |
146 |
------- |
147 |
|
148 |
To save disk space on your system, or in preparation of a fresh build |
149 |
with different settings, you can clean up the source tree by invoking |
150 |
|
151 |
$> scons -c |
152 |
|
153 |
This will delete all the generated object files, libraries, and |
154 |
executables in and below the "ray/src/" subdirectory. |
155 |
|
156 |
|