README-local

   1
   2                  SCons - a software construction tool
   3
   4 This is the scons-README file for a version of SCons packaged for local
   5 execution--that is, execution out of a specific local directory, without
   6 having to install SCons as a system-wide utility.
   7
   8 You are likely reading this file in one of the following two situations:
   9
  10     1)  You have unpacked an scons-local-{version} package and are
  11         examining the contents.
  12
  13         In this case, you are presumably interested in using this
  14         package to include a local copy of SCons with some other
  15         software that you package, so that you can use SCons to build
  16         your software without forcing all of your users to have it fully
  17         installed.  Instructions for this can be found below.
  18
  19         If you are not looking to use SCons in this way, then please
  20         use either the scons-{version} package to install SCons on your
  21         system, or the scons-src-{version} package if you want the full
  22         source to SCons, including its packaging code and underlying
  23         tests and testing infrastructure.
  24
  25     2)  This file was included in some other software package so that
  26         the package could be built using SCons.
  27
  28         In this case, follow the instructions provided with the
  29         rest of the software package for how to use SCons to build
  30         and/or install the software.  The file containing build and
  31         installation instructions will typically be named README or
  32         INSTALL.
  33
  34 LATEST VERSION
  35 ==============
  36
  37 Before going further, you can check for the latest version of the
  38 scons-local package, or any SCons package, at the SCons download page:
  39
  40         https://scons.org/pages/download.html
  41
  42
  43 EXECUTION REQUIREMENTS
  44 ======================
  45
  46 Running SCons requires Python 3.6 or higher. There should be no other
  47 dependencies or requirements to run standard SCons.
  48 The last release to support Python 3.5 was 4.2.0.
  49
  50 The default SCons configuration assumes use of the Microsoft Visual C++
  51 compiler suite on WIN32 systems (either through the Visual Studio
  52 product, or through the separate Build Tools), and assumes a C compiler
  53 named 'cc', a C++ compiler named 'c++', and a Fortran compiler named 'g77'
  54 (such as found in the GNU Compiler Collection) on any other type of system.
  55 You may, of course, override these default values by appropriate
  56 configuration of Environment construction variables.
  57
  58
  59 INSTALLATION
  60 ============
  61
  62 Installation of this package should be as simple as unpacking the
  63 archive (either .tar.gz or .zip) in any directory (top-level or a
  64 subdirectory) within the software package with which you want to ship
  65 SCons.
  66
  67 Once you have installed this package, you should write an SConstruct
  68 file at the top level of your source tree to build your software as you
  69 see fit.
  70
  71 Then modify the build/install instructions for your package to instruct
  72 your users to execute SCons as follows (if you installed this package in
  73 your top-level directory):
  74
  75         $ python scons.py
  76
  77 Or (if, for example, you installed this package in a subdirectory named
  78 "scons"):
  79
  80         $ python scons/scons.py
  81
  82 That should be all you have to do.  (If it isn't that simple, please let
  83 us know!)
  84
  85 Since 4.5, there is also an alternate form of scons-local avaialble:
  86 a zipapp. This is a single file with a .pyz suffix, which can be
  87 downloaded and executed directly (e.g.: python scons-local-4.5.2.pyz)
  88 without unpacking. This may be more convenient in a few cases.
  89
  90
  91 CONTENTS OF THIS PACKAGE
  92 ========================
  93
  94 This scons-local package consists of the following:
  95
  96 scons-LICENSE
  97         A copy of the copyright and terms under which SCons is
  98         distributed (the Open Source Initiative-approved MIT license).
  99
 100         A disclaimer has been added to the beginning to make clear that
 101         this license applies only to SCons, and not to any separate
 102         software you've written with which you're planning to package
 103         SCons.
 104
 105 scons-README
 106         What you're looking at right now.
 107
 108 scons-local-{version}/
 109         The SCons build engine.  This is structured as a Python
 110         library.
 111
 112 scons.py
 113         The SCons script itself.  The script sets up the Python
 114         sys.path variable to use the build engine found in the
 115         scons-local-{version}/ directory in preference to any other
 116         SCons build engine installed on your system.
 117
 118
 119 DOCUMENTATION
 120 =============
 121
 122 Because this package is intended to be included with other software by
 123 experienced users, we have not included any SCons documentation in this
 124 package (other than this scons-README file you're reading right now).
 125
 126 If, however, you need documentation about SCons, then consult any of the
 127 following from the corresponding scons-{version} or scons-src-{version}
 128 package:
 129
 130         The RELEASE.txt file (src/RELEASE.txt file in the
 131         scons-src-{version} package), which contains notes about this
 132         specific release, including known problems.
 133
 134         The CHANGES.txt file (src/CHANGES.txt file in the
 135         scons-src-{version} package), which contains a list of changes
 136         since the previous release.
 137
 138         The scons.1 man page (doc/man/scons.1 in the scons-src-{version}
 139         package), which contains a section of small examples for getting
 140         started using SCons.
 141
 142 Additional documentation for SCons is available at:
 143
 144         http://www.scons.org/doc.html
 145
 146
 147 LICENSING
 148 =========
 149
 150 SCons is distributed under the MIT license, a full copy of which is
 151 available in the scons-LICENSE file in this package. The MIT license is
 152 an approved Open Source license, which means:
 153
 154         This software is OSI Certified Open Source Software.  OSI
 155         Certified is a certification mark of the Open Source Initiative.
 156
 157 More information about OSI certifications and Open Source software is
 158 available at:
 159
 160         http://www.opensource.org/
 161
 162
 163 REPORTING BUGS
 164 ==============
 165
 166 The SCons project welcomes bug reports and feature requests.
 167
 168 Please make sure you send email with the problem or feature request to
 169 the SCons users mailing list, which you can join via the link below:
 170
 171         http://two.pairlist.net/mailman/listinfo/scons-users
 172
 173 Once you have discussed your issue on the users mailing list and the
 174 community has confirmed that it is either a new bug or a duplicate of an
 175 existing bug, then please follow the instructions the community provides
 176 to file a new bug or to add yourself to the CC list for an existing bug
 177
 178 You can explore the list of existing bugs, which may include workarounds
 179 for the problem you've run into, on GitHub:
 180
 181         https://github.com/SCons/scons/issues
 182
 183
 184
 185 MAILING LISTS
 186 =============
 187
 188 A mailing list for users of SCons is available.  You may send questions
 189 or comments to the list at:
 190
 191         scons-users@scons.org
 192
 193 You may subscribe to the scons-users mailing list at:
 194
 195         http://two.pairlist.net/mailman/listinfo/scons-users
 196
 197 In addition to the scons-users list which is appropriate for almost any
 198 question, there is a mailing list specifically for developers of SCons
 199 You may send questions or comments to the list at:
 200
 201         scons-dev@scons.org
 202
 203 You may subscribe to the developer's mailing list using form on this page:
 204
 205         http://two.pairlist.net/mailman/listinfo/scons-dev
 206
 207 Subscription to the developer's mailing list is by approval.  In practice, no
 208 one is refused list membership, but we reserve the right to limit membership
 209 in the future and/or weed out lurkers.
 210
 211 Note that while this list still exists, the number of different places you
 212 can talk about SCons means it is no longer very active.  GitHub has
 213 support for discussions as well as for issues, and there is usually more
 214 immediacy on the Discord chat, so these are probably now considered the
 215 preferred places for "development" topics.
 216
 217
 218 FOR MORE INFORMATION
 219 ====================
 220
 221 Check the SCons web site at:
 222
 223         http://www.scons.org/
 224
 225
 226 Author Info
 227 ===========
 228
 229 SCons was originally written by Steven Knight, knight at baldmt dot com.
 230 Since around 2010 it has been maintained by the SCons
 231 development team, co-managed by Bill Deegan and Gary Oberbrunner, with
 232 many contributors, including but not at all limited to:
 233
 234 - Chad Austin
 235 - Dirk Baechle
 236 - Charles Crain
 237 - William Deegan
 238 - Steve Leblanc
 239 - Rob Managan
 240 - Greg Noel
 241 - Gary Oberbrunner
 242 - Anthony Roach
 243 - Greg Spencer
 244 - Tom Tanner
 245 - Anatoly Techtonik
 246 - Christoph Wiedemann
 247 - Mats Wichmann
 248 - Russel Winder
 249 - Mats Wichmann
 250
 251 \... and many others.