Merge branch tutorial into 24837

Makefile

@@ -41,6 +41,13 @@ build/make/Makefile: configure build/make/deps build/pkgs/*/*
 			echo "Since 'SAGE_PORT' is set, we will try to build anyway."; \
 		fi; )
 
+# This is used to monitor progress towards Python 3 and prevent
+# regressions. The target "build" should be upgraded to reflect the
+# level of Python 3 support that is known to work.
+buildbot-python3: configure
+	./configure --with-python=3
+	$(MAKE) build
+
 # Preemptively download all standard upstream source tarballs.
 download:
 	export SAGE_ROOT=$$(pwd) && \
@@ -146,4 +153,5 @@ install: all
 .PHONY: default build install micro_release \
 	misc-clean bdist-clean distclean bootstrap-clean maintainer-clean \
 	test check testoptional testall testlong testoptionallong testallong \
-	ptest ptestoptional ptestall ptestlong ptestoptionallong ptestallong
+	ptest ptestoptional ptestall ptestlong ptestoptionallong ptestallong \
+	buildbot-python3

README.md

@@ -344,6 +344,62 @@ For more details, see:
     http://doc.sagemath.org/html/en/developer/coding_basics.html#files-and-directory-structure
 
 
+Build System
+------------
+
+This is a brief summary of the Sage software distribution's build system.
+There are two components to the full Sage system--the Sage Python library
+and its associated user interfaces, and the larger software distribution of
+Sage's main dependencies (for those dependencies not supplied by the user's
+system).
+
+Sage's Python library is built and installed using a `setup.py` script as is
+standard for Python packages (Sage's `setup.py` is non-trivial, but not
+unusual).
+
+Most of the rest of the build system is concerned with building all of Sage's
+dependencies in the correct order in relation to each other.  The dependencies
+included by Sage are referred to as SPKGs (i.e. "Sage Packages") and are listed
+under `build/pkgs`.
+
+The main entrypoint to Sage's build system is the top-level `Makefile` at the
+root of the source tree.  Unlike most normal projects that use autoconf (Sage
+does as well, as described below), this `Makefile` is not generated.  Instead,
+it contains a few high-level targets and targets related to bootstrapping the
+system.  Nonetheless, we still run `make <target>` from the root of the source
+tree--targets not explicitly defined in the top-level `Makefile` are passed
+through to another Makefile under `build/make/Makefile`.
+
+The latter `build/make/Makefile` *is* generated by an autoconf-generated
+`configure` script, using the template in `build/make/Makefile.in`.  This
+includes rules for building the Sage library itself (`make sagelib`), and for
+building and installing each of Sage's dependencies (e.g. `make python2`).
+
+Although it's possible to manually run Sage's `configure` script if one wants
+to provide some customizations (e.g. it is possible to select which BLAS
+implementation to use), the top-level `Makefile` will run `configure` for you,
+in order to build `build/make/Makefile` since it's a prerequisite for most of
+Sage's make targets.
+
+The `configure` script itself, if it is not already built, can be generated by
+running the `bootstrap` script.  The top-level `Makefile` also takes care of
+this automatically.
+
+To summarize, running a command like `make python2` at the top-level of the
+source tree goes something like this:
+
+1. `make python2`
+2. run `./bootstrap` if `configure` does not exist
+3. run `./configure` if `build/make/Makefile` doe not exist
+4. `cd` into `build/make` and run the `install` script--this is little more
+   than a front-end to running `make -f build/make/Makefile python2`, which
+   sets some necessary environment variables and logs some information
+5. `build/make/Makefile` contains the actual rule for building `python2`; this
+   includes building all of `python2`'s dependencies first (and their
+   dependencies, recursively); the actual package installation is performed
+   with the `sage-spkg` program
+
+
 Relocation
 ----------
 

VERSION.txt

@@ -1 +1 @@
-SageMath version 8.2.beta7, Release Date: 2018-03-03
+SageMath version 8.2.rc1, Release Date: 2018-03-31

build/bin/sage-spkg

@@ -801,6 +801,26 @@ export https_proxy=$http_proxy
 export ftp_proxy=$http_proxy
 export rsync_proxy=$http_proxy
 
+##################################################################
+# We need to run sage-rebase.sh for each package installed, but it
+# can be dangerous to do this while other packages are installing
+# so we need to use a lock to manage when rebase is allowed to
+# run.  Because of this, if multiple sage-spkg runs are waiting on
+# the rebase lock, we can end up with multiple consecutive rebase
+# calls that are redundant, but I don't see an obvious way around
+# that.  This also unfortunately slows down parallel builds since
+# all packages will eventually need to wait for this lock, but
+# again there's no simple way around that.
+##################################################################
+
+if [ "$UNAME" = "CYGWIN" ]; then
+    if [ ! -d "$SAGE_LOCAL/var/lock" ]; then
+        mkdir -p "$SAGE_LOCAL/var/lock"
+    fi
+    exec 200>"$SAGE_LOCAL/var/lock/rebase.lock"
+    sage-flock -s $lock_type 200
+fi
+
 ##################################################################
 # Actually install
 ##################################################################
@@ -810,6 +830,13 @@ export rsync_proxy=$http_proxy
 # this in one place)
 export SAGE_DESTDIR="${SAGE_BUILD_DIR}/${PKG_NAME}/inst"
 
+# The actual prefix where the installation will be staged. This is the
+# directory that you need to work in if you want to change the staged
+# installation tree (before final installation to $SAGE_LOCAL) at the
+# end of spkg-install.
+export SAGE_DESTDIR_LOCAL="${SAGE_DESTDIR}${SAGE_LOCAL}"
+
+
 if [ -f spkg-build ]; then
     # Package has both spkg-build and spkg-install; execute the latter with SAGE_SUDO
     time ./spkg-build
@@ -835,7 +862,7 @@ fi
 # case DESTDIR=$SAGE_DESTDIR installation was not used
 echo "Copying package files from temporary location $SAGE_DESTDIR to $SAGE_LOCAL"
 if [ -d "$SAGE_DESTDIR" ]; then
-    PREFIX="${SAGE_DESTDIR}${SAGE_LOCAL%/}/"
+    PREFIX="${SAGE_DESTDIR_LOCAL%/}/"
 
     rm -f "$PREFIX"lib/*.la
     if [ $? -ne 0 ]; then
@@ -872,9 +899,14 @@ if [ -d "$SAGE_DESTDIR" ]; then
 fi
 
 if [ "$UNAME" = "CYGWIN" ]; then
+    # Drop our sage-spkg's shared lock, and try to call sage-rebase.sh
+    # under an exclusive lock
+    sage-flock -u 200
+
     # Rebase after installing each package--in case any packages load this
     # package at build time we need to ensure during the build that no binaries
     # have conflicting address spaces
+    echo "Waiting for rebase lock"
     sage-flock -x "$SAGE_LOCAL/var/lock/rebase.lock" \
         sage-rebase.sh "$SAGE_LOCAL" 2>/dev/null
 fi