ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/radiance/ray/INSTALL.scons
Revision: 1.7
Committed: Tue Jan 9 00:08:57 2018 UTC (6 years, 2 months ago) by schorsch
Branch: MAIN
CVS Tags: rad5R4, rad5R2, rad5R3, HEAD
Changes since 1.6: +5 -0 lines
Log Message:
SCons Option to build Pmap with OOC data on unix

File Contents

# Content
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 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/
26
27 For many systems, precompiled packages are available, such as Installer
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. 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
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 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 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, 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 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
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 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, usually relative to RAD_BASEDIR)
98
99 RAD_MANDIR=<directory>
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, usually relative to RAD_BASEDIR)
106
107 RAD_DEBUG=1|0
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)
114
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
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
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.
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 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
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 $> scons -c
211
212 This will delete all the generated object files, libraries, and
213 executables below the respective "ray/scbuild/<platform>/" subdirectory.
214
215