ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/radiance/INSTALL.scons
(Generate patch)

Comparing INSTALL.scons (file contents):
Revision 1.4 by schorsch, Thu Mar 10 02:06:11 2016 UTC vs.
Revision 1.6 by schorsch, Mon Jan 8 13:38:37 2018 UTC

# Line 2 | Line 2 | 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).
5 > based build system, an alternative to the traditional makeall script
6 > explained in the README file.
7  
8  
9   Requirements
# Line 17 | Line 17 | them, and SCons will be unable to build the software.
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/
# Line 29 | Line 32 | SCons *may* use a libtiff already installed on your sy
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  
# Line 43 | Line 54 | or just
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 MingW.
# Line 69 | Line 88 | You can add the following command line options when in
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 > MSVC_VERSION=12.0|13.0|14.1
116 >   This is only relevant for building with VC on Windows.
117 >   "12.0" for Visual C/C++ 2013.
118 >   "13.0" for Visual C/C++ 2015 (watch out for CRT bug).
119 >   "14.1" for Visual C/C++ 2017 with up-to-date service packs as of
120 >          this writing.
121 >   By default, SCons will select the C/C++ toolset from the most recent
122 >   installed VC version. If it doesn't select the one you want, you can
123 >   supply an invalid value (eg. 'xxx') and it will print out a list
124 >   of the versions that it found to be available.
125  
126 + SCons will remember the values given with those options, for each
127 + platform seperately. You don't need to supply them again each time when
128 + you run repeated builds and installs, but only when something changes.
129 +
130   Invoking SCons with the -H flag will display informtion about many other
131   options, but you won't normally need any of those.
132  
# Line 106 | Line 140 | run by invoking
140   $> scons test
141  
142   This executes a series of tests, each indicating success or failure.
143 < Testing will use the Radiance binaries in the "ray/bin/" directory, and the
144 < support files in "ray/lib/", where they are located after building but
145 < before installing. However, it will not trigger a (re-)build if any of
146 < those files are out of date or missing (instead, it will complain about
147 < failed tests because of missing executables etc.). You need to manually
148 < invoke building and testing after each other to ensure that everything
143 >
144 > Testing via SCons will use the Radiance binaries in the
145 > "ray/scbuild/<platform>/bin" directory, where they are located after
146 > building but before installing, and the support files in "ray/lib/"
147 > or elsewhere in the source tree.
148 > However, it will not trigger a (re-)build if any of those files are out
149 > of date or missing. Instead, it will complain about failed tests because
150 > of missing executables and other files. You need to manually invoke
151 > building and testing runs one after the other to ensure that everything
152   is where it should be.
153  
154   Users (that means you!) are invited to contribute more test cases.
# Line 125 | Line 162 | and instructions on how to contribute test cases.
162   Installation
163   ------------
164  
165 + At the begin of each run, SCons will print the currently configured
166 + installations directories to the console, even when it won't actually
167 + install anything. You can use this to verify that you're about to
168 + install in the right location. If uncertain, just start another build
169 + run (possibly resulting just in a "`build' is up to date." message) while
170 + supplying eg. a new "RAD_BASEDIR=..." parameter to verify the output.
171 + If the path configuration seems botched up, just remove the file
172 + "ray/scbuild/<platform>/install_paths.py" and start from scratch.
173 +
174 + The default installation directory structure is as follows:
175 +  Base:      <>       # default depending on platform
176 +  Binaries:  <>/bin
177 +  Library:   <>/share/lib
178 +  Manpages:  <>/share/man
179 + If you keep this structure, make sure to set the PATH, RAYPATH, and
180 + MANPATH environment variables accordingly.
181 +
182   The software will be installed into the directories given either in the
183   configuration file or through command options, by invoking
184  
# Line 151 | Line 205 | with different settings, you can clean up the source t
205   $> scons -c
206  
207   This will delete all the generated object files, libraries, and
208 < executables in and below the "ray/src/" subdirectory.
208 > executables below the respective "ray/scbuild/<platform>/" subdirectory.
209  
210  

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines