viewcvs.cgi/ray/INSTALL.scons

Building and Installing Radiance with SCons
-------------------------------------------

This file describes how to build and install Radiance using the SCons
based build system, an alternative to the traditional makeall script
explained in the README file.


Requirements
------------

Please make sure that you have dowloaded and unpacked BOTH the Radiance
source package AND the archive with the auxiliary support files.
Crucial parts of the system will be missing if you only have one of
them, and SCons will be unable to build the software.

SCons is a platform-independent software configuration and build system
written in Python. If SCons and Python are not already installed on your
system, then you need to download and install them first.
At the time of this writing, all versions of SCons work with Python 2.7.
SCons versions from 3.0 up also work with Python 3.x, even if the
documentation may still say otherwise.

  Python:  http://www.python.org/
  SCons:   http://www.scons.org/

For many systems, precompiled packages are available, such as Installer
files for Windows. Most Linux distributions already come with Python
installed and ready to use.

SCons *may* use a libtiff already installed on your system. On posix
systems it usually does. Otherwise the executables requiring it are
not built.

On Windows, Radiance gets built with MS Visual Studio if present, the
free (of cost) community editions are sufficient.
Warning: when VS 2015 came out, the new "universal CRT" from Windows 10,
which was used at the time, had a bug that corrupts data in text pipes.
(Technically, the UCRT is now part of the OS instead of the compiler, 
so you need to make sure you have a fixed version of the CRT SDK.)
Since VS 2017, the "universal CRT" bug is fixed and everyting works fine.


Building
--------

For building Radiance, go to the "ray" directory (where this file
resides) in a console window and type:

 $> scons build

or just

 $> scons

The Scons program will find the necessary information, display a
copyright message for you to acknowledge (once), and proceed to build
the software.

On Windows, the distribution includes a file named "scons.bat", in
case the SCons script is not on the system execution path. You may
need to change this file to point to your actual Python installation.

All build products are stored under "ray/scbuild/<platform>/", where
they are then available for testing and installation.


Configuration
-------------

In the subdirectory "ray/platform/" there are a number of configuration
files for various build environments. In this context, a "platform" is a
specific combination of operating system, Memory model (32 or 64 bit),
and build tools (eg. compiler).
On unix based systems, the compiler usually doesn't make much of a
difference, but on Windows, there are seperate build environments for
toolkits like MingW.

The file "ray/platform/README" explains the settings that can be
configured in those files, and how to create a new one, if you use a
platform that isn't supported yet.


Options
-------

You can add the following command line options when invoking Scons.
The directories given here will override those specified in the
configuration file.

RAD_BASEDIR=<directory>
   The base directory for the installation
   (Default read from config file, depending on platform)

RAD_BINDIR=<directory>
   Install executables here
   (Default read from config file, usually relative to RAD_BASEDIR)

RAD_MANDIR=<directory>
   Install man pages here
   (Default read from config file, usually relative to RAD_BASEDIR)

RAD_RLIBDIR=<directory>
   Install support files here
   (Default read from config file, usually relative to RAD_BASEDIR)

RAD_DEBUG=1|0
   1: Build a debug version
   0: Build a production version (default)

SKIP=1|0
   1: Skip display of License terms
   0: Don't skip (default)

MSVC_VERSION=12.0|13.0|14.1
   This is only relevant for building with VC on Windows.
   "12.0" for Visual C/C++ 2013.
   "13.0" for Visual C/C++ 2015 (watch out for CRT bug).
   "14.1" for Visual C/C++ 2017 with up-to-date service packs as of
          this writing.
   By default, SCons will select the C/C++ toolset from the most recent
   installed VC version. If it doesn't select the one you want, you can
   supply an invalid value (eg. 'xxx') and it will print out a list
   of the versions that it found to be available.

SCons will remember the values given with those options, for each
platform seperately. You don't need to supply them again each time when
you run repeated builds and installs, but only when something changes.

Invoking SCons with the -H flag will display informtion about many other
options, but you won't normally need any of those.


Testing
-------

Radiance comes with a (still very incomplete) test suite, which can be
run by invoking

 $> scons test

This executes a series of tests, each indicating success or failure.

Testing via SCons will use the Radiance binaries in the
"ray/scbuild/<platform>/bin" directory, where they are located after
building but before installing, and the support files in "ray/lib/"
or elsewhere in the source tree.
However, it will not trigger a (re-)build if any of those files are out
of date or missing. Instead, it will complain about failed tests because
of missing executables and other files. You need to manually invoke
building and testing runs one after the other to ensure that everything
is where it should be.

Users (that means you!) are invited to contribute more test cases.
The goal is that eventually (almost) all Radiance functionality can be
tested for compliance with the specification and/or expected results.

See the file "ray/test/README.txt" for details about the testing framework
and instructions on how to contribute test cases.


Installation
------------

At the begin of each run, SCons will print the currently configured
installations directories to the console, even when it won't actually
install anything. You can use this to verify that you're about to
install in the right location. If uncertain, just start another build
run (possibly resulting just in a "`build' is up to date." message) while
supplying eg. a new "RAD_BASEDIR=..." parameter to verify the output.
If the path configuration seems botched up, just remove the file
"ray/scbuild/<platform>/install_paths.py" and start from scratch.

The default installation directory structure is as follows:
  Base:      <>       # default depending on platform
  Binaries:  <>/bin
  Library:   <>/share/lib
  Manpages:  <>/share/man
If you keep this structure, make sure to set the PATH, RAYPATH, and
MANPATH environment variables accordingly.

The software will be installed into the directories given either in the
configuration file or through command options, by invoking

 $> scons install

To do this you need write permission in the target directories.
Any files that are not present or not up to date will be (re-)built
before being installed.

You can install parts of the software by specifying one of three special
targets:

 $> scons bininstall   # only executable files
 $> scons rlibinstall  # only support files
 $> scons maninstall   # only manual pages


Cleanup
-------

To save disk space on your system, or in preparation of a fresh build
with different settings, you can clean up the source tree by invoking

 $> scons -c

This will delete all the generated object files, libraries, and
executables below the respective "ray/scbuild/<platform>/" subdirectory.


Revision:	1.6
Committed:	Mon Jan 8 13:38:37 2018 UTC (6 years, 3 months ago) by schorsch
Branch:	MAIN
Changes since 1.5:	+79 -40 lines
Log Message:	Updating to SCons 3.x, adding support for Python 3
#	User	Rev	Content
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.6	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	schorsch	1.1
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
133
134			Testing
135			-------
136
137			Radiance comes with a (still very incomplete) test suite, which can be
138			run by invoking
139
140			$> scons test
141
142			This executes a series of tests, each indicating success or failure.
143	schorsch	1.6
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	schorsch	1.1	is where it should be.
153
154			Users (that means you!) are invited to contribute more test cases.
155			The goal is that eventually (almost) all Radiance functionality can be
156			tested for compliance with the specification and/or expected results.
157
158			See the file "ray/test/README.txt" for details about the testing framework
159			and instructions on how to contribute test cases.
160
161
162			Installation
163			------------
164
165	schorsch	1.6	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	schorsch	1.1	The software will be installed into the directories given either in the
183	schorsch	1.2	configuration file or through command options, by invoking
184	schorsch	1.1
185			$> scons install
186
187			To do this you need write permission in the target directories.
188			Any files that are not present or not up to date will be (re-)built
189			before being installed.
190
191			You can install parts of the software by specifying one of three special
192			targets:
193
194			$> scons bininstall # only executable files
195			$> scons rlibinstall # only support files
196			$> scons maninstall # only manual pages
197
198
199			Cleanup
200			-------
201
202			To save disk space on your system, or in preparation of a fresh build
203			with different settings, you can clean up the source tree by invoking
204
205	schorsch	1.2	$> scons -c
206	schorsch	1.1
207			This will delete all the generated object files, libraries, and
208	schorsch	1.6	executables below the respective "ray/scbuild/<platform>/" subdirectory.
209	schorsch	1.1
210