README-package.rst

   1 SCons - a Software Construction Tool
   2 ####################################
   3
   4 .. image:: https://img.shields.io/badge/IRC-scons-blue.svg
   5    :target: https://web.libera.chat/#scons
   6    :alt: IRC
   7
   8 .. image:: https://img.shields.io/sourceforge/dm/scons.svg
   9    :target: https://sourceforge.net/projects/scons
  10    :alt: Sourceforge Monthly Downloads
  11
  12 .. image:: https://img.shields.io/sourceforge/dt/scons.svg
  13    :target: https://sourceforge.net/projects/scons
  14    :alt: Sourceforge Total Downloads
  15
  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
  19
  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
  23
  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
  27
  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
  30    :alt: Github Actions
  31
  32
  33 What is SCons?
  34 ==============
  35
  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.
  40
  41
  42 Features:
  43
  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
  54       or file types.
  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.
  70     * Written in Python.
  71
  72
  73 Documentation
  74 =============
  75
  76 Documentation for SCons is available at
  77 http://www.scons.org/documentation.html.
  78
  79
  80 Execution Requirements
  81 ======================
  82
  83 Running SCons requires Python 3.6 or higher. There should be no other
  84 dependencies or requirements to run standard SCons.
  85 The last release to support Python 3.5 was 4.2.0.
  86
  87 Some experimental features may require additional Python packages
  88 to be installed - at the moment the Ninja feature requires the
  89 supporting `ninja package <https://pypi.org/project/ninja/>`_.
  90
  91 The default SCons configuration assumes use of the Microsoft Visual C++
  92 compiler suite on Win32 systems, and assumes a C compiler named ``cc``, a C++
  93 compiler named ``c++``, and a Fortran compiler named ``gfortran`` (such as found
  94 in the GNU Compiler Collection) on any other type of system.  You may
  95 override these default values by appropriate configuration of variables
  96 in a Construction Environment, or in the case of Cygwin on a Win32 system,
  97 by selecting the 'cygwin' platform, which will set some of those Construction
  98 Variables for you.
  99
 100 By default, SCons knows how to search for available programming tools on
 101 various systems - see the
 102 `SCons man page <https://scons.org/doc/production/HTML/scons-man.html>`_
 103 for details.  You can override
 104 the default SCons choices made by appropriate configuration of
 105 construction variables.
 106
 107
 108 Installation Requirements
 109 =========================
 110
 111 SCons has no installation dependencies beyond a compatible version
 112 of Python. The tools which will be used to to actually construct the
 113 project, such as compilers, documentation production tools, etc.
 114 should of course be installed by the appropriate means.
 115
 116
 117 Getting Started Using SCons
 118 ===========================
 119
 120 If you're new to SCons, the first couple of chapters of the
 121 `SCons User Guide <https://scons.org/doc/production/HTML/scons-user.html>`_
 122 provide an excellent starting spot.
 123
 124
 125 Contributing to SCons
 126 =====================
 127
 128 Please see `CONTRIBUTING <https://github.com/scons/scons/CONTRIBUTING.rst>`_.
 129
 130
 131 License
 132 =======
 133
 134 SCons is distributed under the MIT license, a full copy of which is available
 135 in the LICENSE file.
 136
 137
 138 Reporting Bugs
 139 ==============
 140
 141 The SCons project welcomes bug reports and feature requests.
 142
 143 Please make sure you send email with the problem or feature request to
 144 the SCons users mailing list, which you can join at
 145 https://two.pairlist.net/mailman/listinfo/scons-users,
 146 or on the SCons Discord server in
 147 `#scons-help <https://discord.gg/bXVpWAy#scons-help>`_.
 148
 149 Once you have discussed your issue on the users mailing list and the
 150 community has confirmed that it is either a new bug or a duplicate of an
 151 existing bug, then please follow the instructions the community provides
 152 to file a new bug or to add yourself to the CC list for an existing bug
 153
 154 You can explore the list of existing bugs, which may include workarounds
 155 for the problem you've run into, on the
 156 `GitHub issue tracker <https://github.com/SCons/scons/issues>`_.
 157
 158
 159 Mailing Lists
 160 =============
 161
 162 In addition to the scons-users list which is appropriate for almost any
 163 question, there is a mailing list specifically for developers of SCons
 164 You may send questions or comments to the list at:
 165
 166 You may subscribe to the developer's mailing list using the form at
 167 https://two.pairlist.net/mailman/listinfo/scons-dev.
 168
 169 Subscription to the developer's mailing list is by approval.  In practice, no
 170 one is refused list membership, but we reserve the right to limit membership
 171 in the future and/or weed out lurkers.
 172
 173 Note that while this list still exists, the number of different places you
 174 can talk about SCons means it is no longer very active.  GitHub has
 175 support for discussions as well as for issues, and there is usually more
 176 immediacy on the Discord chat, so these are probably now considered the
 177 preferred places for "development" topics.
 178
 179
 180 Donations
 181 =========
 182
 183 If you find SCons helpful, please consider making a donation (of cash,
 184 software, or hardware) to support continued work on the project.  Information
 185 is available at https://www.scons.org/donate.html
 186 or the GitHub Sponsors button on https://github.com/scons/scons.
 187
 188
 189 For More Information
 190 ====================
 191
 192 Check the SCons web site at https://www.scons.org/
 193
 194
 195 Copyright (c) 2001 - 2021 The SCons Foundation
 196