From e9fe1258201d598ce1feec35345d08bf524238fc Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Fri, 11 Nov 2022 11:05:19 -0700 Subject: Update setup/installation chapter in User Guide [skip appveyor] No longer tell people to install via "python setup.py install", possibly with arguments on library directories and paths. Simplify, and mention use of virtualenvs as the current way to have multiple SCons versions installed. Fixes #4259 Signed-off-by: Mats Wichmann --- CHANGES.txt | 4 + RELEASE.txt | 3 + doc/user/build-install.xml | 428 ++++++++++++++++++--------------------------- 3 files changed, 180 insertions(+), 255 deletions(-) diff --git a/CHANGES.txt b/CHANGES.txt index 0a9f697..e7ba3f3 100755 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -52,6 +52,10 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER Fixes #4243. - Cleanup: make sure BoolVariable usage in tests and examples uses Python boolean values instead of 0/1. + - Stop telling people to run "python setup.py install" in the User Guide. + Adds new content on using virtualenvs to be able to have multiple + different SCons versions available on one system. + From Andrew Morrow - Avoid returning UniqueList for `children` and other `Executor` APIs. This type diff --git a/RELEASE.txt b/RELEASE.txt index 94ba72e..a796668 100644 --- a/RELEASE.txt +++ b/RELEASE.txt @@ -79,6 +79,9 @@ DOCUMENTATION Added note on the possibly surprising feature that SCons always passes -sourcepath when calling javac, which affects how the class path is used when finding sources. +- Updated the User Guide chapter on installation: modernized the notes + on Python installs, SCons installs, and having multiple SCons versions + present on a single system. DEVELOPMENT ----------- diff --git a/doc/user/build-install.xml b/doc/user/build-install.xml index c106dc5..697f5a2 100644 --- a/doc/user/build-install.xml +++ b/doc/user/build-install.xml @@ -1,4 +1,10 @@ + + @@ -22,46 +28,19 @@ xmlns="http://www.scons.org/dbxsd/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd"> -Building and Installing &SCons; - - +Building and Installing &SCons; 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). + of installing &SCons; so you can use it for your your projects. Before that, however, this chapter will also describe the basic steps - involved in installing Python on your system, + 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. + Fortunately, both &SCons; and &Python; + are easy to install on almost any system, + and &Python; already comes installed on many systems. @@ -70,31 +49,31 @@ Lastly, this chapter also contains a section that - provides a brief overview of the Python programming language, + provides a brief overview of the &Python; programming language, which is the language used to implement &SCons;, and which forms the basis of the &SCons; configuration files. - Becoming familiar with some Python concepts will make it easier + Becoming familiar with some &Python; concepts will make it easier to understand many of the examples in this User's Guide. Nevertheless, it is possible - to configure simple &SCons; builds without knowing Python, + to configure simple &SCons; builds without knowing &Python;, so you can skip this section if you want to dive in and pick up things by example- -or, of course, if you are - already familiar with Python. + already familiar with &Python;. --> -
+
Installing Python - Because &SCons; is written in Python, - you need to have Python installed on your system + Because &SCons; is written in the &Python; programming language, + you need to have a &Python; interpreter available on your system to use &SCons;. - Before you try to install Python, - you should check to see if Python is already + Before you try to install &Python;, + check to see if &Python; is already available on your system by typing python -V (capital 'V') @@ -106,28 +85,34 @@ $ python -V -Python 3.7.1 +Python 3.9.15 - Note to Windows users: there are a number of different ways Python + If you get a version like 2.7.x, you may need to try using the + name python3 - current &SCons; no longer + works with &Python; 2. + + + + 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 + of this guide to unravel all of them. Some 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. + back to trying python C:\>py -V -Python 3.7.1 +Python 3.9.15 - If Python is not installed on your system, + 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" @@ -135,14 +120,14 @@ Python 3.7.1 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 + 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: + The link for downloading &Python; installers (Windows and Mac) + from the project's own website is: https://www.python.org/download. There are useful system-specific entries on setup and usage to be found at: @@ -150,34 +135,56 @@ Python 3.7.1 - For Linux systems, Python is - almost certainly available as a supported package, possibly + For Linux systems, &Python; is + almost certainly available as a supported package, probably installed by default; this is often preferred over installing - by other means, and is easier than installing from source code. + by other means as the system package will be built with + carefully chosen optimizations, and will be kept up to date + with bug fixes and security patches. In fact, the &Python; + project itself does not build installers for Linux for this reason. Many such systems have separate packages for - Python 2 and Python 3 - make sure the Python 3 package is + &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 + useful option if you need a specific 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 + Recent versions of the Mac no longer come with &Python; + pre-installed; older versions came with a rather out of date + version (based on &Python; 2.7) which is insufficient to run + current &SCons;. + The python.org installer can be used on the Mac, but there are + also other sources such as MacPorts and Homebrew. + The Anaconda installation also comes with a bundled &Python;. + + + + Windows has even more choices. The Python.org installer is + a traditional .exe style; + the same software is also released as a Windows application through + the Microsoft Store. Several alternative builds also exist + such as Chocolatey and ActiveState, and, again, + a version of Python comes with Anaconda. + + + + &SCons; will work with &Python; 3.6 or later. + If you need to install &Python; and have a choice, + we recommend using the most recent &Python; version available. + Newer &Python; versions have significant improvements that help speed up the performance of &SCons;.
-
+
Installing &SCons; - The canonical way to install &SCons; is from the Python Package - Index (PyPi): + The recommended way to install &SCons; is from the &Python; Package + Index (PyPI): @@ -185,9 +192,9 @@ Python 3.7.1 - 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: + 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 and &Python; version: @@ -197,7 +204,7 @@ Python 3.7.1 For those users using Anaconda or Miniconda, use the conda installer instead, so the &scons; - install location will match the version of Python that + install location will match the version of &Python; that system will be using. For example: @@ -206,43 +213,61 @@ Python 3.7.1 - &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 current version, + pip has a version option + (e.g. python -m pip install scons==3.1.2), + or you can follow the instructions in the following sections. - 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. + &SCons; does comes pre-packaged for installation on many Linux systems. + Check your package installation system + to see if there is an up-to-date &SCons; package available. + Many people prefer to install distribution-native packages if available, + as they provide a central point for management and updating; + however not all distributions update in a timely fashion. + 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.
-
- Building and Installing &SCons; on Any System +
+ Using &SCons; Without Installing - 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. + You don't actually need to "install" &SCons; to use it. + Nor do you need to "build" it, unless you are interested in + producing the &SCons; documentation, which does use several + tools to produce HTML, PDF and other output formats from + files in the source tree. + All you need to do is + call the scons.py driver script in a + location that contains an &SCons; tree, and it will figure out + the rest. You can test that like this: + +$ python /path/to/unpacked/scripts/scons.py --version + + - The first step is to download either the + To make use of an uninstalled &SCons;, + 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. + There is also a scons-local bundle you can make + use of. It is arranged a little bit differently, with the idea + that you can include it with your own project if you want people + to be able to do builds without having to download or install &SCons;. + Finally, you can also use a checkout of the git tree from GitHub + at a location to point to. @@ -252,195 +277,88 @@ Python 3.7.1 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: + usually in your local directory. The driver script + will be in a subdirectory named scripts, + unless you are using scons-local, + in which case it will be in the top directory. + Now you only need to call scons.py by + giving a full or relative path to it in order to use that + &SCons; version. - -# 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. - + Note that instructions for older versions may have suggested + running python setup.py install to + "build and install" &SCons;. This is no longer recommended + (in fact, it is not recommended by the wider &Python; packaging + community for any end-user installations + of &Python; software). There is a setup.py file, + but it is only tested and used for the automated procedure which + prepares an &SCons; bundle for making a release on PyPI, + and even that is not guaranteed to work in future. - - -
- Building and Installing Multiple Versions of &SCons; Side-by-Side - - +
- 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. - - +
+ Running Multiple Versions of &SCons; Side-by-Side - - To install &SCons; in a version-specific location, - add the option - when you call setup.py: - + In some cases you may need several versions of &SCons; + present on a system at the same time - perhaps you have + an older project to build that has not yet been "ported" + to a newer &SCons; version, or maybe you want to test a + new &SCons; release side-by-side with a previous one + before switching over. + The use of an "uninstalled" package as described in the + previous section can be of use for this purpose. - -# 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. - + Another approach to multiple versions is to create + &Python; virtualenvs, and install different &SCons; versions in each. + A Python virtual environment + is a directory with an isolated set of Python packages, + where packages you install/upgrade/remove inside the + environment do not affect anything outside it, + and those you install/upgrade/remove outside of it + do not affect anything inside it. + In other words, anything you do with pip + in the environment stays in that environment. + The &Python; standard library provides a module called + venv for creating these + (), + although there are also other tools which provide more precise + control of the setup. - - If you use the 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 option. - + Using a virtualenv can be useful even for a single version of + &SCons;, to gain the advantages of having an isolated environment. + It also gets around the problem of not having administrative + privileges on a particular system to install a distribution + package or use pip to install to a + system location, as the virtualenv is completely under your control. -
- -
- Installing &SCons; in Other Locations - - - You can install &SCons; in locations other than - the default by specifying the option: - + The following outline shows how this could be set up + on a Linux/POSIX system (the syntax will be a bit different + on Windows): -# python setup.py install --prefix=/opt/scons +$ create virtualenv named scons3 +$ create virtualenv named scons4 +$ source scons3/bin/activate +$ pip install scons==3.1.2 +$ deactivate +$ source scons4/bin/activate +$ pip install scons +$ deactivate +$ activate a virtualenv and run 'scons' to use that version - - - 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 - and the 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 to the - above example would install the build engine in - /opt/scons/lib/scons-&buildversion;. - - - -
- -
- Building and Installing &SCons; Without Administrative Privileges - - - - 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 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. - - - -
-