Update scons to 2.3.1
[scons.git] / scons-README
1 # Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 The SCons Foundation
2
3                  SCons - a software construction tool
4
5 This is the scons-README file for a version of SCons packaged for local
6 execution--that is, execution out of a specific local directory, without
7 having to install SCons as a system-wide utility.
8
9 You are likely reading this file in one of the following two situations:
10
11     1)  You have unpacked an scons-local-{version} package and are
12         examining the contents.
13
14         In this case, you are presumably interested in using this
15         package to include a local copy of SCons with some other
16         software that you package, so that you can use SCons to build
17         your software without forcing all of your users to have it fully
18         installed.  Instructions for this can be found below.
19
20         If you are not looking to use SCons in this way, then please
21         use either the scons-{version} package to install SCons on your
22         system, or the scons-src-{version} package if you want the full
23         source to SCons, including its packaging code and underlying
24         tests and testing infrastructure.
25
26     2)  This file was included in some other software package so that
27         the package could be built using SCons.
28
29         In this case, follow the instructions provided with the
30         rest of the software package for how to use SCons to build
31         and/or install the software.  The file containing build and
32         installation instructions will typically be named README or
33         INSTALL.
34
35 LATEST VERSION
36 ==============
37
38 Before going further, you can check for the latest version of the
39 scons-local package, or any SCons package, at the SCons download page:
40
41         http://www.scons.org/download.html
42
43
44 EXECUTION REQUIREMENTS
45 ======================
46
47 Running SCons requires Python version 1.5.2 or later.  There should be
48 no other dependencies or requirements to run SCons.
49
50 The default SCons configuration assumes use of the Microsoft Visual C++
51 compiler suite on WIN32 systems, and assumes a C compiler named 'cc',
52 a C++ compiler named 'c++', and a Fortran compiler named 'g77' (such
53 as found in the GNU C compiler suite) on any other type of system.
54 You may, of course, override these default values by appropriate
55 configuration of Environment construction variables.
56
57
58 INSTALLATION
59 ============
60
61 Installation of this package should be as simple as unpacking the
62 archive (either .tar.gz or .zip) in any directory (top-level or a
63 subdirectory) within the software package with which you want to ship
64 SCons.
65
66 Once you have installed this package, you should write an SConstruct
67 file at the top level of your source tree to build your software as you
68 see fit.
69
70 Then modify the build/install instructions for your package to instruct
71 your users to execute SCons as follows (if you installed this package in
72 your top-level directory):
73
74         $ python scons.py
75
76 Or (if, for example, you installed this package in a subdirectory named
77 "scons"):
78
79         $ python scons/scons.py
80
81 That should be all you have to do.  (If it isn't that simple, please let
82 us know!)
83
84
85 CONTENTS OF THIS PACKAGE
86 ========================
87
88 This scons-local package consists of the following:
89
90 scons-LICENSE
91         A copy of the copyright and terms under which SCons is
92         distributed (the Open Source Initiative-approved MIT license).
93
94         A disclaimer has been added to the beginning to make clear that
95         this license applies only to SCons, and not to any separate
96         software you've written with which you're planning to package
97         SCons.
98
99 scons-README
100         What you're looking at right now.
101
102 scons-local-{version}/
103         The SCons build engine.  This is structured as a Python
104         library.
105
106 scons.py
107         The SCons script itself.  The script sets up the Python
108         sys.path variable to use the build engine found in the
109         scons-local-{version}/ directory in preference to any other
110         SCons build engine installed on your system.
111
112
113 DOCUMENTATION
114 =============
115
116 Because this package is intended to be included with other software by
117 experienced users, we have not included any SCons documentation in this
118 package (other than this scons-README file you're reading right now).
119
120 If, however, you need documentation about SCons, then consult any of the
121 following from the corresponding scons-{version} or scons-src-{version}
122 package:
123
124         The RELEASE.txt file (src/RELEASE.txt file in the
125         scons-src-{version} package), which contains notes about this
126         specific release, including known problems.
127
128         The CHANGES.txt file (src/CHANGES.txt file in the
129         scons-src-{version} package), which contains a list of changes
130         since the previous release.
131
132         The scons.1 man page (doc/man/scons.1 in the scons-src-{version}
133         package), which contains a section of small examples for getting
134         started using SCons.
135
136 Additional documentation for SCons is available at:
137
138         http://www.scons.org/doc.html
139
140
141 LICENSING
142 =========
143
144 SCons is distributed under the MIT license, a full copy of which is
145 available in the scons-LICENSE file in this package. The MIT license is
146 an approved Open Source license, which means:
147
148         This software is OSI Certified Open Source Software.  OSI
149         Certified is a certification mark of the Open Source Initiative.
150
151 More information about OSI certifications and Open Source software is
152 available at:
153
154         http://www.opensource.org/
155
156
157 REPORTING BUGS
158 ==============
159
160 You can report bugs either by following the "Tracker - Bugs" link
161 on the SCons project page:
162
163         http://sourceforge.net/projects/scons/
164
165 or by sending mail to the SCons developers mailing list:
166
167         scons-devel@lists.sourceforge.net
168
169
170 MAILING LISTS
171 =============
172
173 A mailing list for users of SCons is available.  You may send questions
174 or comments to the list at:
175
176         scons-users@lists.sourceforge.net
177
178 You may subscribe to the scons-users mailing list at:
179
180         http://lists.sourceforge.net/lists/listinfo/scons-users
181
182
183 FOR MORE INFORMATION
184 ====================
185
186 Check the SCons web site at:
187
188         http://www.scons.org/
189
190
191 AUTHOR INFO
192 ===========
193
194 Steven Knight
195 knight at baldmt dot com
196 http://www.baldmt.com/~knight/
197
198 With plenty of help from the SCons Development team:
199         Chad Austin
200         Charles Crain
201         Steve Leblanc
202         Anthony Roach
203         Terrel Shumway
204