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.

  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
community editions are sufficient.
VS 2013 is currently the most recent version that does it correctly.
VS 2015 also performs the build, but it uses the new "universal CRT"
from Windows 10, which has a bug that corrupts data in text pipes.
A fix is apparently ready and should be released via autoupdate,
probably around the time of the "anniversary update" in summer 2016.
Older versions of VS may work as well, but haven't been tested with
the current sources.


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, and proceed to build the
software.


Configuring
-----------

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 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_BINDIR=<directory>
        Install executables here
        (Default read from config file)

RAD_MANDIR=<directory>
        Install man pages here
        (Default read from config file)

RAD_RLIBDIR=<directory>
        Install support files here
        (Default read from config file)

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|14.0
        "12.0" is the default for Visual Studio 2013.
        Once the text pipe bug in the universal CRT is fixed, the default
        will be changed to "14.0" for Visual Studio 2015.

SCons will remember the values given with those options. 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 will use the Radiance binaries in the "ray/bin/" directory, and the
support files in "ray/lib/", where they are located after building but
before installing. 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 etc.). You need to manually
invoke building and testing after each 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
------------

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 in and below the "ray/src/" subdirectory.


Revision:	1.5
Committed:	Tue Apr 19 21:21:23 2016 UTC (8 years ago) by schorsch
Branch:	MAIN
CVS Tags:	rad5R1
Changes since 1.4:	+15 -0 lines
Log Message:	Build with VC2013 until text pipe bug is fixed; prepare for pyinstaller on scripts
#	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
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. On posix
29	systems it usually does. Otherwise the executables requiring it are
30	not built.
31
32	On Windows, Radiance gets built with MS Visual Studio if present, the
33	community editions are sufficient.
34	VS 2013 is currently the most recent version that does it correctly.
35	VS 2015 also performs the build, but it uses the new "universal CRT"
36	from Windows 10, which has a bug that corrupts data in text pipes.
37	A fix is apparently ready and should be released via autoupdate,
38	probably around the time of the "anniversary update" in summer 2016.
39	Older versions of VS may work as well, but haven't been tested with
40	the current sources.
41
42
43	Building
44	--------
45
46	For building Radiance, go to the "ray" directory (where this file
47	resides) in a console window and type:
48
49	$> scons build
50
51	or just
52
53	$> scons
54
55	The Scons program will find the necessary information, display a
56	copyright message for you to acknowledge, and proceed to build the
57	software.
58
59
60	Configuring
61	-----------
62
63	In the subdirectory "ray/platform/" there are a number of configuration
64	files for various build environments. In this context, a "platform" is a
65	specific combination of operating system and build tools (eg. compiler).
66	On unix based systems, the compiler usually doesn't make much of a
67	difference, but on Windows, there are seperate build environments for
68	toolkits like MingW.
69
70	The file "ray/platform/README" explains the settings that can be
71	configured in those files, and how to create a new one, if you use a
72	platform that isn't supported yet.
73
74
75	Options
76	-------
77
78	You can add the following command line options when invoking Scons.
79	The directories given here will override those specified in the
80	configuration file.
81
82	RAD_BINDIR=<directory>
83	Install executables here
84	(Default read from config file)
85
86	RAD_MANDIR=<directory>
87	Install man pages here
88	(Default read from config file)
89
90	RAD_RLIBDIR=<directory>
91	Install support files here
92	(Default read from config file)
93
94	RAD_DEBUG=1\|0
95	1: Build a debug version
96	0: Build a production version (default)
97
98	SKIP=1\|0
99	1: Skip display of License terms
100	0: Don't skip (default)
101
102	MSVC_VERSION=12.0\|14.0
103	"12.0" is the default for Visual Studio 2013.
104	Once the text pipe bug in the universal CRT is fixed, the default
105	will be changed to "14.0" for Visual Studio 2015.
106
107	SCons will remember the values given with those options. You don't need
108	to supply them again each time when you run repeated builds and
109	installs, but only when something changes.
110
111	Invoking SCons with the -H flag will display informtion about many other
112	options, but you won't normally need any of those.
113
114
115	Testing
116	-------
117
118	Radiance comes with a (still very incomplete) test suite, which can be
119	run by invoking
120
121	$> scons test
122
123	This executes a series of tests, each indicating success or failure.
124	Testing will use the Radiance binaries in the "ray/bin/" directory, and the
125	support files in "ray/lib/", where they are located after building but
126	before installing. However, it will not trigger a (re-)build if any of
127	those files are out of date or missing (instead, it will complain about
128	failed tests because of missing executables etc.). You need to manually
129	invoke building and testing after each other to ensure that everything
130	is where it should be.
131
132	Users (that means you!) are invited to contribute more test cases.
133	The goal is that eventually (almost) all Radiance functionality can be
134	tested for compliance with the specification and/or expected results.
135
136	See the file "ray/test/README.txt" for details about the testing framework
137	and instructions on how to contribute test cases.
138
139
140	Installation
141	------------
142
143	The software will be installed into the directories given either in the
144	configuration file or through command options, by invoking
145
146	$> scons install
147
148	To do this you need write permission in the target directories.
149	Any files that are not present or not up to date will be (re-)built
150	before being installed.
151
152	You can install parts of the software by specifying one of three special
153	targets:
154
155	$> scons bininstall # only executable files
156	$> scons rlibinstall # only support files
157	$> scons maninstall # only manual pages
158
159
160	Cleanup
161	-------
162
163	To save disk space on your system, or in preparation of a fresh build
164	with different settings, you can clean up the source tree by invoking
165
166	$> scons -c
167
168	This will delete all the generated object files, libraries, and
169	executables in and below the "ray/src/" subdirectory.
170
171