%version; %scons; %builders-mod; %functions-mod; %tools-mod; %variables-mod; ]> This chapter will take you through the basic steps of installing &SCons; on your system, and building &SCons; if you don't have a pre-built package available (or simply prefer the flexibility of building it yourself). Before that, however, this chapter will also describe the basic steps involved in installing Python on your system, in case that is necessary. Fortunately, both &SCons; and Python are very easy to install on almost any system, and Python already comes installed on many systems.

Because &SCons; is written in Python, you need to have Python installed on your system to use &SCons;. Before you try to install Python, you should check to see if Python is already available on your system by typing python -V (capital 'V') or python --version at your system's command-line prompt. For Linux/Unix/MacOS/BSD type systems this looks like: $ python -V Python 3.7.1 Note to Windows users: there are a number of different ways Python can be installed or invoked on Windows, it is beyond the scope of this guide to unravel all of them. Many will have an additional program called the Python launcher (described, somewhat technically, in PEP 397): try using the command name py instead of python, if that is not available drop back to trying python. C:\>py -V Python 3.7.1 If Python is not installed on your system, or is not findable in the current search path, you will see an error message stating something like "command not found" (on UNIX or Linux) or "'python' is not recognized as an internal or external command, operable progam or batch file" (on Windows cmd). In that case, you need to either install Python or fix the search path before you can install &SCons;. The canonical location for downloading Python from Python's own website is: https://www.python.org/download. There are useful system-specific entries on setup and usage to be found at: https://docs.python.org/3/using For Linux systems, Python is almost certainly available as a supported package, possibly installed by default; this is often preferred over installing by other means, and is easier than installing from source code. Many such systems have separate packages for Python 2 and Python 3 - make sure the Python 3 package is installed, as the latest &SCons; requires it. Building from source may still be a useful option if you need a version that is not offered by the distribution you are using. &SCons; will work with Python 3.5 or later. If you need to install Python and have a choice, we recommend using the most recent Python version available. Newer Pythons have significant improvements that help speed up the performance of &SCons;.

The canonical way to install &SCons; is from the Python Package Index (PyPi): % python -m pip install scons If you prefer not to install to the Python system location, or do not have privileges to do so, you can add a flag to install to a location specific to your own account: % python -m pip install --user scons For those users using Anaconda or Miniconda, use the conda installer instead, so the &scons; install location will match the version of Python that system will be using. For example: % conda install -c conda-forge scons &SCons; comes pre-packaged for installation on many Linux systems. Check your package installation system to see if there is an &SCons; package available. Many people prefer to install distribution-native packages if available, as they provide a central point for management and updating. During the still-ongoing Python 2 to 3 transition, some distributions may still have two &SCons; packages available, one which uses Python 2 and one which uses Python 3. Since the latest &scons; only runs on Python 3, to get the current version you should choose the Python 3 package. If you need a specific version of &SCons; that is different from the package available, pip has a version option or you can follow the instructions in the next section.

If a pre-built &SCons; package is not available for your system, and installing using pip is not suitable, then you can still easily build and install &SCons; using the native Python setuptools package. The first step is to download either the scons-&buildversion;.tar.gz or scons-&buildversion;.zip, which are available from the SCons download page at https://scons.org/pages/download.html. Unpack the archive you downloaded, using a utility like tar on Linux or UNIX, or WinZip on Windows. This will create a directory called scons-&buildversion;, usually in your local directory. Then change your working directory to that directory and install &SCons; by executing the following commands: # cd scons-&buildversion; # python setup.py install This will build &SCons;, install the &scons; script in the python which is used to run the setup.py's scripts directory (/usr/local/bin or C:\Python37\Scripts), and will install the &SCons; build engine in the corresponding library directory for the python used (/usr/local/lib/scons or C:\Python37\scons). Because these are system directories, you may need root (on Linux or UNIX) or Administrator (on Windows) privileges to install &SCons; like this.

The &SCons; setup.py script has some extensions that support easy installation of multiple versions of &SCons; in side-by-side locations. This makes it easier to download and experiment with different versions of &SCons; before moving your official build process to a new version, for example. To install &SCons; in a version-specific location, add the --version-lib option when you call setup.py: # python setup.py install --version-lib This will install the &SCons; build engine in the /usr/lib/scons-&buildversion; or C:\Python27\scons-&buildversion; directory, for example. If you use the --version-lib option the first time you install &SCons;, you do not need to specify it each time you install a new version. The &SCons; setup.py script will detect the version-specific directory name(s) and assume you want to install all versions in version-specific directories. You can override that assumption in the future by explicitly specifying the --standalone-lib option.

You can install &SCons; in locations other than the default by specifying the --prefix= option: # python setup.py install --prefix=/opt/scons This would install the scons script in /opt/scons/bin and the build engine in /opt/scons/lib/scons, Note that you can specify both the --prefix= and the --version-lib options at the same type, in which case setup.py will install the build engine in a version-specific directory relative to the specified prefix. Adding --version-lib to the above example would install the build engine in /opt/scons/lib/scons-&buildversion;.

If you don't have the right privileges to install &SCons; in a system location, simply use the --prefix= option to install it in a location of your choosing. For example, to install &SCons; in appropriate locations relative to the user's $HOME directory, the &scons; script in $HOME/bin and the build engine in $HOME/lib/scons, simply type: $ python setup.py install --prefix=$HOME You may, of course, specify any other location you prefer, and may use the --version-lib option if you would like to install version-specific directories relative to the specified prefix. This can also be used to experiment with a newer version of &SCons; than the one installed in your system locations. Of course, the location in which you install the newer version of the &scons; script ($HOME/bin in the above example) must be configured in your &PATH; variable before the directory containing the system-installed version of the &scons; script.