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
expleined 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 files. Crucial parts
of the system will be missing if you only have one of them.

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 availabls, 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. However, if
it doesn't find one, it will build its own from sources included with
Radiance.


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 Cygwin or 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)

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