1 SCons - a Software Construction Tool
2 ####################################
4 .. image:: https://img.shields.io/badge/IRC-scons-blue.svg
5 :target: https://web.libera.chat/#scons
8 .. image:: https://img.shields.io/sourceforge/dm/scons.svg
9 :target: https://sourceforge.net/projects/scons
10 :alt: Sourceforge Monthly Downloads
12 .. image:: https://img.shields.io/sourceforge/dt/scons.svg
13 :target: https://sourceforge.net/projects/scons
14 :alt: Sourceforge Total Downloads
16 .. image:: https://travis-ci.com/SCons/scons.svg?branch=master
17 :target: https://travis-ci.com/SCons/scons
18 :alt: Travis CI build status
20 .. image:: https://ci.appveyor.com/api/projects/status/github/SCons/scons?svg=true&branch=master
21 :target: https://ci.appveyor.com/project/SCons/scons
22 :alt: AppVeyor CI build Status
24 .. image:: https://codecov.io/gh/SCons/scons/branch/master/graph/badge.svg
25 :target: https://codecov.io/gh/SCons/scons
26 :alt: CodeCov Coverage Status
28 .. image:: https://github.com/SCons/scons/workflows/SCons%20Build/badge.svg
29 :target: https://github.com/SCons/scons/actions?query=workflow%3A%22SCons+Build%22
36 SCons is an Open Source software construction tool which orchestrates the construction of software
37 (and other tangible products such as documentation files) by determining which
38 component pieces must be built or rebuilt and invoking the necessary
39 commands to build them.
44 * Configuration files are Python scripts -
45 use the power of a real programming language
46 to solve build problems; no complex domain-specific language to learn.
47 * Reliable, automatic dependency analysis built-in for C, C++ and FORTRAN.
48 No more "make depend" or "make clean" to get all of the dependencies.
49 Dependency analysis is easily extensible through user-defined
50 dependency Scanners for other languages or file types.
51 * Built-in support for C, C++, D, Java, FORTRAN, Yacc, Lex, Qt and SWIG,
52 and building TeX and LaTeX documents.
53 Easily extensible through user-defined Builders for other languages
55 * Building from central repositories of source code and/or pre-built targets.
56 * Built-in support for Microsoft Visual Studio, including generation of
57 .dsp, .dsw, .sln and .vcproj files.
58 * Reliable detection of build changes using cryptographic hashes;
59 optionally can configure other algorithms including traditional timestamps.
60 * Support for parallel builds - can keep multiple jobs running
61 simultaneously regardless of directory hierarchy.
62 * Integrated Autoconf-like support for finding #include files, libraries,
63 functions and typedefs.
64 * Global view of all dependencies - no more multiple build passes or
65 reordering targets to build everything.
66 * Ability to share built files in a cache to speed up multiple builds.
67 * Designed from the ground up for cross-platform builds, and known to
68 work on Linux, other POSIX systems (including AIX, BSD systems,
69 HP/UX, IRIX and Solaris), Windows 7/8/10, MacOS, and OS/2.
76 Documentation for SCons is available at
77 http://www.scons.org/documentation.html.
83 If you already have SCons installed, you can check that the package you have
84 is the latest version at the
85 `SCons download page <https://www.scons.org/pages/download.html>`_.
88 Execution Requirements
89 ======================
91 Running SCons requires Python 3.6 or higher. There should be no other
92 dependencies or requirements to run standard SCons.
93 The last release to support Python 3.5 was 4.2.0.
95 Some experimental features may require additional Python packages
96 to be installed - at the moment the Ninja feature requires the
97 supporting `ninja package <https://pypi.org/project/ninja/>`_.
99 The default SCons configuration assumes use of the Microsoft Visual C++
100 compiler suite on Win32 systems, and assumes a C compiler named ``cc``, a C++
101 compiler named ``c++``, and a FORTRAN compiler named ``gfortran`` (such as found
102 in the GNU Compiler Collection) on any other type of system. You may
103 override these default values by appropriate configuration of variables
104 in a Construction Environment, or in the case of Cygwin on a Win32 system,
105 by selecting the 'cygwin' platform, which will set some of those Construction
108 By default, SCons knows how to search for available programming tools on
109 various systems - see the
110 `SCons man page <https://scons.org/doc/production/HTML/scons-man.html>`_
111 for details. You can override
112 the default SCons choices made by appropriate configuration of
113 construction variables.
116 Installation Requirements
117 =========================
119 SCons has no installation dependencies beyond a compatible version
120 of Python. The tools which will be used to actually construct the
121 project, such as compilers, documentation production tools, etc.
122 should of course be installed by the appropriate means.
128 The preferred way to install SCons is through the Python installer, ``pip``
129 (or equivalent alternatives, such as the Anaconda installer, ``conda``).
130 You can install either from a wheel package or from the source directory.
131 To work on a project that builds using SCons, installation lets you
132 just use ``scons`` as a command and not worry about things. In this
133 case, we usually suggest using a virtualenv, to isolate the Python
134 environment to that project
136 `Python Packaging User Guide: Creating and using virtual environments
137 <https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment>`_).
139 Some installation examples::
141 # to do a system-level install:
142 $ python -m pip install --user scons
144 # Windows variant, assuming Python Launcher:
145 C:\Users\me> py -m pip install --user scons
147 # inside a virtualenv it's safe to use bare pip:
148 (myvenv) $ pip install scons
150 # install in a virtualenv from a wheel file:
151 (myvenv) $ pip install SCons-4.3.0-py3-none-any.whl
153 # install in a virtualenv from source directory:
154 (myvenv) $ pip install --editable .
156 Note that on Windows, SCons installed via ``pip`` puts an executable
157 ``scons.exe`` in the script directory of the Python installation,
158 or in a shadow script directory if you did a User Install.
159 To run ``scons`` as a command, you'll need this in your search path.
161 Fortunately, ``pip`` will warn you about this - pay attention to any
162 messages during installation like this::
164 WARNING: The scripts scons-configure-cache.exe, scons.exe and sconsign.exe
165 are installed in 'C:\Users\me\AppData\Roaming\Python\Python310\Scripts'
166 which is not on PATH.
167 Consider adding this directory to PATH or, if you prefer to suppress this warning,
168 use --no-warn-script-location.
170 If you are running on a system which uses a package manager
171 (for example most Linux distributions), you may, at your option,
172 use the package manager (e.g. ``apt``, ``dnf``, ``yum``,
173 ``zypper``, ``brew``, ``pacman`` etc.) to install a version
174 of SCons. Some distributions keep up to date with SCons releases
175 very quickly, while others may delay, so the version of SCons
176 you want to run may factor into your choice.
179 Getting Started Using SCons
180 ===========================
182 If you're new to SCons, the first couple of chapters of the
183 `SCons User Guide <https://scons.org/doc/production/HTML/scons-user.html>`_
184 provide an excellent starting spot.
187 Contributing to SCons
188 =====================
190 Please see `<CONTRIBUTING.rst>`_
196 SCons is distributed under the MIT license, a full copy of which is available
197 in the `<LICENSE>`_ file.
203 The SCons project welcomes bug reports and feature requests.
205 Please make sure you send email with the problem or feature request to
206 the SCons users mailing list, which you can join at
207 https://two.pairlist.net/mailman/listinfo/scons-users,
208 or on the SCons Discord server in
209 `#scons-help <https://discord.gg/bXVpWAy#scons-help>`_.
211 Once you have discussed your issue on the users mailing list and the
212 community has confirmed that it is either a new bug or a duplicate of an
213 existing bug, then please follow the instructions the community provides
214 (including the issue template presented by GitHub)
215 to file a new bug or to add yourself to the CC list for an existing bug.
217 You can explore the list of existing bugs, which may include workarounds
218 for the problem you've run into, on the
219 `GitHub issue tracker <https://github.com/SCons/scons/issues>`_.
224 At this time, the application of bug-fix pull requests *normally* happens
225 at the head of the main branch. In other words fixes are likely to appear
226 in the next regular release and there probably won't be a bugfix update
227 to a past release. Consumers are of course free to internally maintain
228 releases on their own by taking submitted patches and applying them.
231 Mailing Lists and Other Contacts
232 ================================
234 In addition to the scons-users list, an active mailing list for developers
235 of SCons is available. You may send questions or comments to the list
236 at scons-dev@scons.org.
238 You may subscribe to the developer's mailing list using the form at
239 https://two.pairlist.net/mailman/listinfo/scons-dev. The same page
240 contains archives of past postings.
242 Subscription to the developer's mailing list is by approval. In practice, no
243 one is refused list membership, but we reserve the right to limit membership
244 in the future and/or weed out lurkers.
246 There are other ways to contact the SCons community. An active Discord
247 server is the most direct. The server includes a channel for code
248 notifications and other GitHub events (``#github-update``),
249 if those are of interest. See the website for more contact information:
250 https://scons.org/contact.html.
256 If you find SCons helpful, please consider making a donation (of cash,
257 software, or hardware) to support continued work on the project. Information
258 is available at https://www.scons.org/donate.html
259 or the GitHub Sponsors button on https://github.com/scons/scons.
263 In order to suppor those users who which to produce reproducible builds
264 (https://reproducible-builds.org/specs/source-date-epoch/) we're now including
265 logic to force SCons to propagate SOURCE_DATE_EPOCH from your shell environment for
266 all SCons builds to support reproducible builds we're now providing an example
267 site_init.py and a script to install it in your ~/.scons. See packaging/etc/README.txt
273 Check the SCons web site at https://www.scons.org/
279 SCons was originally written by Steven Knight, knight at baldmt dot com.
280 Since around 2010 it has been maintained by the SCons
281 development team, co-managed by Bill Deegan and Gary Oberbrunner, with
282 many contributors, including but not at all limited to:
296 - Christoph Wiedemann
300 \... and many others.
302 Copyright (c) 2001 - 2024 The SCons Foundation