Added useful README and example build.bat

README.md

@@ -1,2 +1,33 @@
 # bootstrap-scons
-Scripts to simplify acquiring and running SCons
+Scripts to simplify acquiring and running SCons on Windows machines
+
+## What is this for?
+SCons is a powerful build tool, but using it to build a project on a Windows computer requires several manual steps: first, one must install Python, and then SCons. Only then can one type "scons" to build the project. On UNIX-derived systems, this is not such a problem, because SCons and Python can usually be installed via the system's native package manager (e.g., apt).
+
+The goal of bootstrap-scons is to make SCons-based projects effortless to build on Windows. By using bootstrap-scons, a SCons-based project may be cloned from source control, and then built by running a single command:
+
+    D:\> git clone <my-project-url.git> my-project
+    D:\> cd my-project
+    D:\my-project\> build
+
+The "build" command first locates or installs Python, then locates or installs SCons, and finally invokes SCons to build the project.
+
+## How do I use it?
+To use this in your project, do the following:
+1. Drop a copy of bootstrap-scons as a subdirectory of your project, or better yet add bootstrap-scons as a submodule of your project. E.g.:
+
+       D:\my-project\> git add submodule [email protected]:jediry/bootstrap-scons.git
+
+   By adding bootstrap-scons as a submodule, you can easily pick up updates and bugfixes, just by updating your submodule version.
+
+2. Copy bootstrap-scons/build.bat.example and modify it to your liking. E.g.:
+
+       D:\my-project\> copy bootstrap-scons\build.bat.example build.bat
+
+## Things that you can customize
+The main things that you might want to customize are:
+* Which versions of Python/SCons are downloaded, if none can be found
+* Where the downloaded Python/SCons are installed
+* Whether the detected Python/SCons are cached in environment variables
+
+Take a look at the example build.bat included with bootstrap-scons to see how to alter these things, or invoke find_python.bat or find_scons.bat with the /? parameter to see all the things that can be customized.

build.bat.example

@@ -0,0 +1,55 @@
+@ECHO OFF
+
+:: Uncomment this SETLOCAL if you want built.bat to "forget" the discovered Python/SCons after executing SCons.
+::
+:: When this line is commented out, a small number of environment variables will be set in the calling shell's
+:: environment, allowing the "find" scripts to remember where Python/SCons were previously found, making subsequent
+:: runs faster. However, it does modify the calling shell's environment, and some people may not like this. Also,
+:: if they "remember" the results of the previous run, the "find" scripts will not detect any newly installed Python
+:: or SCons until the command shell is closed and re-launched, so uncommenting this can be helpful when testing the
+:: "find" scripts.
+::SETLOCAL
+
+
+:: Ensure that most environment variables set here, stay here...except for those that are explicitly propagated back
+:: to the caller at the end of this script
+SETLOCAL
+
+
+:: Uncomment these (or set them in your environment) to make bootstrap-scons print out information about where it's
+:: looking for things
+::SET FIND_PYTHON_DEBUG=1
+::SET FIND_SCONS_DEBUG=1
+
+:: Where bootstrap-scons is located, relative to this script (%~dp0 expands to the directory containing this script)
+SET BOOTSTRAP_SCONS=%~dp0bootstrap-scons
+
+:: Where to put Python and/or SCons if we have to download them. This is used to initialise FIND_PYTHON_LOCAL_ROOT and
+:: FIND_SCONS_LOCAL_ROOT immediately below.
+SET FIND_STUFF_LOCAL_ROOT=%~dp0
+
+:: Set default versions of Python & SCons, and where to install them, but let the user
+:: override these by setting them in the environment, if desired
+IF "%FIND_PYTHON_VERSION%"    == "" (SET FIND_PYTHON_VERSION=3.7.0)
+IF "%FIND_PYTHON_LOCAL_ROOT%" == "" (SET FIND_PYTHON_LOCAL_ROOT=%FIND_STUFF_LOCAL_ROOT%)
+IF "%FIND_SCONS_VERSION%"     == "" (SET FIND_SCONS_VERSION=3.0.1)
+IF "%FIND_SCONS_LOCAL_ROOT%"  == "" (SET FIND_SCONS_LOCAL_ROOT=%FIND_STUFF_LOCAL_ROOT%)
+
+
+:: Do it! Locate/download Python and/or SCons, and then invoke SCons
+CALL %BOOTSTRAP_SCONS%\scons.bat %*
+
+
+:: Configure the environment in the calling shell. Since everyting up through here is inside of SETLOCAL, we need to
+:: ENDLOCAL here so that we can modify the outer environment. Environment variables within ( )s are expanded
+:: immediately, before executing anything inside, which allows us to pass values out of the SETLOCAL/ENDLOCAL scope.
+::
+:: However, if the first call to SETLOCAL (around line 11) is uncommented, that will defeat this and prevent the calling
+:: environment from being altered, by still keeping everything in this script inside of a SETLOCAL scope.
+(
+    ENDLOCAL
+    SET "FOUND_SCONS_AT=%FOUND_SCONS_AT%"
+    SET "FOUND_PYTHON_AT=%FOUND_PYTHON_AT%"
+    SET "PYTHONPATH=%PYTHONPATH%"
+    SET "PATH=%PATH%"
+)