WIP -- wait for 18205 to continue

* no clean -t option, use 'spack test remove'

* refactor commands to make better use of TestSuite objects

.codecov.yml

@@ -5,7 +5,7 @@ coverage:
   status:
     project:
       default:
-        threshold: 0.3%
+        threshold: 0.2%
 
 ignore:
   - lib/spack/spack/test/.*

.flake8_packages

@@ -9,7 +9,7 @@
 #
 # Note that we also add *per-line* exemptions for certain patterns in the
 # `spack flake8` command.  This is where F403 for `from spack import *`
-# is added (beause we *only* allow that wildcard).
+# is added (because we *only* allow that wildcard).
 #
 # See .flake8 for regular exceptions.
 #

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,14 +1,11 @@
 ---
-name: Bug report 
-about: Report a bug in the core of Spack (command not working as expected, etc.) 
-labels: bug
+name: "\U0001F41E Bug report"
+about: Report a bug in the core of Spack (command not working as expected, etc.)
+labels: "bug,triage"
 ---
 
-
-*Explain, in a clear and concise way, the command you ran and the result you were trying to achieve.
-Example: "I ran Spack find to list all the installed packages and..."*
-
-
+<!-- Explain, in a clear and concise way, the command you ran and the result you were trying to achieve.
+Example: "I ran `spack find` to list all the installed packages and ..." -->
 
 ### Steps to reproduce the issue
 
@@ -20,30 +17,26 @@ $ spack <command2> <spec>
 
 ### Error Message
 
-If Spack reported an error, provide the error message. If it did not report an error
-but the output appears incorrect, provide the incorrect output. If there was no error
-message and no output but the result is incorrect, describe how it does not match
-what you expect. To provide more information you might re-run the commands with 
-the additional -d/--stacktrace flags:
+<!-- If Spack reported an error, provide the error message. If it did not report an error but the output appears incorrect, provide the incorrect output. If there was no error message and no output but the result is incorrect, describe how it does not match what you expect. -->
 ```console
-$ spack -d --stacktrace <command1> <spec>
-$ spack -d --stacktrace <command2> <spec>
-...
+$ spack --debug --stacktrace <command>
 ```
-that activate the full debug output. 
-
 
 ### Information on your system
 
-This includes:
+<!-- Please include the output of `spack debug report` -->
 
- 1. which platform you are using
- 2. any relevant configuration detail (custom `packages.yaml` or `modules.yaml`, etc.)
+<!-- If you have any relevant configuration detail (custom `packages.yaml` or `modules.yaml`, etc.) you can add that here as well. -->
 
------
+### Additional information
 
-We encourage you to try, as much as possible, to reduce your problem to the minimal example that still reproduces the issue. That would help us a lot in fixing it quickly and effectively!
+<!-- These boxes can be checked by replacing [ ] with [x] or by clicking them after submitting the issue. -->
+- [ ] I have run `spack debug report` and reported the version of Spack/Python/Platform
+- [ ] I have searched the issues of this repo and believe this is not a duplicate
+- [ ] I have run the failing commands in debug mode and reported the output
+
+<!-- We encourage you to try, as much as possible, to reduce your problem to the minimal example that still reproduces the issue. That would help us a lot in fixing it quickly and effectively!
 
 If you want to ask a question about the tool (how to use it, what it can currently do, etc.), try the `#general` channel on our Slack first. We have a welcoming community and chances are you'll get your reply faster and without opening an issue.
 
-Other than that, thanks for taking the time to contribute to Spack!
+Other than that, thanks for taking the time to contribute to Spack! -->

.github/ISSUE_TEMPLATE/build_error.md

@@ -1,78 +1,43 @@
 ---
-name: Build error 
-about: Some package in Spack didn't build correctly  
+name: "\U0001F4A5 Build error"
+about: Some package in Spack didn't build correctly
+title: "Installation issue: "
 labels: "build-error"
 ---
 
-*Thanks for taking the time to report this build failure. To proceed with the
-report please:*
+<!-- Thanks for taking the time to report this build failure. To proceed with the report please:
+
 1. Title the issue "Installation issue: <name-of-the-package>".
 2. Provide the information required below.
-3. Remove the template instructions before posting the issue.
 
-We encourage you to try, as much as possible, to reduce your problem to the minimal example that still reproduces the issue. That would help us a lot in fixing it quickly and effectively!
-
-
----
+We encourage you to try, as much as possible, to reduce your problem to the minimal example that still reproduces the issue. That would help us a lot in fixing it quickly and effectively! -->
 
 ### Steps to reproduce the issue
 
+<!-- Fill in the exact spec you are trying to build and the relevant part of the error message -->
 ```console
-$ spack install <spec> # Fill in the exact spec you are using
-... # and the relevant part of the error message
+$ spack install <spec>
+...
 ```
 
-### Platform and user environment
+### Information on your system
 
-Please report your OS here:
-```commandline
-$ uname -a 
-Linux nuvolari 4.15.0-29-generic #31-Ubuntu SMP Tue Jul 17 15:39:52 UTC 2018 x86_64 x86_64 x86_64 GNU/Linux
-$ lsb_release -d
-Description:	Ubuntu 18.04.1 LTS
-``` 
-and, if relevant, post or attach:
+<!-- Please include the output of `spack debug report` -->
 
-- `packages.yaml`
-- `compilers.yaml`
-
-to the issue
+<!-- If you have any relevant configuration detail (custom `packages.yaml` or `modules.yaml`, etc.) you can add that here as well. -->
 
 ### Additional information
 
-Sometimes the issue benefits from additional details. In these cases there are
-a few things we can suggest doing. First of all, you can post the full output of:
-```console
-$ spack spec --install-status <spec>
-...
-```
-to show people whether Spack installed a faulty software or if it was not able to
-build it at all. 
+<!-- Please upload the following files. They should be present in the stage directory of the failing build. Also upload any config.log or similar file if one exists. -->
+* [spack-build-out.txt]()
+* [spack-build-env.txt]()
 
-If your build didn't make it past the configure stage, Spack as also commands to parse 
-logs and report error and warning messages:
-```console
-$ spack log-parse --show=errors,warnings <file-to-parse>
-```
-You might want to run this command on the `config.log` or any other similar file
-found in the stage directory: 
-```console
-$ spack location -s <spec>
-```
-In case in `config.log` there are other settings that you think might be the cause 
-of the build failure, you can consider attaching the file to this issue.
+<!-- Some packages have maintainers who have volunteered to debug build failures. Run `spack maintainers <name-of-the-package>` and @mention them here if they exist. -->
 
-Rebuilding the package with the following options:
-```console
-$ spack -d install -j 1 <spec>
-...
-```
-will provide additional debug information. After the failure you will find two files in the current directory:
+### General information
 
-1. `spack-cc-<spec>.in`, which contains details on the command given in input 
-    to Spack's compiler wrapper  
-1. `spack-cc-<spec>.out`, which contains the command used to compile / link the 
-    failed object after Spack's compiler wrapper did its processing 
-
-You can post or attach those files to provide maintainers with more information on what
-is causing the failure.
+<!-- These boxes can be checked by replacing [ ] with [x] or by clicking them after submitting the issue. -->
+- [ ] I have run `spack debug report` and reported the version of Spack/Python/Platform
+- [ ] I have run `spack maintainers <name-of-the-package>` and @mentioned any maintainers
+- [ ] I have uploaded the build log and environment files
+- [ ] I have searched the issues of this repo and believe this is not a duplicate

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,28 +1,33 @@
 ---
-name: Feature request 
+name: "\U0001F38A Feature request" 
 about: Suggest adding a feature that is not yet in Spack  
 labels: feature
 
 ---
 
-*Please add a concise summary of your suggestion here.*
+<!--*Please add a concise summary of your suggestion here.*-->
 
 ### Rationale
 
-*Is your feature request related to a problem? Please describe it!*
+<!--*Is your feature request related to a problem? Please describe it!*-->
 
 ### Description
 
-*Describe the solution you'd like and the alternatives you have considered.*
+<!--*Describe the solution you'd like and the alternatives you have considered.*-->
 
 
 ### Additional information
-*Add any other context about the feature request here.*
+<!--*Add any other context about the feature request here.*-->
 
 
------
+### General information
+
+- [ ] I have run `spack --version` and reported the version of Spack
+- [ ] I have searched the issues of this repo and believe this is not a duplicate
 
 
-If you want to ask a question about the tool (how to use it, what it can currently do, etc.), try the `#general` channel on our Slack first. We have a welcoming community and chances are you'll get your reply faster and without opening an issue.
 
-Other than that, thanks for taking the time to contribute to Spack!
+<!--If you want to ask a question about the tool (how to use it, what it can currently do, etc.), try the `#general` channel on our Slack first. We have a welcoming community and chances are you'll get your reply faster and without opening an issue.
+
+Other than that, thanks for taking the time to contribute to Spack!
+-->

.github/workflows/install_spack.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env sh
+. share/spack/setup-env.sh
+echo -e "config:\n  build_jobs: 2" > etc/spack/config.yaml
+spack config add "packages:all:target:[x86_64]"
+# TODO: remove this explicit setting once apple-clang detection is fixed
+cat <<EOF > etc/spack/compilers.yaml
+compilers:
+- compiler:
+    spec: apple-clang@11.0.3
+    paths:
+      cc: /usr/bin/clang
+      cxx: /usr/bin/clang++
+      f77: /usr/local/bin/gfortran-9
+      fc: /usr/local/bin/gfortran-9
+    modules: []
+    operating_system: catalina
+    target: x86_64
+EOF
+spack compiler info apple-clang
+spack debug report

.github/workflows/linux_build_tests.yaml

@@ -3,12 +3,12 @@ name: linux builds
 on:
   push:
     branches:
-    - master
     - develop
+    - releases/**
   pull_request:
     branches:
-    - master
     - develop
+    - releases/**
     paths-ignore:
       # Don't run if we only modified packages in the built-in repository
       - 'var/spack/repos/builtin/**'
@@ -18,33 +18,41 @@ on:
       - '!var/spack/repos/builtin/packages/py-setuptools/**'
       - '!var/spack/repos/builtin/packages/openjpeg/**'
       - '!var/spack/repos/builtin/packages/r-rcpp/**'
+      - '!var/spack/repos/builtin/packages/ruby-rake/**'
+      # Don't run if we only modified documentation
+      - 'lib/spack/docs/**'
 
 jobs:
   build:
-
     runs-on: ubuntu-latest
     strategy:
-      max-parallel: 4
       matrix:
-        package: [lz4, mpich, tut, py-setuptools, openjpeg, r-rcpp]
+        package:
+        - lz4  # MakefilePackage
+        - mpich  # AutotoolsPackage
+        - tut  # WafPackage
+        - py-setuptools  # PythonPackage
+        - openjpeg  # CMakePackage
+        - r-rcpp  # RPackage
+        - ruby-rake  # RubyPackage
     steps:
-    - uses: actions/checkout@v1
-    - name: Cache ccache's store
-      uses: actions/cache@v1
+    - uses: actions/checkout@v2
+    - uses: actions/cache@v2
       with:
         path: ~/.ccache
         key: ccache-build-${{ matrix.package }}
         restore-keys: |
           ccache-build-${{ matrix.package }}
-    - name: Setup Python
-      uses: actions/setup-python@v1
+    - uses: actions/setup-python@v2
       with:
         python-version: 3.8
     - name: Install System Packages
       run: |
-        sudo apt-get -yqq install ccache gfortran perl perl-base r-base r-base-core r-base-dev findutils openssl libssl-dev libpciaccess-dev
+        sudo apt-get update
+        sudo apt-get -yqq install ccache gfortran perl perl-base r-base r-base-core r-base-dev ruby findutils openssl libssl-dev libpciaccess-dev
         R --version
         perl --version
+        ruby --version
     - name: Copy Configuration
       run: |
         ccache -M 300M && ccache -z

.github/workflows/linux_unit_tests.yaml

@@ -0,0 +1,114 @@
+name: linux tests
+
+on:
+  push:
+    branches:
+      - develop
+      - releases/**
+  pull_request:
+    branches:
+      - develop
+      - releases/**
+jobs:
+  unittests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [2.7, 3.5, 3.6, 3.7, 3.8]
+
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+    - uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install System packages
+      run: |
+          sudo apt-get -y update
+          sudo apt-get install -y coreutils gfortran graphviz gnupg2 mercurial ninja-build patchelf
+          # Needed for kcov
+          sudo apt-get -y install cmake binutils-dev libcurl4-openssl-dev zlib1g-dev libdw-dev libiberty-dev
+    - name: Install Python packages
+      run: |
+          pip install --upgrade pip six setuptools codecov coverage
+    - name: Setup git configuration
+      run: |
+          # Need this for the git tests to succeed.
+          git --version
+          . .github/workflows/setup_git.sh
+    - name: Install kcov for bash script coverage
+      env:
+          KCOV_VERSION: 34
+      run: |
+          KCOV_ROOT=$(mktemp -d)
+          wget --output-document=${KCOV_ROOT}/${KCOV_VERSION}.tar.gz https://github.com/SimonKagstrom/kcov/archive/v${KCOV_VERSION}.tar.gz
+          tar -C ${KCOV_ROOT} -xzvf ${KCOV_ROOT}/${KCOV_VERSION}.tar.gz
+          mkdir -p ${KCOV_ROOT}/build
+          cd ${KCOV_ROOT}/build && cmake -Wno-dev ${KCOV_ROOT}/kcov-${KCOV_VERSION} && cd -
+          make -C ${KCOV_ROOT}/build && sudo  make -C ${KCOV_ROOT}/build install
+    - name: Run unit tests
+      env:
+          COVERAGE: true
+      run: |
+          share/spack/qa/run-unit-tests
+          coverage combine
+          coverage xml
+    - uses: codecov/codecov-action@v1
+      with:
+        flags: unittests,linux
+  shell:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+    - uses: actions/setup-python@v2
+      with:
+        python-version: 3.8
+    - name: Install System packages
+      run: |
+          sudo apt-get -y update
+          sudo apt-get install -y coreutils gfortran gnupg2 mercurial ninja-build patchelf zsh fish
+          # Needed for kcov
+          sudo apt-get -y install cmake binutils-dev libcurl4-openssl-dev zlib1g-dev libdw-dev libiberty-dev
+    - name: Install Python packages
+      run: |
+          pip install --upgrade pip six setuptools codecov coverage
+    - name: Setup git configuration
+      run: |
+          # Need this for the git tests to succeed.
+          git --version
+          . .github/workflows/setup_git.sh
+    - name: Install kcov for bash script coverage
+      env:
+          KCOV_VERSION: 38
+      run: |
+          KCOV_ROOT=$(mktemp -d)
+          wget --output-document=${KCOV_ROOT}/${KCOV_VERSION}.tar.gz https://github.com/SimonKagstrom/kcov/archive/v${KCOV_VERSION}.tar.gz
+          tar -C ${KCOV_ROOT} -xzvf ${KCOV_ROOT}/${KCOV_VERSION}.tar.gz
+          mkdir -p ${KCOV_ROOT}/build
+          cd ${KCOV_ROOT}/build && cmake -Wno-dev ${KCOV_ROOT}/kcov-${KCOV_VERSION} && cd -
+          make -C ${KCOV_ROOT}/build && sudo  make -C ${KCOV_ROOT}/build install
+    - name: Run shell tests
+      env:
+          COVERAGE: true
+      run: |
+          share/spack/qa/run-shell-tests
+    - uses: codecov/codecov-action@v1
+      with:
+        flags: shelltests,linux
+  centos6:
+    # Test for Python2.6 run on Centos 6
+    runs-on: ubuntu-latest
+    container: spack/github-actions:centos6
+    steps:
+    - name: Run unit tests
+      env:
+          HOME: /home/spack-test
+      run: |
+          whoami && echo $HOME && cd $HOME
+          git clone https://github.com/spack/spack.git && cd spack
+          git fetch origin ${{ github.ref }}:test-branch
+          git checkout test-branch
+          share/spack/qa/run-unit-tests

.github/workflows/macos_python.yml

@@ -0,0 +1,79 @@
+# These are nightly package tests for macOS
+# focus areas:
+# - initial user experience
+# - scientific python stack
+name: macOS builds nightly
+
+on:
+  schedule:
+    # nightly at 1 AM
+    - cron: '0 1 * * *'
+  pull_request:
+    branches:
+    - develop
+    paths:
+      # Run if we modify this yaml file
+      - '.github/workflows/macos_python.yml'
+      # TODO: run if we touch any of the recipes involved in this
+
+# GitHub Action Limits
+# https://help.github.com/en/actions/reference/workflow-syntax-for-github-actions
+
+jobs:
+  install_gcc:
+    name: gcc with clang
+    runs-on: macos-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions/setup-python@v2
+      with:
+        python-version: 3.8
+    - name: spack install
+      run: |
+        . .github/workflows/install_spack.sh
+        # 9.2.0 is the latest version on which we apply homebrew patch
+        spack install -v --fail-fast gcc@9.2.0 %apple-clang
+
+  install_jupyter_clang:
+    name: jupyter
+    runs-on: macos-latest
+    timeout-minutes: 700
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions/setup-python@v2
+      with:
+        python-version: 3.8
+    - name: spack install
+      run: |
+        . .github/workflows/install_spack.sh
+        spack config add packages:opengl:paths:opengl@4.1:/usr/X11R6
+        spack install -v --fail-fast py-jupyter %apple-clang
+
+  install_scipy_clang:
+    name: scipy, mpl, pd
+    runs-on: macos-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions/setup-python@v2
+      with:
+        python-version: 3.8
+    - name: spack install
+      run: |
+        . .github/workflows/install_spack.sh
+        spack install -v --fail-fast py-scipy %apple-clang
+        spack install -v --fail-fast py-matplotlib %apple-clang
+        spack install -v --fail-fast py-pandas %apple-clang
+
+  install_mpi4py_clang:
+    name: mpi4py, petsc4py
+    runs-on: macos-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions/setup-python@v2
+      with:
+        python-version: 3.8
+    - name: spack install
+      run: |
+        . .github/workflows/install_spack.sh
+        spack install -v --fail-fast py-mpi4py %apple-clang
+        spack install -v --fail-fast py-petsc4py %apple-clang

.github/workflows/macos_unit_tests.yaml

@@ -0,0 +1,41 @@
+name: macos tests
+
+on:
+  push:
+    branches:
+      - develop
+      - releases/**
+  pull_request:
+    branches:
+      - develop
+      - releases/**
+jobs:
+  build:
+    runs-on: macos-latest
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+    - uses: actions/setup-python@v2
+      with:
+        python-version: 3.8
+    - name: Install Python packages
+      run: |
+          pip install --upgrade pip six setuptools
+          pip install --upgrade codecov coverage
+          pip install --upgrade flake8 pep8-naming
+    - name: Setup Homebrew packages
+      run: |
+        brew install gcc gnupg2 dash kcov
+    - name: Run unit tests
+      run: |
+        git --version
+        . .github/workflows/setup_git.sh
+        . share/spack/setup-env.sh
+        coverage run $(which spack) unit-test
+        coverage combine
+        coverage xml
+    - uses: codecov/codecov-action@v1
+      with:
+        file: ./coverage.xml
+        flags: unittests,macos

.github/workflows/minimum_python_versions.yaml

@@ -1,30 +0,0 @@
-name: python version check
-
-on:
-  push:
-    branches:
-      - master
-      - develop
-  pull_request:
-    branches:
-      - master
-      - develop
-jobs:
-  validate:
-
-    runs-on: ubuntu-latest
-
-    steps:
-    - uses: actions/checkout@v1
-    - name: Setup Python
-      uses: actions/setup-python@v1
-      with:
-        python-version: 3.7
-    - name: Install Python Packages
-      run: |
-        pip install --upgrade pip
-        pip install --upgrade vermin
-    - name: Minimum Version (Spack's Core)
-      run: vermin --backport argparse -t=2.6- -t=3.5- -v lib/spack/spack/ lib/spack/llnl/ bin/
-    - name: Minimum Version (Repositories)
-      run: vermin --backport argparse -t=2.6- -t=3.5- -v var/spack/repos

.github/workflows/setup_git.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env sh
+git config --global user.email "spack@example.com"
+git config --global user.name "Test User"
+# With fetch-depth: 0 we have a remote develop
+# but not a local branch. Don't do this on develop
+if [ "$(git branch --show-current)" != "develop" ]
+then
+  git branch develop origin/develop
+fi

.github/workflows/style_and_docs.yaml

@@ -0,0 +1,65 @@
+name: style and docs
+
+on:
+  push:
+    branches:
+      - develop
+      - releases/**
+  pull_request:
+    branches:
+      - develop
+      - releases/**
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions/setup-python@v2
+      with:
+        python-version: 3.8
+    - name: Install Python Packages
+      run: |
+        pip install --upgrade pip
+        pip install --upgrade vermin
+    - name: Minimum Version (Spack's Core)
+      run: vermin --backport argparse -t=2.6- -t=3.5- -v lib/spack/spack/ lib/spack/llnl/ bin/
+    - name: Minimum Version (Repositories)
+      run: vermin --backport argparse -t=2.6- -t=3.5- -v var/spack/repos
+  flake8:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+    - uses: actions/setup-python@v2
+      with:
+        python-version: 3.8
+    - name: Install Python packages
+      run: |
+        pip install --upgrade pip six setuptools flake8
+    - name: Setup git configuration
+      run: |
+        # Need this for the git tests to succeed.
+        git --version
+        . .github/workflows/setup_git.sh
+    - name: Run flake8 tests
+      run: |
+          share/spack/qa/run-flake8-tests
+  documentation:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions/setup-python@v2
+      with:
+        python-version: 3.8
+    - name: Install System packages
+      run: |
+        sudo apt-get -y update
+        sudo apt-get install -y coreutils ninja-build graphviz
+    - name: Install Python packages
+      run: |
+        pip install --upgrade pip six setuptools
+        pip install --upgrade -r lib/spack/docs/requirements.txt
+    - name: Build documentation
+      run: |
+          share/spack/qa/run-doc-tests

.gitignore

@@ -4,6 +4,7 @@
 /var/spack/environments
 /var/spack/repos/*/index.yaml
 /var/spack/repos/*/lock
+__pycache__/
 *.pyc
 /opt
 *~
@@ -22,8 +23,18 @@
 .coverage
 \#*
 .#*
+.cache
 lib/spack/spack/test/.cache
 /bin/spackc
 *.in.log
 *.out.log
 *.orig
+
+# Eclipse files
+.project
+.cproject
+.pydevproject
+
+# VSCode files
+.vscode
+.devcontainer

.mailmap

@@ -20,8 +20,8 @@ Geoffrey Oxberry      <oxberry1@llnl.gov>               Geoffrey Oxberry
 Glenn Johnson         <glenn-johnson@uiowa.edu>         Glenn Johnson           <gjohnson@argon-ohpc.hpc.uiowa.edu>
 Glenn Johnson         <glenn-johnson@uiowa.edu>         Glenn Johnson           <glennpj@gmail.com>
 Gregory Becker        <becker33@llnl.gov>               Gregory Becker          <becker33.llnl.gov>
-Gregory Becker        <becker33@llnl.gov>               becker33                <becker33.llnl.gov>
-Gregory Becker        <becker33@llnl.gov>               becker33                <becker33@llnl.gov>
+Gregory Becker        <becker33@llnl.gov>               Gregory Becker          <becker33.llnl.gov>
+Gregory Becker        <becker33@llnl.gov>               Gregory Becker          <becker33@llnl.gov>
 Gregory L. Lee        <lee218@llnl.gov>                 Greg Lee                <lee218@llnl.gov>
 Gregory L. Lee        <lee218@llnl.gov>                 Gregory L. Lee          <lee218@cab687.llnl.gov>
 Gregory L. Lee        <lee218@llnl.gov>                 Gregory L. Lee          <lee218@cab690.llnl.gov>

.travis.yml

@@ -1,168 +0,0 @@
-#=============================================================================
-# Project settings
-#=============================================================================
-# Only build master and develop on push; do not build every branch.
-branches:
-  only:
-    - master
-    - develop
-    - /^releases\/.*$/
-
-#=============================================================================
-# Build matrix
-#=============================================================================
-
-dist: xenial
-
-jobs:
-  fast_finish: true
-  include:
-    - stage: 'style checks'
-      python: '3.8'
-      os: linux
-      language: python
-      env: TEST_SUITE=flake8
-# Shell integration with module files
-    - python: '3.8'
-      os: linux
-      language: python
-      env: [ TEST_SUITE=bootstrap ]
-    - stage: 'unit tests + documentation'
-      python: '2.6'
-      dist: trusty
-      os: linux
-      language: python
-      env: [ TEST_SUITE=unit, COVERAGE=true ]
-    - python: '2.7'
-      os: linux
-      language: python
-      env: [ TEST_SUITE=unit, COVERAGE=true ]
-    - python: '3.5'
-      os: linux
-      language: python
-      env: TEST_SUITE=unit
-    - python: '3.6'
-      os: linux
-      language: python
-      env: TEST_SUITE=unit
-    - python: '3.7'
-      os: linux
-      language: python
-      env: TEST_SUITE=unit
-    - python: '3.8'
-      os: linux
-      language: python
-      env: [ TEST_SUITE=unit, COVERAGE=true ]
-    - python: '3.8'
-      os: linux
-      language: python
-      env: TEST_SUITE=doc
-    - os: osx
-      language: generic
-      env: [ TEST_SUITE=unit, PYTHON_VERSION=2.7, COVERAGE=true ]
-      if: type != pull_request
-
-stages:
-  - 'style checks'
-  - 'unit tests + documentation'
-
-
-#=============================================================================
-# Environment
-#=============================================================================
-
-# Docs need graphviz to build
-addons:
-  # for Linux builds, we use APT
-  apt:
-    packages:
-      - ccache
-      - cmake
-      - gfortran
-      - graphviz
-      - gnupg2
-      - kcov
-      - mercurial
-      - ninja-build
-      - perl
-      - perl-base
-      - realpath
-      - r-base
-      - r-base-core
-      - r-base-dev
-      - zsh
-  # for Mac builds, we use Homebrew
-  homebrew:
-    packages:
-      - python@2
-      - gcc
-      - gnupg2
-      - ccache
-      - dash
-      - kcov
-    update: true
-
-# ~/.ccache needs to be cached directly as Travis is not taking care of it
-# (possibly because we use 'language: python' and not 'language: c')
-cache:
-  pip: true
-  ccache: true
-  directories:
-    - ~/.ccache
-
-# Work around Travis's lack of support for Python on OSX
-before_install:
-  - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
-        pip2 install --upgrade pip;
-        pip2 install virtualenv;
-        virtualenv venv;
-        source venv/bin/activate;
-    fi
-  - ccache -M 2G && ccache -z
-
-# Install various dependencies
-install:
-  - pip install --upgrade pip
-  - pip install --upgrade six
-  - pip install --upgrade setuptools
-  - pip install --upgrade codecov coverage==4.5.4
-  - pip install --upgrade flake8
-  - pip install --upgrade pep8-naming
-  - if [[ "$TEST_SUITE" == "doc" ]]; then
-        pip install --upgrade -r lib/spack/docs/requirements.txt;
-    fi
-
-before_script:
-  # Need this for the git tests to succeed.
-  - git config --global user.email "spack@example.com"
-  - git config --global user.name "Test User"
-
-  # Need this to be able to compute the list of changed files
-  - git fetch origin ${TRAVIS_BRANCH}:${TRAVIS_BRANCH}
-
-#=============================================================================
-# Building
-#=============================================================================
-script:
-  - share/spack/qa/run-$TEST_SUITE-tests
-
-after_success:
-  - ccache -s
-  - case "$TEST_SUITE" in
-        unit)
-            if [[ "$COVERAGE" == "true" ]]; then
-                codecov --env PYTHON_VERSION
-                        --required
-                        --flags "${TEST_SUITE}${TRAVIS_OS_NAME}";
-            fi
-            ;;
-    esac
-
-#=============================================================================
-# Notifications
-#=============================================================================
-notifications:
-  email:
-    recipients: tgamblin@llnl.gov
-    on_success: change
-    on_failure: always

CHANGELOG.md

@@ -1,3 +1,285 @@
+# v0.15.4 (2020-08-12)
+
+This release contains one feature addition:
+
+* Users can set `SPACK_GNUPGHOME` to override Spack's GPG path (#17139)
+
+Several bugfixes for CUDA, binary packaging, and `spack -V`:
+
+* CUDA package's `.libs` method searches for `libcudart` instead of `libcuda` (#18000)
+* Don't set `CUDAHOSTCXX` in environments that contain CUDA (#17826)
+* `buildcache create`: `NoOverwriteException` is a warning, not an error (#17832)
+* Fix `spack buildcache list --allarch` (#17884)
+* `spack -V` works with `releases/latest` tag and shallow clones (#17884)
+
+And fixes for GitHub Actions and tests to ensure that CI passes on the
+release branch (#15687, #17279, #17328, #17377, #17732).
+
+# v0.15.3 (2020-07-28)
+
+This release contains the following bugfixes:
+
+* Fix handling of relative view paths (#17721)
+* Fixes for binary relocation (#17418, #17455)
+* Fix redundant printing of error messages in build environment (#17709)
+
+It also adds a support script for Spack tutorials:
+
+* Add a tutorial setup script to share/spack (#17705, #17722)
+
+# v0.15.2 (2020-07-23)
+
+This minor release includes two new features:
+
+* Spack install verbosity is decreased, and more debug levels are added (#17546)
+* The $spack/share/spack/keys directory contains public keys that may be optionally trusted for public binary mirrors (#17684)
+
+This release also includes several important fixes:
+
+* MPICC and related variables are now cleand in the build environment (#17450)
+* LLVM flang only builds CUDA offload components when +cuda (#17466)
+* CI pipelines no longer upload user environments that can contain secrets to the internet (#17545)
+* CI pipelines add bootstrapped compilers to the compiler config (#17536)
+* `spack buildcache list` does not exit on first failure and lists later mirrors (#17565)
+* Apple's "gcc" executable that is an apple-clang compiler does not generate a gcc compiler config (#17589)
+* Mixed compiler toolchains are merged more naturally across different compiler suffixes (#17590)
+* Cray Shasta platforms detect the OS properly (#17467)
+* Additional more minor fixes.
+
+# v0.15.1 (2020-07-10)
+
+This minor release includes several important fixes:
+
+* Fix shell support on Cray (#17386)
+* Fix use of externals installed with other Spack instances (#16954)
+* Fix gcc+binutils build (#9024)
+* Fixes for usage of intel-mpi (#17378 and #17382)
+* Fixes to Autotools config.guess detection (#17333 and #17356)
+* Update `spack install` message to prompt user when an environment is not
+  explicitly activated (#17454)
+
+This release also adds a mirror for all sources that are
+fetched in Spack (#17077). It is expected to be useful when the
+official website for a Spack package is unavailable.
+
+# v0.15.0 (2020-06-28)
+
+`v0.15.0` is a major feature release.
+
+## Major Features in this release
+
+1. **Cray support** Spack will now work properly on Cray "Cluster"
+systems (non XC systems) and after a `module purge` command on Cray
+systems. See #12989
+
+2. **Virtual package configuration** Virtual packages are allowed in
+packages.yaml configuration. This allows users to specify a virtual
+package as non-buildable without needing to specify for each
+implementation. See #14934
+
+3. **New config subcommands** This release adds `spack config add` and
+`spack config remove` commands to add to and remove from yaml
+configuration files from the CLI. See #13920
+
+4. **Environment activation** Anonymous environments are **no longer**
+automatically activated in the current working directory. To activate
+an environment from a `spack.yaml` file in the current directory, use
+the `spack env activate .` command. This removes a concern that users
+were too easily polluting their anonymous environments with accidental
+installations. See #17258
+
+5. **Apple clang compiler** The clang compiler and the apple-clang
+compiler are now separate compilers in Spack. This allows Spack to
+improve support for the apple-clang compiler. See #17110
+
+6. **Finding external packages** Spack packages can now support an API
+for finding external installations. This allows the `spack external
+find` command to automatically add installations of those packages to
+the user's configuration. See #15158
+
+
+## Additional new features of note
+
+* support for using Spack with the fish shell (#9279)
+* `spack load --first` option to load first match (instead of prompting user) (#15622)
+* support the Cray cce compiler both new and classic versions (#17256, #12989)
+* `spack dev-build` command:
+  * supports stopping before a specified phase (#14699)
+  * supports automatically launching a shell in the build environment (#14887)
+* `spack install --fail-fast` allows builds to fail at the first error (rather than best-effort) (#15295)
+* environments: SpecList references can be dereferenced as compiler or dependency constraints (#15245)
+* `spack view` command: new support for a copy/relocate view type (#16480)
+* ci pipelines: see documentation for several improvements
+* `spack mirror -a` command now supports excluding packages (#14154)
+* `spack buildcache create` is now environment-aware (#16580)
+* module generation: more flexible format for specifying naming schemes (#16629)
+* lmod module generation: packages can be configured as core specs for lmod hierarchy (#16517)
+
+## Deprecations and Removals
+
+The following commands were deprecated in v0.13.0, and have now been removed:
+
+* `spack configure`
+* `spack build`
+* `spack diy`
+
+The following commands were deprecated in v0.14.0, and will be removed in the next major release:
+
+* `spack bootstrap`
+
+## Bugfixes
+
+Some of the most notable bugfixes in this release include:
+
+* Spack environments can now contain the string `-h` (#15429)
+* The `spack install` gracefully handles being backgrounded (#15723, #14682)
+* Spack uses `-isystem` instead of `-I` in cases that the underlying build system does as well (#16077)
+* Spack no longer prints any specs that cannot be safely copied into a Spack command (#16462)
+* Incomplete Spack environments containing python no longer cause problems (#16473)
+* Several improvements to binary package relocation
+
+## Package Improvements
+
+The Spack project is constantly engaged in routine maintenance,
+bugfixes, and improvements for the package ecosystem. Of particular
+note in this release are the following:
+
+* Spack now contains 4339 packages. There are 430 newly supported packages in v0.15.0
+* GCC now builds properly on ARM architectures (#17280)
+* Python: patched to support compiling mixed C/C++ python modules through distutils (#16856)
+* improvements to pytorch and py-tensorflow packages
+* improvements to major MPI implementations: mvapich2, mpich, openmpi, and others
+
+## Spack Project Management:
+
+* Much of the Spack CI infrastructure has moved from Travis to GitHub Actions (#16610, #14220, #16345)
+* All merges to the `develop` branch run E4S CI pipeline (#16338)
+* New `spack debug report` command makes reporting bugs easier (#15834)
+
+# v0.14.2 (2020-04-15)
+
+This is a minor release on the `0.14` series. It includes performance
+improvements and bug fixes:
+
+* Improvements to how `spack install` handles foreground/background (#15723)
+* Major performance improvements for reading the package DB (#14693, #15777)
+* No longer check for the old `index.yaml` database file (#15298)
+* Properly activate environments with '-h' in the name (#15429)
+* External packages have correct `.prefix` in environments/views (#15475)
+* Improvements to computing env modifications from sourcing files (#15791)
+* Bugfix on Cray machines when getting `TERM` env variable (#15630)
+* Avoid adding spurious `LMOD` env vars to Intel modules (#15778)
+* Don't output [+] for mock installs run during tests (#15609)
+
+# v0.14.1 (2020-03-20)
+
+This is a bugfix release on top of `v0.14.0`.  Specific fixes include:
+
+* several bugfixes for parallel installation (#15339, #15341, #15220, #15197)
+* `spack load` now works with packages that have been renamed (#14348)
+* bugfix for `suite-sparse` installation (#15326)
+* deduplicate identical suffixes added to module names (#14920)
+* fix issues with `configure_args` during module refresh (#11084)
+* increased test coverage and test fixes (#15237, #15354, #15346)
+* remove some unused code (#15431)
+
+# v0.14.0 (2020-02-23)
+
+`v0.14.0` is a major feature release, with 3 highlighted features:
+
+1. **Distributed builds.** Multiple Spack instances will now coordinate
+   properly with each other through locks. This works on a single node
+   (where you've called `spack` several times) or across multiple nodes
+   with a shared filesystem. For example, with SLURM, you could build
+   `trilinos` and its dependencies on 2 24-core nodes, with 3 Spack
+   instances per node and 8 build jobs per instance, with `srun -N 2 -n 6
+   spack install -j 8 trilinos`. This requires a filesystem with locking
+   enabled, but not MPI or any other library for parallelism.
+
+2.  **Build pipelines.** You can also build in parallel through Gitlab
+   CI. Simply create a Spack environment and push it to Gitlab to build
+   on Gitlab runners. Pipeline support is now integrated into a single
+   `spack ci` command, so setting it up is easier than ever.  See the
+   [Pipelines section](https://spack.readthedocs.io/en/v0.14.0/pipelines.html)
+   in the docs.
+
+3. **Container builds.** The new `spack containerize` command allows you
+   to create a Docker or Singularity recipe from any Spack environment.
+   There are options to customize the build if you need them. See the
+   [Container Images section](https://spack.readthedocs.io/en/latest/containers.html)
+   in the docs.
+
+In addition, there are several other new commands, many bugfixes and
+improvements, and `spack load` no longer requires modules, so you can use
+it the same way on your laptop or on your supercomputer.
+
+Spack grew by over 300 packages since our last release in November 2019,
+and the project grew to over 500 contributors.  Thanks to all of you for
+making yet another great release possible. Detailed notes below.
+
+## Major new core features
+* Distributed builds: spack instances coordinate and build in parallel (#13100)
+* New `spack ci` command to manage CI pipelines (#12854)
+* Generate container recipes from environments: `spack containerize` (#14202)
+* `spack load` now works without using modules (#14062, #14628)
+* Garbage collect old/unused installations with `spack gc` (#13534)
+* Configuration files all set environment modifications the same way (#14372,
+  [docs](https://spack.readthedocs.io/en/v0.14.0/configuration.html#environment-modifications))
+* `spack commands --format=bash` auto-generates completion (#14393, #14607)
+* Packages can specify alternate fetch URLs in case one fails (#13881)
+
+## Improvements
+* Improved locking for concurrency with environments (#14676, #14621, #14692)
+* `spack test` sends args to `pytest`, supports better listing (#14319)
+* Better support for aarch64 and cascadelake microarch (#13825, #13780, #13820)
+* Archspec is now a separate library (see https://github.com/archspec/archspec)
+* Many improvements to the `spack buildcache` command (#14237, #14346,
+  #14466, #14467, #14639, #14642, #14659, #14696, #14698, #14714, #14732,
+  #14929, #15003, #15086, #15134)
+
+## Selected Bugfixes
+* Compilers now require an exact match on version (#8735, #14730, #14752)
+* Bugfix for patches that specified specific versions (#13989)
+* `spack find -p` now works in environments (#10019, #13972)
+* Dependency queries work correctly in `spack find` (#14757)
+* Bugfixes for locking upstream Spack instances chains (#13364)
+* Fixes for PowerPC clang optimization flags (#14196)
+* Fix for issue with compilers and specific microarchitectures (#13733, #14798)
+
+## New commands and options
+* `spack ci` (#12854)
+* `spack containerize` (#14202)
+* `spack gc` (#13534)
+* `spack load` accepts `--only package`, `--only dependencies` (#14062, #14628)
+* `spack commands --format=bash` (#14393)
+* `spack commands --update-completion` (#14607)
+* `spack install --with-cache` has new option: `--no-check-signature` (#11107)
+* `spack test` now has `--list`, `--list-long`, and `--list-names` (#14319)
+* `spack install --help-cdash` moves CDash help out of the main help (#13704)
+
+## Deprecations
+* `spack release-jobs` has been rolled into `spack ci`
+* `spack bootstrap` will be removed in a future version, as it is no longer
+  needed to set up modules (see `spack load` improvements above)
+
+## Documentation
+* New section on building container images with Spack (see
+  [docs](https://spack.readthedocs.io/en/latest/containers.html))
+* New section on using `spack ci` command to build pipelines (see
+  [docs](https://spack.readthedocs.io/en/latest/pipelines.html))
+* Document how to add conditional dependencies (#14694)
+* Document how to use Spack to replace Homebrew/Conda (#13083, see
+  [docs](https://spack.readthedocs.io/en/latest/workflows.html#using-spack-to-replace-homebrew-conda))
+
+## Important package changes
+* 3,908 total packages (345 added since 0.13.0)
+* Added first cut at a TensorFlow package (#13112)
+* We now build R without "recommended" packages, manage them w/Spack (#12015)
+* Elpa and OpenBLAS now leverage microarchitecture support (#13655, #14380)
+* Fix `octave` compiler wrapper usage (#14726)
+* Enforce that packages in `builtin` aren't missing dependencies (#13949)
+
+
 # v0.13.4 (2020-02-07)
 
 This release contains several bugfixes:
@@ -16,8 +298,8 @@ RHEL8.
 * mirror bugfixes: symlinks, duplicate patches, and exception handling (#13789)
 * don't try to fetch `BundlePackages` (#13908)
 * avoid re-fetching patches already added to a mirror (#13908)
-* avoid re-fetching alread added patches (#13908)
-* avoid re-fetching alread added patches (#13908)
+* avoid re-fetching already added patches (#13908)
+* avoid re-fetching already added patches (#13908)
 * allow repeated invocations of `spack mirror create` on the same dir (#13908)
 * bugfix for RHEL8 when `python` is unavailable (#14252)
 * improve concretization performance in environments (#14190)

LICENSE-MIT

@@ -1,20 +1,21 @@
-Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
-Spack Project Developers. See the top-level COPYRIGHT file for details.
+MIT License
 
-Permission is hereby granted, free of charge, to any person obtaining a
-copy of this software and associated documentation files (the "Software"),
-to deal in the Software without restriction, including without limitation
-the rights to use, copy, modify, merge, publish, distribute, sublicense,
-and/or sell copies of the Software, and to permit persons to whom the
-Software is furnished to do so, subject to the following conditions:
+Copyright (c) 2013-2020 LLNS, LLC and other Spack Project Developers.
 
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
-DEALINGS IN THE SOFTWARE.
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,7 +1,9 @@
 # <img src="https://cdn.rawgit.com/spack/spack/develop/share/spack/logo/spack-logo.svg" width="64" valign="middle" alt="Spack"/> Spack
 
-[![Build Status](https://travis-ci.org/spack/spack.svg?branch=develop)](https://travis-ci.org/spack/spack)
+[![MacOS Tests](https://github.com/spack/spack/workflows/macos%20tests/badge.svg)](https://github.com/spack/spack/actions)
+[![Linux Tests](https://github.com/spack/spack/workflows/linux%20tests/badge.svg)](https://github.com/spack/spack/actions)
 [![Linux Builds](https://github.com/spack/spack/workflows/linux%20builds/badge.svg)](https://github.com/spack/spack/actions)
+[![macOS Builds (nightly)](https://github.com/spack/spack/workflows/macOS%20builds%20nightly/badge.svg?branch=develop)](https://github.com/spack/spack/actions?query=workflow%3A%22macOS+builds+nightly%22)
 [![codecov](https://codecov.io/gh/spack/spack/branch/develop/graph/badge.svg)](https://codecov.io/gh/spack/spack)
 [![Read the Docs](https://readthedocs.org/projects/spack/badge/?version=latest)](https://spack.readthedocs.io)
 [![Slack](https://spackpm.herokuapp.com/badge.svg)](https://spackpm.herokuapp.com)
@@ -71,15 +73,33 @@ When you send your request, make ``develop`` the destination branch on the
 
 Your PR must pass Spack's unit tests and documentation tests, and must be
 [PEP 8](https://www.python.org/dev/peps/pep-0008/) compliant.  We enforce
-these guidelines with [Travis CI](https://travis-ci.org/spack/spack).  To
-run these tests locally, and for helpful tips on git, see our
+these guidelines with our CI process. To run these tests locally, and for 
+helpful tips on git, see our
 [Contribution Guide](http://spack.readthedocs.io/en/latest/contribution_guide.html).
 
-Spack uses a rough approximation of the
-[Git Flow](http://nvie.com/posts/a-successful-git-branching-model/)
-branching model.  The ``develop`` branch contains the latest
-contributions, and ``master`` is always tagged and points to the latest
-stable release.
+Spack's `develop` branch has the latest contributions. Pull requests
+should target `develop`, and users who want the latest package versions,
+features, etc. can use `develop`.
+
+Releases
+--------
+
+For multi-user site deployments or other use cases that need very stable
+software installations, we recommend using Spack's
+[stable releases](https://github.com/spack/spack/releases).
+
+Each Spack release series also has a corresponding branch, e.g.
+`releases/v0.14` has `0.14.x` versions of Spack, and `releases/v0.13` has
+`0.13.x` versions. We backport important bug fixes to these branches but
+we do not advance the package versions or make other changes that would
+change the way Spack concretizes dependencies within a release branch.
+So, you can base your Spack deployment on a release branch and `git pull`
+to get fixes, without the package churn that comes with `develop`.
+
+The latest release is always available with the `releases/latest` tag.
+
+See the [docs on releases](https://spack.readthedocs.io/en/latest/developer_guide.html#releases)
+for more details.
 
 Code of Conduct
 ------------------------
@@ -120,4 +140,4 @@ See [LICENSE-MIT](https://github.com/spack/spack/blob/develop/LICENSE-MIT),
 
 SPDX-License-Identifier: (Apache-2.0 OR MIT)
 
-LLNL-CODE-647188
+LLNL-CODE-811652

bin/spack-python

@@ -22,4 +22,4 @@
 #
 # This is compatible across platforms.
 #
-/usr/bin/env spack python "$@"
+exec /usr/bin/env spack python "$@"

etc/spack/defaults/config.yaml

@@ -16,7 +16,7 @@
 config:
   # This is the path to the root of the Spack install tree.
   # You can use $spack here to refer to the root of the spack instance.
-  install_tree: ~/.spack/opt/spack
+  install_tree: $spack/opt/spack
 
 
   # Locations where templates should be found
@@ -30,8 +30,8 @@ config:
 
   # Locations where different types of modules should be installed.
   module_roots:
-    tcl:    ~/.spack/share/spack/modules
-    lmod:   ~/.spack/share/spack/lmod
+    tcl:    $spack/share/spack/modules
+    lmod:   $spack/share/spack/lmod
 
 
   # Temporary locations Spack can try to use for builds.
@@ -64,10 +64,14 @@ config:
     - ~/.spack/stage
   # - $spack/var/spack/stage
 
+  # Directory in which to run tests and store test results.
+  # Tests will be stored in directories named by date/time and package
+  # name/hash.
+  test_stage: ~/.spack/test
 
   # Cache directory for already downloaded source tarballs and archived
   # repositories. This can be purged with `spack clean --downloads`.
-  source_cache: ~/.spack/var/spack/cache
+  source_cache: $spack/var/spack/cache
 
 
   # Cache directory for miscellaneous files, like the package index.
@@ -75,6 +79,12 @@ config:
   misc_cache: ~/.spack/cache
 
 
+  # Timeout in seconds used for downloading sources etc. This only applies
+  # to the connection phase and can be increased for slow connections or
+  # servers. 0 means no timeout.
+  connect_timeout: 10
+
+
   # If this is false, tools like curl that use SSL will not verify
   # certifiates. (e.g., curl will use use the -k option)
   verify_ssl: true
@@ -137,7 +147,7 @@ config:
   # when Spack needs to manage its own package metadata and all operations are
   # expected to complete within the default time limit. The timeout should
   # therefore generally be left untouched.
-  db_lock_timeout: 120
+  db_lock_timeout: 3
 
 
   # How long to wait when attempting to modify a package (e.g. to install it).
@@ -151,3 +161,7 @@ config:
   # Has no effect on macOS. DO NOT MIX these within the same install tree.
   # See the Spack documentation for details.
   shared_linking: 'rpath'
+
+  # Set to 'false' to allow installation on filesystems that doesn't allow setgid bit
+  # manipulation by unprivileged user (e.g. AFS)
+  allow_sgid: true

etc/spack/defaults/darwin/modules.yaml

@@ -16,8 +16,6 @@
 modules:
   prefix_inspections:
     lib:
-      - DYLD_LIBRARY_PATH
       - DYLD_FALLBACK_LIBRARY_PATH
     lib64:
-      - DYLD_LIBRARY_PATH
       - DYLD_FALLBACK_LIBRARY_PATH

etc/spack/defaults/darwin/packages.yaml

@@ -15,13 +15,20 @@
 # -------------------------------------------------------------------------
 packages:
   all:
-    compiler: [clang, gcc, intel]
+    compiler:
+    - apple-clang
+    - clang
+    - gcc
+    - intel
     providers:
-      elf: [libelf]
-      unwind: [apple-libunwind]
+      elf:
+      - libelf
+      unwind:
+      - apple-libunwind
   apple-libunwind:
-    paths:
+    buildable: false
+    externals:
     # Apple bundles libunwind version 35.3 with macOS 10.9 and later,
     # although the version number used here isn't critical
-      apple-libunwind@35.3: /usr
-    buildable: False
+    - spec: apple-libunwind@35.3
+      prefix: /usr

etc/spack/defaults/mirrors.yaml

@@ -0,0 +1,2 @@
+mirrors:
+  spack-public: https://spack-llnl-mirror.s3-us-west-2.amazonaws.com/

etc/spack/defaults/modules.yaml

@@ -30,7 +30,11 @@ modules:
     lib64:
       - LIBRARY_PATH
     include:
-      - CPATH
+      - C_INCLUDE_PATH
+      - CPLUS_INCLUDE_PATH
+      # The INCLUDE env variable specifies paths to look for
+      # .mod file for Intel Fortran compilers
+      - INCLUDE
     lib/pkgconfig:
       - PKG_CONFIG_PATH
     lib64/pkgconfig:

etc/spack/defaults/packages.yaml

@@ -27,6 +27,7 @@ packages:
       glx: [mesa+glx, opengl]
       glu: [mesa-glu, openglu]
       golang: [gcc]
+      iconv: [libiconv]
       ipp: [intel-ipp]
       java: [openjdk, jdk, ibm-java]
       jpeg: [libjpeg-turbo, libjpeg]
@@ -37,12 +38,15 @@ packages:
       mpi: [openmpi, mpich]
       mysql-client: [mysql, mariadb-c-client]
       opencl: [pocl]
-      pil: [py-pillow]
+      pil: [py-pillow-simd]
       pkgconfig: [pkgconf, pkg-config]
+      rpc: [libtirpc]
       scalapack: [netlib-scalapack]
+      sycl: [hipsycl]
       szip: [libszip, libaec]
       tbb: [intel-tbb]
       unwind: [libunwind]
+      sycl: [hipsycl]
     permissions:
       read: world
       write: user

etc/spack/defaults/upstreams.yaml

@@ -1,7 +0,0 @@
-upstreams:
-  global:
-    install_tree: $spack/opt/spack
-    modules:
-      tcl:    $spack/share/spack/modules
-      lmod:   $spack/share/spack/lmod
-      dotkit: $spack/share/spack/dotkit

lib/spack/docs/basic_usage.rst

@@ -25,6 +25,14 @@ It is recommended that the following be put in your ``.bashrc`` file:
 
     alias less='less -R'
 
+If you do not see colorized output when using ``less -R`` it is because color
+is being disabled in the piped output. In this case, tell spack to force
+colorized output.
+
+.. code-block:: console
+
+    $ spack --color always | less -R 
+
 --------------------------
 Listing available packages
 --------------------------
@@ -45,7 +53,7 @@ can install:
 .. command-output:: spack list
    :ellipsis: 10
 
-There are thosands of them, so we've truncated the output above, but you
+There are thousands of them, so we've truncated the output above, but you
 can find a :ref:`full list here <package-list>`.
 Packages are listed by name in alphabetical order.
 A pattern to match with no wildcards, ``*`` or ``?``,
@@ -267,7 +275,7 @@ the ``spack gc`` ("garbage collector") command, which will uninstall all unneede
    -- linux-ubuntu18.04-broadwell / gcc@9.0.1 ----------------------
    hdf5@1.10.5  libiconv@1.16  libpciaccess@0.13.5  libszip@2.1.1  libxml2@2.9.9  mpich@3.3.2  openjpeg@2.3.1  xz@5.2.4  zlib@1.2.11
 
-In the example above Spack went through all the packages in the DB
+In the example above Spack went through all the packages in the package database
 and removed everything that is not either:
 
 1. A package installed upon explicit request of the user
@@ -619,8 +627,8 @@ output metadata on specs and all dependencies as json:
        "target": "x86_64"
       },
       "compiler": {
-       "name": "clang",
-       "version": "10.0.0-apple"
+       "name": "apple-clang",
+       "version": "10.0.0"
       },
       "namespace": "builtin",
       "parameters": {
@@ -687,11 +695,11 @@ Here is an example of a much longer spec than we've seen thus far:
 
 .. code-block:: none
 
-   mpileaks @1.2:1.4 %gcc@4.7.5 +debug -qt arch=bgq_os ^callpath @1.1 %gcc@4.7.2
+   mpileaks @1.2:1.4 %gcc@4.7.5 +debug -qt target=x86_64 ^callpath @1.1 %gcc@4.7.2
 
 If provided to ``spack install``, this will install the ``mpileaks``
 library at some version between ``1.2`` and ``1.4`` (inclusive),
-built using ``gcc`` at version 4.7.5 for the Blue Gene/Q architecture,
+built using ``gcc`` at version 4.7.5 for a generic ``x86_64`` architecture,
 with debug options enabled, and without Qt support.  Additionally, it
 says to link it with the ``callpath`` library (which it depends on),
 and to build callpath with ``gcc`` 4.7.2.  Most specs will not be as
@@ -854,7 +862,7 @@ Variants are named options associated with a particular package. They are
 optional, as each package must provide default values for each variant it
 makes available. Variants can be specified using
 a flexible parameter syntax ``name=<value>``. For example,
-``spack install libelf debug=True`` will install libelf build with debug
+``spack install libelf debug=True`` will install libelf built with debug
 flags. The names of particular variants available for a package depend on
 what was provided by the package author. ``spack info <package>`` will
 provide information on what build variants are available.
@@ -917,7 +925,7 @@ contains any spaces. Any of ``cppflags=-O3``, ``cppflags="-O3"``,
 ``cppflags='-O3'``, and ``cppflags="-O3 -fPIC"`` are acceptable, but
 ``cppflags=-O3 -fPIC`` is not. Additionally, if the value of the
 compiler flags is not the last thing on the line, it must be followed
-by a space. The commmand ``spack install libelf cppflags="-O3"%intel``
+by a space. The command ``spack install libelf cppflags="-O3"%intel``
 will be interpreted as an attempt to set ``cppflags="-O3%intel"``.
 
 The six compiler flags are injected in the order of implicit make commands
@@ -1067,13 +1075,13 @@ of failing:
 In the snippet above, for instance, the microarchitecture was demoted to ``haswell`` when
 compiling with ``gcc@4.8`` since support to optimize for ``broadwell`` starts from ``gcc@4.9:``.
 
-Finally if Spack has no information to match compiler and target, it will
+Finally, if Spack has no information to match compiler and target, it will
 proceed with the installation but avoid injecting any microarchitecture
 specific flags.
 
 .. warning::
 
-   Currently Spack doesn't print any warning to the user if it has no information
+   Currently, Spack doesn't print any warning to the user if it has no information
    on which optimization flags should be used for a given compiler. This behavior
    might change in the future.
 
@@ -1083,7 +1091,7 @@ specific flags.
 Virtual dependencies
 --------------------
 
-The dependence graph for ``mpileaks`` we saw above wasn't *quite*
+The dependency graph for ``mpileaks`` we saw above wasn't *quite*
 accurate.  ``mpileaks`` uses MPI, which is an interface that has many
 different implementations.  Above, we showed ``mpileaks`` and
 ``callpath`` depending on ``mpich``, which is one *particular*
@@ -1226,6 +1234,8 @@ add a version specifier to the spec:
 Notice that the package versions that provide insufficient MPI
 versions are now filtered out.
 
+.. _extensions:
+
 ---------------------------
 Extensions & Python support
 ---------------------------
@@ -1233,8 +1243,7 @@ Extensions & Python support
 Spack's installation model assumes that each package will live in its
 own install prefix.  However, certain packages are typically installed
 *within* the directory hierarchy of other packages.  For example,
-modules in interpreted languages like `Python
-<https://www.python.org>`_ are typically installed in the
+`Python <https://www.python.org>`_ packages are typically installed in the
 ``$prefix/lib/python-2.7/site-packages`` directory.
 
 Spack has support for this type of installation as well.  In Spack,
@@ -1410,12 +1419,12 @@ packages listed as activated:
    py-nose@1.3.4  py-numpy@1.9.1  py-setuptools@11.3.1
 
 Now, when a user runs python, ``numpy`` will be available for import
-*without* the user having to explicitly loaded.  ``python@2.7.8`` now
+*without* the user having to explicitly load it.  ``python@2.7.8`` now
 acts like a system Python installation with ``numpy`` installed inside
 of it.
 
 Spack accomplishes this by symbolically linking the *entire* prefix of
-the ``py-numpy`` into the prefix of the ``python`` package.  To the
+the ``py-numpy`` package into the prefix of the ``python`` package.  To the
 python interpreter, it looks like ``numpy`` is installed in the
 ``site-packages`` directory.
 

lib/spack/docs/binary_caches.rst

@@ -57,6 +57,12 @@ Build caches are installed via:
 
    $ spack buildcache install
 
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+List of popular build caches
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* `Extreme-scale Scientific Software Stack (E4S) <https://e4s-project.github.io/>`_: `build cache <https://oaciss.uoregon.edu/e4s/inventory.html>`_
+
 
 ----------
 Relocation

lib/spack/docs/build_settings.rst

@@ -57,10 +57,13 @@ directory. Here's an example of an external configuration:
 
    packages:
      openmpi:
-       paths:
-         openmpi@1.4.3%gcc@4.4.7 arch=linux-x86_64-debian7: /opt/openmpi-1.4.3
-         openmpi@1.4.3%gcc@4.4.7 arch=linux-x86_64-debian7+debug: /opt/openmpi-1.4.3-debug
-         openmpi@1.6.5%intel@10.1 arch=linux-x86_64-debian7: /opt/openmpi-1.6.5-intel
+       externals:
+       - spec: "openmpi@1.4.3%gcc@4.4.7 arch=linux-debian7-x86_64"
+         prefix: /opt/openmpi-1.4.3
+       - spec: "openmpi@1.4.3%gcc@4.4.7 arch=linux-debian7-x86_64+debug"
+         prefix: /opt/openmpi-1.4.3-debug
+       - spec: "openmpi@1.6.5%intel@10.1 arch=linux-debian7-x86_64"
+         prefix: /opt/openmpi-1.6.5-intel
 
 This example lists three installations of OpenMPI, one built with GCC,
 one built with GCC and debug information, and another built with Intel.
@@ -76,13 +79,15 @@ of the installation prefixes.  The following example says that module
 .. code-block:: yaml
 
    cmake:
-     modules:
-       cmake@3.7.2: CMake/3.7.2
+     externals:
+     - spec: cmake@3.7.2
+       modules:
+       - CMake/3.7.2
 
-Each ``packages.yaml`` begins with a ``packages:`` token, followed
-by a list of package names.  To specify externals, add a ``paths`` or ``modules``
-token under the package name, which lists externals in a
-``spec: /path`` or ``spec: module-name`` format.  Each spec should be as
+Each ``packages.yaml`` begins with a ``packages:`` attribute, followed
+by a list of package names.  To specify externals, add an ``externals:``
+attribute under the package name, which lists externals.
+Each external should specify a ``spec:`` string that should be as
 well-defined as reasonably possible.  If a
 package lacks a spec component, such as missing a compiler or
 package version, then Spack will guess the missing component based
@@ -106,10 +111,13 @@ be:
 
    packages:
      openmpi:
-       paths:
-         openmpi@1.4.3%gcc@4.4.7 arch=linux-x86_64-debian7: /opt/openmpi-1.4.3
-         openmpi@1.4.3%gcc@4.4.7 arch=linux-x86_64-debian7+debug: /opt/openmpi-1.4.3-debug
-         openmpi@1.6.5%intel@10.1 arch=linux-x86_64-debian7: /opt/openmpi-1.6.5-intel
+       externals:
+       - spec: "openmpi@1.4.3%gcc@4.4.7 arch=linux-debian7-x86_64"
+         prefix: /opt/openmpi-1.4.3
+       - spec: "openmpi@1.4.3%gcc@4.4.7 arch=linux-debian7-x86_64+debug"
+         prefix: /opt/openmpi-1.4.3-debug
+       - spec: "openmpi@1.6.5%intel@10.1 arch=linux-debian7-x86_64"
+         prefix: /opt/openmpi-1.6.5-intel
        buildable: False
 
 The addition of the ``buildable`` flag tells Spack that it should never build
@@ -124,6 +132,82 @@ The ``buildable`` does not need to be paired with external packages.
 It could also be used alone to forbid packages that may be
 buggy or otherwise undesirable.
 
+Virtual packages in Spack can also be specified as not buildable, and
+external implementations can be provided. In the example above,
+OpenMPI is configured as not buildable, but Spack will often prefer
+other MPI implementations over the externally available OpenMPI. Spack
+can be configured with every MPI provider not buildable individually,
+but more conveniently:
+
+.. code-block:: yaml
+
+   packages:
+     mpi:
+       buildable: False
+     openmpi:
+       externals:
+       - spec: "openmpi@1.4.3%gcc@4.4.7 arch=linux-debian7-x86_64"
+         prefix: /opt/openmpi-1.4.3
+       - spec: "openmpi@1.4.3%gcc@4.4.7 arch=linux-debian7-x86_64+debug"
+         prefix: /opt/openmpi-1.4.3-debug
+       - spec: "openmpi@1.6.5%intel@10.1 arch=linux-debian7-x86_64"
+         prefix: /opt/openmpi-1.6.5-intel
+
+Implementations can also be listed immediately under the virtual they provide:
+
+.. code-block:: yaml
+
+   packages:
+     mpi:
+       buildable: False
+         openmpi@1.4.3%gcc@4.4.7 arch=linux-debian7-x86_64: /opt/openmpi-1.4.3
+         openmpi@1.4.3%gcc@4.4.7 arch=linux-debian7-x86_64+debug: /opt/openmpi-1.4.3-debug
+         openmpi@1.6.5%intel@10.1 arch=linux-debian7-x86_64: /opt/openmpi-1.6.5-intel
+         mpich@3.3 %clang@9.0.0 arch=linux-debian7-x86_64: /opt/mpich-3.3-intel
+
+Spack can then use any of the listed external implementations of MPI
+to satisfy a dependency, and will choose depending on the compiler and
+architecture.
+
+.. _cmd-spack-external-find:
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Automatically Find External Packages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can run the :ref:`spack external find <spack-external-find>` command
+to search for system-provided packages and add them to ``packages.yaml``.
+After running this command your ``packages.yaml`` may include new entries:
+
+.. code-block:: yaml
+
+   packages:
+     cmake:
+       externals:
+       - spec: cmake@3.17.2
+         prefix: /usr
+
+Generally this is useful for detecting a small set of commonly-used packages;
+for now this is generally limited to finding build-only dependencies.
+Specific limitations include:
+
+* Packages are not discoverable by default: For a package to be
+  discoverable with ``spack external find``, it needs to add special
+  logic. See :ref:`here <make-package-findable>` for more details.
+* The current implementation only collects and examines executable files,
+  so it is typically only useful for build/run dependencies (in some cases
+  if a library package also provides an executable, it may be possible to
+  extract a meaningful Spec by running the executable - for example the
+  compiler wrappers in MPI implementations).
+* The logic does not search through module files, it can only detect
+  packages with executables defined in ``PATH``; you can help Spack locate
+  externals which use module files by loading any associated modules for
+  packages that you want Spack to know about before running
+  ``spack external find``.
+* Spack does not overwrite existing entries in the package configuration:
+  If there is an external defined for a spec at any configuration scope,
+  then Spack will not add a new external entry (``spack config blame packages``
+  can help locate all external entries).
 
 .. _concretization-preferences:
 

lib/spack/docs/build_systems.rst

@@ -29,6 +29,7 @@ on these ideas for each distinct build system that Spack supports:
    :maxdepth: 1
    :caption: Make-incompatible
 
+   build_systems/mavenpackage
    build_systems/sconspackage
    build_systems/wafpackage
 

lib/spack/docs/build_systems/autotoolspackage.rst

@@ -233,7 +233,124 @@ You may have noticed that most of the Autotools flags are of the form
 ``--without-baz``. Since these flags are so common, Spack provides a
 couple of helper functions to make your life easier.
 
-TODO: document ``with_or_without`` and ``enable_or_disable``.
+"""""""""""""""""
+enable_or_disable
+"""""""""""""""""
+
+Autotools flags for simple boolean variants can be automatically
+generated by calling the ``enable_or_disable`` method. This is
+typically used to enable or disable some feature within the package.
+
+.. code-block:: python
+
+   variant(
+       'memchecker',
+       default=False,
+       description='Memchecker support for debugging [degrades performance]'
+   )
+   config_args.extend(self.enable_or_disable('memchecker'))
+
+In this example, specifying the variant ``+memchecker`` will generate
+the following configuration options:
+
+.. code-block:: console
+
+   --enable-memchecker
+
+"""""""""""""""
+with_or_without
+"""""""""""""""
+
+Autotools flags for more complex variants, including boolean variants
+and multi-valued variants, can be automatically generated by calling
+the ``with_or_without`` method.
+
+.. code-block:: python
+
+   variant(
+       'schedulers',
+       values=disjoint_sets(
+           ('auto',), ('alps', 'lsf', 'tm', 'slurm', 'sge', 'loadleveler')
+       ).with_non_feature_values('auto', 'none'),
+       description="List of schedulers for which support is enabled; "
+       "'auto' lets openmpi determine",
+   )
+   if 'schedulers=auto' not in spec:
+       config_args.extend(self.with_or_without('schedulers'))
+
+In this example, specifying the variant ``schedulers=slurm,sge`` will
+generate the following configuration options:
+
+.. code-block:: console
+
+   --with-slurm --with-sge
+
+``enable_or_disable`` is actually functionally equivalent with
+``with_or_without``, and accepts the same arguments and variant types;
+but idiomatic autotools packages often follow these naming
+conventions.
+
+""""""""""""""""
+activation_value
+""""""""""""""""
+
+Autotools parameters that require an option can still be automatically
+generated, using the ``activation_value`` argument to
+``with_or_without`` (or, rarely, ``enable_or_disable``).
+
+.. code-block:: python
+
+   variant(
+      'fabrics',
+       values=disjoint_sets(
+           ('auto',), ('psm', 'psm2', 'verbs', 'mxm', 'ucx', 'libfabric')
+       ).with_non_feature_values('auto', 'none'),
+       description="List of fabrics that are enabled; "
+       "'auto' lets openmpi determine",
+   )
+   if 'fabrics=auto' not in spec:
+       config_args.extend(self.with_or_without('fabrics',
+           activation_value='prefix'))
+
+``activation_value`` accepts a callable that generates the configure
+parameter value given the variant value; but the special value
+``prefix`` tells Spack to automatically use the dependenency's
+installation prefix, which is the most common use for such
+parameters. In this example, specifying the variant
+``fabrics=libfabric`` will generate the following configuration
+options:
+
+.. code-block:: console
+
+   --with-libfabric=</path/to/libfabric>
+
+""""""""""""""""""""
+activation overrides
+""""""""""""""""""""
+
+Finally, the behavior of either ``with_or_without`` or
+``enable_or_disable`` can be overridden for specific variant
+values. This is most useful for multi-values variants where some of
+the variant values require atypical behavior.
+
+.. code-block:: python
+
+   def with_or_without_verbs(self, activated):
+       # Up through version 1.6, this option was named --with-openib.
+       # In version 1.7, it was renamed to be --with-verbs.
+       opt = 'verbs' if self.spec.satisfies('@1.7:') else 'openib'
+       if not activated:
+           return '--without-{0}'.format(opt)
+       return '--with-{0}={1}'.format(opt, self.spec['rdma-core'].prefix)
+
+Defining ``with_or_without_verbs`` overrides the behavior of a
+``fabrics=verbs`` variant, changing the configure-time option to
+``--with-openib`` for older versions of the package and specifying an
+alternative dependency name:
+
+.. code-block::
+
+   --with-openib=</path/to/rdma-core>
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Configure script in a sub-directory

lib/spack/docs/build_systems/cmakepackage.rst

@@ -128,17 +128,20 @@ Adding flags to cmake
 ^^^^^^^^^^^^^^^^^^^^^
 
 To add additional flags to the ``cmake`` call, simply override the
-``cmake_args`` function:
+``cmake_args`` function. The following example defines values for the flags
+``WHATEVER``, ``ENABLE_BROKEN_FEATURE``, ``DETECT_HDF5``, and ``THREADS`` with
+and without the :py:meth:`~.CMakePackage.define` and
+:py:meth:`~.CMakePackage.define_from_variant` helper functions:
 
 .. code-block:: python
 
    def cmake_args(self):
-       args = []
-
-       if '+hdf5' in self.spec:
-           args.append('-DDETECT_HDF5=ON')
-       else:
-           args.append('-DDETECT_HDF5=OFF')
+       args = [
+           '-DWHATEVER:STRING=somevalue',
+           self.define('ENABLE_BROKEN_FEATURE', False),
+           self.define_from_variant('DETECT_HDF5', 'hdf5'),
+           self.define_from_variant('THREADS'), # True if +threads
+       ]
 
        return args
 

lib/spack/docs/build_systems/cudapackage.rst

@@ -37,7 +37,7 @@ In order to use it, just add another base class to your package, for example:
             if '+cuda' in spec:
                 options.append('-DWITH_CUDA=ON')
                 cuda_arch = spec.variants['cuda_arch'].value
-                if cuda_arch is not None:
+                if cuda_arch != 'none':
                     options.append('-DCUDA_FLAGS=-arch=sm_{0}'.format(cuda_arch[0]))
             else:
                 options.append('-DWITH_CUDA=OFF')

lib/spack/docs/build_systems/custompackage.rst

@@ -175,7 +175,7 @@ In the ``perl`` package, we can see:
 
    @run_after('build')
    @on_package_attributes(run_tests=True)
-   def test(self):
+   def build_test(self):
        make('test')
 
 As you can guess, this runs ``make test`` *after* building the package,

lib/spack/docs/build_systems/intelpackage.rst

@@ -418,9 +418,13 @@ Adapt the following example. Be sure to maintain the indentation:
    # other content ...
 
      intel-mkl:
-       modules:
-         intel-mkl@2018.2.199  arch=linux-centos6-x86_64:  intel-mkl/18/18.0.2
-         intel-mkl@2018.3.222  arch=linux-centos6-x86_64:  intel-mkl/18/18.0.3
+       externals:
+       - spec: "intel-mkl@2018.2.199  arch=linux-centos6-x86_64"
+         modules:
+         -  intel-mkl/18/18.0.2
+       - spec: "intel-mkl@2018.3.222  arch=linux-centos6-x86_64"
+         modules:
+         -  intel-mkl/18/18.0.3
 
 The version numbers for the ``intel-mkl`` specs defined here correspond to file
 and directory names that Intel uses for its products because they were adopted
@@ -451,12 +455,16 @@ mechanism.
 
    packages:
      intel-parallel-studio:
-       modules:
-         intel-parallel-studio@cluster.2018.2.199 +mkl+mpi+ipp+tbb+daal  arch=linux-centos6-x86_64:  intel/18/18.0.2
-         intel-parallel-studio@cluster.2018.3.222 +mkl+mpi+ipp+tbb+daal  arch=linux-centos6-x86_64:  intel/18/18.0.3
+       externals:
+       - spec: "intel-parallel-studio@cluster.2018.2.199 +mkl+mpi+ipp+tbb+daal  arch=linux-centos6-x86_64"
+         modules:
+         -  intel/18/18.0.2
+       - spec: "intel-parallel-studio@cluster.2018.3.222 +mkl+mpi+ipp+tbb+daal  arch=linux-centos6-x86_64"
+         modules:
+         -  intel/18/18.0.3
        buildable: False
 
-One additional example illustrates the use of ``paths:`` instead of
+One additional example illustrates the use of ``prefix:`` instead of
 ``modules:``, useful when external modulefiles are not available or not
 suitable:
 
@@ -464,13 +472,15 @@ suitable:
 
    packages:
      intel-parallel-studio:
-       paths:
-         intel-parallel-studio@cluster.2018.2.199 +mkl+mpi+ipp+tbb+daal: /opt/intel
-         intel-parallel-studio@cluster.2018.3.222 +mkl+mpi+ipp+tbb+daal: /opt/intel
+       externals:
+       - spec: "intel-parallel-studio@cluster.2018.2.199 +mkl+mpi+ipp+tbb+daal"
+         prefix: /opt/intel
+       - spec: "intel-parallel-studio@cluster.2018.3.222 +mkl+mpi+ipp+tbb+daal"
+         prefix: /opt/intel
        buildable: False
 
 Note that for the Intel packages discussed here, the directory values in the
-``paths:`` entries must be the high-level and typically version-less
+``prefix:`` entries must be the high-level and typically version-less
 "installation directory" that has been used by Intel's product installer.
 Such a directory will typically accumulate various product versions.  Amongst
 them, Spack will select the correct version-specific product directory based on
@@ -553,7 +563,7 @@ follow `the next section <intel-install-libs_>`_ instead.
                f77:      stub
                fc:       stub
 
-      Replace ``18.0.3`` with the version that you determined in the preceeding
+      Replace ``18.0.3`` with the version that you determined in the preceding
       step. The contents under ``paths:`` do not matter yet.
 
    You are right to ask: "Why on earth is that necessary?" [fn8]_.
@@ -696,7 +706,7 @@ follow `the next section <intel-install-libs_>`_ instead.
              - /home/$user/spack-stage
 
         Do not duplicate the ``config:`` line if it already is present.
-        Adapt the location, which here is the same as in the preceeding example.
+        Adapt the location, which here is the same as in the preceding example.
 
    3. Retry installing the large package.
 
@@ -965,7 +975,7 @@ a *virtual* ``mkl`` package is declared in Spack.
 
   Likewise, in a
   :ref:`MakefilePackage <makefilepackage>`
-  or similiar package that does not use AutoTools you may need to provide include
+  or similar package that does not use AutoTools you may need to provide include
   and link options for use on command lines or in environment variables.
   For example, to generate an option string of the form ``-I<dir>``, use:
 
@@ -1055,6 +1065,6 @@ Footnotes
    2. Set the hash length in ``install-path-scheme``, also in ``config.yaml``
       (:ref:`q.v. <config-yaml>`).
    3. You will want to set the *same* hash length for
-      :ref:`tcl module files <modules-naming-scheme>`
-      if you have Spack produce them for you, under ``naming_scheme`` in
-      ``modules.yaml``.  Other module dialects cannot be altered in this manner.
+      :ref:`module files <modules-projections>`
+      if you have Spack produce them for you, under ``projections`` in
+      ``modules.yaml``.

lib/spack/docs/build_systems/mavenpackage.rst

@@ -0,0 +1,84 @@
+.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+   Spack Project Developers. See the top-level COPYRIGHT file for details.
+
+   SPDX-License-Identifier: (Apache-2.0 OR MIT)
+
+.. _mavenpackage:
+
+------------
+MavenPackage
+------------
+
+Apache Maven is a general-purpose build system that does not rely
+on Makefiles to build software. It is designed for building and
+managing and Java-based project.
+
+^^^^^^
+Phases
+^^^^^^
+
+The ``MavenPackage`` base class comes with the following phases:
+
+#. ``build`` - compile code and package into a JAR file
+#. ``install`` - copy to installation prefix
+
+By default, these phases run:
+
+.. code-block:: console
+
+   $ mvn package
+   $ install . <prefix>
+
+
+^^^^^^^^^^^^^^^
+Important files
+^^^^^^^^^^^^^^^
+
+Maven packages can be identified by the presence of a ``pom.xml`` file.
+This file lists dependencies and other metadata about the project.
+There may also be configuration files in the ``.mvn`` directory.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^
+Build system dependencies
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Maven requires the ``mvn`` executable to build the project. It also
+requires Java at both build- and run-time. Because of this, the base
+class automatically adds the following dependencies:
+
+.. code-block:: python
+
+   depends_on('java', type=('build', 'run'))
+   depends_on('maven', type='build')
+
+
+In the ``pom.xml`` file, you may see sections like:
+
+.. code-block:: xml
+
+   <requireJavaVersion>
+      <version>[1.7,)</version>
+   </requireJavaVersion>
+   <requireMavenVersion>
+      <version>[3.5.4,)</version>
+   </requireMavenVersion>
+
+
+This specifies the versions of Java and Maven that are required to
+build the package. See
+https://docs.oracle.com/middleware/1212/core/MAVEN/maven_version.htm#MAVEN402
+for a description of this version range syntax. In this case, you
+should add:
+
+.. code-block:: python
+
+   depends_on('java@7:', type='build')
+   depends_on('maven@3.5.4:', type='build')
+
+
+^^^^^^^^^^^^^^^^^^^^^^
+External documentation
+^^^^^^^^^^^^^^^^^^^^^^
+
+For more information on the Maven build system, see:
+https://maven.apache.org/index.html

lib/spack/docs/build_systems/pythonpackage.rst

@@ -81,6 +81,24 @@ you'll need to define a function for it like so:
        self.setup_py('configure')
 
 
+^^^^^^
+Wheels
+^^^^^^
+
+Some Python packages are closed-source and distributed as wheels.
+Instead of using the ``PythonPackage`` base class, you should extend
+the ``Package`` base class and implement the following custom installation
+procedure:
+
+.. code-block::
+
+   def install(self, spec, prefix):
+       pip = which('pip')
+       pip('install', self.stage.archive_file, '--prefix={0}'.format(prefix))
+
+
+This will require a dependency on pip, as mentioned below.
+
 ^^^^^^^^^^^^^^^
 Important files
 ^^^^^^^^^^^^^^^
@@ -95,6 +113,27 @@ file should be considered to be the truth. As dependencies are added or
 removed, the documentation is much more likely to become outdated than
 the ``setup.py``.
 
+The Python ecosystem has evolved significantly over the years. Before
+setuptools became popular, most packages listed their dependencies in a
+``requirements.txt`` file. Once setuptools took over, these dependencies
+were listed directly in the ``setup.py``. Newer PEPs introduced additional
+files, like ``setup.cfg`` and ``pyproject.toml``. You should look out for
+all of these files, as they may all contain important information about
+package dependencies.
+
+Some Python packages are closed-source and are distributed as Python
+wheels. For example, ``py-azureml-sdk`` downloads a ``.whl`` file. This
+file is simply a zip file, and can be extracted using:
+
+.. code-block:: console
+
+   $ unzip *.whl
+
+
+The zip file will not contain a ``setup.py``, but it will contain a
+``METADATA`` file which contains all the information you need to
+write a ``package.py`` build recipe.
+
 ^^^^^^^^^^^^^^^^^^^^^^^
 Finding Python packages
 ^^^^^^^^^^^^^^^^^^^^^^^
@@ -105,8 +144,9 @@ it the only option for developers who want a simple installation.
 Search for "PyPI <package-name>" to find the download page. Note that
 some pages are versioned, and the first result may not be the newest
 version. Click on the "Latest Version" button to the top right to see
-if a newer version is available. The download page is usually at:
-https://pypi.org/project/<package-name>
+if a newer version is available. The download page is usually at::
+
+   https://pypi.org/project/<package-name>
 
 ^^^^^^^^^^^
 Description
@@ -151,39 +191,67 @@ replacing this with the requested version. Obviously, if Spack cannot
 guess the version correctly, or if non-version-related things change
 in the URL, Spack cannot substitute the version properly.
 
-Once upon a time, PyPI offered nice, simple download URLs like:
-https://pypi.python.org/packages/source/n/numpy/numpy-1.13.1.zip
+Once upon a time, PyPI offered nice, simple download URLs like::
+
+   https://pypi.python.org/packages/source/n/numpy/numpy-1.13.1.zip
+
 
 As you can see, the version is 1.13.1. It probably isn't hard to guess
 what URL to use to download version 1.12.0, and Spack was perfectly
 capable of performing this calculation.
 
-However, PyPI switched to a new download URL format:
-https://pypi.python.org/packages/c0/3a/40967d9f5675fbb097ffec170f59c2ba19fc96373e73ad47c2cae9a30aed/numpy-1.13.1.zip#md5=2c3c0f4edf720c3a7b525dacc825b9ae
+However, PyPI switched to a new download URL format::
+
+   https://pypi.python.org/packages/c0/3a/40967d9f5675fbb097ffec170f59c2ba19fc96373e73ad47c2cae9a30aed/numpy-1.13.1.zip#md5=2c3c0f4edf720c3a7b525dacc825b9ae
+
+
+and more recently::
+
+   https://files.pythonhosted.org/packages/b0/2b/497c2bb7c660b2606d4a96e2035e92554429e139c6c71cdff67af66b58d2/numpy-1.14.3.zip
 
-and more recently:
-https://files.pythonhosted.org/packages/b0/2b/497c2bb7c660b2606d4a96e2035e92554429e139c6c71cdff67af66b58d2/numpy-1.14.3.zip
 
 As you can imagine, it is impossible for Spack to guess what URL to
 use to download version 1.12.0 given this URL. There is a solution,
 however. PyPI offers a new hidden interface for downloading
-Python packages that does not include a hash in the URL:
-https://pypi.io/packages/source/n/numpy/numpy-1.13.1.zip
+Python packages that does not include a hash in the URL::
 
-This URL redirects to the files.pythonhosted.org URL. The general syntax for
-this pypi.io URL is:
-https://pypi.io/packages/source/<first-letter-of-name>/<name>/<name>-<version>.<extension>
+   https://pypi.io/packages/source/n/numpy/numpy-1.13.1.zip
+
+
+This URL redirects to the https://files.pythonhosted.org URL. The general
+syntax for this https://pypi.io URL is::
+
+   https://pypi.io/packages/<type>/<first-letter-of-name>/<name>/<name>-<version>.<extension>
+
+
+Please use the https://pypi.io URL instead of the https://pypi.python.org
+URL. If both ``.tar.gz`` and ``.zip`` versions are available, ``.tar.gz``
+is preferred. If some releases offer both ``.tar.gz`` and ``.zip`` versions,
+but some only offer ``.zip`` versions, use ``.zip``.
+
+Some Python packages are closed-source and do not ship ``.tar.gz`` or ``.zip``
+files on either PyPI or GitHub. If this is the case, you can still download
+and install a Python wheel. For example, ``py-azureml-sdk`` is closed source
+and can be downloaded from::
+
+   https://pypi.io/packages/py3/a/azureml_sdk/azureml_sdk-1.11.0-py3-none-any.whl
+
+
+Note that instead of ``<type>`` being ``source``, it is now ``py3`` since this
+wheel will work for any generic version of Python 3. You may see Python-specific
+or OS-specific URLs. Note that when you add a ``.whl`` URL, you should add
+``expand=False`` to ensure that Spack doesn't try to extract the wheel:
+
+.. code-block:: python
+
+   version('1.11.0', sha256='d8c9d24ea90457214d798b0d922489863dad518adde3638e08ef62de28fb183a', expand=False)
 
-Please use the pypi.io URL instead of the pypi.python.org URL. If both
-``.tar.gz`` and ``.zip`` versions are available, ``.tar.gz`` is preferred.
-If some releases offer both ``.tar.gz`` and ``.zip`` versions, but some
-only offer ``.zip`` versions, use ``.zip``.
 
 """""""""""""""
 PyPI vs. GitHub
 """""""""""""""
 
-Many packages are hosted on PyPI, but are developed on GitHub and other
+Many packages are hosted on PyPI, but are developed on GitHub or another
 version control systems. The tarball can be downloaded from either
 location, but PyPI is preferred for the following reasons:
 
@@ -226,7 +294,7 @@ location, but PyPI is preferred for the following reasons:
 
 There are some reasons to prefer downloading from GitHub:
 
-#. The GitHub tarball may contain unit tests
+#. The GitHub tarball may contain unit tests.
 
    As previously mentioned, the PyPI tarball contains the bare minimum
    of files to install the package. Unless explicitly specified by the
@@ -234,12 +302,6 @@ There are some reasons to prefer downloading from GitHub:
    If you desire to run the unit tests during installation, you should
    use the GitHub tarball instead.
 
-#. Spack does not yet support ``spack versions`` and ``spack checksum``
-   with PyPI URLs
-
-   These commands work just fine with GitHub URLs. This is a minor
-   annoyance, not a reason to prefer GitHub over PyPI.
-
 If you really want to run these unit tests, no one will stop you from
 submitting a PR for a new package that downloads from GitHub.
 
@@ -280,8 +342,8 @@ If Python 2.7 is the only version that works, you can use:
 
 
 The documentation may not always specify supported Python versions.
-Another place to check is in the ``setup.py`` file. Look for a line
-containing ``python_requires``. An example from
+Another place to check is in the ``setup.py`` or ``setup.cfg`` file.
+Look for a line containing ``python_requires``. An example from
 `py-numpy <https://github.com/spack/spack/blob/develop/var/spack/repos/builtin/packages/py-numpy/package.py>`_
 looks like:
 
@@ -290,7 +352,7 @@ looks like:
    python_requires='>=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*'
 
 
-More commonly, you will find a version check at the top of the file:
+You may also find a version check at the top of the ``setup.py``:
 
 .. code-block:: python
 
@@ -305,6 +367,39 @@ This can be converted to Spack's spec notation like so:
    depends_on('python@2.7:2.8,3.4:', type=('build', 'run'))
 
 
+If you are writing a recipe for a package that only distributes
+wheels, look for a section in the ``METADATA`` file that looks like::
+
+   Requires-Python: >=3.5,<4
+
+
+This would be translated to:
+
+.. code-block:: python
+
+   extends('python')
+   depends_on('python@3.5:3.999', type=('build', 'run'))
+
+
+Many ``setup.py`` or ``setup.cfg`` files also contain information like::
+
+   Programming Language :: Python :: 2
+   Programming Language :: Python :: 2.6
+   Programming Language :: Python :: 2.7
+   Programming Language :: Python :: 3
+   Programming Language :: Python :: 3.3
+   Programming Language :: Python :: 3.4
+   Programming Language :: Python :: 3.5
+   Programming Language :: Python :: 3.6
+
+
+This is a list of versions of Python that the developer likely tests.
+However, you should not use this to restrict the versions of Python
+the package uses unless one of the two former methods (``python_requires``
+or ``sys.version_info``) is used. There is no logic in setuptools
+that prevents the package from building for Python versions not in
+this list, and often new releases like Python 3.7 or 3.8 work just fine.
+
 """"""""""
 setuptools
 """"""""""
@@ -317,7 +412,7 @@ Most notably, there was no way to list a project's dependencies
 with distutils. Along came setuptools, a non-builtin build system
 designed to overcome the limitations of distutils. Both projects
 use a similar API, making the transition easy while adding much
-needed functionality. Today, setuptools is used in around 75% of
+needed functionality. Today, setuptools is used in around 90% of
 the Python packages in Spack.
 
 Since setuptools isn't built-in to Python, you need to add it as a
@@ -360,6 +455,20 @@ run-time. This can be specified as:
    depends_on('py-setuptools', type='build')
 
 
+"""
+pip
+"""
+
+Packages distributed as Python wheels will require an extra dependency
+on pip:
+
+.. code-block:: python
+
+   depends_on('py-pip', type='build')
+
+
+We will use pip to install the actual wheel.
+
 """"""
 cython
 """"""
@@ -383,6 +492,12 @@ where speed is crucial. There is no reason why someone would not
 want an optimized version of a library instead of the pure-Python
 version.
 
+Note that some release tarballs come pre-cythonized, and cython is
+not needed as a dependency. However, this is becoming less common
+as Python continues to evolve and developers discover that cythonized
+sources are no longer compatible with newer versions of Python and
+need to be re-cythonized.
+
 ^^^^^^^^^^^^^^^^^^^
 Python dependencies
 ^^^^^^^^^^^^^^^^^^^
@@ -429,15 +544,26 @@ Obviously, this means that ``py-numpy`` is a dependency.
 
 If the package uses ``setuptools``, check for the following clues:
 
+* ``python_requires``
+
+  As mentioned above, this specifies which versions of Python are
+  required.
+
+* ``setup_requires``
+
+  These packages are usually only needed at build-time, so you can
+  add them with ``type='build'``.
+
 * ``install_requires``
 
-  These packages are required for installation.
+  These packages are required for building and installation. You can
+  add them with ``type=('build', 'run')``.
 
 * ``extra_requires``
 
   These packages are optional dependencies that enable additional
   functionality. You should add a variant that optionally adds these
-  dependencies.
+  dependencies. This variant should be False by default.
 
 * ``test_requires``
 
@@ -461,13 +587,37 @@ sphinx. If you can't find any information about the package's
 dependencies, you can take a look in ``requirements.txt``, but be sure
 not to add test or documentation dependencies.
 
+Newer PEPs have added alternative ways to specify a package's dependencies.
+If you don't see any dependencies listed in the ``setup.py``, look for a
+``setup.cfg`` or ``pyproject.toml``. These files can be used to store the
+same ``install_requires`` information that ``setup.py`` used to use.
+
+If you are write a recipe for a package that only distributes wheels,
+check the ``METADATA`` file for lines like::
+
+   Requires-Dist: azureml-core (~=1.11.0)
+   Requires-Dist: azureml-dataset-runtime[fuse] (~=1.11.0)
+   Requires-Dist: azureml-train (~=1.11.0)
+   Requires-Dist: azureml-train-automl-client (~=1.11.0)
+   Requires-Dist: azureml-pipeline (~=1.11.0)
+   Provides-Extra: accel-models
+   Requires-Dist: azureml-accel-models (~=1.11.0); extra == 'accel-models'
+   Provides-Extra: automl
+   Requires-Dist: azureml-train-automl (~=1.11.0); extra == 'automl'
+
+
+Lines that use ``Requires-Dist`` are similar to ``install_requires``.
+Lines that use ``Provides-Extra`` are similar to ``extra_requires``,
+and you can add a variant for those dependencies. The ``~=1.11.0``
+syntax is equivalent to ``1.11.0:1.11.999``.
+
 """"""""""
 setuptools
 """"""""""
 
 Setuptools is a bit of a special case. If a package requires setuptools
 at run-time, how do they express this? They could add it to
-``install_requires``, but setuptools is imported long before this and
+``install_requires``, but setuptools is imported long before this and is
 needed to read this line. And since you can't install the package
 without setuptools, the developers assume that setuptools will already
 be there, so they never mention when it is required. We don't want to
@@ -580,11 +730,13 @@ By default, Spack runs:
 
 if it detects that the ``setup.py`` file supports a ``test`` phase.
 You can add additional build-time or install-time tests by overriding
-``test`` and ``installtest``, respectively. For example, ``py-numpy``
-adds:
+``test`` or adding a custom install-time test function. For example,
+``py-numpy`` adds:
 
 .. code-block:: python
 
+   install_time_test_callbacks = ['install_test', 'import_module_test']
+
    def install_test(self):
         with working_dir('..'):
             python('-c', 'import numpy; numpy.test("full", verbose=2)')
@@ -651,6 +803,8 @@ that the package uses the ``PythonPackage`` build system. However, there
 are occasionally packages that use ``PythonPackage`` that shouldn't
 start with ``py-``. For example:
 
+* awscli
+* aws-parallelcluster
 * busco
 * easybuild
 * httpie
@@ -736,8 +890,9 @@ non-Python dependencies. Anaconda contains many Python packages that
 are not yet in Spack, and Spack contains many Python packages that are
 not yet in Anaconda. The main advantage of Spack over Anaconda is its
 ability to choose a specific compiler and BLAS/LAPACK or MPI library.
-Spack also has better platform support for supercomputers. On the
-other hand, Anaconda offers Windows support.
+Spack also has better platform support for supercomputers, and can build
+optimized binaries for your specific microarchitecture. On the other hand,
+Anaconda offers Windows support.
 
 ^^^^^^^^^^^^^^^^^^^^^^
 External documentation

lib/spack/docs/build_systems/rubypackage.rst

@@ -12,5 +12,173 @@ RubyPackage
 Like Perl, Python, and R, Ruby has its own build system for
 installing Ruby gems.
 
-This build system is a work-in-progress. See
-https://github.com/spack/spack/pull/3127 for more information.
+^^^^^^
+Phases
+^^^^^^
+
+The ``RubyPackage`` base class provides the following phases that
+can be overridden:
+
+#. ``build`` - build everything needed to install
+#. ``install`` - install everything from build directory
+
+For packages that come with a ``*.gemspec`` file, these phases run:
+
+.. code-block:: console
+
+   $ gem build *.gemspec
+   $ gem install *.gem
+
+
+For packages that come with a ``Rakefile`` file, these phases run:
+
+.. code-block:: console
+
+   $ rake package
+   $ gem install *.gem
+
+
+For packages that come pre-packaged as a ``*.gem`` file, the build
+phase is skipped and the install phase runs:
+
+.. code-block:: console
+
+   $ gem install *.gem
+
+
+These are all standard ``gem`` commands and can be found by running:
+
+.. code-block:: console
+
+   $ gem help commands
+
+
+For packages that only distribute ``*.gem`` files, these files can be
+downloaded with the ``expand=False`` option in the ``version`` directive.
+The build phase will be automatically skipped.
+
+^^^^^^^^^^^^^^^
+Important files
+^^^^^^^^^^^^^^^
+
+When building from source, Ruby packages can be identified by the
+presence of any of the following files:
+
+* ``*.gemspec``
+* ``Rakefile``
+* ``setup.rb`` (not yet supported)
+
+However, not all Ruby packages are released as source code. Some are only
+released as ``*.gem`` files. These files can be extracted using:
+
+.. code-block:: console
+
+   $ gem unpack *.gem
+
+
+^^^^^^^^^^^
+Description
+^^^^^^^^^^^
+
+The ``*.gemspec`` file may contain something like:
+
+.. code-block:: ruby
+
+   summary = 'An implementation of the AsciiDoc text processor and publishing toolchain'
+   description = 'A fast, open source text processor and publishing toolchain for converting AsciiDoc content to HTML 5, DocBook 5, and other formats.'
+
+
+Either of these can be used for the description of the Spack package.
+
+^^^^^^^^
+Homepage
+^^^^^^^^
+
+The ``*.gemspec`` file may contain something like:
+
+.. code-block:: ruby
+
+   homepage = 'https://asciidoctor.org'
+
+
+This should be used as the official homepage of the Spack package.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^
+Build system dependencies
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+All Ruby packages require Ruby at build and run-time. For this reason,
+the base class contains:
+
+.. code-block:: python
+
+   extends('ruby')
+   depends_on('ruby', type=('build', 'run'))
+
+
+The ``*.gemspec`` file may contain something like:
+
+.. code-block:: ruby
+
+   required_ruby_version = '>= 2.3.0'
+
+
+This can be added to the Spack package using:
+
+.. code-block:: python
+
+   depends_on('ruby@2.3.0:', type=('build', 'run'))
+
+
+^^^^^^^^^^^^^^^^^
+Ruby dependencies
+^^^^^^^^^^^^^^^^^
+
+When you install a package with ``gem``, it reads the ``*.gemspec``
+file in order to determine the dependencies of the package.
+If the dependencies are not yet installed, ``gem`` downloads them
+and installs them for you. This may sound convenient, but Spack
+cannot rely on this behavior for two reasons:
+
+#. Spack needs to be able to install packages on air-gapped networks.
+
+   If there is no internet connection, ``gem`` can't download the
+   package dependencies. By explicitly listing every dependency in
+   the ``package.py``, Spack knows what to download ahead of time.
+
+#. Duplicate installations of the same dependency may occur.
+
+   Spack supports *activation* of Ruby extensions, which involves
+   symlinking the package installation prefix to the Ruby installation
+   prefix. If your package is missing a dependency, that dependency
+   will be installed to the installation directory of the same package.
+   If you try to activate the package + dependency, it may cause a
+   problem if that package has already been activated.
+
+For these reasons, you must always explicitly list all dependencies.
+Although the documentation may list the package's dependencies,
+often the developers assume people will use ``gem`` and won't have to
+worry about it. Always check the ``*.gemspec`` file to find the true
+dependencies.
+
+Check for the following clues in the ``*.gemspec`` file:
+
+* ``add_runtime_dependency``
+
+  These packages are required for installation.
+
+* ``add_dependency``
+
+  This is an alias for ``add_runtime_dependency``
+
+* ``add_development_dependency``
+
+  These packages are optional dependencies used for development.
+  They should not be added as dependencies of the package.
+
+^^^^^^^^^^^^^^^^^^^^^^
+External documentation
+^^^^^^^^^^^^^^^^^^^^^^
+
+For more information on Ruby packaging, see:
+https://guides.rubygems.org/

lib/spack/docs/build_systems/sconspackage.rst

@@ -56,7 +56,7 @@ overridden like so:
 
 .. code-block:: python
 
-   def test(self):
+   def build_test(self):
        scons('check')
 
 

lib/spack/docs/build_systems/sippackage.rst

@@ -51,10 +51,8 @@ Build system dependencies
 ``SIPPackage`` requires several dependencies. Python is needed to run
 the ``configure.py`` build script, and to run the resulting Python
 libraries. Qt is needed to provide the ``qmake`` command. SIP is also
-needed to build the package. SIP is an unusual dependency in that it
-must be installed in the same installation directory as the package,
-so instead of a ``depends_on``, we use a ``resource``. All of these
-dependencies are automatically added via the base class
+needed to build the package. All of these dependencies are automatically
+added via the base class
 
 .. code-block:: python
 
@@ -62,11 +60,7 @@ dependencies are automatically added via the base class
 
    depends_on('qt', type='build')
 
-   resource(name='sip',
-            url='https://www.riverbankcomputing.com/static/Downloads/sip/4.19.18/sip-4.19.18.tar.gz',
-            sha256='c0bd863800ed9b15dcad477c4017cdb73fa805c25908b0240564add74d697e1e',
-            destination='.')
-
+   depends_on('py-sip', type='build')
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Passing arguments to ``configure.py``

lib/spack/docs/build_systems/wafpackage.rst

@@ -47,8 +47,9 @@ Each phase provides a ``<phase>`` function that runs:
 
 where ``<jobs>`` is the number of parallel jobs to build with. Each phase
 also has a ``<phase_args>`` function that can pass arguments to this call.
-All of these functions are empty except for the ``configure_args``
-function, which passes ``--prefix=/path/to/installation/prefix``.
+All of these functions are empty. The ``configure`` phase
+automatically adds  ``--prefix=/path/to/installation/prefix``, so you
+don't need to add that in the ``configure_args``.
 
 ^^^^^^^
 Testing

lib/spack/docs/config_yaml.rst

@@ -99,7 +99,7 @@ username is not already in the path, Spack will append the value of ``$user`` to
 the selected ``build_stage`` path.
 
 .. warning:: We highly recommend specifying ``build_stage`` paths that
-   distinguish between staging and other activities to ensure 
+   distinguish between staging and other activities to ensure
    ``spack clean`` does not inadvertently remove unrelated files.
    Spack prepends ``spack-stage-`` to temporary staging directory names to
    reduce this risk.  Using a combination of ``spack`` and or ``stage`` in
@@ -223,7 +223,7 @@ To build all software in serial, set ``build_jobs`` to 1.
 --------------------
 
 When set to ``true`` Spack will use ccache to cache compiles. This is
-useful specifically in two cases: (1) when using ``spack setup``, and (2)
+useful specifically in two cases: (1) when using ``spack dev-build``, and (2)
 when building the same package with many different variants. The default is
 ``false``.
 

lib/spack/docs/containers.rst

@@ -44,8 +44,8 @@ Environments:
    &&   echo "    install_tree: /opt/software" \
    &&   echo "  view: /opt/view") > /opt/spack-environment/spack.yaml
 
-   # Install the software, remove unecessary deps
-   RUN cd /opt/spack-environment && spack install && spack gc -y
+   # Install the software, remove unnecessary deps
+   RUN cd /opt/spack-environment && spack env activate . && spack install && spack gc -y
 
    # Strip all the binaries
    RUN find -L /opt/view/* -type f -exec readlink -f '{}' \; | \
@@ -71,7 +71,7 @@ Environments:
     && yum install -y libgomp \
     && rm -rf /var/cache/yum  && yum clean all
 
-   RUN echo 'export PS1="\[$(tput bold)\]\[$(tput setaf 1)\][gromacs]\[$(tput setaf 2)\]\u\[$(tput sgr0)\]:\w $ \[$(tput sgr0)\]"' >> ~/.bashrc
+   RUN echo 'export PS1="\[$(tput bold)\]\[$(tput setaf 1)\][gromacs]\[$(tput setaf 2)\]\u\[$(tput sgr0)\]:\w $ "' >> ~/.bashrc
 
 
    LABEL "app"="gromacs"
@@ -108,7 +108,7 @@ are currently supported are summarized in the table below:
      - ``ubuntu:16.04``
      - ``spack/ubuntu-xenial``
    * - Ubuntu 18.04
-     - ``ubuntu:16.04``
+     - ``ubuntu:18.04``
      - ``spack/ubuntu-bionic``
    * - CentOS 6
      - ``centos:6``
@@ -165,7 +165,7 @@ of environments:
        # Extra instructions
        extra_instructions:
          final: |
-   RUN echo 'export PS1="\[$(tput bold)\]\[$(tput setaf 1)\][gromacs]\[$(tput setaf 2)\]\u\[$(tput sgr0)\]:\w $ \[$(tput sgr0)\]"' >> ~/.bashrc
+           RUN echo 'export PS1="\[$(tput bold)\]\[$(tput setaf 1)\][gromacs]\[$(tput setaf 2)\]\u\[$(tput sgr0)\]:\w $ "' >> ~/.bashrc
 
        # Labels for the image
        labels:
@@ -266,8 +266,8 @@ following ``Dockerfile``:
    &&   echo "    install_tree: /opt/software" \
    &&   echo "  view: /opt/view") > /opt/spack-environment/spack.yaml
 
-   # Install the software, remove unecessary deps
-   RUN cd /opt/spack-environment && spack install && spack gc -y
+   # Install the software, remove unnecessary deps
+   RUN cd /opt/spack-environment && spack env activate . && spack install && spack gc -y
 
    # Strip all the binaries
    RUN find -L /opt/view/* -type f -exec readlink -f '{}' \; | \
@@ -293,7 +293,7 @@ following ``Dockerfile``:
     && yum install -y libgomp \
     && rm -rf /var/cache/yum  && yum clean all
 
-   RUN echo 'export PS1="\[$(tput bold)\]\[$(tput setaf 1)\][gromacs]\[$(tput setaf 2)\]\u\[$(tput sgr0)\]:\w $ \[$(tput sgr0)\]"' >> ~/.bashrc
+   RUN echo 'export PS1="\[$(tput bold)\]\[$(tput setaf 1)\][gromacs]\[$(tput setaf 2)\]\u\[$(tput sgr0)\]:\w $ "' >> ~/.bashrc
 
 
    LABEL "app"="gromacs"
@@ -304,4 +304,4 @@ following ``Dockerfile``:
 .. note::
    Spack can also produce Singularity definition files to build the image. The
    minimum version of Singularity required to build a SIF (Singularity Image Format)
-   from them is ``3.5.3``.
+   from them is ``3.5.3``.

lib/spack/docs/contribution_guide.rst

@@ -27,17 +27,28 @@ correspond to one feature/bugfix/extension/etc. One can create PRs with
 changes relevant to different ideas, however reviewing such PRs becomes tedious
 and error prone. If possible, try to follow the **one-PR-one-package/feature** rule.
 
-Spack uses a rough approximation of the `Git Flow <http://nvie.com/posts/a-successful-git-branching-model/>`_
-branching model. The develop branch contains the latest contributions, and
-master is always tagged and points to the latest stable release. Therefore, when
-you send your request, make ``develop`` the destination branch on the
-`Spack repository <https://github.com/spack/spack>`_.
+--------
+Branches
+--------
+
+Spack's ``develop`` branch has the latest contributions. Nearly all pull
+requests should start from ``develop`` and target ``develop``.
+
+There is a branch for each major release series. Release branches
+originate from ``develop`` and have tags for each point release in the
+series. For example, ``releases/v0.14`` has tags for ``0.14.0``,
+``0.14.1``, ``0.14.2``, etc. versions of Spack. We backport important bug
+fixes to these branches, but we do not advance the package versions or
+make other changes that would change the way Spack concretizes
+dependencies. Currently, the maintainers manage these branches by
+cherry-picking from ``develop``. See :ref:`releases` for more
+information.
 
 ----------------------
 Continuous Integration
 ----------------------
 
-Spack uses `Travis CI <https://travis-ci.org/spack/spack>`_ for Continuous Integration
+Spack uses `Github Actions <https://docs.github.com/en/actions>`_ for Continuous Integration
 testing. This means that every time you submit a pull request, a series of tests will
 be run to make sure you didn't accidentally introduce any bugs into Spack. **Your PR
 will not be accepted until it passes all of these tests.** While you can certainly wait
@@ -46,25 +57,24 @@ locally to speed up the review process.
 
 .. note::
 
-   Oftentimes, Travis will fail for reasons other than a problem with your PR.
+   Oftentimes, CI will fail for reasons other than a problem with your PR.
    For example, apt-get, pip, or homebrew will fail to download one of the
    dependencies for the test suite, or a transient bug will cause the unit tests
-   to timeout. If Travis fails, click the "Details" link and click on the test(s)
+   to timeout. If any job fails, click the "Details" link and click on the test(s)
    that is failing. If it doesn't look like it is failing for reasons related to
    your PR, you have two options. If you have write permissions for the Spack
-   repository, you should see a "Restart job" button on the right-hand side. If
+   repository, you should see a "Restart workflow" button on the right-hand side. If
    not, you can close and reopen your PR to rerun all of the tests. If the same
    test keeps failing, there may be a problem with your PR. If you notice that
-   every recent PR is failing with the same error message, it may be that Travis
-   is down or one of Spack's dependencies put out a new release that is causing
-   problems. If this is the case, please file an issue.
+   every recent PR is failing with the same error message, it may be that an issue
+   occurred with the CI infrastructure or one of Spack's dependencies put out a
+   new release that is causing problems. If this is the case, please file an issue.
 
 
-If you take a look in ``$SPACK_ROOT/.travis.yml``, you'll notice that we test
-against Python 2.6, 2.7, and 3.4-3.7 on both macOS and Linux. We currently
+We currently test against Python 2.6, 2.7, and 3.5-3.7 on both macOS and Linux and
 perform 3 types of tests:
 
-.. _cmd-spack-test:
+.. _cmd-spack-unit-test:
 
 ^^^^^^^^^^
 Unit Tests
@@ -86,7 +96,7 @@ To run *all* of the unit tests, use:
 
 .. code-block:: console
 
-   $ spack test
+   $ spack unit-test
 
 These tests may take several minutes to complete. If you know you are
 only modifying a single Spack feature, you can run subsets of tests at a
@@ -95,51 +105,53 @@ time.  For example, this would run all the tests in
 
 .. code-block:: console
 
-   $ spack test architecture.py
+   $ spack unit-test lib/spack/spack/test/architecture.py
 
 And this would run the ``test_platform`` test from that file:
 
 .. code-block:: console
 
-   $ spack test architecture.py::test_platform
+   $ spack unit-test lib/spack/spack/test/architecture.py::test_platform
 
 This allows you to develop iteratively: make a change, test that change,
 make another change, test that change, etc.  We use `pytest
-<http://pytest.org/>`_ as our tests fromework, and these types of
+<http://pytest.org/>`_ as our tests framework, and these types of
 arguments are just passed to the ``pytest`` command underneath. See `the
 pytest docs
 <http://doc.pytest.org/en/latest/usage.html#specifying-tests-selecting-tests>`_
 for more details on test selection syntax.
 
-``spack test`` has a few special options that can help you understand
-what tests are available.  To get a list of all available unit test
-files, run:
+``spack unit-test`` has a few special options that can help you
+understand what tests are available.  To get a list of all available
+unit test files, run:
 
-.. command-output:: spack test --list
+.. command-output:: spack unit-test --list
    :ellipsis: 5
 
-To see a more detailed list of available unit tests, use ``spack test
---list-long``:
+To see a more detailed list of available unit tests, use ``spack
+unit-test --list-long``:
 
-.. command-output:: spack test --list-long
+.. command-output:: spack unit-test --list-long
    :ellipsis: 10
 
 And to see the fully qualified names of all tests, use ``--list-names``:
 
-.. command-output:: spack test --list-names
+.. command-output:: spack unit-test --list-names
    :ellipsis: 5
 
 You can combine these with ``pytest`` arguments to restrict which tests
 you want to know about.  For example, to see just the tests in
 ``architecture.py``:
 
-.. command-output:: spack test --list-long architecture.py
+.. command-output:: spack unit-test --list-long lib/spack/spack/test/architecture.py
 
 You can also combine any of these options with a ``pytest`` keyword
-search.  For example, to see the names of all tests that have "spec"
+search.  See the `pytest usage docs
+<https://docs.pytest.org/en/stable/usage.html#specifying-tests-selecting-tests>`_:
+for more details on test selection syntax. For example, to see the names of all tests that have "spec"
 or "concretize" somewhere in their names:
 
-.. command-output:: spack test --list-names -k "spec and concretize"
+.. command-output:: spack unit-test --list-names -k "spec and concretize"
 
 By default, ``pytest`` captures the output of all unit tests, and it will
 print any captured output for failed tests. Sometimes it's helpful to see
@@ -149,7 +161,7 @@ argument to ``pytest``:
 
 .. code-block:: console
 
-   $ spack test -s architecture.py::test_platform
+   $ spack unit-test -s --list-long lib/spack/spack/test/architecture.py::test_platform
 
 Unit tests are crucial to making sure bugs aren't introduced into
 Spack. If you are modifying core Spack libraries or adding new
@@ -162,9 +174,9 @@ how to write tests!
 .. note::
 
    You may notice the ``share/spack/qa/run-unit-tests`` script in the
-   repository.  This script is designed for Travis CI.  It runs the unit
+   repository.  This script is designed for CI.  It runs the unit
    tests and reports coverage statistics back to Codecov. If you want to
-   run the unit tests yourself, we suggest you use ``spack test``.
+   run the unit tests yourself, we suggest you use ``spack unit-test``.
 
 ^^^^^^^^^^^^
 Flake8 Tests
@@ -235,7 +247,7 @@ to update them.
 
    Try fixing flake8 errors in reverse order. This eliminates the need for
    multiple runs of ``spack flake8`` just to re-compute line numbers and
-   makes it much easier to fix errors directly off of the Travis output.
+   makes it much easier to fix errors directly off of the CI output.
 
 .. warning::
 
@@ -315,7 +327,7 @@ Once all of the dependencies are installed, you can try building the documentati
 
 .. code-block:: console
 
-   $ cd "$SPACK_ROOT/lib/spack/docs"
+   $ cd path/to/spack/lib/spack/docs/
    $ make clean
    $ make
 
@@ -327,7 +339,7 @@ your PR is accepted.
    There is also a ``run-doc-tests`` script in ``share/spack/qa``. The only
    difference between running this script and running ``make`` by hand is that
    the script will exit immediately if it encounters an error or warning. This
-   is necessary for Travis CI. If you made a lot of documentation changes, it is
+   is necessary for CI. If you made a lot of documentation changes, it is
    much quicker to run ``make`` by hand so that you can see all of the warnings
    at once.
 
@@ -385,13 +397,13 @@ coverage. This helps us tell what percentage of lines of code in Spack are
 covered by unit tests. Although code covered by unit tests can still contain
 bugs, it is much less error prone than code that is not covered by unit tests.
 
-Codecov provides `browser extensions <https://github.com/codecov/browser-extension>`_
-for Google Chrome, Firefox, and Opera. These extensions integrate with GitHub
+Codecov provides `browser extensions <https://github.com/codecov/sourcegraph-codecov>`_
+for Google Chrome and Firefox. These extensions integrate with GitHub
 and allow you to see coverage line-by-line when viewing the Spack repository.
 If you are new to Spack, a great way to get started is to write unit tests to
 increase coverage!
 
-Unlike with Travis, Codecov tests are not required to pass in order for your
+Unlike with CI on Github Actions Codecov tests are not required to pass in order for your
 PR to be merged. If you modify core Spack libraries, we would greatly
 appreciate unit tests that cover these changed lines. Otherwise, we have no
 way of knowing whether or not your changes introduce a bug. If you make

lib/spack/docs/developer_guide.rst

@@ -363,11 +363,12 @@ Developer commands
 ``spack doc``
 ^^^^^^^^^^^^^
 
-^^^^^^^^^^^^^^
-``spack test``
-^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^
+``spack unit-test``
+^^^^^^^^^^^^^^^^^^^
 
-See the :ref:`contributor guide section <cmd-spack-test>` on ``spack test``.
+See the :ref:`contributor guide section <cmd-spack-unit-test>` on
+``spack unit-test``.
 
 .. _cmd-spack-python:
 
@@ -495,3 +496,398 @@ The bottom of the output shows the top most time consuming functions,
 slowest on top.  The profiling support is from Python's built-in tool,
 `cProfile
 <https://docs.python.org/2/library/profile.html#module-cProfile>`_.
+
+.. _releases:
+
+--------
+Releases
+--------
+
+This section documents Spack's release process. It is intended for
+project maintainers, as the tasks described here require maintainer
+privileges on the Spack repository. For others, we hope this section at
+least provides some insight into how the Spack project works.
+
+.. _release-branches:
+
+^^^^^^^^^^^^^^^^
+Release branches
+^^^^^^^^^^^^^^^^
+
+There are currently two types of Spack releases: :ref:`major releases
+<major-releases>` (``0.13.0``, ``0.14.0``, etc.) and :ref:`point releases
+<point-releases>` (``0.13.1``, ``0.13.2``, ``0.13.3``, etc.). Here is a
+diagram of how Spack release branches work::
+
+    o    branch: develop  (latest version)
+    |
+    o    merge v0.14.1 into develop
+    |\
+    | o  branch: releases/v0.14, tag: v0.14.1
+    o |  merge v0.14.0 into develop
+    |\|
+    | o  tag: v0.14.0
+    |/
+    o    merge v0.13.2 into develop
+    |\
+    | o  branch: releases/v0.13, tag: v0.13.2
+    o |  merge v0.13.1 into develop
+    |\|
+    | o  tag: v0.13.1
+    o |  merge v0.13.0 into develop
+    |\|
+    | o  tag: v0.13.0
+    o |
+    | o
+    |/
+    o
+
+The ``develop`` branch has the latest contributions, and nearly all pull
+requests target ``develop``.
+
+Each Spack release series also has a corresponding branch, e.g.
+``releases/v0.14`` has ``0.14.x`` versions of Spack, and
+``releases/v0.13`` has ``0.13.x`` versions. A major release is the first
+tagged version on a release branch. Minor releases are back-ported from
+develop onto release branches. This is typically done by cherry-picking
+bugfix commits off of ``develop``.
+
+To avoid version churn for users of a release series, minor releases
+should **not** make changes that would change the concretization of
+packages. They should generally only contain fixes to the Spack core.
+
+Both major and minor releases are tagged. After each release, we merge
+the release branch back into ``develop`` so that the version bump and any
+other release-specific changes are visible in the mainline. As a
+convenience, we also tag the latest release as ``releases/latest``,
+so that users can easily check it out to get the latest
+stable version. See :ref:`merging-releases` for more details.
+
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Scheduling work for releases
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+We schedule work for releases by creating `GitHub projects
+<https://github.com/spack/spack/projects>`_. At any time, there may be
+several open release projects. For example, here are two releases (from
+some past version of the page linked above):
+
+.. image:: images/projects.png
+
+Here, there's one release in progress for ``0.15.1`` and another for
+``0.16.0``. Each of these releases has a project board containing issues
+and pull requests. GitHub shows a status bar with completed work in
+green, work in progress in purple, and work not started yet in gray, so
+it's fairly easy to see progress.
+
+Spack's project boards are not firm commitments, and we move work between
+releases frequently. If we need to make a release and some tasks are not
+yet done, we will simply move them to next minor or major release, rather
+than delaying the release to complete them.
+
+For more on using GitHub project boards, see `GitHub's documentation
+<https://docs.github.com/en/github/managing-your-work-on-github/about-project-boards>`_.
+
+.. _major-releases:
+
+^^^^^^^^^^^^^^^^^^^^^
+Making Major Releases
+^^^^^^^^^^^^^^^^^^^^^
+
+Assuming you've already created a project board and completed the work
+for a major release, the steps to make the release are as follows:
+
+#. Create two new project boards:
+
+   * One for the next major release
+   * One for the next point release
+
+#. Move any tasks that aren't done yet to one of the new project boards.
+   Small bugfixes should go to the next point release. Major features,
+   refactors, and changes that could affect concretization should go in
+   the next major release.
+
+#. Create a branch for the release, based on ``develop``:
+
+   .. code-block:: console
+
+      $ git checkout -b releases/v0.15 develop
+
+   For a version ``vX.Y.Z``, the branch's name should be
+   ``releases/vX.Y``. That is, you should create a ``releases/vX.Y``
+   branch if you are preparing the ``X.Y.0`` release.
+
+#. Bump the version in ``lib/spack/spack/__init__.py``. See `this example from 0.13.0
+   <https://github.com/spack/spack/commit/8eeb64096c98b8a43d1c587f13ece743c864fba9>`_
+
+#. Update the release version lists in these files to include the new version:
+
+   * ``lib/spack/spack/schema/container.py``
+   * ``lib/spack/spack/container/images.json``
+
+.. TODO: We should get rid of this step in some future release.
+
+#. Update ``CHANGELOG.md`` with major highlights in bullet form. Use
+   proper markdown formatting, like `this example from 0.15.0
+   <https://github.com/spack/spack/commit/d4bf70d9882fcfe88507e9cb444331d7dd7ba71c>`_.
+
+#. Push the release branch to GitHub.
+
+#. Make sure CI passes on the release branch, including:
+
+   * Regular unit tests
+   * Build tests
+   * The E4S pipeline at `gitlab.spack.io <https://gitlab.spack.io>`_
+
+   If CI is not passing, submit pull requests to ``develop`` as normal
+   and keep rebasing the release branch on ``develop`` until CI passes.
+
+#. Follow the steps in :ref:`publishing-releases`.
+
+#. Follow the steps in :ref:`merging-releases`.
+
+#. Follow the steps in :ref:`announcing-releases`.
+
+
+.. _point-releases:
+
+^^^^^^^^^^^^^^^^^^^^^
+Making Point Releases
+^^^^^^^^^^^^^^^^^^^^^
+
+This assumes you've already created a project board for a point release
+and completed the work to be done for the release. To make a point
+release:
+
+#. Create one new project board for the next point release.
+
+#. Move any cards that aren't done yet to the next project board.
+
+#. Check out the release branch (it should already exist). For the
+   ``X.Y.Z`` release, the release branch is called ``releases/vX.Y``. For
+   ``v0.15.1``, you would check out ``releases/v0.15``:
+
+   .. code-block:: console
+
+      $ git checkout releases/v0.15
+
+#. Cherry-pick each pull request in the ``Done`` column of the release
+   project onto the release branch.
+
+   This is **usually** fairly simple since we squash the commits from the
+   vast majority of pull requests, which means there is only one commit
+   per pull request to cherry-pick. For example, `this pull request
+   <https://github.com/spack/spack/pull/15777>`_ has three commits, but
+   the were squashed into a single commit on merge. You can see the
+   commit that was created here:
+
+   .. image:: images/pr-commit.png
+
+   You can easily cherry pick it like this (assuming you already have the
+   release branch checked out):
+
+   .. code-block:: console
+
+      $ git cherry-pick 7e46da7
+
+   For pull requests that were rebased, you'll need to cherry-pick each
+   rebased commit individually. There have not been any rebased PRs like
+   this in recent point releases.
+
+   .. warning::
+
+      It is important to cherry-pick commits in the order they happened,
+      otherwise you can get conflicts while cherry-picking. When
+      cherry-picking onto a point release, look at the merge date,
+      **not** the number of the pull request or the date it was opened.
+
+      Sometimes you may **still** get merge conflicts even if you have
+      cherry-picked all the commits in order. This generally means there
+      is some other intervening pull request that the one you're trying
+      to pick depends on. In these cases, you'll need to make a judgment
+      call:
+
+      1. If the dependency is small, you might just cherry-pick it, too.
+         If you do this, add it to the release board.
+
+      2. If it is large, then you may decide that this fix is not worth
+         including in a point release, in which case you should remove it
+         from the release project.
+
+      3. You can always decide to manually back-port the fix to the release
+         branch if neither of the above options makes sense, but this can
+         require a lot of work. It's seldom the right choice.
+
+#. Bump the version in ``lib/spack/spack/__init__.py``. See `this example from 0.14.1
+   <https://github.com/spack/spack/commit/ff0abb9838121522321df2a054d18e54b566b44a>`_.
+
+#. Updaate the release version lists in these files to include the new version:
+
+   * ``lib/spack/spack/schema/container.py``
+   * ``lib/spack/spack/container/images.json``
+
+   **TODO**: We should get rid of this step in some future release.
+
+#. Update ``CHANGELOG.md`` with a list of bugfixes. This is typically just a
+   summary of the commits you cherry-picked onto the release branch. See
+   `the changelog from 0.14.1
+   <https://github.com/spack/spack/commit/ff0abb9838121522321df2a054d18e54b566b44a>`_.
+
+#. Push the release branch to GitHub.
+
+#. Make sure CI passes on the release branch, including:
+   * Regular unit tests
+   * Build tests
+   * The E4S pipeline at `gitlab.spack.io <https://gitlab.spack.io>`_
+
+   If CI does not pass, you'll need to figure out why, and make changes
+   to the release branch until it does. You can make more commits, modify
+   or remove cherry-picked commits, or cherry-pick **more** from
+   ``develop`` to make this happen.
+
+#. Follow the steps in :ref:`publishing-releases`.
+
+#. Follow the steps in :ref:`merging-releases`.
+
+#. Follow the steps in :ref:`announcing-releases`.
+
+
+.. _publishing-releases:
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Publishing a release on GitHub
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. Go to `github.com/spack/spack/releases
+   <https://github.com/spack/spack/releases>`_ and click ``Draft a new
+   release``.  Set the following:
+
+   * ``Tag version`` should start with ``v`` and contain *all three*
+     parts of the version, .g. ``v0.15.1``. This is the name of the tag
+     that will be created.
+
+   * ``Target`` should be the ``releases/vX.Y`` branch (e.g., ``releases/v0.15``).
+
+   * ``Release title`` should be ``vX.Y.Z`` (To match the tag, e.g., ``v0.15.1``).
+
+   * For the text, paste the latest release markdown from your ``CHANGELOG.md``.
+
+   You can save the draft and keep coming back to this as you prepare the release.
+
+#. When you are done, click ``Publish release``.
+
+#. Immediately after publishing, go back to
+   `github.com/spack/spack/releases
+   <https://github.com/spack/spack/releases>`_ and download the
+   auto-generated ``.tar.gz`` file for the release. It's the ``Source
+   code (tar.gz)`` link.
+
+#. Click ``Edit`` on the release you just did and attach the downloaded
+   release tarball as a binary. This does two things:
+
+   #. Makes sure that the hash of our releases doesn't change over time.
+      GitHub sometimes annoyingly changes they way they generate
+      tarballs, and then hashes can change if you rely on the
+      auto-generated tarball links.
+
+   #. Gets us download counts on releases visible through the GitHub
+      API. GitHub tracks downloads of artifacts, but *not* the source
+      links. See the `releases
+      page <https://api.github.com/repos/spack/spack/releases>`_ and search
+      for ``download_count`` to see this.
+
+#. Go to `readthedocs.org <https://readthedocs.org/projects/spack>`_ and activate
+   the release tag. This builds the documentation and makes the released version
+   selectable in the versions menu.
+
+
+.. _merging-releases:
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Updating `releases/latest` and `develop`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If the new release is the **highest** Spack release yet, you should
+also tag it as ``releases/latest``. For example, suppose the highest
+release is currently ``0.15.3``:
+
+     * If you are releasing ``0.15.4`` or ``0.16.0``, then you should tag
+       it with ``releases/latest``, as these are higher than ``0.15.3``.
+
+     * If you are making a new release of an **older** major version of
+       Spack, e.g. ``0.14.4``, then you should not tag it as
+       ``releases/latest`` (as there are newer major versions).
+
+   To tag ``releases/latest``, do this:
+
+   .. code-block:: console
+
+      $ git checkout releases/vX.Y     # vX.Y is the new release's branch
+      $ git tag --force releases/latest
+      $ git push --tags
+
+   The ``--force`` argument makes ``git`` overwrite the existing
+   ``releases/latest`` tag with the new one.
+
+We also merge each release that we tag as ``releases/latest`` into ``develop``.
+Make sure to do this with a merge commit:
+
+.. code-block:: console
+
+   $ git checkout develop
+   $ git merge --no-ff vX.Y.Z  # vX.Y.Z is the new release's tag
+   $ git push
+
+We merge back to ``develop`` because it:
+
+  * updates the version and ``CHANGELOG.md`` on ``develop``.
+  * ensures that your release tag is reachable from the head of
+    ``develop``
+
+We *must* use a real merge commit (via the ``--no-ff`` option) because it
+ensures that the release tag is reachable from the tip of ``develop``.
+This is necessary for ``spack -V`` to work properly -- it uses ``git
+describe --tags`` to find the last reachable tag in the repository and
+reports how far we are from it. For example:
+
+.. code-block:: console
+
+   $ spack -V
+   0.14.2-1486-b80d5e74e5
+
+This says that we are at commit ``b80d5e74e5``, which is 1,486 commits
+ahead of the ``0.14.2`` release.
+
+We put this step last in the process because it's best to do it only once
+the release is complete and tagged. If you do it before you've tagged the
+release and later decide you want to tag some later commit, you'll need
+to merge again.
+
+.. _announcing-releases:
+
+^^^^^^^^^^^^^^^^^^^^
+Announcing a release
+^^^^^^^^^^^^^^^^^^^^
+
+We announce releases in all of the major Spack communication channels.
+Publishing the release takes care of GitHub. The remaining channels are
+Twitter, Slack, and the mailing list. Here are the steps:
+
+#. Make a tweet to announce the release. It should link to the release's
+   page on GitHub. You can base it on `this example tweet
+   <https://twitter.com/spackpm/status/1231761858182307840>`_.
+
+#. Ping ``@channel`` in ``#general`` on Slack (`spackpm.slack.com
+   <https://spackpm.slack.com>`_) with a link to the tweet. The tweet
+   will be shown inline so that you do not have to retype your release
+   announcement.
+
+#. Email the Spack mailing list to let them know about the release. As
+   with the tweet, you likely want to link to the release's page on
+   GitHub. It's also helpful to include some information directly in the
+   email. You can base yours on this `example email
+   <https://groups.google.com/forum/#!topic/spack/WT4CT9i_X4s>`_.
+
+Once you've announced the release, congratulations, you're done! You've
+finished making the release!

lib/spack/docs/environments.rst

@@ -130,7 +130,7 @@ To activate an environment, use the following command:
 By default, the ``spack env activate`` will load the view associated
 with the Environment into the user environment. The ``-v,
 --with-view`` argument ensures this behavior, and the ``-V,
---without-vew`` argument activates the environment without changing
+--without-view`` argument activates the environment without changing
 the user environment variables.
 
 The ``-p`` option to the ``spack env activate`` command modifies the
@@ -167,15 +167,6 @@ Any directory can be treated as an environment if it contains a file
 
    $ spack env activate -d /path/to/directory
 
-Spack commands that are environment sensitive will also act on the
-environment any time the current working directory contains a
-``spack.yaml`` file. Changing working directory to a directory
-containing a ``spack.yaml`` file is equivalent to the command:
-
-.. code-block:: console
-
-   $ spack env activate -d /path/to/dir --without-view
-
 Anonymous specs can be created in place using the command:
 
 .. code-block:: console
@@ -281,18 +272,18 @@ in the lockfile, nor does it install the spec.
 
 The ``spack add`` command is environment aware. It adds to the
 currently active environment. All environment aware commands can also
-be called using the ``spack -E`` flag to specify the environment.
+be called using the ``spack -e`` flag to specify the environment.
 
 .. code-block:: console
 
-   $ spack activate myenv
+   $ spack env activate myenv
    $ spack add mpileaks
 
 or
 
 .. code-block:: console
 
-   $ spack -E myenv add python
+   $ spack -e myenv add python
 
 .. _environments_concretization:
 
@@ -602,7 +593,7 @@ files are identical.
    spack:
      definitions:
        - first: [libelf, libdwarf]
-       - compilers: ['%gcc', '^intel']
+       - compilers: ['%gcc', '%intel']
        - second:
            - $first
            - matrix:
@@ -647,7 +638,7 @@ named list ``compilers`` is ``['%gcc', '%clang', '%intel']`` on
    spack:
      definitions:
        - compilers: ['%gcc', '%clang']
-       - when: target == 'x86_64'
+       - when: arch.satisfies('x86_64:')
          compilers: ['%intel']
 
 .. note::
@@ -666,8 +657,12 @@ The valid variables for a ``when`` clause are:
 #. ``target``. The target string of the default Spack
    architecture on the system.
 
-#. ``architecture`` or ``arch``. The full string of the
-   default Spack architecture on the system.
+#. ``architecture`` or ``arch``. A Spack spec satisfying the default Spack
+   architecture on the system. This supports querying via the ``satisfies``
+   method, as shown above.
+
+#. ``arch_str``. The architecture string of the default Spack architecture
+   on the system.
 
 #. ``re``. The standard regex module in Python.
 
@@ -676,6 +671,40 @@ The valid variables for a ``when`` clause are:
 #. ``hostname``. The hostname of the system (if ``hostname`` is an
    executable in the user's PATH).
 
+""""""""""""""""""""""""
+SpecLists as Constraints
+""""""""""""""""""""""""
+
+Dependencies and compilers in Spack can be both packages in an
+environment and constraints on other packages. References to SpecLists
+allow a shorthand to treat packages in a list as either a compiler or
+a dependency using the ``$%`` or ``$^`` syntax respectively.
+
+For example, the following environment has three root packages:
+``gcc@8.1.0``, ``mvapich2@2.3.1 %gcc@8.1.0``, and ``hdf5+mpi
+%gcc@8.1.0 ^mvapich2@2.3.1``.
+
+.. code-block:: yaml
+
+   spack:
+     definitions:
+     - compilers: [gcc@8.1.0]
+     - mpis: [mvapich2@2.3.1]
+     - packages: [hdf5+mpi]
+
+     specs:
+     - $compilers
+     - matrix:
+       - [$mpis]
+       - [$%compilers]
+     - matrix:
+       - [$packages]
+       - [$^mpis]
+       - [$%compilers]
+
+This allows for a much-needed reduction in redundancy between packages
+and constraints.
+
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 Environment-managed Views
 ^^^^^^^^^^^^^^^^^^^^^^^^^

lib/spack/docs/extensions.rst

@@ -87,11 +87,12 @@ will be available from the command line:
      --implicit       select specs that are not installed or were installed implicitly
      --output OUTPUT  where to dump the result
 
-The corresponding unit tests can be run giving the appropriate options to ``spack test``:
+The corresponding unit tests can be run giving the appropriate options
+to ``spack unit-test``:
 
 .. code-block:: console
 
-   $ spack test --extension=scripting
+   $ spack unit-test --extension=scripting
 
    ============================================================== test session starts ===============================================================
    platform linux2 -- Python 2.7.15rc1, pytest-3.2.5, py-1.4.34, pluggy-0.4.0

lib/spack/docs/features.rst

@@ -48,8 +48,8 @@ platform, all on the command line.
    # Add compiler flags using the conventional names
    $ spack install mpileaks@1.1.2 %gcc@4.7.3 cppflags="-O3 -floop-block"
 
-   # Cross-compile for a different architecture with arch=
-   $ spack install mpileaks@1.1.2 arch=bgqos_0
+   # Cross-compile for a different micro-architecture with target=
+   $ spack install mpileaks@1.1.2 target=icelake
 
 Users can specify as many or few options as they care about. Spack
 will fill in the unspecified values with sensible defaults. The two listed

lib/spack/docs/getting_started.rst

@@ -19,6 +19,9 @@ before Spack is run:
 #. Python 2 (2.6 or 2.7) or 3 (3.5 - 3.8) to run Spack
 #. A C/C++ compiler for building
 #. The ``make`` executable for building
+#. The ``tar``, ``gzip``, ``bzip2``, ``xz`` and optionally ``zstd``
+   executables for extracting source code
+#. The ``patch`` command to apply patches
 #. The ``git`` and ``curl`` commands for fetching
 #. If using the ``gpg`` subcommand, ``gnupg2`` is required
 
@@ -50,31 +53,42 @@ in the ``SPACK_ROOT`` environment variable.  Add ``$SPACK_ROOT/bin``
 to your path and you're ready to go:
 
 .. code-block:: console
-
+   
+   # For bash/zsh users
+   $ export SPACK_ROOT=/path/to/spack
    $ export PATH=$SPACK_ROOT/bin:$PATH
+
+   # For tsch/csh users 
+   $ setenv SPACK_ROOT /path/to/spack
+   $ setenv PATH $SPACK_ROOT/bin:$PATH
+
+   # For fish users
+   $ set -x SPACK_ROOT /path/to/spack
+   $ set -U fish_user_paths /path/to/spack $fish_user_paths
+
+.. code-block:: console
+
    $ spack install libelf
 
 For a richer experience, use Spack's shell support:
 
 .. code-block:: console
 
+   # Note you must set SPACK_ROOT
+
    # For bash/zsh users
-   $ export SPACK_ROOT=/path/to/spack
    $ . $SPACK_ROOT/share/spack/setup-env.sh
 
-   # For tcsh or csh users (note you must set SPACK_ROOT)
-   $ setenv SPACK_ROOT /path/to/spack
+   # For tcsh/csh users
    $ source $SPACK_ROOT/share/spack/setup-env.csh
 
+   # For fish users
+   $ source $SPACK_ROOT/share/spack/setup-env.fish
 
 This automatically adds Spack to your ``PATH`` and allows the ``spack``
 command to be used to execute spack :ref:`commands <shell-support>` and
 :ref:`useful packaging commands <packaging-shell-support>`.
 
-If :ref:`environment-modules <InstallEnvironmentModules>` is
-installed and available, the ``spack`` command can also load and unload
-:ref:`modules <modules>`.
-
 ^^^^^^^^^^^^^^^^^
 Clean Environment
 ^^^^^^^^^^^^^^^^^
@@ -482,7 +496,7 @@ Fortran.
           cxx: /usr/bin/clang++
           f77: /path/to/bin/gfortran
           fc: /path/to/bin/gfortran
-        spec: clang@11.0.0-apple
+        spec: apple-clang@11.0.0
 
 
    If you used Spack to install GCC, you can get the installation prefix by
@@ -716,8 +730,9 @@ an OpenMPI installed in /opt/local, one would use:
 
     packages:
         openmpi:
-            paths:
-                openmpi@1.10.1: /opt/local
+            externals:
+            - spec: openmpi@1.10.1
+              prefix: /opt/local
             buildable: False
 
 In general, Spack is easier to use and more reliable if it builds all of
@@ -779,8 +794,9 @@ Then add the following to ``~/.spack/packages.yaml``:
 
     packages:
         openssl:
-            paths:
-                openssl@1.0.2g: /usr
+            externals:
+            - spec: openssl@1.0.2g
+              prefix: /usr
             buildable: False
 
 
@@ -795,8 +811,9 @@ to add the following to ``packages.yaml``:
 
     packages:
         netlib-lapack:
-            paths:
-                netlib-lapack@3.6.1: /usr
+            externals:
+            - spec: netlib-lapack@3.6.1
+              prefix: /usr
             buildable: False
         all:
             providers:
@@ -822,7 +839,7 @@ Git
 
 Some Spack packages use ``git`` to download, which might not work on
 some computers.  For example, the following error was
-encountered on a Macintosh during ``spack install julia-master``:
+encountered on a Macintosh during ``spack install julia@master``:
 
 .. code-block:: console
 
@@ -851,7 +868,7 @@ from websites and from git.
 
 .. warning::
 
-   This workaround should be used ONLY as a last resort!  Wihout SSL
+   This workaround should be used ONLY as a last resort!  Without SSL
    certificate verification, spack and git will download from sites you
    wouldn't normally trust.  The code you download and run may then be
    compromised!  While this is not a major issue for archives that will
@@ -900,9 +917,8 @@ Core Spack Utilities
 ^^^^^^^^^^^^^^^^^^^^
 
 Core Spack uses the following packages, mainly to download and unpack
-source code, and to load generated environment modules: ``curl``,
-``env``, ``git``, ``go``, ``hg``, ``svn``, ``tar``, ``unzip``,
-``patch``, ``environment-modules``.
+source code: ``curl``, ``env``, ``git``, ``go``, ``hg``, ``svn``,
+``tar``, ``unzip``, ``patch``
 
 As long as the user's environment is set up to successfully run these
 programs from outside of Spack, they should work inside of Spack as
@@ -910,10 +926,6 @@ well.  They can generally be activated as in the ``curl`` example above;
 or some systems might already have an appropriate hand-built
 environment module that may be loaded.  Either way works.
 
-If you find that you are missing some of these programs, ``spack`` can
-build some of them for you with ``spack bootstrap``. Currently supported
-programs are ``environment-modules``.
-
 A few notes on specific programs in this list:
 
 """"""""""""""""""""""""""
@@ -941,45 +953,6 @@ other programs will also not work, because they also rely on OpenSSL.
 Once ``curl`` has been installed, you can similarly install the others.
 
 
-.. _InstallEnvironmentModules:
-
-"""""""""""""""""""
-Environment Modules
-"""""""""""""""""""
-
-In order to use Spack's generated module files, you must have
-installed ``environment-modules`` or ``lmod``. The simplest way
-to get the latest version of either of these tools is installing
-it as part of Spack's bootstrap procedure:
-
-.. code-block:: console
-
-   $ spack bootstrap
-
-.. warning::
-   At the moment ``spack bootstrap`` is only able to install ``environment-modules``.
-   Extending its capabilities to prefer ``lmod`` where possible is in the roadmap,
-   and likely to happen before the next release.
-
-Alternatively, on many Linux distributions, you can install a pre-built binary
-from the vendor's repository. On Fedora/RHEL/CentOS, for example, this can be
-done with the command:
-
-.. code-block:: console
-
-   $ yum install environment-modules
-
-Once you have the tool installed and available in your path, you can source
-Spack's setup file:
-
-.. code-block:: console
-
-   $ source share/spack/setup-env.sh
-
-This activates :ref:`shell support <shell-support>` and makes commands like
-``spack load`` available for use.
-
-
 ^^^^^^^^^^^^^^^^^
 Package Utilities
 ^^^^^^^^^^^^^^^^^
@@ -1229,9 +1202,13 @@ Here's an example of an external configuration for cray modules:
 
    packages:
      mpich:
-       modules:
-         mpich@7.3.1%gcc@5.2.0 arch=cray_xc-haswell-CNL10: cray-mpich
-         mpich@7.3.1%intel@16.0.0.109 arch=cray_xc-haswell-CNL10: cray-mpich
+       externals:
+       - spec: "mpich@7.3.1%gcc@5.2.0 arch=cray_xc-haswell-CNL10"
+         modules:
+         - cray-mpich
+       - spec: "mpich@7.3.1%intel@16.0.0.109 arch=cray_xc-haswell-CNL10"
+         modules:
+         - cray-mpich
      all:
        providers:
          mpi: [mpich]
@@ -1243,7 +1220,7 @@ via module load.
 
 .. note::
 
-    For Cray-provided packages, it is best to use ``modules:`` instead of ``paths:``
+    For Cray-provided packages, it is best to use ``modules:`` instead of ``prefix:``
     in ``packages.yaml``, because the Cray Programming Environment heavily relies on
     modules (e.g., loading the ``cray-mpich`` module adds MPI libraries to the
     compiler wrapper link line).
@@ -1259,19 +1236,31 @@ Here is an example of a full packages.yaml used at NERSC
 
    packages:
      mpich:
-       modules:
-         mpich@7.3.1%gcc@5.2.0 arch=cray_xc-CNL10-ivybridge: cray-mpich
-         mpich@7.3.1%intel@16.0.0.109 arch=cray_xc-SuSE11-ivybridge: cray-mpich
+       externals:
+       - spec: "mpich@7.3.1%gcc@5.2.0 arch=cray_xc-CNL10-ivybridge"
+         modules:
+         - cray-mpich
+       - spec: "mpich@7.3.1%intel@16.0.0.109 arch=cray_xc-SuSE11-ivybridge"
+         modules:
+         - cray-mpich
        buildable: False
      netcdf:
-       modules:
-         netcdf@4.3.3.1%gcc@5.2.0 arch=cray_xc-CNL10-ivybridge: cray-netcdf
-         netcdf@4.3.3.1%intel@16.0.0.109 arch=cray_xc-CNL10-ivybridge: cray-netcdf
+       externals:
+       - spec: "netcdf@4.3.3.1%gcc@5.2.0 arch=cray_xc-CNL10-ivybridge"
+         modules:
+         - cray-netcdf
+       - spec: "netcdf@4.3.3.1%intel@16.0.0.109 arch=cray_xc-CNL10-ivybridge"
+         modules:
+         - cray-netcdf
        buildable: False
      hdf5:
-       modules:
-         hdf5@1.8.14%gcc@5.2.0 arch=cray_xc-CNL10-ivybridge: cray-hdf5
-         hdf5@1.8.14%intel@16.0.0.109 arch=cray_xc-CNL10-ivybridge: cray-hdf5
+       externals:
+       - spec: "hdf5@1.8.14%gcc@5.2.0 arch=cray_xc-CNL10-ivybridge"
+         modules:
+         - cray-hdf5
+       - spec: "hdf5@1.8.14%intel@16.0.0.109 arch=cray_xc-CNL10-ivybridge"
+         modules:
+         - cray-hdf5
        buildable: False
      all:
        compiler: [gcc@5.2.0, intel@16.0.0.109]
@@ -1295,6 +1284,6 @@ environment variables may be propagated into containers that are not
 using the Cray programming environment.
 
 To ensure that Spack does not autodetect the Cray programming
-environment, unset the environment variable ``CRAYPE_VERSION``. This
+environment, unset the environment variable ``MODULEPATH``. This
 will cause Spack to treat a linux container on a Cray system as a base
 linux distro.

lib/spack/docs/known_issues.rst

@@ -14,7 +14,7 @@ problems if you encounter them.
 Variants are not properly forwarded to dependencies
 ---------------------------------------------------
 
-**Status:** Expected to be fixed in the next release
+**Status:** Expected to be fixed by Spack's new concretizer
 
 Sometimes, a variant of a package can also affect how its dependencies are
 built. For example, in order to build MPI support for a package, it may
@@ -49,15 +49,29 @@ A workaround is to explicitly activate the variants of dependencies as well:
 See https://github.com/spack/spack/issues/267 and
 https://github.com/spack/spack/issues/2546 for further details.
 
+-----------------------------------------------
+depends_on cannot handle recursive dependencies
+-----------------------------------------------
 
-----------------------------
-``spack setup`` doesn't work
-----------------------------
+**Status:** Not yet a work in progress
 
-**Status:** Work in progress
+Although ``depends_on`` can handle any aspect of Spack's spec syntax,
+it currently cannot handle recursive dependencies. If the ``^`` sigil
+appears in a ``depends_on`` statement, the concretizer will hang.
+For example, something like:
 
-Spack provides a ``setup`` command that is useful for the development of
-software outside of Spack. Unfortunately, this command no longer works.
-See https://github.com/spack/spack/issues/2597 and
-https://github.com/spack/spack/issues/2662 for details. This is expected
-to be fixed by https://github.com/spack/spack/pull/2664.
+.. code-block:: python
+
+   depends_on('mfem+cuda ^hypre+cuda', when='+cuda')
+
+
+should be rewritten as:
+
+.. code-block:: python
+
+   depends_on('mfem+cuda', when='+cuda')
+   depends_on('hypre+cuda', when='+cuda')
+
+
+See https://github.com/spack/spack/issues/17660 and
+https://github.com/spack/spack/issues/11160 for more details.

lib/spack/docs/module_file_support.rst

@@ -17,22 +17,16 @@ Spack integrates with `Environment Modules
 <http://lmod.readthedocs.io/en/latest/>`_ by
 providing post-install hooks that generate module files and commands to manipulate them.
 
-.. note::
-
-   If your machine does not already have a module system installed,
-   we advise you to use either Environment Modules or LMod. See :ref:`InstallEnvironmentModules`
-   for more details.
-
 .. _shell-support:
 
 ----------------------------
 Using module files via Spack
 ----------------------------
 
-If you have installed a supported module system either manually or through
-``spack bootstrap``, you should be able to run either ``module avail`` or
-``use -l spack`` to see what module files have been installed.  Here is
-sample output of those programs, showing lots of installed packages:
+If you have installed a supported module system you should be able to
+run either ``module avail`` or ``use -l spack`` to see what module
+files have been installed.  Here is sample output of those programs,
+showing lots of installed packages:
 
 .. code-block:: console
 
@@ -93,9 +87,7 @@ Note that in the latter case it is necessary to explicitly set ``SPACK_ROOT``
 before sourcing the setup file (you will get a meaningful error message
 if you don't).
 
-When ``bash`` and ``ksh`` users update their environment with ``setup-env.sh``, it will check for spack-installed environment modules and add the ``module`` command to their environment; This only occurs if the module command is not already available. You can install ``environment-modules`` with ``spack bootstrap`` as described in :ref:`InstallEnvironmentModules`.
-
-Finally, if you want to have Spack's shell support available on the command line at
+If you want to have Spack's shell support available on the command line at
 any login you can put this source line in one of the files that are sourced
 at startup (like ``.profile``, ``.bashrc`` or ``.cshrc``). Be aware though
 that the startup time may be slightly increased because of that.
@@ -165,8 +157,6 @@ used ``gcc``.  You could therefore just type:
 
 To identify just the one built with the Intel compiler.
 
-.. _extensions:
-
 .. _cmd-spack-module-loads:
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -469,14 +459,14 @@ is compiled with ``gcc@4.4.7``, with the only exception of any ``gcc``
 or any ``llvm`` installation.
 
 
-.. _modules-naming-scheme:
+.. _modules-projections:
 
-"""""""""""""""""""""""""""
-Customize the naming scheme
-"""""""""""""""""""""""""""
+"""""""""""""""""""""""""""""""
+Customize the naming of modules
+"""""""""""""""""""""""""""""""
 
 The names of environment modules generated by spack are not always easy to
-fully comprehend due to the long hash in the name. There are two module
+fully comprehend due to the long hash in the name. There are three module
 configuration options to help with that. The first is a global setting to
 adjust the hash length. It can be set anywhere from 0 to 32 and has a default
 length of 7. This is the representation of the hash in the module file name and
@@ -510,20 +500,46 @@ version of python a set of python extensions is associated with. Likewise, the
 ``openblas`` string is attached to any program that has openblas in the spec,
 most likely via the ``+blas`` variant specification.
 
+The most heavyweight solution to module naming is to change the entire
+naming convention for module files. This uses the projections format
+covered in :ref:`adding_projections_to_views`.
+
+.. code-block:: yaml
+
+  modules:
+    tcl:
+      projections:
+        all: '{name}/{version}-{compiler.name}-{compiler.version}-module'
+        ^mpi: '{name}/{version}-{^mpi.name}-{^mpi.version}-{compiler.name}-{compiler.version}-module'
+
+will create module files that are nested in directories by package
+name, contain the version and compiler name and version, and have the
+word ``module`` before the hash for all specs that do not depend on
+mpi, and will have the same information plus the MPI implementation
+name and version for all packages that depend on mpi.
+
+When specifying module names by projection for Lmod modules, we
+recommend NOT including names of dependencies (e.g., MPI, compilers)
+that are already in the LMod hierarchy.
+
+
+
 .. note::
-   TCL module files
-     A modification that is specific to ``tcl`` module files is the possibility
-     to change the naming scheme of modules.
+   TCL modules
+     TCL modules also allow for explicit conflicts between modulefiles.
 
      .. code-block:: yaml
 
-       modules:
-         tcl:
-           naming_scheme: '{name}/{version}-{compiler.name}-{compiler.version}'
-           all:
-             conflict:
-               - '{name}'
-               - 'intel/14.0.1'
+        modules:
+          enable:
+            - tcl
+          tcl:
+            projections:
+              all: '{name}/{version}-{compiler.name}-{compiler.version}'
+            all:
+              conflict:
+                - '{name}'
+                - 'intel/14.0.1'
 
      will create module files that will conflict with ``intel/14.0.1`` and with the
      base directory of the same module, effectively preventing the possibility to
@@ -548,6 +564,8 @@ most likely via the ``+blas`` variant specification.
          lmod:
            core_compilers:
              - 'gcc@4.8'
+           core_specs:
+             - 'python'
            hierarchy:
              - 'mpi'
              - 'lapack'
@@ -557,6 +575,15 @@ most likely via the ``+blas`` variant specification.
      implementations of ``mpi`` and ``lapack``, and let LMod switch safely from one to the
      other.
 
+     All packages built with a compiler in ``core_compilers`` and all
+     packages that satisfy a spec in ``core_specs`` will be put in the
+     ``Core`` hierarchy of the lua modules.
+
+.. warning::
+  Consistency of Core packages
+   The user is responsible for maintining consistency among core packages, as ``core_specs``
+   bypasses the hierarchy that allows LMod to safely switch between coherent software stacks.
+
 .. warning::
   Deep hierarchies and ``lmod spider``
    For hierarchies that are deeper than three layers ``lmod spider`` may have some issues.

lib/spack/docs/packaging_guide.rst

@@ -645,7 +645,7 @@ multiple fields based on delimiters such as ``.``, ``-`` etc. Then
 matching fields are compared using the rules below:
 
 #. The following develop-like strings are greater (newer) than all
-   numbers and are ordered as ``develop > master > head > trunk``.
+   numbers and are ordered as ``develop > main > master > head > trunk``.
 
 #. Numbers are all less than the chosen develop-like strings above,
    and are sorted numerically.
@@ -1675,15 +1675,15 @@ can see the patches that would be applied to ``m4``::
 
   Concretized
   --------------------------------
-  m4@1.4.18%clang@9.0.0-apple patches=3877ab548f88597ab2327a2230ee048d2d07ace1062efe81fc92e91b7f39cd00,c0a408fbffb7255fcc75e26bd8edab116fc81d216bfd18b473668b7739a4158e,fc9b61654a3ba1a8d6cd78ce087e7c96366c290bc8d2c299f09828d793b853c8 +sigsegv arch=darwin-highsierra-x86_64
-      ^libsigsegv@2.11%clang@9.0.0-apple arch=darwin-highsierra-x86_64
+  m4@1.4.18%apple-clang@9.0.0 patches=3877ab548f88597ab2327a2230ee048d2d07ace1062efe81fc92e91b7f39cd00,c0a408fbffb7255fcc75e26bd8edab116fc81d216bfd18b473668b7739a4158e,fc9b61654a3ba1a8d6cd78ce087e7c96366c290bc8d2c299f09828d793b853c8 +sigsegv arch=darwin-highsierra-x86_64
+      ^libsigsegv@2.11%apple-clang@9.0.0 arch=darwin-highsierra-x86_64
 
 You can also see patches that have been applied to installed packages
 with ``spack find -v``::
 
   $ spack find -v m4
   ==> 1 installed package
-  -- darwin-highsierra-x86_64 / clang@9.0.0-apple -----------------
+  -- darwin-highsierra-x86_64 / apple-clang@9.0.0 -----------------
   m4@1.4.18 patches=3877ab548f88597ab2327a2230ee048d2d07ace1062efe81fc92e91b7f39cd00,c0a408fbffb7255fcc75e26bd8edab116fc81d216bfd18b473668b7739a4158e,fc9b61654a3ba1a8d6cd78ce087e7c96366c290bc8d2c299f09828d793b853c8 +sigsegv
 
 .. _cmd-spack-resource:
@@ -1713,7 +1713,7 @@ wonder where the extra boost patches are coming from::
 
   $ spack spec dealii ^boost@1.68.0 ^hdf5+fortran | grep '\^boost'
       ^boost@1.68.0
-          ^boost@1.68.0%clang@9.0.0-apple+atomic+chrono~clanglibcpp cxxstd=default +date_time~debug+exception+filesystem+graph~icu+iostreams+locale+log+math~mpi+multithreaded~numpy patches=2ab6c72d03dec6a4ae20220a9dfd5c8c572c5294252155b85c6874d97c323199,b37164268f34f7133cbc9a4066ae98fda08adf51e1172223f6a969909216870f ~pic+program_options~python+random+regex+serialization+shared+signals~singlethreaded+system~taggedlayout+test+thread+timer~versionedlayout+wave arch=darwin-highsierra-x86_64
+          ^boost@1.68.0%apple-clang@9.0.0+atomic+chrono~clanglibcpp cxxstd=default +date_time~debug+exception+filesystem+graph~icu+iostreams+locale+log+math~mpi+multithreaded~numpy patches=2ab6c72d03dec6a4ae20220a9dfd5c8c572c5294252155b85c6874d97c323199,b37164268f34f7133cbc9a4066ae98fda08adf51e1172223f6a969909216870f ~pic+program_options~python+random+regex+serialization+shared+signals~singlethreaded+system~taggedlayout+test+thread+timer~versionedlayout+wave arch=darwin-highsierra-x86_64
   $ spack resource show b37164268
   b37164268f34f7133cbc9a4066ae98fda08adf51e1172223f6a969909216870f
       path:       /home/spackuser/src/spack/var/spack/repos/builtin/packages/dealii/boost_1.68.0.patch
@@ -1967,22 +1967,29 @@ exactly what kind of a dependency you need. For example:
    depends_on('cmake', type='build')
    depends_on('py-numpy', type=('build', 'run'))
    depends_on('libelf', type=('build', 'link'))
+   depends_on('py-pytest', type='test')
 
 The following dependency types are available:
 
-* **"build"**: made available during the project's build. The package will
-  be added to ``PATH``, the compiler include paths, and ``PYTHONPATH``.
-  Other projects which depend on this one will not have these modified
-  (building project X doesn't need project Y's build dependencies).
-* **"link"**: the project is linked to by the project. The package will be
-  added to the current package's ``rpath``.
-* **"run"**: the project is used by the project at runtime. The package will
-  be added to ``PATH`` and ``PYTHONPATH``.
+* **"build"**: the dependency will be added to the ``PATH`` and
+  ``PYTHONPATH`` at build-time.
+* **"link"**: the dependency will be added to Spack's compiler
+  wrappers, automatically injecting the appropriate linker flags,
+  including ``-I``, ``-L``, and RPATH/RUNPATH handling.
+* **"run"**: the dependency will be added to the ``PATH`` and
+  ``PYTHONPATH`` at run-time. This is true for both ``spack load``
+  and the module files Spack writes.
+* **"test"**: the dependency will be added to the ``PATH`` and
+  ``PYTHONPATH`` at build-time. The only difference between
+  "build" and "test" is that test dependencies are only built
+  if the user requests unit tests with ``spack install --test``.
 
 One of the advantages of the ``build`` dependency type is that although the
 dependency needs to be installed in order for the package to be built, it
 can be uninstalled without concern afterwards. ``link`` and ``run`` disallow
-this because uninstalling the dependency would break the package.
+this because uninstalling the dependency would break the package. Another
+consequence of this is that ``build``-only dependencies do not affect the
+hash of the package. The same is true for ``test`` dependencies.
 
 If the dependency type is not specified, Spack uses a default of
 ``('build', 'link')``. This is the common case for compiler languages.
@@ -2003,7 +2010,8 @@ package. In that case, you could say something like:
 
 .. code-block:: python
 
-   variant('mpi', default=False)
+   variant('mpi', default=False, description='Enable MPI support')
+
    depends_on('mpi', when='+mpi')
 
 ``when`` can include constraints on the variant, version, compiler, etc. and
@@ -2169,13 +2177,17 @@ Adding the following to a package:
 
 .. code-block:: python
 
-    conflicts('%intel', when='@1.2')
+    conflicts('%intel', when='@:1.2',
+              msg='<myNicePackage> <= v1.2 cannot be built with Intel ICC, '
+                  'please use a newer release.')
 
 we express the fact that the current package *cannot be built* with the Intel
-compiler when we are trying to install version "1.2". The ``when`` argument can
-be omitted, in which case the conflict will always be active.
+compiler when we are trying to install a version "<=1.2". The ``when`` argument
+can be omitted, in which case the conflict will always be active.
 Conflicts are always evaluated after the concretization step has been performed,
 and if any match is found a detailed error message is shown to the user.
+You can add an additional message via the ``msg=`` parameter to a conflict that
+provideds more specific instructions for users.
 
 .. _packaging_extensions:
 
@@ -2197,7 +2209,7 @@ property to ``True``, e.g.:
        extendable = True
        ...
 
-To make a package into an extension, simply add simply add an
+To make a package into an extension, simply add an
 ``extends`` call in the package definition, and pass it the name of an
 extendable package:
 
@@ -2212,6 +2224,10 @@ Now, the ``py-numpy`` package can be used as an argument to ``spack
 activate``.  When it is activated, all the files in its prefix will be
 symbolically linked into the prefix of the python package.
 
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Adding additional constraints
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 Some packages produce a Python extension, but are only compatible with
 Python 3, or with Python 2.  In those cases, a ``depends_on()``
 declaration should be made in addition to the ``extends()``
@@ -2231,8 +2247,7 @@ variant(s) are selected.  This may be accomplished with conditional
 .. code-block:: python
 
    class FooLib(Package):
-       variant('python', default=True, description= \
-           'Build the Python extension Module')
+       variant('python', default=True, description='Build the Python extension Module')
        extends('python', when='+python')
        ...
 
@@ -2913,7 +2928,7 @@ discover its dependencies.
 
 If you want to see the environment that a package will build with, or
 if you want to run commands in that environment to test them out, you
-can use the :ref:`cmd-spack-env` command, documented
+can use the :ref:`cmd-spack-build-env` command, documented
 below.
 
 ^^^^^^^^^^^^^^^^^^^^^
@@ -3607,7 +3622,7 @@ the command line.
     For most compilers, ``$rpath_flag`` is ``-Wl,-rpath,``. However, NAG
     passes its flags to GCC instead of passing them directly to the linker.
     Therefore, its ``$rpath_flag`` is doubly wrapped: ``-Wl,-Wl,,-rpath,``.
-    ``$rpath_flag`` can be overriden on a compiler specific basis in
+    ``$rpath_flag`` can be overridden on a compiler specific basis in
     ``lib/spack/spack/compilers/$compiler.py``.
 
 The compiler wrappers also pass the compiler flags specified by the user from
@@ -4041,6 +4056,273 @@ File functions
 :py:func:`touch(path) <spack.touch>`
   Create an empty file at ``path``.
 
+.. _make-package-findable:
+
+----------------------------------------------------------
+Making a package discoverable with ``spack external find``
+----------------------------------------------------------
+
+The simplest way to make a package discoverable with
+:ref:`spack external find <cmd-spack-external-find>` is to:
+
+1. Define the executables associated with the package
+2. Implement a method to determine the versions of these executables
+
+^^^^^^^^^^^^^^^^^
+Minimal detection
+^^^^^^^^^^^^^^^^^
+
+The first step is fairly simple, as it requires only to
+specify a package level ``executables`` attribute:
+
+.. code-block:: python
+
+   class Foo(Package):
+       # Each string provided here is treated as a regular expression, and
+       # would match for example 'foo', 'foobar', and 'bazfoo'.
+       executables = ['foo']
+
+This attribute must be a list of strings. Each string is a regular
+expression (e.g. 'gcc' would match 'gcc', 'gcc-8.3', 'my-weird-gcc', etc.) to
+determine a set of system executables that might be part or this package. Note
+that to match only executables named 'gcc' the regular expression ``'^gcc$'``
+must be used.
+
+Finally to determine the version of each executable the ``determine_version``
+method must be implemented:
+
+.. code-block:: python
+
+   @classmethod
+   def determine_version(cls, exe):
+       """Return either the version of the executable passed as argument
+       or ``None`` if the version cannot be determined.
+
+       Args:
+           exe (str): absolute path to the executable being examined
+       """
+
+This method receives as input the path to a single executable and must return
+as output its version as a string; if the user cannot determine the version
+or determines that the executable is not an instance of the package, they can
+return None and the exe will be discarded as a candidate.
+Implementing the two steps above is mandatory, and gives the package the
+basic ability to detect if a spec is present on the system at a given version.
+
+.. note::
+   Any executable for which the ``determine_version`` method returns ``None``
+   will be discarded and won't appear in later stages of the workflow described below.
+
+^^^^^^^^^^^^^^^^^^^^^^^^
+Additional functionality
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Besides the two mandatory steps described above, there are also optional
+methods that can be implemented to either increase the amount of details
+being detected or improve the robustness of the detection logic in a package.
+
+""""""""""""""""""""""""""""""
+Variants and custom attributes
+""""""""""""""""""""""""""""""
+
+The ``determine_variants`` method can be optionally implemented in a package
+to detect additional details of the spec:
+
+.. code-block:: python
+
+   @classmethod
+   def determine_variants(cls, exes, version_str):
+       """Return either a variant string, a tuple of a variant string
+       and a dictionary of extra attributes that will be recorded in
+       packages.yaml or a list of those items.
+
+       Args:
+           exes (list of str): list of executables (absolute paths) that
+               live in the same prefix and share the same version
+           version_str (str): version associated with the list of
+               executables, as detected by ``determine_version``
+       """
+
+This method takes as input a list of executables that live in the same prefix and
+share the same version string, and returns either:
+
+1. A variant string
+2. A tuple of a variant string and a dictionary of extra attributes
+3. A list of items matching either 1 or 2 (if multiple specs are detected
+   from the set of executables)
+
+If extra attributes are returned, they will be recorded in ``packages.yaml``
+and be available for later reuse. As an example, the ``gcc`` package will record
+by default the different compilers found and an entry in ``packages.yaml``
+would look like:
+
+.. code-block:: yaml
+
+   packages:
+     gcc:
+       externals:
+       - spec: 'gcc@9.0.1 languages=c,c++,fortran'
+         prefix: /usr
+         extra_attributes:
+           compilers:
+             c: /usr/bin/x86_64-linux-gnu-gcc-9
+             c++: /usr/bin/x86_64-linux-gnu-g++-9
+             fortran: /usr/bin/x86_64-linux-gnu-gfortran-9
+
+This allows us, for instance, to keep track of executables that would be named
+differently if built by Spack (e.g. ``x86_64-linux-gnu-gcc-9``
+instead of just ``gcc``).
+
+.. TODO: we need to gather some more experience on overriding 'prefix'
+   and other special keywords in extra attributes, but as soon as we are
+   confident that this is the way to go we should document the process.
+   See https://github.com/spack/spack/pull/16526#issuecomment-653783204
+
+"""""""""""""""""""""""""""
+Filter matching executables
+"""""""""""""""""""""""""""
+
+Sometimes defining the appropriate regex for the ``executables``
+attribute might prove to be difficult, especially if one has to
+deal with corner cases or exclude "red herrings". To help keeping
+the regular expressions as simple as possible, each package can
+optionally implement a ``filter_executables`` method:
+
+.. code-block:: python
+
+    @classmethod
+    def filter_detected_exes(cls, prefix, exes_in_prefix):
+        """Return a filtered list of the executables in prefix"""
+
+which takes as input a prefix and a list of matching executables and
+returns a filtered list of said executables.
+
+Using this method has the advantage of allowing custom logic for
+filtering, and does not restrict the user to regular expressions
+only.  Consider the case of detecting the GNU C++ compiler. If we
+try to search for executables that match ``g++``, that would have
+the unwanted side effect of selecting also ``clang++`` - which is
+a C++ compiler provided by another package - if present on the system.
+Trying to select executables that contain ``g++`` but not ``clang``
+would be quite complicated to do using regex only. Employing the
+``filter_detected_exes`` method it becomes:
+
+.. code-block:: python
+
+   class Gcc(Package):
+      executables = ['g++']
+
+      def filter_detected_exes(cls, prefix, exes_in_prefix):
+         return [x for x in exes_in_prefix if 'clang' not in x]
+
+Another possibility that this method opens is to apply certain
+filtering logic when specific conditions are met (e.g. take some
+decisions on an OS and not on another).
+
+^^^^^^^^^^^^^^^^^^
+Validate detection
+^^^^^^^^^^^^^^^^^^
+
+To increase detection robustness, packagers may also implement a method
+to validate the detected Spec objects:
+
+.. code-block:: python
+
+   @classmethod
+   def validate_detected_spec(cls, spec, extra_attributes):
+       """Validate a detected spec. Raise an exception if validation fails."""
+
+This method receives a detected spec along with its extra attributes and can be
+used to check that certain conditions are met by the spec. Packagers can either
+use assertions or raise an ``InvalidSpecDetected`` exception when the check fails.
+In case the conditions are not honored the spec will be discarded and any message
+associated with the assertion or the exception will be logged as the reason for
+discarding it.
+
+As an example, a package that wants to check that the ``compilers`` attribute is
+in the extra attributes can implement this method like this:
+
+.. code-block:: python
+
+   @classmethod
+   def validate_detected_spec(cls, spec, extra_attributes):
+       """Check that 'compilers' is in the extra attributes."""
+       msg = ('the extra attribute "compilers" must be set for '
+              'the detected spec "{0}"'.format(spec))
+       assert 'compilers' in extra_attributes, msg
+
+or like this:
+
+.. code-block:: python
+
+   @classmethod
+   def validate_detected_spec(cls, spec, extra_attributes):
+       """Check that 'compilers' is in the extra attributes."""
+       if 'compilers' not in extra_attributes:
+           msg = ('the extra attribute "compilers" must be set for '
+                  'the detected spec "{0}"'.format(spec))
+           raise InvalidSpecDetected(msg)
+
+.. _determine_spec_details:
+
+^^^^^^^^^^^^^^^^^^^^^^^^^
+Custom detection workflow
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In the rare case when the mechanisms described so far don't fit the
+detection of a package, the implementation of all the methods above
+can be disregarded and instead a custom ``determine_spec_details``
+method can be implemented directly in the package class (note that
+the definition of the ``executables`` attribute is still required):
+
+.. code-block:: python
+
+   @classmethod
+   def determine_spec_details(cls, prefix, exes_in_prefix):
+       # exes_in_prefix = a set of paths, each path is an executable
+       # prefix = a prefix that is common to each path in exes_in_prefix
+
+       # return None or [] if none of the exes represent an instance of
+       # the package. Return one or more Specs for each instance of the
+       # package which is thought to be installed in the provided prefix
+
+This method takes as input a set of discovered executables (which match
+those specified by the user) as well as a common prefix shared by all
+of those executables. The function must return one or more :py:class:`spack.spec.Spec` associated
+with the executables (it can also return ``None`` to indicate that no
+provided executables are associated with the package).
+
+As an example, consider a made-up package called ``foo-package`` which
+builds an executable called ``foo``. ``FooPackage`` would appear as
+follows:
+
+.. code-block:: python
+
+   class FooPackage(Package):
+       homepage = "..."
+       url = "..."
+
+       version(...)
+
+       # Each string provided here is treated as a regular expression, and
+       # would match for example 'foo', 'foobar', and 'bazfoo'.
+       executables = ['foo']
+
+       @classmethod
+       def determine_spec_details(cls, prefix, exes_in_prefix):
+           candidates = list(x for x in exes_in_prefix
+                             if os.path.basename(x) == 'foo')
+           if not candidates:
+               return
+           # This implementation is lazy and only checks the first candidate
+           exe_path = candidates[0]
+           exe = Executable(exe_path)
+           output = exe('--version', output=str, error=str)
+           version_str = ...  # parse output for version string
+           return Spec.from_detection(
+               'foo-package@{0}'.format(version_str)
+           )
+
 .. _package-lifecycle:
 
 -----------------------------
@@ -4096,16 +4378,23 @@ want to clean up the temporary directory, or if the package isn't
 downloading properly, you might want to run *only* the ``fetch`` stage
 of the build.
 
+Spack performs best-effort installation of package dependencies by default,
+which means it will continue to install as many dependencies as possible
+after detecting failures.  If you are trying to install a package with a
+lot of dependencies where one or more may fail to build, you might want to
+try the ``--fail-fast`` option to stop the installation process on the first
+failure.
+
 A typical package workflow might look like this:
 
 .. code-block:: console
 
    $ spack edit mypackage
-   $ spack install mypackage
+   $ spack install --fail-fast mypackage
    ... build breaks! ...
    $ spack clean mypackage
    $ spack edit mypackage
-   $ spack install mypackage
+   $ spack install --fail-fast mypackage
    ... repeat clean/install until install works ...
 
 Below are some commands that will allow you some finer-grained
@@ -4174,23 +4463,29 @@ Does this in one of two ways:
 ``spack clean``
 ^^^^^^^^^^^^^^^
 
-Cleans up all of Spack's temporary and cached files.  This can be used to
+Cleans up Spack's temporary and cached files.  This command can be used to
 recover disk space if temporary files from interrupted or failed installs
-accumulate in the staging area.
+accumulate.
 
 When called with ``--stage`` or without arguments this removes all staged
 files.
 
-When called with ``--downloads`` this will clear all resources
-:ref:`cached <caching>` during installs.
+The ``--downloads`` option removes cached :ref:`cached <caching>` downloads.
 
-When called with ``--user-cache`` this will remove caches in the user home
-directory, including cached virtual indices.
+You can force the removal of all install failure tracking markers using the
+``--failures`` option.  Note that ``spack install`` will automatically clear
+relevant failure markings prior to performing the requested installation(s).
+
+Long-lived caches, like the virtual package index, are removed using the
+``--misc-cache`` option.
+
+The ``--python-cache`` option removes `.pyc`, `.pyo`, and `__pycache__`
+folders.
 
 To remove all of the above, the command can be called with ``--all``.
 
-When called with positional arguments, cleans up temporary files only
-for a particular package. If ``fetch``, ``stage``, or ``install``
+When called with positional arguments, this command cleans up temporary files
+only for a particular package. If ``fetch``, ``stage``, or ``install``
 are run again after this, Spack's build process will start from scratch.
 
 
@@ -4332,31 +4627,31 @@ directory, install directory, package directory) and others change to
 core spack locations.  For example, ``spack cd --module-dir`` will take you to
 the main python source directory of your spack install.
 
-.. _cmd-spack-env:
+.. _cmd-spack-build-env:
 
-^^^^^^^^^^^^^
-``spack env``
-^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^
+``spack build-env``
+^^^^^^^^^^^^^^^^^^^
 
-``spack env`` functions much like the standard unix ``env`` command,
-but it takes a spec as an argument.  You can use it to see the
+``spack build-env`` functions much like the standard unix ``build-env``
+command, but it takes a spec as an argument.  You can use it to see the
 environment variables that will be set when a particular build runs,
 for example:
 
 .. code-block:: console
 
-   $ spack env mpileaks@1.1%intel
+   $ spack build-env mpileaks@1.1%intel
 
 This will display the entire environment that will be set when the
 ``mpileaks@1.1%intel`` build runs.
 
 To run commands in a package's build environment, you can simply
-provide them after the spec argument to ``spack env``:
+provide them after the spec argument to ``spack build-env``:
 
 .. code-block:: console
 
    $ spack cd mpileaks@1.1%intel
-   $ spack env mpileaks@1.1%intel ./configure
+   $ spack build-env mpileaks@1.1%intel ./configure
 
 This will cd to the build directory and then run ``configure`` in the
 package's build environment.
@@ -4390,119 +4685,3 @@ might write:
    DWARF_PREFIX = $(spack location --install-dir libdwarf)
    CXXFLAGS += -I$DWARF_PREFIX/include
    CXXFLAGS += -L$DWARF_PREFIX/lib
-
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Build System Configuration Support
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Imagine a developer creating a CMake or Autotools-based project in a
-local directory, which depends on libraries A-Z.  Once Spack has
-installed those dependencies, one would like to run ``cmake`` with
-appropriate command line and environment so CMake can find them.  The
-``spack setup`` command does this conveniently, producing a CMake
-configuration that is essentially the same as how Spack *would have*
-configured the project.  This can be demonstrated with a usage
-example:
-
-.. code-block:: console
-
-   $ cd myproject
-   $ spack setup myproject@local
-   $ mkdir build; cd build
-   $ ../spconfig.py ..
-   $ make
-   $ make install
-
-Notes:
-
-* Spack must have ``myproject/package.py`` in its repository for
-  this to work.
-* ``spack setup`` produces the executable script ``spconfig.py`` in
-  the local directory, and also creates the module file for the
-  package.  ``spconfig.py`` is normally run from the user's
-  out-of-source build directory.
-* The version number given to ``spack setup`` is arbitrary, just
-  like ``spack diy``.  ``myproject/package.py`` does not need to
-  have any valid downloadable versions listed (typical when a
-  project is new).
-* spconfig.py produces a CMake configuration that *does not* use the
-  Spack wrappers.  Any resulting binaries *will not* use RPATH,
-  unless the user has enabled it.  This is recommended for
-  development purposes, not production.
-* ``spconfig.py`` is human readable, and can serve as a developer
-  reference of what dependencies are being used.
-* ``make install`` installs the package into the Spack repository,
-  where it may be used by other Spack packages.
-* CMake-generated makefiles re-run CMake in some circumstances.  Use
-  of ``spconfig.py`` breaks this behavior, requiring the developer
-  to manually re-run ``spconfig.py`` when a ``CMakeLists.txt`` file
-  has changed.
-
-^^^^^^^^^^^^
-CMakePackage
-^^^^^^^^^^^^
-
-In order to enable ``spack setup`` functionality, the author of
-``myproject/package.py`` must subclass from ``CMakePackage`` instead
-of the standard ``Package`` superclass.  Because CMake is
-standardized, the packager does not need to tell Spack how to run
-``cmake; make; make install``.  Instead the packager only needs to
-create (optional) methods ``configure_args()`` and ``configure_env()``, which
-provide the arguments (as a list) and extra environment variables (as
-a dict) to provide to the ``cmake`` command.  Usually, these will
-translate variant flags into CMake definitions.  For example:
-
-.. code-block:: python
-
-   def configure_args(self):
-       spec = self.spec
-       return [
-           '-DUSE_EVERYTRACE=%s' % ('YES' if '+everytrace' in spec else 'NO'),
-           '-DBUILD_PYTHON=%s' % ('YES' if '+python' in spec else 'NO'),
-           '-DBUILD_GRIDGEN=%s' % ('YES' if '+gridgen' in spec else 'NO'),
-           '-DBUILD_COUPLER=%s' % ('YES' if '+coupler' in spec else 'NO'),
-           '-DUSE_PISM=%s' % ('YES' if '+pism' in spec else 'NO')
-       ]
-
-If needed, a packager may also override methods defined in
-``StagedPackage`` (see below).
-
-^^^^^^^^^^^^^
-StagedPackage
-^^^^^^^^^^^^^
-
-``CMakePackage`` is implemented by subclassing the ``StagedPackage``
-superclass, which breaks down the standard ``Package.install()``
-method into several sub-stages: ``setup``, ``configure``, ``build``
-and ``install``.  Details:
-
-* Instead of implementing the standard ``install()`` method, package
-  authors implement the methods for the sub-stages
-  ``install_setup()``, ``install_configure()``,
-  ``install_build()``, and ``install_install()``.
-
-* The ``spack install`` command runs the sub-stages ``configure``,
-  ``build`` and ``install`` in order.  (The ``setup`` stage is
-  not run by default; see below).
-* The ``spack setup`` command runs the sub-stages ``setup``
-  and a dummy install (to create the module file).
-* The sub-stage install methods take no arguments (other than
-  ``self``).  The arguments ``spec`` and ``prefix`` to the standard
-  ``install()`` method may be accessed via ``self.spec`` and
-  ``self.prefix``.
-
-^^^^^^^^^^^^^
-GNU Autotools
-^^^^^^^^^^^^^
-
-The ``setup`` functionality is currently only available for
-CMake-based packages.  Extending this functionality to GNU
-Autotools-based packages would be easy (and should be done by a
-developer who actively uses Autotools).  Packages that use
-non-standard build systems can gain ``setup`` functionality by
-subclassing ``StagedPackage`` directly.
-
-.. Emacs local variables
-   Local Variables:
-   fill-column: 79
-   End:

lib/spack/docs/pipelines.rst

@@ -32,30 +32,47 @@ for setting up a build pipeline are as follows:
 #. Create a repository on your gitlab instance
 #. Add a ``spack.yaml`` at the root containing your pipeline environment (see
    below for details)
-#. Add a ``.gitlab-ci.yml`` at the root containing a single job, similar to
+#. Add a ``.gitlab-ci.yml`` at the root containing two jobs (one to generate
+   the pipeline dynamically, and one to run the generated jobs), similar to
    this one:
 
    .. code-block:: yaml
 
-      pipeline-job:
+      stages: [generate, build]
+
+      generate-pipeline:
+        stage: generate
         tags:
           - <custom-tag>
-          ...
         script:
-          - spack ci start
+          - spack env activate --without-view .
+          - spack ci generate
+            --output-file "${CI_PROJECT_DIR}/jobs_scratch_dir/pipeline.yml"
+        artifacts:
+          paths:
+            - "${CI_PROJECT_DIR}/jobs_scratch_dir/pipeline.yml"
+
+      build-jobs:
+        stage: build
+        trigger:
+          include:
+            - artifact: "jobs_scratch_dir/pipeline.yml"
+              job: generate-pipeline
+          strategy: depend
+
 
 #. Add any secrets required by the CI process to environment variables using the
    CI web ui
 #. Push a commit containing the ``spack.yaml`` and ``.gitlab-ci.yml`` mentioned above
    to the gitlab repository
 
-The ``<custom-tag>``, above, is used to pick one of your configured runners,
-while the use of the ``spack ci start`` command implies that runner has an
-appropriate version of spack installed and configured for use.  Of course, there
-are myriad ways to customize the process.  You can configure CDash reporting
-on the progress of your builds, set up S3 buckets to mirror binaries built by
-the pipeline, clone a custom spack repository/ref for use by the pipeline, and
-more.
+The ``<custom-tag>``, above, is used to pick one of your configured runners to
+run the pipeline generation phase (this is implemented in the ``spack ci generate``
+command, which assumes the runner has an appropriate version of spack installed
+and configured for use).  Of course, there are many ways to customize the process.
+You can configure CDash reporting on the progress of your builds, set up S3 buckets
+to mirror binaries built by the pipeline, clone a custom spack repository/ref for
+use by the pipeline, and more.
 
 While it is possible to set up pipelines on gitlab.com, the builds there are
 limited to 60 minutes and generic hardware.  It is also possible to
@@ -64,21 +81,30 @@ Gitlab to Google Kubernetes Engine (`GKE <https://cloud.google.com/kubernetes-en
 or Amazon Elastic Kubernetes Service (`EKS <https://aws.amazon.com/eks>`_), though those
 topics are outside the scope of this document.
 
+Spack's pipelines are now making use of the
+`trigger <https://docs.gitlab.com/12.9/ee/ci/yaml/README.html#trigger>`_ syntax to run
+dynamically generated
+`child pipelines <https://docs.gitlab.com/12.9/ee/ci/parent_child_pipelines.html>`_.
+Note that the use of dynamic child pipelines requires running Gitlab version
+``>= 12.9``.
+
 -----------------------------------
 Spack commands supporting pipelines
 -----------------------------------
 
-Spack provides a command `ci` with sub-commands for doing various things related
-to automated build pipelines.  All of the ``spack ci ...`` commands must be run
-from within a environment, as each one makes use of the environment for different
-purposes.  Additionally, some options to the commands (or conditions present in
-the spack environment file) may require particular environment variables to be
+Spack provides a command ``ci`` with two sub-commands: ``spack ci generate`` generates
+a pipeline (a .gitlab-ci.yml file) from a spack environment, and ``spack ci rebuild``
+checks a spec against a remote mirror and possibly rebuilds it from source and updates
+the binary mirror with the latest built package.  Both ``spack ci ...`` commands must
+be run from within the same environment, as each one makes use of the environment for
+different purposes.  Additionally, some options to the commands (or conditions present
+in the spack environment file) may require particular environment variables to be
 set in order to function properly.  Examples of these are typically secrets
 needed for pipeline operation that should not be visible in a spack environment
 file.  These environment variables are described in more detail
 :ref:`ci_environment_variables`.
 
-.. _cmd_spack_ci:
+.. _cmd-spack-ci:
 
 ^^^^^^^^^^^^^^^^^^
 ``spack ci``
@@ -87,16 +113,7 @@ file.  These environment variables are described in more detail
 Super-command for functionality related to generating pipelines and executing
 pipeline jobs.
 
-.. _cmd_spack_ci_start:
-
-^^^^^^^^^^^^^^^^^^
-``spack ci start``
-^^^^^^^^^^^^^^^^^^
-
-Currently this command is a short-cut to first run ``spack ci generate``, followed
-by ``spack ci pushyaml``.
-
-.. _cmd_spack_ci_generate:
+.. _cmd-spack-ci-generate:
 
 ^^^^^^^^^^^^^^^^^^^^^
 ``spack ci generate``
@@ -105,19 +122,11 @@ by ``spack ci pushyaml``.
 Concretizes the specs in the active environment, stages them (as described in
 :ref:`staging_algorithm`), and writes the resulting ``.gitlab-ci.yml`` to disk.
 
-.. _cmd_spack_ci_pushyaml:
+This sub-command takes two arguments, but the most useful is ``--output-file``,
+which should be an absolute path (including file name) to the generated
+pipeline, if the default (``./.gitlab-ci.yml``) is not desired.
 
-^^^^^^^^^^^^^^^^^^^^^
-``spack ci pushyaml``
-^^^^^^^^^^^^^^^^^^^^^
-
-Generates a commit containing the generated ``.gitlab-ci.yml`` and pushes it to a
-``DOWNSTREAM_CI_REPO``, which is frequently the same repository.  The branch
-created has the same name as the current branch being tested, but has ``multi-ci-``
-prepended to the branch name.  Once Gitlab CI has full support for dynamically
-defined workloads, this command will be deprecated.
-
-.. _cmd_spack_ci_rebuild:
+.. _cmd-spack-ci-rebuild:
 
 ^^^^^^^^^^^^^^^^^^^^
 ``spack ci rebuild``
@@ -127,12 +136,16 @@ This sub-command is responsible for ensuring a single spec from the release
 environment is up to date on the remote mirror configured in the environment,
 and as such, corresponds to a single job in the ``.gitlab-ci.yml`` file.
 
+Rather than taking command-line arguments, this sub-command expects information
+to be communicated via environment variables, which will typically come via the
+``.gitlab-ci.yml`` job as ``variables``.
+
 ------------------------------------
 A pipeline-enabled spack environment
 ------------------------------------
 
 Here's an example of a spack environment file that has been enhanced with
-sections desribing a build pipeline:
+sections describing a build pipeline:
 
 .. code-block:: yaml
 
@@ -158,14 +171,14 @@ sections desribing a build pipeline:
              - os=ubuntu18.04
            runner-attributes:
              tags:
-               - spack-k8s
-             image: spack/spack_builder_ubuntu_18.04
+               - spack-kube
+             image: spack/ubuntu-bionic
          - match:
              - os=centos7
            runner-attributes:
              tags:
-               - spack-k8s
-             image: spack/spack_builder_centos_7
+               - spack-kube
+             image: spack/centos7
      cdash:
        build-group: Release Testing
        url: https://cdash.spack.io
@@ -184,15 +197,33 @@ corresponds to a known gitlab runner, where the ``match`` section is used
 in assigning a release spec to one of the runners, and the ``runner-attributes``
 section is used to configure the spec/job for that particular runner.
 
+Both the top-level ``gitlab-ci`` section as well as each ``runner-attributes``
+section can also contain the following keys: ``image``, ``tags``, ``variables``,
+``before_script``, ``script``, and ``after_script``.  If any of these keys are
+provided at the ``gitlab-ci`` level, they will be used as the defaults for any
+``runner-attributes``, unless they are overridden in those sections.  Specifying
+any of these keys at the ``runner-attributes`` level generally overrides the
+keys specified at the higher level, with a couple exceptions.  Any ``variables``
+specified at both levels result in those dictionaries getting merged in the
+resulting generated job, and any duplicate variable names get assigned the value
+provided in the specific ``runner-attributes``.  If ``tags`` are specified both
+at the ``gitlab-ci`` level as well as the ``runner-attributes`` level, then the
+lists of tags are combined, and any duplicates are removed.
+
+See the section below on using a custom spack for an example of how these keys
+could be used.
+
 There are other pipeline options you can configure within the ``gitlab-ci`` section
-as well.  The ``bootstrap`` section allows you to specify lists of specs from
+as well.
+
+The ``bootstrap`` section allows you to specify lists of specs from
 your ``definitions`` that should be staged ahead of the environment's ``specs`` (this
 section is described in more detail below).  The ``enable-artifacts-buildcache`` key
 takes a boolean and determines whether the pipeline uses artifacts to store and
 pass along the buildcaches from one stage to the next (the default if you don't
-provide this option is ``False``).  The ``enable-debug-messages`` key takes a boolean
-and allows you to choose whether the pipeline build jobs are run as ``spack -d ci rebuild``
-or just ``spack ci rebuild`` (the default is not to enable debug messages).  The
+provide this option is ``False``).
+
+The
 ``final-stage-rebuild-index`` section controls whether an extra job is added to the
 end of your pipeline (in a stage by itself) which will regenerate the mirror's
 buildcache index.  Under normal operation, each pipeline job that rebuilds a package
@@ -215,6 +246,11 @@ progresses, this build group may have jobs added or removed. The url, project,
 and site are used to specify the CDash instance to which build results should
 be reported.
 
+Take a look at the
+`schema <https://github.com/spack/spack/blob/develop/lib/spack/spack/schema/gitlab_ci.py>`_
+for the gitlab-ci section of the spack environment file, to see precisely what
+syntax is allowed there.
+
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Assignment of specs to runners
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -240,7 +276,18 @@ runners known to the gitlab instance.  For Docker executor type runners, the
 as well as an ``entrypoint`` to override whatever the default for that image is).
 For other types of runners the ``variables`` key will be useful to pass any
 information on to the runner that it needs to do its work (e.g. scheduler
-parameters, etc.).
+parameters, etc.).  Any ``variables`` provided here will be added, verbatim, to
+each job.
+
+The ``runner-attributes`` section also allows users to supply custom ``script``,
+``before_script``, and ``after_script`` sections to be applied to every job
+scheduled on that runner.  This allows users to do any custom preparation or
+cleanup tasks that fit their particular workflow, as well as completely
+customize the rebuilding of a spec if they so choose.  Spack will not generate
+a ``before_script`` or ``after_script`` for jobs, but if you do not provide
+a custom ``script``, spack will generate one for you that assumes your
+``spack.yaml`` is at the root of the repository, activates that environment for
+you, and invokes ``spack ci rebuild``.
 
 .. _staging_algorithm:
 
@@ -251,8 +298,8 @@ Summary of ``.gitlab-ci.yml`` generation algorithm
 All specs yielded by the matrix (or all the specs in the environment) have their
 dependencies computed, and the entire resulting set of specs are staged together
 before being run through the ``gitlab-ci/mappings`` entries, where each staged
-spec is assigned a runner.  "Staging" is the name we have given to the process
-of figuring out in what order the specs should be built, taking into consideration
+spec is assigned a runner.  "Staging" is the name given to the process of
+figuring out in what order the specs should be built, taking into consideration
 Gitlab CI rules about jobs/stages.  In the staging process the goal is to maximize
 the number of jobs in any stage of the pipeline, while ensuring that the jobs in
 any stage only depend on jobs in previous stages (since those jobs are guaranteed
@@ -263,7 +310,7 @@ a runner, the ``.gitlab-ci.yml`` is written to disk.
 
 The short example provided above would result in the ``readline``, ``ncurses``,
 and ``pkgconf`` packages getting staged and built on the runner chosen by the
-``spack-k8s`` tag.  In this example, we assume the runner is a Docker executor
+``spack-k8s`` tag.  In this example, spack assumes the runner is a Docker executor
 type runner, and thus certain jobs will be run in the ``centos7`` container,
 and others in the ``ubuntu-18.04`` container.  The resulting ``.gitlab-ci.yml``
 will contain 6 jobs in three stages.  Once the jobs have been generated, the
@@ -322,12 +369,12 @@ Here's an example of what bootstrapping some compilers might look like:
          # mappings similar to the example higher up in this description
          ...
 
-In the example above, we have added a list to the ``definitions`` called
-``compiler-pkgs`` (you can add any number of these), which lists compiler packages
-we want to be staged ahead of the full matrix of release specs (which consists
-only of readline in our example).  Then within the ``gitlab-ci`` section, we
-have added a ``bootstrap`` section, which can contain a list of items, each
-referring to a list in the ``definitions`` section.  These items can either
+The example above adds a list to the ``definitions`` called ``compiler-pkgs``
+(you can add any number of these), which lists compiler packages that should
+be staged ahead of the full matrix of release specs (in this example, only
+readline).  Then within the ``gitlab-ci`` section, note the addition of a
+``bootstrap`` section, which can contain a list of items, each referring to
+a list in the ``definitions`` section.  These items can either
 be a dictionary or a string.  If you supply a dictionary, it must have a name
 key whose value must match one of the lists in definitions and it can have a
 ``compiler-agnostic`` key whose value is a boolean.  If you supply a string,
@@ -363,32 +410,95 @@ Using a custom spack in your pipeline
 
 If your runners will not have a version of spack ready to invoke, or if for some
 other reason you want to use a custom version of spack to run your pipelines,
-this can be accomplished fairly simply.  First, create CI environment variables
-containing the url and branch/tag you want to clone (calling them, for example,
-``SPACK_REPO`` and ``SPACK_REF``), use them to clone spack in your pre-ci
-``before_script``, and finally pass those same values along to the workload
-generation process via the ``spack-repo`` and ``spack-ref`` cli args.  Here's
-an example:
+this section provides an example of how you could take advantage of
+user-provided pipeline scripts to accomplish this fairly simply.  First, you
+could use the GitLab user interface to create CI environment variables
+containing the url and branch or tag you want to use (calling them, for
+example, ``SPACK_REPO`` and ``SPACK_REF``), then refer to those in a custom shell
+script invoked both from your pipeline generation job, as well as in your rebuild
+jobs.  Here's the ``generate-pipeline`` job from the top of this document,
+updated to invoke a custom shell script that will clone and source a custom
+spack:
 
 .. code-block:: yaml
 
-   pipeline-job:
+   generate-pipeline:
      tags:
        - <some-other-tag>
    before_script:
-     - git clone ${SPACK_REPO} --branch ${SPACK_REF}
-     - . ./spack/share/spack/setup-env.sh
+     - ./cloneSpack.sh
    script:
-     - spack ci start --spack-repo ${SPACK_REPO} --spack-ref ${SPACK_REF} <...args>
+     - spack env activate --without-view .
+     - spack ci generate
+       --output-file "${CI_PROJECT_DIR}/jobs_scratch_dir/pipeline.yml"
    after_script:
      - rm -rf ./spack
+   artifacts:
+     paths:
+       - "${CI_PROJECT_DIR}/jobs_scratch_dir/pipeline.yml"
 
-If the ``spack ci start`` command receives those extra command line arguments,
-then it adds similar ``before_script`` and ``after_script`` sections for each of
-the ``spack ci rebuild`` jobs it generates (cloning and sourcing a custom
-spack in the ``before_script`` and removing it again in the ``after_script``).
-This gives you control over the version of spack used when the rebuild jobs
-are actually run on the gitlab runner.
+And the ``cloneSpack.sh`` script could contain:
+
+.. code-block:: bash
+
+   #!/bin/bash
+
+   git clone ${SPACK_REPO}
+   pushd ./spack
+   git checkout ${SPACK_REF}
+   popd
+
+   . "./spack/share/spack/setup-env.sh"
+
+   spack --version
+
+Finally, you would also want your generated rebuild jobs to clone that version
+of spack, so you would update your ``spack.yaml`` from above as follows:
+
+.. code-block:: yaml
+
+   spack:
+     ...
+     gitlab-ci:
+       mappings:
+         - match:
+             - os=ubuntu18.04
+           runner-attributes:
+             tags:
+               - spack-kube
+             image: spack/ubuntu-bionic
+             before_script:
+               - ./cloneSpack.sh
+             script:
+               - spack env activate --without-view .
+               - spack -d ci rebuild
+             after_script:
+               - rm -rf ./spack
+
+Now all of the generated rebuild jobs will use the same shell script to clone
+spack before running their actual workload.  Note in the above example the
+provision of a custom ``script`` section.  The reason for this is to run
+``spack ci rebuild`` in debug mode to get more information when builds fail.
+
+Now imagine you have long pipelines with many specs to be built, and you
+are pointing to a spack repository and branch that has a tendency to change
+frequently, such as the main repo and it's ``develop`` branch.  If each child
+job checks out the ``develop`` branch, that could result in some jobs running
+with one SHA of spack, while later jobs run with another.  To help avoid this
+issue, the pipeline generation process saves global variables called
+``SPACK_VERSION`` and ``SPACK_CHECKOUT_VERSION`` that capture the version
+of spack used to generate the pipeline.  While the ``SPACK_VERSION`` variable
+simply contains the human-readable value produced by ``spack -V`` at pipeline
+generation time, the ``SPACK_CHECKOUT_VERSION`` variable can be used in a
+``git checkout`` command to make sure all child jobs checkout the same version
+of spack used to generate the pipeline.  To take advantage of this, you could
+simply replace ``git checkout ${SPACK_REF}`` in the example ``cloneSpack.sh``
+script above with ``git checkout ${SPACK_CHECKOUT_VERSION}``.
+
+On the other hand, if you're pointing to a spack repository and branch under your
+control, there may be no benefit in using the captured ``SPACK_CHECKOUT_VERSION``,
+and you can instead just clone using the project CI variables you set (in the
+earlier example these were ``SPACK_REPO`` and ``SPACK_REF``).
 
 .. _ci_environment_variables:
 
@@ -430,10 +540,3 @@ SPACK_SIGNING_KEY
 ^^^^^^^^^^^^^^^^^
 
 Needed to sign/verify binary packages from the remote binary mirror.
-
-^^^^^^^^^^^^^^^^^^
-DOWNSTREAM_CI_REPO
-^^^^^^^^^^^^^^^^^^
-
-Needed until Gitlab CI supports dynamic job generation.  Can contain connection
-credentials, and could be the same repository or a different one.

lib/spack/docs/repositories.rst

@@ -280,16 +280,16 @@ you install it, you can use ``spack spec -N``:
 
    Concretized
    --------------------------------
-   builtin.hdf5@1.10.0-patch1%clang@7.0.2-apple+cxx~debug+fortran+mpi+shared~szip~threadsafe arch=darwin-elcapitan-x86_64
-       ^builtin.openmpi@2.0.1%clang@7.0.2-apple~mxm~pmi~psm~psm2~slurm~sqlite3~thread_multiple~tm~verbs+vt arch=darwin-elcapitan-x86_64
-           ^builtin.hwloc@1.11.4%clang@7.0.2-apple arch=darwin-elcapitan-x86_64
-               ^builtin.libpciaccess@0.13.4%clang@7.0.2-apple arch=darwin-elcapitan-x86_64
-                   ^builtin.libtool@2.4.6%clang@7.0.2-apple arch=darwin-elcapitan-x86_64
-                       ^builtin.m4@1.4.17%clang@7.0.2-apple+sigsegv arch=darwin-elcapitan-x86_64
-                           ^builtin.libsigsegv@2.10%clang@7.0.2-apple arch=darwin-elcapitan-x86_64
-                   ^builtin.pkg-config@0.29.1%clang@7.0.2-apple+internal_glib arch=darwin-elcapitan-x86_64
-                   ^builtin.util-macros@1.19.0%clang@7.0.2-apple arch=darwin-elcapitan-x86_64
-       ^builtin.zlib@1.2.8%clang@7.0.2-apple+pic arch=darwin-elcapitan-x86_64
+   builtin.hdf5@1.10.0-patch1%apple-clang@7.0.2+cxx~debug+fortran+mpi+shared~szip~threadsafe arch=darwin-elcapitan-x86_64
+       ^builtin.openmpi@2.0.1%apple-clang@7.0.2~mxm~pmi~psm~psm2~slurm~sqlite3~thread_multiple~tm~verbs+vt arch=darwin-elcapitan-x86_64
+           ^builtin.hwloc@1.11.4%apple-clang@7.0.2 arch=darwin-elcapitan-x86_64
+               ^builtin.libpciaccess@0.13.4%apple-clang@7.0.2 arch=darwin-elcapitan-x86_64
+                   ^builtin.libtool@2.4.6%apple-clang@7.0.2 arch=darwin-elcapitan-x86_64
+                       ^builtin.m4@1.4.17%apple-clang@7.0.2+sigsegv arch=darwin-elcapitan-x86_64
+                           ^builtin.libsigsegv@2.10%apple-clang@7.0.2 arch=darwin-elcapitan-x86_64
+                   ^builtin.pkg-config@0.29.1%apple-clang@7.0.2+internal_glib arch=darwin-elcapitan-x86_64
+                   ^builtin.util-macros@1.19.0%apple-clang@7.0.2 arch=darwin-elcapitan-x86_64
+       ^builtin.zlib@1.2.8%apple-clang@7.0.2+pic arch=darwin-elcapitan-x86_64
 
 .. warning::
 

lib/spack/docs/workflows.rst

@@ -284,8 +284,10 @@ have some drawbacks:
    The ``spack load`` and ``spack module tcl loads`` commands, on the
    other hand, are not very smart: if the user-supplied spec matches
    more than one installed package, then ``spack module tcl loads`` will
-   fail. This may change in the future.  For now, the workaround is to
-   be more specific on any ``spack load`` commands that fail.
+   fail. This default behavior may change in the future.  For now,
+   the workaround is to either be more specific on any failing ``spack load``
+   commands or to use ``spack load --first`` to allow spack to load the
+   first matching spec.
 
 
 """"""""""""""""""""""
@@ -444,7 +446,7 @@ environment.
 
 A single-prefix filesystem view is a single directory tree that is the
 union of the directory hierarchies of a number of installed packages;
-it is similar to the directory hiearchy that might exist under
+it is similar to the directory hierarchy that might exist under
 ``/usr/local``.  The files of the view's installed packages are
 brought into the view by symbolic or hard links, referencing the
 original Spack installation.
@@ -701,400 +703,6 @@ environments:
   Administrators might find things easier to maintain without the
   added "heavyweight" state of a view.
 
-------------------------------
-Developing Software with Spack
-------------------------------
-
-For any project, one needs to assemble an
-environment of that application's dependencies.  You might consider
-loading a series of modules or creating a filesystem view.  This
-approach, while obvious, has some serious drawbacks:
-
-1. There is no guarantee that an environment created this way will be
-   consistent.  Your application could end up with dependency A
-   expecting one version of MPI, and dependency B expecting another.
-   The linker will not be happy...
-
-2. Suppose you need to debug a package deep within your software DAG.
-   If you build that package with a manual environment, then it
-   becomes difficult to have Spack auto-build things that depend on
-   it.  That could be a serious problem, depending on how deep the
-   package in question is in your dependency DAG.
-
-3. At its core, Spack is a sophisticated concretization algorithm that
-   matches up packages with appropriate dependencies and creates a
-   *consistent* environment for the package it's building.  Writing a
-   list of ``spack load`` commands for your dependencies is at least
-   as hard as writing the same list of ``depends_on()`` declarations
-   in a Spack package.  But it makes no use of Spack concretization
-   and is more error-prone.
-
-4. Spack provides an automated, systematic way not just to find a
-   packages's dependencies --- but also to build other packages on
-   top.  Any Spack package can become a dependency for another Spack
-   package, offering a powerful vision of software re-use.  If you
-   build your package A outside of Spack, then your ability to use it
-   as a building block for other packages in an automated way is
-   diminished: other packages depending on package A will not
-   be able to use Spack to fulfill that dependency.
-
-5. If you are reading this manual, you probably love Spack.  You're
-   probably going to write a Spack package for your software so
-   prospective users can install it with the least amount of pain.
-   Why should you go to additional work to find dependencies in your
-   development environment?  Shouldn't Spack be able to help you build
-   your software based on the package you've already written?
-
-In this section, we show how Spack can be used in the software
-development process to greatest effect, and how development packages
-can be seamlessly integrated into the Spack ecosystem.  We will show
-how this process works by example, assuming the software you are
-creating is called ``mylib``.
-
-^^^^^^^^^^^^^^^^^^^^^
-Write the CMake Build
-^^^^^^^^^^^^^^^^^^^^^
-
-For now, the techniques in this section only work for CMake-based
-projects, although they could be easily extended to other build
-systems in the future.  We will therefore assume you are using CMake
-to build your project.
-
-The ``CMakeLists.txt`` file should be written as normal.  A few caveats:
-
-1. Your project should produce binaries with RPATHs.  This will ensure
-   that they work the same whether built manually or automatically by
-   Spack.  For example:
-
-.. code-block:: cmake
-
-   # enable @rpath in the install name for any shared library being built
-   # note: it is planned that a future version of CMake will enable this by default
-   set(CMAKE_MACOSX_RPATH 1)
-
-   # Always use full RPATH
-   # http://www.cmake.org/Wiki/CMake_RPATH_handling
-   # http://www.kitware.com/blog/home/post/510
-
-   # use, i.e. don't skip the full RPATH for the build tree
-   SET(CMAKE_SKIP_BUILD_RPATH  FALSE)
-
-   # when building, don't use the install RPATH already
-   # (but later on when installing)
-   SET(CMAKE_BUILD_WITH_INSTALL_RPATH FALSE)
-
-   # add the automatically determined parts of the RPATH
-   # which point to directories outside the build tree to the install RPATH
-   SET(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE)
-
-   # the RPATH to be used when installing, but only if it's not a system directory
-   LIST(FIND CMAKE_PLATFORM_IMPLICIT_LINK_DIRECTORIES "${CMAKE_INSTALL_PREFIX}/lib" isSystemDir)
-   IF("${isSystemDir}" STREQUAL "-1")
-      SET(CMAKE_INSTALL_RPATH "${CMAKE_INSTALL_PREFIX}/lib")
-   ENDIF("${isSystemDir}" STREQUAL "-1")
-
-
-2. Spack provides a CMake variable called
-   ``SPACK_TRANSITIVE_INCLUDE_PATH``, which contains the ``include/``
-   directory for all of your project's transitive dependencies.  It
-   can be useful if your project ``#include``s files from package B,
-   which ``#include`` files from package C, but your project only
-   lists project B as a dependency.  This works in traditional
-   single-tree build environments, in which B and C's include files
-   live in the same place.  In order to make it work with Spack as
-   well, you must add the following to ``CMakeLists.txt``.  It will
-   have no effect when building without Spack:
-
-   .. code-block:: cmake
-
-      # Include all the transitive dependencies determined by Spack.
-      # If we're not running with Spack, this does nothing...
-      include_directories($ENV{SPACK_TRANSITIVE_INCLUDE_PATH})
-
-   .. note::
-
-      Note that this feature is controversial and could break with
-      future versions of GNU ld.  The best practice is to make sure
-      anything you ``#include`` is listed as a dependency in your
-      CMakeLists.txt (and Spack package).
-
-.. _write-the-spack-package:
-
-^^^^^^^^^^^^^^^^^^^^^^^
-Write the Spack Package
-^^^^^^^^^^^^^^^^^^^^^^^
-
-The Spack package also needs to be written, in tandem with setting up
-the build (for example, CMake).  The most important part of this task
-is declaring dependencies.  Here is an example of the Spack package
-for the ``mylib`` package (ellipses for brevity):
-
-.. code-block:: python
-
-   class Mylib(CMakePackage):
-       """Misc. reusable utilities used by Myapp."""
-
-       homepage = "https://github.com/citibeth/mylib"
-       url = "https://github.com/citibeth/mylib/tarball/123"
-
-       version('0.1.2', '3a6acd70085e25f81b63a7e96c504ef9')
-       version('develop', git='https://github.com/citibeth/mylib.git',
-           branch='develop')
-
-       variant('everytrace', default=False,
-               description='Report errors through Everytrace')
-       ...
-
-       extends('python')
-
-       depends_on('eigen')
-       depends_on('everytrace', when='+everytrace')
-       depends_on('proj', when='+proj')
-       ...
-       depends_on('cmake', type='build')
-       depends_on('doxygen', type='build')
-
-       def cmake_args(self):
-           spec = self.spec
-           return [
-               '-DUSE_EVERYTRACE=%s' % ('YES' if '+everytrace' in spec else 'NO'),
-               '-DUSE_PROJ4=%s' % ('YES' if '+proj' in spec else 'NO'),
-               ...
-               '-DUSE_UDUNITS2=%s' % ('YES' if '+udunits2' in spec else 'NO'),
-               '-DUSE_GTEST=%s' % ('YES' if '+googletest' in spec else 'NO')]
-
-This is a standard Spack package that can be used to install
-``mylib`` in a production environment.  The list of dependencies in
-the Spack package will generally be a repeat of the list of CMake
-dependencies.  This package also has some features that allow it to be
-used for development:
-
-1. It subclasses ``CMakePackage`` instead of ``Package``.  This
-   eliminates the need to write an ``install()`` method, which is
-   defined in the superclass.  Instead, one just needs to write the
-   ``configure_args()`` method.  That method should return the
-   arguments needed for the ``cmake`` command (beyond the standard
-   CMake arguments, which Spack will include already).  These
-   arguments are typically used to turn features on/off in the build.
-
-2. It specifies a non-checksummed version ``develop``.  Running
-   ``spack install mylib@develop`` the ``@develop`` version will
-   install the latest version off the develop branch.  This method of
-   download is useful for the developer of a project while it is in
-   active development; however, it should only be used by developers
-   who control and trust the repository in question!
-
-3. The ``url``, ``url_for_version()`` and ``homepage`` attributes are
-   not used in development.  Don't worry if you don't have any, or if
-   they are behind a firewall.
-
-^^^^^^^^^^^^^^^^
-Build with Spack
-^^^^^^^^^^^^^^^^
-
-Now that you have a Spack package, you can use Spack to find its
-dependencies automatically.  For example:
-
-.. code-block:: console
-
-   $ cd mylib
-   $ spack setup mylib@local
-
-The result will be a file ``spconfig.py`` in the top-level
-``mylib/`` directory.  It is a short script that calls CMake with the
-dependencies and options determined by Spack --- similar to what
-happens in ``spack install``, but now written out in script form.
-From a developer's point of view, you can think of ``spconfig.py`` as
-a stand-in for the ``cmake`` command.
-
-.. note::
-
-   You can invent any "version" you like for the ``spack setup``
-   command.
-
-.. note::
-
-   Although ``spack setup`` does not build your package, it does
-   create and install a module file, and mark in the database that
-   your package has been installed.  This can lead to errors, of
-   course, if you don't subsequently install your package.
-   Also... you will need to ``spack uninstall`` before you run
-   ``spack setup`` again.
-
-
-You can now build your project as usual with CMake:
-
-.. code-block:: console
-
-   $ mkdir build; cd build
-   $ ../spconfig.py ..   # Instead of cmake ..
-   $ make
-   $ make install
-
-Once your ``make install`` command is complete, your package will be
-installed, just as if you'd run ``spack install``.  Except you can now
-edit, re-build and re-install as often as needed, without checking
-into Git or downloading tarballs.
-
-.. note::
-
-   The build you get this way will be *almost* the same as the build
-   from ``spack install``.  The only difference is, you will not be
-   using Spack's compiler wrappers.  This difference has not caused
-   problems in our experience, as long as your project sets
-   RPATHs as shown above.  You DO use RPATHs, right?
-
-^^^^^^^^^^^^^^^^^^^^
-Build Other Software
-^^^^^^^^^^^^^^^^^^^^
-
-Now that you've built ``mylib`` with Spack, you might want to build
-another package that depends on it --- for example, ``myapp``.  This
-is accomplished easily enough:
-
-.. code-block:: console
-
-   $ spack install myapp ^mylib@local
-
-Note that auto-built software has now been installed *on top of*
-manually-built software, without breaking Spack's "web."  This
-property is useful if you need to debug a package deep in the
-dependency hierarchy of your application.  It is a *big* advantage of
-using ``spack setup`` to build your package's environment.
-
-If you feel your software is stable, you might wish to install it with
-``spack install`` and skip the source directory.  You can just use,
-for example:
-
-.. code-block:: console
-
-   $ spack install mylib@develop
-
-.. _release-your-software:
-
-^^^^^^^^^^^^^^^^^^^^^
-Release Your Software
-^^^^^^^^^^^^^^^^^^^^^
-
-You are now ready to release your software as a tarball with a
-numbered version, and a Spack package that can build it.  If you're
-hosted on GitHub, this process will be a bit easier.
-
-#. Put tag(s) on the version(s) in your GitHub repo you want to be
-   release versions.  For example, a tag ``v0.1.0`` for version 0.1.0.
-
-#. Set the ``url`` in your ``package.py`` to download a tarball for
-   the appropriate version.  GitHub will give you a tarball for any
-   commit in the repo, if you tickle it the right way.  For example:
-
-   .. code-block:: python
-
-      url = 'https://github.com/citibeth/mylib/tarball/v0.1.2'
-
-#. Use Spack to determine your version's hash, and cut'n'paste it into
-   your ``package.py``:
-
-   .. code-block:: console
-
-      $ spack checksum mylib 0.1.2
-      ==> Found 1 versions of mylib
-        0.1.2     https://github.com/citibeth/mylib/tarball/v0.1.2
-
-      How many would you like to checksum? (default is 5, q to abort)
-      ==> Downloading...
-      ==> Trying to fetch from https://github.com/citibeth/mylib/tarball/v0.1.2
-      ######################################################################## 100.0%
-      ==> Checksummed new versions of mylib:
-            version('0.1.2', '3a6acd70085e25f81b63a7e96c504ef9')
-
-#. You should now be able to install released version 0.1.2 of your package with:
-
-   .. code-block:: console
-
-      $ spack install mylib@0.1.2
-
-#. There is no need to remove the `develop` version from your package.
-   Spack concretization will always prefer numbered version to
-   non-numeric versions.  Users will only get it if they ask for it.
-
-^^^^^^^^^^^^^^^^^^^^^^^^
-Distribute Your Software
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-Once you've released your software, other people will want to build
-it; and you will need to tell them how.  In the past, that has meant a
-few paragraphs of prose explaining which dependencies to install.  But
-now you use Spack, and those instructions are written in executable
-Python code.  But your software has many dependencies, and you know
-Spack is the best way to install it:
-
-#. First, you will want to fork Spack's ``develop`` branch.  Your aim
-   is to provide a stable version of Spack that you KNOW will install
-   your software.  If you make changes to Spack in the process, you
-   will want to submit pull requests to Spack core.
-
-#. Add your software's ``package.py`` to that fork.  You should submit
-   a pull request for this as well, unless you don't want the public
-   to know about your software.
-
-#. Prepare instructions that read approximately as follows:
-
-   #. Download Spack from your forked repo.
-
-   #. Install Spack; see :ref:`getting_started`.
-
-   #. Set up an appropriate ``packages.yaml`` file.  You should tell
-      your users to include in this file whatever versions/variants
-      are needed to make your software work correctly (assuming those
-      are not already in your ``packages.yaml``).
-
-   #. Run ``spack install mylib``.
-
-   #. Run this script to generate the ``module load`` commands or
-      filesystem view needed to use this software.
-
-#. Be aware that your users might encounter unexpected bootstrapping
-   issues on their machines, especially if they are running on older
-   systems.  The :ref:`getting_started` section should cover this, but
-   there could always be issues.
-
-^^^^^^^^^^^^^^^^^^^
-Other Build Systems
-^^^^^^^^^^^^^^^^^^^
-
-``spack setup`` currently only supports CMake-based builds, in
-packages that subclass ``CMakePackage``.  The intent is that this
-mechanism should support a wider range of build systems; for example,
-GNU Autotools.  Someone well-versed in Autotools is needed to develop
-this patch and test it out.
-
-Python Distutils is another popular build system that should get
-``spack setup`` support.  For non-compiled languages like Python,
-``spack diy`` may be used.  Even better is to put the source directory
-directly in the user's ``PYTHONPATH``.  Then, edits in source files
-are immediately available to run without any install process at all!
-
-^^^^^^^^^^
-Conclusion
-^^^^^^^^^^
-
-The ``spack setup`` development workflow provides better automation,
-flexibility and safety than workflows relying on environment modules
-or filesystem views.  However, it has some drawbacks:
-
-#. It currently works only with projects that use the CMake build
-   system.  Support for other build systems is not hard to build, but
-   will require a small amount of effort for each build system to be
-   supported.  It might not work well with some IDEs.
-
-#. It only works with packages that sub-class ``StagedPackage``.
-   Currently, most Spack packages do not.  Converting them is not
-   hard; but must be done on a package-by-package basis.
-
-#. It requires that users are comfortable with Spack, as they
-   integrate Spack explicitly in their workflow.  Not all users are
-   willing to do this.
-
 -------------------------------------
 Using Spack to Replace Homebrew/Conda
 -------------------------------------
@@ -1237,7 +845,7 @@ you can also manually set them in your ``.bashrc``.
    2. Other package managers like Homebrew will try to install things to the
       same directory. If you plan on using Homebrew in conjunction with Spack,
       don't symlink things to ``/usr/local``.
-   3. If you are on a shared workstation, or don't have sudo priveleges, you
+   3. If you are on a shared workstation, or don't have sudo privileges, you
       can't do this.
 
    If you still want to do this anyway, there are several ways around SIP.
@@ -1356,6 +964,14 @@ The main points that are implemented below:
    the spack builds in the config.
    (The Travis yaml parser is a bit buggy on the echo command.)
 
+#. Without control for the user, Travis jobs will run on various
+   ``x86_64`` microarchitectures. If you plan to cache build results,
+   e.g. to accelerate dependency builds, consider building for the
+   generic ``x86_64`` target only.
+   Limiting the microarchitecture will also find more packages when
+   working with the
+   `E4S Spack build cache <https://oaciss.uoregon.edu/e4s/e4s_buildcache_inventory.html>`_.
+
 #. Builds over 10 minutes need to be prefixed with ``travis_wait``.
    Alternatively, generate output once with ``spack install -v``.
 
@@ -1395,10 +1011,13 @@ The main points that are implemented below:
      - export CXXFLAGS="-std=c++11"
 
    install:
-     - if ! which spack >/dev/null; then
+     - |
+       if ! which spack >/dev/null; then
          mkdir -p $SPACK_ROOT &&
          git clone --depth 50 https://github.com/spack/spack.git $SPACK_ROOT &&
-         echo -e "config:""\n  build_jobs:"" 2" > $SPACK_ROOT/etc/spack/config.yaml;
+         printf "config:\n  build_jobs: 2\n" > $SPACK_ROOT/etc/spack/config.yaml &&
+         printf "packages:\n  all:\n    target: ['x86_64']\n" \
+                 > $SPACK_ROOT/etc/spack/packages.yaml;
        fi
      - travis_wait spack install cmake@3.7.2~openssl~ncurses
      - travis_wait spack install boost@1.62.0~graph~iostream~locale~log~wave
@@ -1430,12 +1049,7 @@ The following functionality is prepared:
 
 #. Base image: the example starts from a minimal ubuntu.
 
-#. Installing as root: docker images are usually set up as root.
-   Since some autotools scripts might complain about this being unsafe, we set
-   ``FORCE_UNSAFE_CONFIGURE=1`` to avoid configure errors.
-
-#. Pre-install the spack dependencies, including modules from the packages.
-   This avoids needing to build those from scratch via ``spack bootstrap``.
+#. Pre-install the spack dependencies.
    Package installs are followed by a clean-up of the system package index,
    to avoid outdated information and it saves space.
 
@@ -1464,10 +1078,9 @@ In order to build and run the image, execute:
 
    # general environment for docker
    ENV        DEBIAN_FRONTEND=noninteractive \
-              SPACK_ROOT=/usr/local \
-              FORCE_UNSAFE_CONFIGURE=1
+              SPACK_ROOT=/usr/local
 
-   # install minimal spack depedencies
+   # install minimal spack dependencies
    RUN        apt-get update \
               && apt-get install -y --no-install-recommends \
                  autoconf \
@@ -1538,8 +1151,9 @@ Avoid double-installing CUDA by adding, e.g.
 
    packages:
      cuda:
-       paths:
-         cuda@9.0.176%gcc@5.4.0 arch=linux-ubuntu16-x86_64: /usr/local/cuda
+       externals:
+       - spec: "cuda@9.0.176%gcc@5.4.0 arch=linux-ubuntu16-x86_64"
+         prefix: /usr/local/cuda
        buildable: False
 
 to your ``packages.yaml``.

lib/spack/env/cc

@@ -15,9 +15,9 @@
 # 1. It allows Spack to swap compilers into and out of builds easily.
 # 2. It adds several options to the compile line so that spack
 #    packages can find their dependencies at build time and run time:
-#      -I           arguments for dependency /include directories.
-#      -L           arguments for dependency /lib directories.
-#      -Wl,-rpath   arguments for dependency /lib directories.
+#      -I and/or -isystem arguments for dependency /include directories.
+#      -L                 arguments for dependency /lib directories.
+#      -Wl,-rpath         arguments for dependency /lib directories.
 #
 
 # This is an array of environment variables that need to be set before
@@ -43,7 +43,7 @@ parameters=(
 # The compiler input variables are checked for sanity later:
 #   SPACK_CC, SPACK_CXX, SPACK_F77, SPACK_FC
 # The default compiler flags are passed from these variables:
-#   SPACK_CFLAGS, SPACK_CXXFLAGS, SPACK_FCFLAGS, SPACK_FFLAGS,
+#   SPACK_CFLAGS, SPACK_CXXFLAGS, SPACK_FFLAGS,
 #   SPACK_LDFLAGS, SPACK_LDLIBS
 # Debug env var is optional; set to "TRUE" for debug logging:
 #   SPACK_DEBUG
@@ -251,10 +251,11 @@ input_command="$*"
 #
 # Parse the command line arguments.
 #
-# We extract -L, -I, and -Wl,-rpath arguments from the command line and
-# recombine them with Spack arguments later.  We parse these out so that
-# we can make sure that system paths come last, that package arguments
-# come first, and that Spack arguments are injected properly.
+# We extract -L, -I, -isystem and -Wl,-rpath arguments from the
+# command line and recombine them with Spack arguments later.  We
+# parse these out so that we can make sure that system paths come
+# last, that package arguments come first, and that Spack arguments
+# are injected properly.
 #
 # All other arguments, including -l arguments, are treated as
 # 'other_args' and left in their original order.  This ensures that
@@ -273,12 +274,24 @@ system_libdirs=()
 system_rpaths=()
 libs=()
 other_args=()
+isystem_system_includes=()
+isystem_includes=()
 
 while [ -n "$1" ]; do
     # an RPATH to be added after the case statement.
     rp=""
 
     case "$1" in
+        -isystem*)
+            arg="${1#-isystem}"
+	    isystem_was_used=true
+            if [ -z "$arg" ]; then shift; arg="$1"; fi
+            if system_dir "$arg"; then
+                isystem_system_includes+=("$arg")
+            else
+                isystem_includes+=("$arg")
+            fi
+            ;;
         -I*)
             arg="${1#-I}"
             if [ -z "$arg" ]; then shift; arg="$1"; fi
@@ -425,12 +438,6 @@ then
     esac
 fi
 
-# Prepend include directories
-IFS=':' read -ra include_dirs <<< "$SPACK_INCLUDE_DIRS"
-if [[ $mode == cpp || $mode == cc || $mode == as || $mode == ccld ]]; then
-    includes=("${includes[@]}" "${include_dirs[@]}")
-fi
-
 IFS=':' read -ra rpath_dirs <<< "$SPACK_RPATH_DIRS"
 if [[ $mode == ccld || $mode == ld ]]; then
 
@@ -481,9 +488,22 @@ args=()
 # flags assembled earlier
 args+=("${flags[@]}")
 
-# include directory search paths
+# Insert include directories just prior to any system include directories
+
 for dir in "${includes[@]}";         do args+=("-I$dir"); done
+for dir in "${isystem_includes[@]}";         do args+=("-isystem$dir"); done
+
+IFS=':' read -ra spack_include_dirs <<< "$SPACK_INCLUDE_DIRS"
+if [[ $mode == cpp || $mode == cc || $mode == as || $mode == ccld ]]; then
+    if [[ "$isystem_was_used" == "true" ]] ; then
+	for dir in "${spack_include_dirs[@]}";  do args+=("-isystem$dir"); done
+    else
+	for dir in "${spack_include_dirs[@]}";  do args+=("-I$dir"); done
+    fi
+fi
+
 for dir in "${system_includes[@]}";  do args+=("-I$dir"); done
+for dir in "${isystem_system_includes[@]}";  do args+=("-isystem$dir"); done
 
 # Library search paths
 for dir in "${libdirs[@]}";          do args+=("-L$dir"); done

lib/spack/external/__init__.py

@@ -88,10 +88,11 @@
 * Homepage: https://pypi.python.org/pypi/pytest
 * Usage: Testing framework used by Spack.
 * Version: 3.2.5 (last version supporting Python 2.6)
-* Note: This package has been slightly modified to improve
-  Python 2.6 compatibility. See the following commit if the
-  vendored copy ever needs to be updated again:
-  https://github.com/spack/spack/pull/6801/commits/ff513c39f2c67ff615de5cbc581dd69a8ec96526
+* Note: This package has been slightly modified:
+  * We improve Python 2.6 compatibility. See:
+    https://github.com/spack/spack/pull/6801.
+  * We have patched pytest not to depend on setuptools. See:
+    https://github.com/spack/spack/pull/15612
 
 ruamel.yaml
 ------
@@ -125,4 +126,5 @@
 * Homepage: https://altgraph.readthedocs.io/en/latest/index.html
 * Usage: dependency of macholib
 * Version: 0.16.1
+
 """

lib/spack/external/_pytest/config.py

@@ -1028,34 +1028,13 @@ def _consider_importhook(self, args):
             except SystemError:
                 mode = 'plain'
             else:
-                self._mark_plugins_for_rewrite(hook)
+                # REMOVED FOR SPACK: This routine imports `pkg_resources` from
+                # `setuptools`, but we do not need it for Spack. We have removed
+                # it from Spack to avoid a dependency on setuptools.
+                # self._mark_plugins_for_rewrite(hook)
+                pass
         self._warn_about_missing_assertion(mode)
 
-    def _mark_plugins_for_rewrite(self, hook):
-        """
-        Given an importhook, mark for rewrite any top-level
-        modules or packages in the distribution package for
-        all pytest plugins.
-        """
-        import pkg_resources
-        self.pluginmanager.rewrite_hook = hook
-
-        # 'RECORD' available for plugins installed normally (pip install)
-        # 'SOURCES.txt' available for plugins installed in dev mode (pip install -e)
-        # for installed plugins 'SOURCES.txt' returns an empty list, and vice-versa
-        # so it shouldn't be an issue
-        metadata_files = 'RECORD', 'SOURCES.txt'
-
-        package_files = (
-            entry.split(',')[0]
-            for entrypoint in pkg_resources.iter_entry_points('pytest11')
-            for metadata in metadata_files
-            for entry in entrypoint.dist._get_metadata(metadata)
-        )
-
-        for name in _iter_rewritable_modules(package_files):
-            hook.mark_rewrite(name)
-
     def _warn_about_missing_assertion(self, mode):
         try:
             assert False
@@ -1081,7 +1060,12 @@ def _preparse(self, args, addopts=True):
         self._checkversion()
         self._consider_importhook(args)
         self.pluginmanager.consider_preparse(args)
-        self.pluginmanager.load_setuptools_entrypoints('pytest11')
+
+        # REMOVED FOR SPACK: This routine imports `pkg_resources` from
+        # `setuptools`, but we do not need it for Spack. We have removed
+        # it from Spack to avoid a dependency on setuptools.
+        # self.pluginmanager.load_setuptools_entrypoints('pytest11')
+
         self.pluginmanager.consider_env()
         self.known_args_namespace = ns = self._parser.parse_known_args(args, namespace=self.option.copy())
         if self.known_args_namespace.confcutdir is None and self.inifile:

lib/spack/external/_pytest/vendored_packages/pluggy.py

@@ -497,26 +497,6 @@ def check_pending(self):
                                 "unknown hook %r in plugin %r" %
                                 (name, hookimpl.plugin))
 
-    def load_setuptools_entrypoints(self, entrypoint_name):
-        """ Load modules from querying the specified setuptools entrypoint name.
-        Return the number of loaded plugins. """
-        from pkg_resources import (iter_entry_points, DistributionNotFound,
-                                   VersionConflict)
-        for ep in iter_entry_points(entrypoint_name):
-            # is the plugin registered or blocked?
-            if self.get_plugin(ep.name) or self.is_blocked(ep.name):
-                continue
-            try:
-                plugin = ep.load()
-            except DistributionNotFound:
-                continue
-            except VersionConflict as e:
-                raise PluginValidationError(
-                    "Plugin %r could not be loaded: %s!" % (ep.name, e))
-            self.register(plugin, name=ep.name)
-            self._plugin_distinfo.append((plugin, ep.dist))
-        return len(self._plugin_distinfo)
-
     def list_plugin_distinfo(self):
         """ return list of distinfo/plugin tuples for all setuptools registered
         plugins. """

lib/spack/external/altgraph/__init__.py

@@ -139,9 +139,12 @@
   @contributor: U{Reka Albert <http://www.phys.psu.edu/~ralbert/>}
 
 '''
-import pkg_resources
-__version__ = pkg_resources.require('altgraph')[0].version
-
+# import pkg_resources
+# __version__ = pkg_resources.require('altgraph')[0].version
+# pkg_resources is not finding the altgraph import despite the fact that it is in sys.path
+# there is no .dist-info or .egg-info for pkg_resources to query the version from
+# so it must be set manually
+__version__ = '0.16.1'
 
 class GraphError(ValueError):
     pass

lib/spack/external/ctest_log_parser.py

@@ -118,6 +118,7 @@ def match(self, text):
         "([^:]+): (Error:|error|undefined reference|multiply defined)",
         "([^ :]+) ?: (error|fatal error|catastrophic error)",
         "([^:]+)\\(([^\\)]+)\\) ?: (error|fatal error|catastrophic error)"),
+    "^FAILED",
     "^[Bb]us [Ee]rror",
     "^[Ss]egmentation [Vv]iolation",
     "^[Ss]egmentation [Ff]ault",

lib/spack/external/distro.py

@@ -64,6 +64,7 @@
     'enterpriseenterprise': 'oracle',  # Oracle Enterprise Linux
     'redhatenterpriseworkstation': 'rhel',  # RHEL 6, 7 Workstation
     'redhatenterpriseserver': 'rhel',  # RHEL 6, 7 Server
+    'redhatenterprisecomputenode': 'rhel',  # RHEL 6 ComputeNode
 }
 
 #: Translation table for normalizing the distro ID derived from the file name

lib/spack/llnl/util/argparsewriter.py

@@ -45,18 +45,18 @@ def __init__(self, prog, description, usage,
 class ArgparseWriter(argparse.HelpFormatter):
     """Analyzes an argparse ArgumentParser for easy generation of help."""
 
-    def __init__(self, prog, out=sys.stdout, aliases=False):
+    def __init__(self, prog, out=None, aliases=False):
         """Initializes a new ArgparseWriter instance.
 
         Parameters:
             prog (str): the program name
-            out (file object): the file to write to
+            out (file object): the file to write to (default sys.stdout)
             aliases (bool): whether or not to include subparsers for aliases
         """
         super(ArgparseWriter, self).__init__(prog)
         self.level = 0
         self.prog = prog
-        self.out = out
+        self.out = sys.stdout if out is None else out
         self.aliases = aliases
 
     def parse(self, parser, prog):
@@ -167,7 +167,7 @@ def write(self, parser):
 class ArgparseRstWriter(ArgparseWriter):
     """Write argparse output as rst sections."""
 
-    def __init__(self, prog, out=sys.stdout, aliases=False,
+    def __init__(self, prog, out=None, aliases=False,
                  rst_levels=_rst_levels):
         """Create a new ArgparseRstWriter.
 
@@ -178,6 +178,7 @@ def __init__(self, prog, out=sys.stdout, aliases=False,
             rst_levels (list of str): list of characters
                 for rst section headings
         """
+        out = sys.stdout if out is None else out
         super(ArgparseRstWriter, self).__init__(prog, out, aliases)
         self.rst_levels = rst_levels
 

lib/spack/llnl/util/cpu/microarchitecture.py

@@ -204,10 +204,22 @@ def optimization_flags(self, compiler, version):
             compiler (str): name of the compiler to be used
             version (str): version of the compiler to be used
         """
-        # If we don't have information on compiler return an empty string
-        if compiler not in self.compilers:
+        # If we don't have information on compiler at all
+        # return an empty string
+        if compiler not in self.family.compilers:
             return ''
 
+        # If we have information but it stops before this
+        # microarchitecture, fall back to the best known target
+        if compiler not in self.compilers:
+            best_target = [
+                x for x in self.ancestors if compiler in x.compilers
+            ][0]
+            msg = ("'{0}' compiler is known to optimize up to the '{1}'"
+                   " microarchitecture in the '{2}' architecture family")
+            msg = msg.format(compiler, best_target, best_target.family)
+            raise UnsupportedMicroarchitecture(msg)
+
         # If we have information on this compiler we need to check the
         # version being used
         compiler_info = self.compilers[compiler]
@@ -219,15 +231,10 @@ def optimization_flags(self, compiler, version):
         def satisfies_constraint(entry, version):
             min_version, max_version = entry['versions'].split(':')
 
-            # Check version suffixes
-            min_version, min_suffix = version_components(min_version)
-            max_version, max_suffix = version_components(max_version)
-            version, suffix = version_components(version)
-
-            # If the suffixes are not all equal there's no match
-            if ((suffix != min_suffix and min_version) or
-                (suffix != max_suffix and max_version)):
-                return False
+            # Extract numeric part of the version
+            min_version, _ = version_components(min_version)
+            max_version, _ = version_components(max_version)
+            version, _ = version_components(version)
 
             # Assume compiler versions fit into semver
             tuplify = lambda x: tuple(int(y) for y in x.split('.'))

lib/spack/llnl/util/cpu/microarchitectures.json

@@ -61,12 +61,14 @@
             "flags": "-march={name} -mtune={name}"
           }
         ],
-        "clang": [
+        "apple-clang": [
           {
-            "versions": "0.0.0-apple:",
+            "versions": ":",
             "name": "x86-64",
             "flags": "-march={name}"
-          },
+          }
+        ],
+        "clang": [
           {
             "versions": ":",
             "name": "x86-64",
@@ -650,15 +652,14 @@
         "avx512cd",
         "avx512vbmi",
         "avx512ifma",
-        "sha",
+        "sha_ni",
         "umip",
-        "clwb",
         "rdpid",
         "gfni",
-        "avx512vbmi2",
-        "avx512vpopcntdq",
-        "avx512bitalg",
-        "avx512vnni",
+        "avx512_vbmi2",
+        "avx512_vpopcntdq",
+        "avx512_bitalg",
+        "avx512_vnni",
         "vpclmulqdq",
         "vaes"
       ],

lib/spack/llnl/util/filesystem.py

@@ -2,7 +2,6 @@
 # Spack Project Developers. See the top-level COPYRIGHT file for details.
 #
 # SPDX-License-Identifier: (Apache-2.0 OR MIT)
-
 import collections
 import errno
 import hashlib
@@ -42,6 +41,8 @@
     'fix_darwin_install_name',
     'force_remove',
     'force_symlink',
+    'chgrp',
+    'chmod_x',
     'copy',
     'install',
     'copy_tree',
@@ -52,6 +53,7 @@
     'partition_path',
     'prefixes',
     'remove_dead_links',
+    'remove_directory_contents',
     'remove_if_dead_link',
     'remove_linked_tree',
     'set_executable',
@@ -338,56 +340,78 @@ def unset_executable_mode(path):
 
 
 def copy(src, dest, _permissions=False):
-    """Copies the file *src* to the file or directory *dest*.
+    """Copy the file(s) *src* to the file or directory *dest*.
 
     If *dest* specifies a directory, the file will be copied into *dest*
     using the base filename from *src*.
 
+    *src* may contain glob characters.
+
     Parameters:
-        src (str): the file to copy
+        src (str): the file(s) to copy
         dest (str): the destination file or directory
         _permissions (bool): for internal use only
+
+    Raises:
+        IOError: if *src* does not match any files or directories
+        ValueError: if *src* matches multiple files but *dest* is
+            not a directory
     """
     if _permissions:
         tty.debug('Installing {0} to {1}'.format(src, dest))
     else:
         tty.debug('Copying {0} to {1}'.format(src, dest))
 
-    # Expand dest to its eventual full path if it is a directory.
-    if os.path.isdir(dest):
-        dest = join_path(dest, os.path.basename(src))
+    files = glob.glob(src)
+    if not files:
+        raise IOError("No such file or directory: '{0}'".format(src))
+    if len(files) > 1 and not os.path.isdir(dest):
+        raise ValueError(
+            "'{0}' matches multiple files but '{1}' is not a directory".format(
+                src, dest))
 
-    shutil.copy(src, dest)
+    for src in files:
+        # Expand dest to its eventual full path if it is a directory.
+        dst = dest
+        if os.path.isdir(dest):
+            dst = join_path(dest, os.path.basename(src))
 
-    if _permissions:
-        set_install_permissions(dest)
-        copy_mode(src, dest)
+        shutil.copy(src, dst)
+
+        if _permissions:
+            set_install_permissions(dst)
+            copy_mode(src, dst)
 
 
 def install(src, dest):
-    """Installs the file *src* to the file or directory *dest*.
+    """Install the file(s) *src* to the file or directory *dest*.
 
     Same as :py:func:`copy` with the addition of setting proper
     permissions on the installed file.
 
     Parameters:
-        src (str): the file to install
+        src (str): the file(s) to install
         dest (str): the destination file or directory
+
+    Raises:
+        IOError: if *src* does not match any files or directories
+        ValueError: if *src* matches multiple files but *dest* is
+            not a directory
     """
     copy(src, dest, _permissions=True)
 
 
-def resolve_link_target_relative_to_the_link(l):
+def resolve_link_target_relative_to_the_link(link):
     """
     os.path.isdir uses os.path.exists, which for links will check
     the existence of the link target. If the link target is relative to
     the link, we need to construct a pathname that is valid from
     our cwd (which may not be the same as the link's directory)
     """
-    target = os.readlink(l)
+    target = os.readlink(link)
     if os.path.isabs(target):
         return target
-    link_dir = os.path.dirname(os.path.abspath(l))
+    link_dir = os.path.dirname(os.path.abspath(link))
     return os.path.join(link_dir, target)
 
 
@@ -397,6 +421,8 @@ def copy_tree(src, dest, symlinks=True, ignore=None, _permissions=False):
     If the destination directory *dest* does not already exist, it will
     be created as well as missing parent directories.
 
+    *src* may contain glob characters.
+
     If *symlinks* is true, symbolic links in the source tree are represented
     as symbolic links in the new tree and the metadata of the original links
     will be copied as far as the platform allows; if false, the contents and
@@ -411,56 +437,66 @@ def copy_tree(src, dest, symlinks=True, ignore=None, _permissions=False):
         symlinks (bool): whether or not to preserve symlinks
         ignore (function): function indicating which files to ignore
         _permissions (bool): for internal use only
+
+    Raises:
+        IOError: if *src* does not match any files or directories
+        ValueError: if *src* is a parent directory of *dest*
     """
     if _permissions:
         tty.debug('Installing {0} to {1}'.format(src, dest))
     else:
         tty.debug('Copying {0} to {1}'.format(src, dest))
 
-    abs_src = os.path.abspath(src)
-    if not abs_src.endswith(os.path.sep):
-        abs_src += os.path.sep
     abs_dest = os.path.abspath(dest)
     if not abs_dest.endswith(os.path.sep):
         abs_dest += os.path.sep
 
-    # Stop early to avoid unnecessary recursion if being asked to copy from a
-    # parent directory.
-    if abs_dest.startswith(abs_src):
-        raise ValueError('Cannot copy ancestor directory {0} into {1}'.
-                         format(abs_src, abs_dest))
+    files = glob.glob(src)
+    if not files:
+        raise IOError("No such file or directory: '{0}'".format(src))
 
-    mkdirp(dest)
+    for src in files:
+        abs_src = os.path.abspath(src)
+        if not abs_src.endswith(os.path.sep):
+            abs_src += os.path.sep
 
-    for s, d in traverse_tree(abs_src, abs_dest, order='pre',
-                              follow_symlinks=not symlinks,
-                              ignore=ignore,
-                              follow_nonexisting=True):
-        if os.path.islink(s):
-            link_target = resolve_link_target_relative_to_the_link(s)
-            if symlinks:
-                target = os.readlink(s)
-                if os.path.isabs(target):
-                    new_target = re.sub(abs_src, abs_dest, target)
-                    if new_target != target:
-                        tty.debug("Redirecting link {0} to {1}"
-                                  .format(target, new_target))
-                        target = new_target
+        # Stop early to avoid unnecessary recursion if being asked to copy
+        # from a parent directory.
+        if abs_dest.startswith(abs_src):
+            raise ValueError('Cannot copy ancestor directory {0} into {1}'.
+                             format(abs_src, abs_dest))
 
-                os.symlink(target, d)
-            elif os.path.isdir(link_target):
-                mkdirp(d)
+        mkdirp(abs_dest)
+
+        for s, d in traverse_tree(abs_src, abs_dest, order='pre',
+                                  follow_symlinks=not symlinks,
+                                  ignore=ignore,
+                                  follow_nonexisting=True):
+            if os.path.islink(s):
+                link_target = resolve_link_target_relative_to_the_link(s)
+                if symlinks:
+                    target = os.readlink(s)
+                    if os.path.isabs(target):
+                        new_target = re.sub(abs_src, abs_dest, target)
+                        if new_target != target:
+                            tty.debug("Redirecting link {0} to {1}"
+                                      .format(target, new_target))
+                            target = new_target
+
+                    os.symlink(target, d)
+                elif os.path.isdir(link_target):
+                    mkdirp(d)
+                else:
+                    shutil.copyfile(s, d)
             else:
-                shutil.copyfile(s, d)
-        else:
-            if os.path.isdir(s):
-                mkdirp(d)
-            else:
-                shutil.copyfile(s, d)
+                if os.path.isdir(s):
+                    mkdirp(d)
+                else:
+                    shutil.copy2(s, d)
 
-        if _permissions:
-            set_install_permissions(d)
-            copy_mode(s, d)
+            if _permissions:
+                set_install_permissions(d)
+                copy_mode(s, d)
 
 
 def install_tree(src, dest, symlinks=True, ignore=None):
@@ -474,6 +510,10 @@ def install_tree(src, dest, symlinks=True, ignore=None):
         dest (str): the destination directory
         symlinks (bool): whether or not to preserve symlinks
         ignore (function): function indicating which files to ignore
+
+    Raises:
+        IOError: if *src* does not match any files or directories
+        ValueError: if *src* is a parent directory of *dest*
     """
     copy_tree(src, dest, symlinks=symlinks, ignore=ignore, _permissions=True)
 
@@ -624,9 +664,9 @@ def replace_directory_transaction(directory_name, tmp_root=None):
     # Check the input is indeed a directory with absolute path.
     # Raise before anything is done to avoid moving the wrong directory
     assert os.path.isdir(directory_name), \
-        '"directory_name" must be a valid directory'
+        'Invalid directory: ' + directory_name
     assert os.path.isabs(directory_name), \
-        '"directory_name" must contain an absolute path'
+        '"directory_name" must contain an absolute path: ' + directory_name
 
     directory_basename = os.path.basename(directory_name)
 
@@ -643,7 +683,7 @@ def replace_directory_transaction(directory_name, tmp_root=None):
 
     try:
         yield tmp_dir
-    except (Exception, KeyboardInterrupt, SystemExit):
+    except (Exception, KeyboardInterrupt, SystemExit) as e:
         # Delete what was there, before copying back the original content
         if os.path.exists(directory_name):
             shutil.rmtree(directory_name)
@@ -654,6 +694,7 @@ def replace_directory_transaction(directory_name, tmp_root=None):
         tty.debug('DIRECTORY RECOVERED [{0}]'.format(directory_name))
 
         msg = 'the transactional move of "{0}" failed.'
+        msg += '\n    ' + str(e)
         raise RuntimeError(msg.format(directory_name))
     else:
         # Otherwise delete the temporary directory
@@ -937,6 +978,53 @@ def remove_linked_tree(path):
             shutil.rmtree(path, True)
 
 
+@contextmanager
+def safe_remove(*files_or_dirs):
+    """Context manager to remove the files passed as input, but restore
+    them in case any exception is raised in the context block.
+
+    Args:
+        *files_or_dirs: glob expressions for files or directories
+            to be removed
+
+    Returns:
+        Dictionary that maps deleted files to their temporary copy
+        within the context block.
+    """
+    # Find all the files or directories that match
+    glob_matches = [glob.glob(x) for x in files_or_dirs]
+    # Sort them so that shorter paths like "/foo/bar" come before
+    # nested paths like "/foo/bar/baz.yaml". This simplifies the
+    # handling of temporary copies below
+    sorted_matches = sorted([
+        os.path.abspath(x) for x in itertools.chain(*glob_matches)
+    ], key=len)
+
+    # Copy files and directories in a temporary location
+    removed, dst_root = {}, tempfile.mkdtemp()
+    try:
+        for id, file_or_dir in enumerate(sorted_matches):
+            # The glob expression at the top ensures that the file/dir exists
+            # at the time we enter the loop. Double check here since it might
+            # happen that a previous iteration of the loop already removed it.
+            # This is the case, for instance, if we remove the directory
+            # "/foo/bar" before the file "/foo/bar/baz.yaml".
+            if not os.path.exists(file_or_dir):
+                continue
+            # The monotonic ID is a simple way to make the filename
+            # or directory name unique in the temporary folder
+            basename = os.path.basename(file_or_dir) + '-{0}'.format(id)
+            temporary_path = os.path.join(dst_root, basename)
+            shutil.move(file_or_dir, temporary_path)
+            removed[file_or_dir] = temporary_path
+        yield removed
+    except BaseException:
+        # Restore the files that were removed
+        for original_path, temporary_path in removed.items():
+            shutil.move(temporary_path, original_path)
+        raise
+
+
 def fix_darwin_install_name(path):
     """Fix install name of dynamic libraries on Darwin to have full path.
 
@@ -1570,6 +1658,19 @@ def can_access_dir(path):
     return os.path.isdir(path) and os.access(path, os.R_OK | os.X_OK)
 
 
+@memoized
+def can_write_to_dir(path):
+    """Return True if the argument is a directory in which we can write.
+
+    Args:
+        path: path to be tested
+
+    Returns:
+        True if ``path`` is an writeable directory, else False
+    """
+    return os.path.isdir(path) and os.access(path, os.R_OK | os.X_OK | os.W_OK)
+
+
 @memoized
 def files_in(*search_paths):
     """Returns all the files in paths passed as arguments.
@@ -1683,3 +1784,28 @@ def prefixes(path):
         pass
 
     return paths
+
+
+def md5sum(file):
+    """Compute the MD5 sum of a file.
+
+    Args:
+        file (str): file to be checksummed
+
+    Returns:
+        MD5 sum of the file's content
+    """
+    md5 = hashlib.md5()
+    with open(file, "rb") as f:
+        md5.update(f.read())
+    return md5.digest()
+
+
+def remove_directory_contents(dir):
+    """Remove all contents of a directory."""
+    if os.path.exists(dir):
+        for entry in [os.path.join(dir, entry) for entry in os.listdir(dir)]:
+            if os.path.isfile(entry) or os.path.islink(entry):
+                os.unlink(entry)
+            else:
+                shutil.rmtree(entry)

lib/spack/llnl/util/lang.py

@@ -5,6 +5,7 @@
 
 from __future__ import division
 
+import multiprocessing
 import os
 import re
 import functools
@@ -19,49 +20,67 @@
 ignore_modules = [r'^\.#', '~$']
 
 
+# On macOS, Python 3.8 multiprocessing now defaults to the 'spawn' start
+# method. Spack cannot currently handle this, so force the process to start
+# using the 'fork' start method.
+#
+# TODO: This solution is not ideal, as the 'fork' start method can lead to
+# crashes of the subprocess. Figure out how to make 'spawn' work.
+#
+# See:
+# * https://github.com/spack/spack/pull/18124
+# * https://docs.python.org/3/library/multiprocessing.html#contexts-and-start-methods  # noqa: E501
+# * https://bugs.python.org/issue33725
+if sys.version_info >= (3,):  # novm
+    fork_context = multiprocessing.get_context('fork')
+else:
+    fork_context = multiprocessing
+
+
 def index_by(objects, *funcs):
     """Create a hierarchy of dictionaries by splitting the supplied
-       set of objects on unique values of the supplied functions.
-       Values are used as keys.  For example, suppose you have four
-       objects with attributes that look like this::
+    set of objects on unique values of the supplied functions.
 
-          a = Spec(name="boost",    compiler="gcc",   arch="bgqos_0")
-          b = Spec(name="mrnet",    compiler="intel", arch="chaos_5_x86_64_ib")
-          c = Spec(name="libelf",   compiler="xlc",   arch="bgqos_0")
-          d = Spec(name="libdwarf", compiler="intel", arch="chaos_5_x86_64_ib")
+    Values are used as keys. For example, suppose you have four
+    objects with attributes that look like this::
 
-          list_of_specs = [a,b,c,d]
-          index1 = index_by(list_of_specs, lambda s: s.arch,
-                            lambda s: s.compiler)
-          index2 = index_by(list_of_specs, lambda s: s.compiler)
+        a = Spec("boost %gcc target=skylake")
+        b = Spec("mrnet %intel target=zen2")
+        c = Spec("libelf %xlc target=skylake")
+        d = Spec("libdwarf %intel target=zen2")
 
-       ``index1`` now has two levels of dicts, with lists at the
-       leaves, like this::
+        list_of_specs = [a,b,c,d]
+        index1 = index_by(list_of_specs, lambda s: str(s.target),
+                          lambda s: s.compiler)
+        index2 = index_by(list_of_specs, lambda s: s.compiler)
 
-           { 'bgqos_0'           : { 'gcc' : [a], 'xlc' : [c] },
-             'chaos_5_x86_64_ib' : { 'intel' : [b, d] }
-           }
+    ``index1`` now has two levels of dicts, with lists at the
+    leaves, like this::
 
-       And ``index2`` is a single level dictionary of lists that looks
-       like this::
+        { 'zen2'    : { 'gcc' : [a], 'xlc' : [c] },
+          'skylake' : { 'intel' : [b, d] }
+        }
 
-           { 'gcc'    : [a],
-             'intel'  : [b,d],
-             'xlc'    : [c]
-           }
+    And ``index2`` is a single level dictionary of lists that looks
+    like this::
 
-       If any elemnts in funcs is a string, it is treated as the name
-       of an attribute, and acts like getattr(object, name).  So
-       shorthand for the above two indexes would be::
+        { 'gcc'    : [a],
+          'intel'  : [b,d],
+          'xlc'    : [c]
+        }
 
-           index1 = index_by(list_of_specs, 'arch', 'compiler')
-           index2 = index_by(list_of_specs, 'compiler')
+    If any elements in funcs is a string, it is treated as the name
+    of an attribute, and acts like getattr(object, name).  So
+    shorthand for the above two indexes would be::
 
-       You can also index by tuples by passing tuples::
+        index1 = index_by(list_of_specs, 'arch', 'compiler')
+        index2 = index_by(list_of_specs, 'compiler')
 
-           index1 = index_by(list_of_specs, ('arch', 'compiler'))
+    You can also index by tuples by passing tuples::
 
-       Keys in the resulting dict will look like ('gcc', 'bgqos_0').
+        index1 = index_by(list_of_specs, ('target', 'compiler'))
+
+    Keys in the resulting dict will look like ('gcc', 'skylake').
     """
     if not funcs:
         return objects
@@ -619,3 +638,28 @@ def load_module_from_file(module_name, module_path):
         import imp
         module = imp.load_source(module_name, module_path)
     return module
+
+
+def uniq(sequence):
+    """Remove strings of duplicate elements from a list.
+
+    This works like the command-line ``uniq`` tool.  It filters strings
+    of duplicate elements in a list. Adjacent matching elements are
+    merged into the first occurrence.
+
+    For example::
+
+        uniq([1, 1, 1, 1, 2, 2, 2, 3, 3]) == [1, 2, 3]
+        uniq([1, 1, 1, 1, 2, 2, 2, 1, 1]) == [1, 2, 1]
+
+    """
+    if not sequence:
+        return []
+
+    uniq_list = [sequence[0]]
+    last = sequence[0]
+    for element in sequence[1:]:
+        if element != last:
+            uniq_list.append(element)
+            last = element
+    return uniq_list

lib/spack/llnl/util/lock.py

@@ -8,14 +8,32 @@
 import errno
 import time
 import socket
+from datetime import datetime
 
 import llnl.util.tty as tty
+import spack.util.string
 
 
 __all__ = ['Lock', 'LockTransaction', 'WriteTransaction', 'ReadTransaction',
            'LockError', 'LockTimeoutError',
            'LockPermissionError', 'LockROFileError', 'CantCreateLockError']
 
+#: Mapping of supported locks to description
+lock_type = {fcntl.LOCK_SH: 'read', fcntl.LOCK_EX: 'write'}
+
+#: A useful replacement for functions that should return True when not provided
+#: for example.
+true_fn = lambda: True
+
+
+def _attempts_str(wait_time, nattempts):
+    # Don't print anything if we succeeded on the first try
+    if nattempts <= 1:
+        return ''
+
+    attempts = spack.util.string.plural(nattempts, 'attempt')
+    return ' after {0:0.2f}s and {1}'.format(wait_time, attempts)
+
 
 class Lock(object):
     """This is an implementation of a filesystem lock using Python's lockf.
@@ -31,8 +49,8 @@ class Lock(object):
     maintain multiple locks on the same file.
     """
 
-    def __init__(self, path, start=0, length=0, debug=False,
-                 default_timeout=None):
+    def __init__(self, path, start=0, length=0, default_timeout=None,
+                 debug=False, desc=''):
         """Construct a new lock on the file at ``path``.
 
         By default, the lock applies to the whole file.  Optionally,
@@ -43,6 +61,16 @@ def __init__(self, path, start=0, length=0, debug=False,
         not currently expose the ``whence`` parameter -- ``whence`` is
         always ``os.SEEK_SET`` and ``start`` is always evaluated from the
         beginning of the file.
+
+        Args:
+            path (str): path to the lock
+            start (int): optional byte offset at which the lock starts
+            length (int): optional number of bytes to lock
+            default_timeout (int): number of seconds to wait for lock attempts,
+                where None means to wait indefinitely
+            debug (bool): debug mode specific to locking
+            desc (str): optional debug message lock description, which is
+                helpful for distinguishing between different Spack locks.
         """
         self.path = path
         self._file = None
@@ -56,6 +84,9 @@ def __init__(self, path, start=0, length=0, debug=False,
         # enable debug mode
         self.debug = debug
 
+        # optional debug description
+        self.desc = ' ({0})'.format(desc) if desc else ''
+
         # If the user doesn't set a default timeout, or if they choose
         # None, 0, etc. then lock attempts will not time out (unless the
         # user sets a timeout for each attempt)
@@ -89,6 +120,20 @@ def _poll_interval_generator(_wait_times=None):
             num_requests += 1
             yield wait_time
 
+    def __repr__(self):
+        """Formal representation of the lock."""
+        rep = '{0}('.format(self.__class__.__name__)
+        for attr, value in self.__dict__.items():
+            rep += '{0}={1}, '.format(attr, value.__repr__())
+        return '{0})'.format(rep.strip(', '))
+
+    def __str__(self):
+        """Readable string (with key fields) of the lock."""
+        location = '{0}[{1}:{2}]'.format(self.path, self._start, self._length)
+        timeout = 'timeout={0}'.format(self.default_timeout)
+        activity = '#reads={0}, #writes={1}'.format(self._reads, self._writes)
+        return '({0}, {1}, {2})'.format(location, timeout, activity)
+
     def _lock(self, op, timeout=None):
         """This takes a lock using POSIX locks (``fcntl.lockf``).
 
@@ -99,8 +144,9 @@ def _lock(self, op, timeout=None):
         successfully acquired, the total wait time and the number of attempts
         is returned.
         """
-        assert op in (fcntl.LOCK_SH, fcntl.LOCK_EX)
+        assert op in lock_type
 
+        self._log_acquiring('{0} LOCK'.format(lock_type[op].upper()))
         timeout = timeout or self.default_timeout
 
         # Create file and parent directories if they don't exist.
@@ -128,6 +174,10 @@ def _lock(self, op, timeout=None):
             # If the file were writable, we'd have opened it 'r+'
             raise LockROFileError(self.path)
 
+        self._log_debug("{0} locking [{1}:{2}]: timeout {3} sec"
+                        .format(lock_type[op], self._start, self._length,
+                                timeout))
+
         poll_intervals = iter(Lock._poll_interval_generator())
         start_time = time.time()
         num_attempts = 0
@@ -139,17 +189,21 @@ def _lock(self, op, timeout=None):
 
             time.sleep(next(poll_intervals))
 
+        # TBD: Is an extra attempt after timeout needed/appropriate?
         num_attempts += 1
         if self._poll_lock(op):
             total_wait_time = time.time() - start_time
             return total_wait_time, num_attempts
 
-        raise LockTimeoutError("Timed out waiting for lock.")
+        raise LockTimeoutError("Timed out waiting for a {0} lock."
+                               .format(lock_type[op]))
 
     def _poll_lock(self, op):
         """Attempt to acquire the lock in a non-blocking manner. Return whether
         the locking attempt succeeds
         """
+        assert op in lock_type
+
         try:
             # Try to get the lock (will raise if not available.)
             fcntl.lockf(self._file, op | fcntl.LOCK_NB,
@@ -158,21 +212,24 @@ def _poll_lock(self, op):
             # help for debugging distributed locking
             if self.debug:
                 # All locks read the owner PID and host
-                self._read_debug_data()
+                self._read_log_debug_data()
+                self._log_debug('{0} locked {1} [{2}:{3}] (owner={4})'
+                                .format(lock_type[op], self.path,
+                                        self._start, self._length, self.pid))
 
                 # Exclusive locks write their PID/host
                 if op == fcntl.LOCK_EX:
-                    self._write_debug_data()
+                    self._write_log_debug_data()
 
             return True
 
         except IOError as e:
-            if e.errno in (errno.EAGAIN, errno.EACCES):
-                # EAGAIN and EACCES == locked by another process
-                pass
-            else:
+            # EAGAIN and EACCES == locked by another process (so try again)
+            if e.errno not in (errno.EAGAIN, errno.EACCES):
                 raise
 
+        return False
+
     def _ensure_parent_directory(self):
         parent = os.path.dirname(self.path)
 
@@ -189,7 +246,7 @@ def _ensure_parent_directory(self):
                 raise
         return parent
 
-    def _read_debug_data(self):
+    def _read_log_debug_data(self):
         """Read PID and host data out of the file if it is there."""
         self.old_pid = self.pid
         self.old_host = self.host
@@ -201,7 +258,7 @@ def _read_debug_data(self):
             _, _, self.host = host.rpartition('=')
             self.pid = int(self.pid)
 
-    def _write_debug_data(self):
+    def _write_log_debug_data(self):
         """Write PID and host data to the file, recording old values."""
         self.old_pid = self.pid
         self.old_host = self.host
@@ -227,6 +284,8 @@ def _unlock(self):
                     self._length, self._start, os.SEEK_SET)
         self._file.close()
         self._file = None
+        self._reads = 0
+        self._writes = 0
 
     def acquire_read(self, timeout=None):
         """Acquires a recursive, shared lock for reading.
@@ -242,15 +301,14 @@ def acquire_read(self, timeout=None):
         timeout = timeout or self.default_timeout
 
         if self._reads == 0 and self._writes == 0:
-            self._debug(
-                'READ LOCK: {0.path}[{0._start}:{0._length}] [Acquiring]'
-                .format(self))
             # can raise LockError.
             wait_time, nattempts = self._lock(fcntl.LOCK_SH, timeout=timeout)
-            self._acquired_debug('READ LOCK', wait_time, nattempts)
             self._reads += 1
+            # Log if acquired, which includes counts when verbose
+            self._log_acquired('READ LOCK', wait_time, nattempts)
             return True
         else:
+            # Increment the read count for nested lock tracking
             self._reads += 1
             return False
 
@@ -268,13 +326,11 @@ def acquire_write(self, timeout=None):
         timeout = timeout or self.default_timeout
 
         if self._writes == 0:
-            self._debug(
-                'WRITE LOCK: {0.path}[{0._start}:{0._length}] [Acquiring]'
-                .format(self))
             # can raise LockError.
             wait_time, nattempts = self._lock(fcntl.LOCK_EX, timeout=timeout)
-            self._acquired_debug('WRITE LOCK', wait_time, nattempts)
             self._writes += 1
+            # Log if acquired, which includes counts when verbose
+            self._log_acquired('WRITE LOCK', wait_time, nattempts)
 
             # return True only if we weren't nested in a read lock.
             # TODO: we may need to return two values: whether we got
@@ -282,9 +338,65 @@ def acquire_write(self, timeout=None):
             # write lock for the first time. Now it returns the latter.
             return self._reads == 0
         else:
+            # Increment the write count for nested lock tracking
             self._writes += 1
             return False
 
+    def is_write_locked(self):
+        """Check if the file is write locked
+
+        Return:
+            (bool): ``True`` if the path is write locked, otherwise, ``False``
+        """
+        try:
+            self.acquire_read()
+
+            # If we have a read lock then no other process has a write lock.
+            self.release_read()
+        except LockTimeoutError:
+            # Another process is holding a write lock on the file
+            return True
+
+        return False
+
+    def downgrade_write_to_read(self, timeout=None):
+        """
+        Downgrade from an exclusive write lock to a shared read.
+
+        Raises:
+            LockDowngradeError: if this is an attempt at a nested transaction
+        """
+        timeout = timeout or self.default_timeout
+
+        if self._writes == 1 and self._reads == 0:
+            self._log_downgrading()
+            # can raise LockError.
+            wait_time, nattempts = self._lock(fcntl.LOCK_SH, timeout=timeout)
+            self._reads = 1
+            self._writes = 0
+            self._log_downgraded(wait_time, nattempts)
+        else:
+            raise LockDowngradeError(self.path)
+
+    def upgrade_read_to_write(self, timeout=None):
+        """
+        Attempts to upgrade from a shared read lock to an exclusive write.
+
+        Raises:
+            LockUpgradeError: if this is an attempt at a nested transaction
+        """
+        timeout = timeout or self.default_timeout
+
+        if self._reads == 1 and self._writes == 0:
+            self._log_upgrading()
+            # can raise LockError.
+            wait_time, nattempts = self._lock(fcntl.LOCK_EX, timeout=timeout)
+            self._reads = 0
+            self._writes = 1
+            self._log_upgraded(wait_time, nattempts)
+        else:
+            raise LockUpgradeError(self.path)
+
     def release_read(self, release_fn=None):
         """Releases a read lock.
 
@@ -305,17 +417,17 @@ def release_read(self, release_fn=None):
         """
         assert self._reads > 0
 
+        locktype = 'READ LOCK'
         if self._reads == 1 and self._writes == 0:
-            self._debug(
-                'READ LOCK: {0.path}[{0._start}:{0._length}] [Released]'
-                .format(self))
+            self._log_releasing(locktype)
 
-            result = True
-            if release_fn is not None:
-                result = release_fn()
+            # we need to call release_fn before releasing the lock
+            release_fn = release_fn or true_fn
+            result = release_fn()
 
             self._unlock()      # can raise LockError.
-            self._reads -= 1
+            self._reads = 0
+            self._log_released(locktype)
             return result
         else:
             self._reads -= 1
@@ -339,45 +451,80 @@ def release_write(self, release_fn=None):
 
         """
         assert self._writes > 0
+        release_fn = release_fn or true_fn
 
+        locktype = 'WRITE LOCK'
         if self._writes == 1 and self._reads == 0:
-            self._debug(
-                'WRITE LOCK: {0.path}[{0._start}:{0._length}] [Released]'
-                .format(self))
+            self._log_releasing(locktype)
 
             # we need to call release_fn before releasing the lock
-            result = True
-            if release_fn is not None:
-                result = release_fn()
+            result = release_fn()
 
             self._unlock()      # can raise LockError.
-            self._writes -= 1
+            self._writes = 0
+            self._log_released(locktype)
             return result
-
         else:
             self._writes -= 1
 
             # when the last *write* is released, we call release_fn here
             # instead of immediately before releasing the lock.
             if self._writes == 0:
-                return release_fn() if release_fn is not None else True
+                return release_fn()
             else:
                 return False
 
-    def _debug(self, *args):
-        tty.debug(*args)
+    def _get_counts_desc(self):
+        return '(reads {0}, writes {1})'.format(self._reads, self._writes) \
+            if tty.is_verbose() else ''
 
-    def _acquired_debug(self, lock_type, wait_time, nattempts):
-        attempts_format = 'attempt' if nattempts == 1 else 'attempt'
-        if nattempts > 1:
-            acquired_attempts_format = ' after {0:0.2f}s and {1:d} {2}'.format(
-                wait_time, nattempts, attempts_format)
-        else:
-            # Dont print anything if we succeeded immediately
-            acquired_attempts_format = ''
-        self._debug(
-            '{0}: {1.path}[{1._start}:{1._length}] [Acquired{2}]'
-            .format(lock_type, self, acquired_attempts_format))
+    def _log_acquired(self, locktype, wait_time, nattempts):
+        attempts_part = _attempts_str(wait_time, nattempts)
+        now = datetime.now()
+        desc = 'Acquired at %s' % now.strftime("%H:%M:%S.%f")
+        self._log_debug(self._status_msg(locktype, '{0}{1}'
+                        .format(desc, attempts_part)))
+
+    def _log_acquiring(self, locktype):
+        self._log_debug(self._status_msg(locktype, 'Acquiring'), level=3)
+
+    def _log_debug(self, *args, **kwargs):
+        """Output lock debug messages."""
+        kwargs['level'] = kwargs.get('level', 2)
+        tty.debug(*args, **kwargs)
+
+    def _log_downgraded(self, wait_time, nattempts):
+        attempts_part = _attempts_str(wait_time, nattempts)
+        now = datetime.now()
+        desc = 'Downgraded at %s' % now.strftime("%H:%M:%S.%f")
+        self._log_debug(self._status_msg('READ LOCK', '{0}{1}'
+                        .format(desc, attempts_part)))
+
+    def _log_downgrading(self):
+        self._log_debug(self._status_msg('WRITE LOCK', 'Downgrading'), level=3)
+
+    def _log_released(self, locktype):
+        now = datetime.now()
+        desc = 'Released at %s' % now.strftime("%H:%M:%S.%f")
+        self._log_debug(self._status_msg(locktype, desc))
+
+    def _log_releasing(self, locktype):
+        self._log_debug(self._status_msg(locktype, 'Releasing'), level=3)
+
+    def _log_upgraded(self, wait_time, nattempts):
+        attempts_part = _attempts_str(wait_time, nattempts)
+        now = datetime.now()
+        desc = 'Upgraded at %s' % now.strftime("%H:%M:%S.%f")
+        self._log_debug(self._status_msg('WRITE LOCK', '{0}{1}'.
+                        format(desc, attempts_part)))
+
+    def _log_upgrading(self):
+        self._log_debug(self._status_msg('READ LOCK', 'Upgrading'), level=3)
+
+    def _status_msg(self, locktype, status):
+        status_desc = '[{0}] {1}'.format(status, self._get_counts_desc())
+        return '{0}{1.desc}: {1.path}[{1._start}:{1._length}] {2}'.format(
+            locktype, self, status_desc)
 
 
 class LockTransaction(object):
@@ -462,10 +609,28 @@ class LockError(Exception):
     """Raised for any errors related to locks."""
 
 
+class LockDowngradeError(LockError):
+    """Raised when unable to downgrade from a write to a read lock."""
+    def __init__(self, path):
+        msg = "Cannot downgrade lock from write to read on file: %s" % path
+        super(LockDowngradeError, self).__init__(msg)
+
+
+class LockLimitError(LockError):
+    """Raised when exceed maximum attempts to acquire a lock."""
+
+
 class LockTimeoutError(LockError):
     """Raised when an attempt to acquire a lock times out."""
 
 
+class LockUpgradeError(LockError):
+    """Raised when unable to upgrade from a read to a write lock."""
+    def __init__(self, path):
+        msg = "Cannot upgrade lock from read to write on file: %s" % path
+        super(LockUpgradeError, self).__init__(msg)
+
+
 class LockPermissionError(LockError):
     """Raised when there are permission issues with a lock."""
 

lib/spack/llnl/util/tty/__init__.py

@@ -19,7 +19,8 @@
 
 from llnl.util.tty.color import cprint, cwrite, cescape, clen
 
-_debug = False
+# Globals
+_debug = 0
 _verbose = False
 _stacktrace = False
 _timestamp = False
@@ -29,21 +30,26 @@
 indent = "  "
 
 
+def debug_level():
+    return _debug
+
+
 def is_verbose():
     return _verbose
 
 
-def is_debug():
-    return _debug
+def is_debug(level=1):
+    return _debug >= level
 
 
 def is_stacktrace():
     return _stacktrace
 
 
-def set_debug(flag):
+def set_debug(level=0):
     global _debug
-    _debug = flag
+    assert level >= 0, 'Debug level must be a positive value'
+    _debug = level
 
 
 def set_verbose(flag):
@@ -132,10 +138,17 @@ def process_stacktrace(countback):
     return st_text
 
 
+def show_pid():
+    return is_debug(2)
+
+
 def get_timestamp(force=False):
     """Get a string timestamp"""
     if _debug or _timestamp or force:
-        return datetime.now().strftime("[%Y-%m-%d-%H:%M:%S.%f] ")
+        # Note inclusion of the PID is useful for parallel builds.
+        pid = ', {0}'.format(os.getpid()) if show_pid() else ''
+        return '[{0}{1}] '.format(
+            datetime.now().strftime("%Y-%m-%d-%H:%M:%S.%f"), pid)
     else:
         return ''
 
@@ -195,7 +208,8 @@ def verbose(message, *args, **kwargs):
 
 
 def debug(message, *args, **kwargs):
-    if _debug:
+    level = kwargs.get('level', 1)
+    if is_debug(level):
         kwargs.setdefault('format', 'g')
         kwargs.setdefault('stream', sys.stderr)
         info(message, *args, **kwargs)

lib/spack/llnl/util/tty/color.py

@@ -215,20 +215,22 @@ def cextra(string):
     return len(''.join(re.findall(r'\033[^m]*m', string)))
 
 
-def cwrite(string, stream=sys.stdout, color=None):
+def cwrite(string, stream=None, color=None):
     """Replace all color expressions in string with ANSI control
        codes and write the result to the stream.  If color is
        False, this will write plain text with no color.  If True,
        then it will always write colored output.  If not supplied,
        then it will be set based on stream.isatty().
     """
+    stream = sys.stdout if stream is None else stream
     if color is None:
         color = get_color_when()
     stream.write(colorize(string, color=color))
 
 
-def cprint(string, stream=sys.stdout, color=None):
+def cprint(string, stream=None, color=None):
     """Same as cwrite, but writes a trailing newline to the stream."""
+    stream = sys.stdout if stream is None else stream
     cwrite(string + "\n", stream, color)
 
 

lib/spack/llnl/util/tty/log.py

@@ -7,17 +7,27 @@
 """
 from __future__ import unicode_literals
 
+import atexit
+import errno
 import multiprocessing
 import os
 import re
 import select
 import sys
 import traceback
+import signal
 from contextlib import contextmanager
 from six import string_types
 from six import StringIO
 
 import llnl.util.tty as tty
+from llnl.util.lang import fork_context
+
+try:
+    import termios
+except ImportError:
+    termios = None
+
 
 # Use this to strip escape sequences
 _escape = re.compile(r'\x1b[^m]*m|\x1b\[?1034h')
@@ -31,6 +41,25 @@
 control = re.compile('(\x11\n|\x13\n)')
 
 
+@contextmanager
+def ignore_signal(signum):
+    """Context manager to temporarily ignore a signal."""
+    old_handler = signal.signal(signum, signal.SIG_IGN)
+    try:
+        yield
+    finally:
+        signal.signal(signum, old_handler)
+
+
+def _is_background_tty(stream):
+    """True if the stream is a tty and calling process is in the background.
+    """
+    return (
+        stream.isatty() and
+        os.getpgrp() != os.tcgetpgrp(stream.fileno())
+    )
+
+
 def _strip(line):
     """Strip color and control characters from a line."""
     return _escape.sub('', line)
@@ -41,22 +70,75 @@ class keyboard_input(object):
 
     Use this with ``sys.stdin`` for keyboard input, e.g.::
 
-        with keyboard_input(sys.stdin):
-            r, w, x = select.select([sys.stdin], [], [])
-            # ... do something with keypresses ...
+        with keyboard_input(sys.stdin) as kb:
+            while True:
+                kb.check_fg_bg()
+                r, w, x = select.select([sys.stdin], [], [])
+                # ... do something with keypresses ...
 
-    This disables canonical input so that keypresses are available on the
-    stream immediately. Typically standard input allows line editing,
-    which means keypresses won't be sent until the user hits return.
+    The ``keyboard_input`` context manager disables canonical
+    (line-based) input and echoing, so that keypresses are available on
+    the stream immediately, and they are not printed to the
+    terminal. Typically, standard input is line-buffered, which means
+    keypresses won't be sent until the user hits return. In this mode, a
+    user can hit, e.g., 'v', and it will be read on the other end of the
+    pipe immediately but not printed.
 
-    It also disables echoing, so that keys pressed aren't printed to the
-    terminal.  So, the user can hit, e.g., 'v', and it's read on the
-    other end of the pipe immediately but not printed.
+    The handler takes care to ensure that terminal changes only take
+    effect when the calling process is in the foreground. If the process
+    is backgrounded, canonical mode and echo are re-enabled. They are
+    disabled again when the calling process comes back to the foreground.
 
-    When the with block completes, prior TTY settings are restored.
+    This context manager works through a single signal handler for
+    ``SIGTSTP``, along with a poolling routine called ``check_fg_bg()``.
+    Here are the relevant states, transitions, and POSIX signals::
+
+        [Running] -------- Ctrl-Z sends SIGTSTP ------------.
+        [ in FG ] <------- fg sends SIGCONT --------------. |
+           ^                                              | |
+           | fg (no signal)                               | |
+           |                                              | v
+        [Running] <------- bg sends SIGCONT ---------- [Stopped]
+        [ in BG ]                                      [ in BG ]
+
+    We handle all transitions exept for ``SIGTSTP`` generated by Ctrl-Z
+    by periodically calling ``check_fg_bg()``.  This routine notices if
+    we are in the background with canonical mode or echo disabled, or if
+    we are in the foreground without canonical disabled and echo enabled,
+    and it fixes the terminal settings in response.
+
+    ``check_fg_bg()`` works *except* for when the process is stopped with
+    ``SIGTSTP``.  We cannot rely on a periodic timer in this case, as it
+    may not rrun before the process stops.  We therefore restore terminal
+    settings in the ``SIGTSTP`` handler.
+
+    Additional notes:
+
+    * We mostly use polling here instead of a SIGARLM timer or a
+      thread. This is to avoid the complexities of many interrupts, which
+      seem to make system calls (like I/O) unreliable in older Python
+      versions (2.6 and 2.7).  See these issues for details:
+
+      1. https://www.python.org/dev/peps/pep-0475/
+      2. https://bugs.python.org/issue8354
+
+      There are essentially too many ways for asynchronous signals to go
+      wrong if we also have to support older Python versions, so we opt
+      not to use them.
+
+    * ``SIGSTOP`` can stop a process (in the foreground or background),
+      but it can't be caught. Because of this, we can't fix any terminal
+      settings on ``SIGSTOP``, and the terminal will be left with
+      ``ICANON`` and ``ECHO`` disabled until it is resumes execution.
+
+    * Technically, a process *could* be sent ``SIGTSTP`` while running in
+      the foreground, without the shell backgrounding that process. This
+      doesn't happen in practice, and we assume that ``SIGTSTP`` always
+      means that defaults should be restored.
+
+    * We rely on ``termios`` support.  Without it, or if the stream isn't
+      a TTY, ``keyboard_input`` has no effect.
 
-    Note: this depends on termios support.  If termios isn't available,
-    or if the stream isn't a TTY, this context manager has no effect.
     """
     def __init__(self, stream):
         """Create a context manager that will enable keyboard input on stream.
@@ -69,44 +151,97 @@ def __init__(self, stream):
         """
         self.stream = stream
 
+    def _is_background(self):
+        """True iff calling process is in the background."""
+        return _is_background_tty(self.stream)
+
+    def _get_canon_echo_flags(self):
+        """Get current termios canonical and echo settings."""
+        cfg = termios.tcgetattr(self.stream)
+        return (
+            bool(cfg[3] & termios.ICANON),
+            bool(cfg[3] & termios.ECHO),
+        )
+
+    def _enable_keyboard_input(self):
+        """Disable canonical input and echoing on ``self.stream``."""
+        # "enable" input by disabling canonical mode and echo
+        new_cfg = termios.tcgetattr(self.stream)
+        new_cfg[3] &= ~termios.ICANON
+        new_cfg[3] &= ~termios.ECHO
+
+        # Apply new settings for terminal
+        with ignore_signal(signal.SIGTTOU):
+            termios.tcsetattr(self.stream, termios.TCSANOW, new_cfg)
+
+    def _restore_default_terminal_settings(self):
+        """Restore the original input configuration on ``self.stream``."""
+        # _restore_default_terminal_settings Can be called in foreground
+        # or background. When called in the background, tcsetattr triggers
+        # SIGTTOU, which we must ignore, or the process will be stopped.
+        with ignore_signal(signal.SIGTTOU):
+            termios.tcsetattr(self.stream, termios.TCSANOW, self.old_cfg)
+
+    def _tstp_handler(self, signum, frame):
+        self._restore_default_terminal_settings()
+        os.kill(os.getpid(), signal.SIGSTOP)
+
+    def check_fg_bg(self):
+        # old_cfg is set up in __enter__ and indicates that we have
+        # termios and a valid stream.
+        if not self.old_cfg:
+            return
+
+        # query terminal flags and fg/bg status
+        flags = self._get_canon_echo_flags()
+        bg = self._is_background()
+
+        # restore sanity if flags are amiss -- see diagram in class docs
+        if not bg and any(flags):    # fg, but input not enabled
+            self._enable_keyboard_input()
+        elif bg and not all(flags):  # bg, but input enabled
+            self._restore_default_terminal_settings()
+
     def __enter__(self):
-        """Enable immediate keypress input on stream.
+        """Enable immediate keypress input, while this process is foreground.
 
         If the stream is not a TTY or the system doesn't support termios,
         do nothing.
         """
         self.old_cfg = None
+        self.old_handlers = {}
 
         # Ignore all this if the input stream is not a tty.
         if not self.stream or not self.stream.isatty():
-            return
+            return self
 
-        try:
-            # If this fails, self.old_cfg will remain None
-            import termios
+        if termios:
+            # save old termios settings to restore later
+            self.old_cfg = termios.tcgetattr(self.stream)
 
-            # save old termios settings
-            fd = self.stream.fileno()
-            self.old_cfg = termios.tcgetattr(fd)
+            # Install a signal handler to disable/enable keyboard input
+            # when the process moves between foreground and background.
+            self.old_handlers[signal.SIGTSTP] = signal.signal(
+                signal.SIGTSTP, self._tstp_handler)
 
-            # create new settings with canonical input and echo
-            # disabled, so keypresses are immediate & don't echo.
-            self.new_cfg = termios.tcgetattr(fd)
-            self.new_cfg[3] &= ~termios.ICANON
-            self.new_cfg[3] &= ~termios.ECHO
+            # add an atexit handler to ensure the terminal is restored
+            atexit.register(self._restore_default_terminal_settings)
 
-            # Apply new settings for terminal
-            termios.tcsetattr(fd, termios.TCSADRAIN, self.new_cfg)
+            # enable keyboard input initially (if foreground)
+            if not self._is_background():
+                self._enable_keyboard_input()
 
-        except Exception:
-            pass  # some OS's do not support termios, so ignore
+        return self
 
     def __exit__(self, exc_type, exception, traceback):
-        """If termios was avaialble, restore old settings."""
+        """If termios was available, restore old settings."""
         if self.old_cfg:
-            import termios
-            termios.tcsetattr(
-                self.stream.fileno(), termios.TCSADRAIN, self.old_cfg)
+            self._restore_default_terminal_settings()
+
+        # restore SIGSTP and SIGCONT handlers
+        if self.old_handlers:
+            for signum, old_handler in self.old_handlers.items():
+                signal.signal(signum, old_handler)
 
 
 class Unbuffered(object):
@@ -189,14 +324,15 @@ class log_output(object):
     work within test frameworks like nose and pytest.
     """
 
-    def __init__(self, file_like=None, echo=False, debug=False, buffer=False):
+    def __init__(self, file_like=None, output=None, error=None,
+                 echo=False, debug=0, buffer=False):
         """Create a new output log context manager.
 
         Args:
             file_like (str or stream): open file object or name of file where
                 output should be logged
             echo (bool): whether to echo output in addition to logging it
-            debug (bool): whether to enable tty debug mode during logging
+            debug (int): positive to enable tty debug mode during logging
             buffer (bool): pass buffer=True to skip unbuffering output; note
                 this doesn't set up any *new* buffering
 
@@ -214,14 +350,16 @@ def __init__(self, file_like=None, echo=False, debug=False, buffer=False):
 
         """
         self.file_like = file_like
+        self.output = output or sys.stdout
+        self.error = error or sys.stderr
         self.echo = echo
         self.debug = debug
         self.buffer = buffer
-
         self._active = False  # used to prevent re-entry
 
-    def __call__(self, file_like=None, echo=None, debug=None, buffer=None):
-        """Thie behaves the same as init. It allows a logger to be reused.
+    def __call__(self, file_like=None, output=None, error=None,
+                 echo=None, debug=None, buffer=None):
+        """This behaves the same as init. It allows a logger to be reused.
 
         Arguments are the same as for ``__init__()``.  Args here take
         precedence over those passed to ``__init__()``.
@@ -241,6 +379,10 @@ def __call__(self, file_like=None, echo=None, debug=None, buffer=None):
         """
         if file_like is not None:
             self.file_like = file_like
+        if output is not None:
+            self.output = output
+        if error is not None:
+            self.error = error
         if echo is not None:
             self.echo = echo
         if debug is not None:
@@ -282,11 +424,11 @@ def __enter__(self):
         self._saved_debug = tty._debug
 
         # OS-level pipe for redirecting output to logger
-        self.read_fd, self.write_fd = os.pipe()
+        read_fd, write_fd = os.pipe()
 
         # Multiprocessing pipe for communication back from the daemon
         # Currently only used to save echo value between uses
-        self.parent, self.child = multiprocessing.Pipe()
+        self.parent_pipe, child_pipe = multiprocessing.Pipe()
 
         # Sets a daemon that writes to file what it reads from a pipe
         try:
@@ -296,11 +438,16 @@ def __enter__(self):
             except BaseException:
                 input_stream = None  # just don't forward input if this fails
 
-            self.process = multiprocessing.Process(
-                target=self._writer_daemon, args=(input_stream,))
+            self.process = fork_context.Process(
+                target=_writer_daemon,
+                args=(
+                    input_stream, read_fd, write_fd, self.echo, self.output,
+                    self.log_file, child_pipe
+                )
+            )
             self.process.daemon = True  # must set before start()
             self.process.start()
-            os.close(self.read_fd)  # close in the parent process
+            os.close(read_fd)  # close in the parent process
 
         finally:
             if input_stream:
@@ -308,43 +455,54 @@ def __enter__(self):
 
         # Flush immediately before redirecting so that anything buffered
         # goes to the original stream
-        sys.stdout.flush()
-        sys.stderr.flush()
+        self.output.flush()
+        self.error.flush()
+#        sys.stdout.flush()
+#        sys.stderr.flush()
 
         # Now do the actual output rediction.
-        self.use_fds = _file_descriptors_work(sys.stdout, sys.stderr)
+        self.use_fds = _file_descriptors_work(self.output, self.error)#sys.stdout, sys.stderr)
+
         if self.use_fds:
             # We try first to use OS-level file descriptors, as this
             # redirects output for subprocesses and system calls.
 
             # Save old stdout and stderr file descriptors
-            self._saved_stdout = os.dup(sys.stdout.fileno())
-            self._saved_stderr = os.dup(sys.stderr.fileno())
+            self._saved_output = os.dup(self.output.fileno())
+            self._saved_error = os.dup(self.error.fileno())
+#            self._saved_stdout = os.dup(sys.stdout.fileno())
+#            self._saved_stderr = os.dup(sys.stderr.fileno())
 
             # redirect to the pipe we created above
-            os.dup2(self.write_fd, sys.stdout.fileno())
-            os.dup2(self.write_fd, sys.stderr.fileno())
-            os.close(self.write_fd)
-
+            os.dup2(write_fd, self.output.fileno())
+            os.dup2(write_fd, self.error.fileno())
+#            os.dup2(write_fd, sys.stdout.fileno())
+#            os.dup2(write_fd, sys.stderr.fileno())
+            os.close(write_fd)
         else:
             # Handle I/O the Python way. This won't redirect lower-level
             # output, but it's the best we can do, and the caller
             # shouldn't expect any better, since *they* have apparently
             # redirected I/O the Python way.
-
             # Save old stdout and stderr file objects
-            self._saved_stdout = sys.stdout
-            self._saved_stderr = sys.stderr
+            self._saved_output = self.output
+            self._saved_error = self.error
+#            self._saved_stdout = sys.stdout
+#            self._saved_stderr = sys.stderr
 
             # create a file object for the pipe; redirect to it.
-            pipe_fd_out = os.fdopen(self.write_fd, 'w')
-            sys.stdout = pipe_fd_out
-            sys.stderr = pipe_fd_out
+            pipe_fd_out = os.fdopen(write_fd, 'w')
+            self.output = pipe_fd_out
+            self.error = pipe_fd_out
+#            sys.stdout = pipe_fd_out
+#            sys.stderr = pipe_fd_out
 
         # Unbuffer stdout and stderr at the Python level
         if not self.buffer:
-            sys.stdout = Unbuffered(sys.stdout)
-            sys.stderr = Unbuffered(sys.stderr)
+            self.output = Unbuffered(self.output)
+            self.error = Unbuffered(self.error)
+#            sys.stdout = Unbuffered(sys.stdout)
+#            sys.stderr = Unbuffered(sys.stderr)
 
         # Force color and debug settings now that we have redirected.
         tty.color.set_color_when(forced_color)
@@ -359,31 +517,40 @@ def __enter__(self):
 
     def __exit__(self, exc_type, exc_val, exc_tb):
         # Flush any buffered output to the logger daemon.
-        sys.stdout.flush()
-        sys.stderr.flush()
+        self.output.flush()
+        self.error.flush()
+#        sys.stdout.flush()
+#        sys.stderr.flush()
 
         # restore previous output settings, either the low-level way or
         # the python way
         if self.use_fds:
-            os.dup2(self._saved_stdout, sys.stdout.fileno())
-            os.close(self._saved_stdout)
+            os.dup2(self._saved_output, self.output.fileno())
+            os.close(self._saved_output)
 
-            os.dup2(self._saved_stderr, sys.stderr.fileno())
-            os.close(self._saved_stderr)
+            os.dup2(self._saved_error, self.error.fileno())
+            os.close(self._saved_error)
+#            os.dup2(self._saved_stdout, sys.stdout.fileno())
+#            os.close(self._saved_stdout)
+
+#            os.dup2(self._saved_stderr, sys.stderr.fileno())
+#            os.close(self._saved_stderr)
         else:
-            sys.stdout = self._saved_stdout
-            sys.stderr = self._saved_stderr
+            self.output = self._saved_output
+            self.error = self._saved_error
+#            sys.stdout = self._saved_stdout
+#            sys.stderr = self._saved_stderr
 
         # print log contents in parent if needed.
         if self.write_log_in_parent:
-            string = self.parent.recv()
+            string = self.parent_pipe.recv()
             self.file_like.write(string)
 
         if self.close_log_in_parent:
             self.log_file.close()
 
         # recover and store echo settings from the child before it dies
-        self.echo = self.parent.recv()
+        self.echo = self.parent_pipe.recv()
 
         # join the daemon process. The daemon will quit automatically
         # when the write pipe is closed; we just wait for it here.
@@ -406,74 +573,170 @@ def force_echo(self):
         # output. We us these control characters rather than, say, a
         # separate pipe, because they're in-band and assured to appear
         # exactly before and after the text we want to echo.
-        sys.stdout.write(xon)
-        sys.stdout.flush()
-        yield
-        sys.stdout.write(xoff)
-        sys.stdout.flush()
-
-    def _writer_daemon(self, stdin):
-        """Daemon that writes output to the log file and stdout."""
-        # Use line buffering (3rd param = 1) since Python 3 has a bug
-        # that prevents unbuffered text I/O.
-        in_pipe = os.fdopen(self.read_fd, 'r', 1)
-        os.close(self.write_fd)
-
-        echo = self.echo        # initial echo setting, user-controllable
-        force_echo = False      # parent can force echo for certain output
-
-        # list of streams to select from
-        istreams = [in_pipe, stdin] if stdin else [in_pipe]
-
-        log_file = self.log_file
+        self.output.write(xon)
+        self.output.flush()
         try:
-            with keyboard_input(stdin):
-                while True:
-                    # No need to set any timeout for select.select
-                    # Wait until a key press or an event on in_pipe.
-                    rlist, _, _ = select.select(istreams, [], [])
-
-                    # Allow user to toggle echo with 'v' key.
-                    # Currently ignores other chars.
-                    if stdin in rlist:
-                        if stdin.read(1) == 'v':
-                            echo = not echo
-
-                    # Handle output from the with block process.
-                    if in_pipe in rlist:
-                        # If we arrive here it means that in_pipe was
-                        # ready for reading : it should never happen that
-                        # line is false-ish
-                        line = in_pipe.readline()
-                        if not line:
-                            break  # EOF
-
-                        # find control characters and strip them.
-                        controls = control.findall(line)
-                        line = re.sub(control, '', line)
-
-                        # Echo to stdout if requested or forced
-                        if echo or force_echo:
-                            sys.stdout.write(line)
-                            sys.stdout.flush()
-
-                        # Stripped output to log file.
-                        log_file.write(_strip(line))
-                        log_file.flush()
-
-                        if xon in controls:
-                            force_echo = True
-                        if xoff in controls:
-                            force_echo = False
-        except BaseException:
-            tty.error("Exception occurred in writer daemon!")
-            traceback.print_exc()
-
+            yield
         finally:
-            # send written data back to parent if we used a StringIO
-            if self.write_log_in_parent:
-                self.child.send(log_file.getvalue())
-            log_file.close()
+            self.output.write(xoff)
+            self.output.flush()
 
-        # send echo value back to the parent so it can be preserved.
-        self.child.send(echo)
+
+def _writer_daemon(stdin, read_fd, write_fd, echo, echo_stream, log_file,
+                   control_pipe):
+    """Daemon used by ``log_output`` to write to a log file and to ``stdout``.
+
+    The daemon receives output from the parent process and writes it both
+    to a log and, optionally, to ``stdout``.  The relationship looks like
+    this::
+
+        Terminal
+           |
+           |          +-------------------------+
+           |          | Parent Process          |
+           +--------> |   with log_output():    |
+           | stdin    |     ...                 |
+           |          +-------------------------+
+           |            ^             | write_fd (parent's redirected stdout)
+           |            | control     |
+           |            | pipe        |
+           |            |             v read_fd
+           |          +-------------------------+   stdout
+           |          | Writer daemon           |------------>
+           +--------> |   read from read_fd     |   log_file
+             stdin    |   write to out and log  |------------>
+                      +-------------------------+
+
+    Within the ``log_output`` handler, the parent's output is redirected
+    to a pipe from which the daemon reads.  The daemon writes each line
+    from the pipe to a log file and (optionally) to ``stdout``.  The user
+    can hit ``v`` to toggle output on ``stdout``.
+
+    In addition to the input and output file descriptors, the daemon
+    interacts with the parent via ``control_pipe``.  It reports whether
+    ``stdout`` was enabled or disabled when it finished and, if the
+    ``log_file`` is a ``StringIO`` object, then the daemon also sends the
+    logged output back to the parent as a string, to be written to the
+    ``StringIO`` in the parent. This is mainly for testing.
+
+    Arguments:
+        stdin (stream): input from the terminal
+        read_fd (int): pipe for reading from parent's redirected stdout
+        write_fd (int): parent's end of the pipe will write to (will be
+            immediately closed by the writer daemon)
+        echo (bool): initial echo setting -- controlled by user and
+            preserved across multiple writer daemons
+        echo_stream (stream): output to echo to when echoing
+        log_file (file-like): file to log all output
+        control_pipe (Pipe): multiprocessing pipe on which to send control
+            information to the parent
+
+    """
+    # Use line buffering (3rd param = 1) since Python 3 has a bug
+    # that prevents unbuffered text I/O.
+    in_pipe = os.fdopen(read_fd, 'r', 1)
+    os.close(write_fd)
+
+    # list of streams to select from
+    istreams = [in_pipe, stdin] if stdin else [in_pipe]
+    force_echo = False      # parent can force echo for certain output
+
+    try:
+        with keyboard_input(stdin) as kb:
+            while True:
+                # fix the terminal settings if we recently came to
+                # the foreground
+                kb.check_fg_bg()
+
+                # wait for input from any stream. use a coarse timeout to
+                # allow other checks while we wait for input
+                rlist, _, _ = _retry(select.select)(istreams, [], [], 1e-1)
+
+                # Allow user to toggle echo with 'v' key.
+                # Currently ignores other chars.
+                # only read stdin if we're in the foreground
+                if stdin in rlist and not _is_background_tty(stdin):
+                    # it's possible to be backgrounded between the above
+                    # check and the read, so we ignore SIGTTIN here.
+                    with ignore_signal(signal.SIGTTIN):
+                        try:
+                            if stdin.read(1) == 'v':
+                                echo = not echo
+                        except IOError as e:
+                            # If SIGTTIN is ignored, the system gives EIO
+                            # to let the caller know the read failed b/c it
+                            # was in the bg. Ignore that too.
+                            if e.errno != errno.EIO:
+                                raise
+
+                if in_pipe in rlist:
+                    # Handle output from the calling process.
+                    line = _retry(in_pipe.readline)()
+                    if not line:
+                        break
+
+                    # find control characters and strip them.
+                    controls = control.findall(line)
+                    line = control.sub('', line)
+
+                    # Echo to stdout if requested or forced.
+                    if echo or force_echo:
+                        echo_stream.write(line)
+                        echo_stream.flush()
+
+                    # Stripped output to log file.
+                    log_file.write(_strip(line))
+                    log_file.flush()
+
+                    if xon in controls:
+                        force_echo = True
+                    if xoff in controls:
+                        force_echo = False
+
+    except BaseException:
+        tty.error("Exception occurred in writer daemon!")
+        traceback.print_exc()
+
+    finally:
+        # send written data back to parent if we used a StringIO
+        if isinstance(log_file, StringIO):
+            control_pipe.send(log_file.getvalue())
+        log_file.close()
+
+    # send echo value back to the parent so it can be preserved.
+    control_pipe.send(echo)
+
+
+def _retry(function):
+    """Retry a call if errors indicating an interrupted system call occur.
+
+    Interrupted system calls return -1 and set ``errno`` to ``EINTR`` if
+    certain flags are not set.  Newer Pythons automatically retry them,
+    but older Pythons do not, so we need to retry the calls.
+
+    This function converts a call like this:
+
+        syscall(args)
+
+    and makes it retry by wrapping the function like this:
+
+        _retry(syscall)(args)
+
+    This is a private function because EINTR is unfortunately raised in
+    different ways from different functions, and we only handle the ones
+    relevant for this file.
+
+    """
+    def wrapped(*args, **kwargs):
+        while True:
+            try:
+                return function(*args, **kwargs)
+            except IOError as e:
+                if e.errno == errno.EINTR:
+                    continue
+                raise
+            except select.error as e:
+                if e.args[0] == errno.EINTR:
+                    continue
+                raise
+    return wrapped

lib/spack/llnl/util/tty/pty.py

@@ -0,0 +1,347 @@
+# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Spack Project Developers. See the top-level COPYRIGHT file for details.
+#
+# SPDX-License-Identifier: (Apache-2.0 OR MIT)
+
+"""The pty module handles pseudo-terminals.
+
+Currently, the infrastructure here is only used to test llnl.util.tty.log.
+
+If this is used outside a testing environment, we will want to reconsider
+things like timeouts in ``ProcessController.wait()``, which are set to
+get tests done quickly, not to avoid high CPU usage.
+
+"""
+from __future__ import print_function
+
+import os
+import signal
+import multiprocessing
+import re
+import sys
+import termios
+import time
+import traceback
+
+import llnl.util.tty.log as log
+from llnl.util.lang import fork_context
+
+from spack.util.executable import which
+
+
+class ProcessController(object):
+    """Wrapper around some fundamental process control operations.
+
+    This allows one process (the controller) to drive another (the
+    minion) similar to the way a shell would, by sending signals and I/O.
+
+    """
+    def __init__(self, pid, controller_fd,
+                 timeout=1, sleep_time=1e-1, debug=False):
+        """Create a controller to manipulate the process with id ``pid``
+
+        Args:
+            pid (int): id of process to control
+            controller_fd (int): controller fd attached to pid's stdin
+            timeout (int): time in seconds for wait operations to time out
+                (default 1 second)
+            sleep_time (int): time to sleep after signals, to control the
+                signal rate of the controller (default 1e-1)
+            debug (bool): whether ``horizontal_line()`` and ``status()`` should
+                produce output when called (default False)
+
+        ``sleep_time`` allows the caller to insert delays after calls
+        that signal or modify the controlled process. Python behaves very
+        poorly if signals arrive too fast, and drowning a Python process
+        with a Python handler with signals can kill the process and hang
+        our tests, so we throttle this a closer-to-interactive rate.
+
+        """
+        self.pid = pid
+        self.pgid = os.getpgid(pid)
+        self.controller_fd = controller_fd
+        self.timeout = timeout
+        self.sleep_time = sleep_time
+        self.debug = debug
+
+        # we need the ps command to wait for process statuses
+        self.ps = which("ps", required=True)
+
+    def get_canon_echo_attrs(self):
+        """Get echo and canon attributes of the terminal of controller_fd."""
+        cfg = termios.tcgetattr(self.controller_fd)
+        return (
+            bool(cfg[3] & termios.ICANON),
+            bool(cfg[3] & termios.ECHO),
+        )
+
+    def horizontal_line(self, name):
+        """Labled horizontal line for debugging."""
+        if self.debug:
+            sys.stderr.write(
+                "------------------------------------------- %s\n" % name
+            )
+
+    def status(self):
+        """Print debug message with status info for the minion."""
+        if self.debug:
+            canon, echo = self.get_canon_echo_attrs()
+            sys.stderr.write("canon: %s, echo: %s\n" % (
+                "on" if canon else "off",
+                "on" if echo else "off",
+            ))
+            sys.stderr.write("input: %s\n" % self.input_on())
+            sys.stderr.write("bg: %s\n" % self.background())
+            sys.stderr.write("\n")
+
+    def input_on(self):
+        """True if keyboard input is enabled on the controller_fd pty."""
+        return self.get_canon_echo_attrs() == (False, False)
+
+    def background(self):
+        """True if pgid is in a background pgroup of controller_fd's tty."""
+        return self.pgid != os.tcgetpgrp(self.controller_fd)
+
+    def tstp(self):
+        """Send SIGTSTP to the controlled process."""
+        self.horizontal_line("tstp")
+        os.killpg(self.pgid, signal.SIGTSTP)
+        time.sleep(self.sleep_time)
+
+    def cont(self):
+        self.horizontal_line("cont")
+        os.killpg(self.pgid, signal.SIGCONT)
+        time.sleep(self.sleep_time)
+
+    def fg(self):
+        self.horizontal_line("fg")
+        with log.ignore_signal(signal.SIGTTOU):
+            os.tcsetpgrp(self.controller_fd, os.getpgid(self.pid))
+        time.sleep(self.sleep_time)
+
+    def bg(self):
+        self.horizontal_line("bg")
+        with log.ignore_signal(signal.SIGTTOU):
+            os.tcsetpgrp(self.controller_fd, os.getpgrp())
+        time.sleep(self.sleep_time)
+
+    def write(self, byte_string):
+        self.horizontal_line("write '%s'" % byte_string.decode("utf-8"))
+        os.write(self.controller_fd, byte_string)
+
+    def wait(self, condition):
+        start = time.time()
+        while (((time.time() - start) < self.timeout) and not condition()):
+            time.sleep(1e-2)
+        assert condition()
+
+    def wait_enabled(self):
+        self.wait(lambda: self.input_on() and not self.background())
+
+    def wait_disabled(self):
+        self.wait(lambda: not self.input_on() and self.background())
+
+    def wait_disabled_fg(self):
+        self.wait(lambda: not self.input_on() and not self.background())
+
+    def proc_status(self):
+        status = self.ps("-p", str(self.pid), "-o", "stat", output=str)
+        status = re.split(r"\s+", status.strip(), re.M)
+        return status[1]
+
+    def wait_stopped(self):
+        self.wait(lambda: "T" in self.proc_status())
+
+    def wait_running(self):
+        self.wait(lambda: "T" not in self.proc_status())
+
+
+class PseudoShell(object):
+    """Sets up controller and minion processes with a PTY.
+
+    You can create a ``PseudoShell`` if you want to test how some
+    function responds to terminal input.  This is a pseudo-shell from a
+    job control perspective; ``controller_function`` and ``minion_function``
+    are set up with a pseudoterminal (pty) so that the controller can drive
+    the minion through process control signals and I/O.
+
+    The two functions should have signatures like this::
+
+        def controller_function(proc, ctl, **kwargs)
+        def minion_function(**kwargs)
+
+    ``controller_function`` is spawned in its own process and passed three
+    arguments:
+
+    proc
+        the ``multiprocessing.Process`` object representing the minion
+    ctl
+        a ``ProcessController`` object tied to the minion
+    kwargs
+        keyword arguments passed from ``PseudoShell.start()``.
+
+    ``minion_function`` is only passed ``kwargs`` delegated from
+    ``PseudoShell.start()``.
+
+    The ``ctl.controller_fd`` will have its ``controller_fd`` connected to
+    ``sys.stdin`` in the minion process. Both processes will share the
+    same ``sys.stdout`` and ``sys.stderr`` as the process instantiating
+    ``PseudoShell``.
+
+    Here are the relationships between processes created::
+
+        ._________________________________________________________.
+        | Minion Process                                          | pid     2
+        | - runs minion_function                                  | pgroup  2
+        |_________________________________________________________| session 1
+            ^
+            | create process with controller_fd connected to stdin
+            | stdout, stderr are the same as caller
+        ._________________________________________________________.
+        | Controller Process                                      | pid     1
+        | - runs controller_function                              | pgroup  1
+        | - uses ProcessController and controller_fd to           | session 1
+        |   control minion                                        |
+        |_________________________________________________________|
+            ^
+            | create process
+            | stdin, stdout, stderr are the same as caller
+        ._________________________________________________________.
+        | Caller                                                  |  pid     0
+        | - Constructs, starts, joins PseudoShell                 |  pgroup  0
+        | - provides controller_function, minion_function         |  session 0
+        |_________________________________________________________|
+
+    """
+    def __init__(self, controller_function, minion_function):
+        self.proc = None
+        self.controller_function = controller_function
+        self.minion_function = minion_function
+
+        # these can be optionally set to change defaults
+        self.controller_timeout = 1
+        self.sleep_time = 0
+
+    def start(self, **kwargs):
+        """Start the controller and minion processes.
+
+        Arguments:
+            kwargs (dict): arbitrary keyword arguments that will be
+                passed to controller and minion functions
+
+        The controller process will create the minion, then call
+        ``controller_function``.  The minion process will call
+        ``minion_function``.
+
+        """
+        self.proc = fork_context.Process(
+            target=PseudoShell._set_up_and_run_controller_function,
+            args=(self.controller_function, self.minion_function,
+                  self.controller_timeout, self.sleep_time),
+            kwargs=kwargs,
+        )
+        self.proc.start()
+
+    def join(self):
+        """Wait for the minion process to finish, and return its exit code."""
+        self.proc.join()
+        return self.proc.exitcode
+
+    @staticmethod
+    def _set_up_and_run_minion_function(
+            tty_name, stdout_fd, stderr_fd, ready, minion_function, **kwargs):
+        """Minion process wrapper for PseudoShell.
+
+        Handles the mechanics of setting up a PTY, then calls
+        ``minion_function``.
+
+        """
+        # new process group, like a command or pipeline launched by a shell
+        os.setpgrp()
+
+        # take controlling terminal and set up pty IO
+        stdin_fd = os.open(tty_name, os.O_RDWR)
+        os.dup2(stdin_fd, sys.stdin.fileno())
+        os.dup2(stdout_fd, sys.stdout.fileno())
+        os.dup2(stderr_fd, sys.stderr.fileno())
+        os.close(stdin_fd)
+
+        if kwargs.get("debug"):
+            sys.stderr.write(
+                "minion: stdin.isatty(): %s\n" % sys.stdin.isatty())
+
+        # tell the parent that we're really running
+        if kwargs.get("debug"):
+            sys.stderr.write("minion: ready!\n")
+        ready.value = True
+
+        try:
+            minion_function(**kwargs)
+        except BaseException:
+            traceback.print_exc()
+
+    @staticmethod
+    def _set_up_and_run_controller_function(
+            controller_function, minion_function, controller_timeout,
+            sleep_time, **kwargs):
+        """Set up a pty, spawn a minion process, execute controller_function.
+
+        Handles the mechanics of setting up a PTY, then calls
+        ``controller_function``.
+
+        """
+        os.setsid()   # new session; this process is the controller
+
+        controller_fd, minion_fd = os.openpty()
+        pty_name = os.ttyname(minion_fd)
+
+        # take controlling terminal
+        pty_fd = os.open(pty_name, os.O_RDWR)
+        os.close(pty_fd)
+
+        ready = multiprocessing.Value('i', False)
+        minion_process = multiprocessing.Process(
+            target=PseudoShell._set_up_and_run_minion_function,
+            args=(pty_name, sys.stdout.fileno(), sys.stderr.fileno(),
+                  ready, minion_function),
+            kwargs=kwargs,
+        )
+        minion_process.start()
+
+        # wait for subprocess to be running and connected.
+        while not ready.value:
+            time.sleep(1e-5)
+            pass
+
+        if kwargs.get("debug"):
+            sys.stderr.write("pid:        %d\n" % os.getpid())
+            sys.stderr.write("pgid:       %d\n" % os.getpgrp())
+            sys.stderr.write("sid:        %d\n" % os.getsid(0))
+            sys.stderr.write("tcgetpgrp:  %d\n" % os.tcgetpgrp(controller_fd))
+            sys.stderr.write("\n")
+
+            minion_pgid = os.getpgid(minion_process.pid)
+            sys.stderr.write("minion pid:  %d\n" % minion_process.pid)
+            sys.stderr.write("minion pgid: %d\n" % minion_pgid)
+            sys.stderr.write(
+                "minion sid:  %d\n" % os.getsid(minion_process.pid))
+            sys.stderr.write("\n")
+            sys.stderr.flush()
+        # set up controller to ignore SIGTSTP, like a shell
+        signal.signal(signal.SIGTSTP, signal.SIG_IGN)
+
+        # call the controller function once the minion is ready
+        try:
+            controller = ProcessController(
+                minion_process.pid, controller_fd, debug=kwargs.get("debug"))
+            controller.timeout = controller_timeout
+            controller.sleep_time = sleep_time
+            error = controller_function(minion_process, controller, **kwargs)
+        except BaseException:
+            error = 1
+            traceback.print_exc()
+
+        minion_process.join()
+
+        # return whether either the parent or minion failed
+        return error or minion_process.exitcode

lib/spack/spack/__init__.py

@@ -5,7 +5,7 @@
 
 
 #: major, minor, patch version for Spack, in a tuple
-spack_version_info = (0, 13, 4)
+spack_version_info = (0, 15, 4)
 
 #: String containing Spack version joined with .'s
 spack_version = '.'.join(str(v) for v in spack_version_info)

lib/spack/spack/abi.py

@@ -18,10 +18,13 @@ class ABI(object):
     """This class provides methods to test ABI compatibility between specs.
        The current implementation is rather rough and could be improved."""
 
-    def architecture_compatible(self, parent, child):
-        """Return true if parent and child have ABI compatible targets."""
-        return not parent.architecture or not child.architecture or \
-            parent.architecture == child.architecture
+    def architecture_compatible(self, target, constraint):
+        """Return true if architecture of target spec is ABI compatible
+           to the architecture of constraint spec. If either the target
+           or constraint specs have no architecture, target is also defined
+           as architecture ABI compatible to constraint."""
+        return not target.architecture or not constraint.architecture or \
+            target.architecture.satisfies(constraint.architecture)
 
     @memoized
     def _gcc_get_libstdcxx_version(self, version):
@@ -107,8 +110,8 @@ def compiler_compatible(self, parent, child, **kwargs):
                     return True
         return False
 
-    def compatible(self, parent, child, **kwargs):
-        """Returns true iff a parent and child spec are ABI compatible"""
+    def compatible(self, target, constraint, **kwargs):
+        """Returns true if target spec is ABI compatible to constraint spec"""
         loosematch = kwargs.get('loose', False)
-        return self.architecture_compatible(parent, child) and \
-            self.compiler_compatible(parent, child, loose=loosematch)
+        return self.architecture_compatible(target, constraint) and \
+            self.compiler_compatible(target, constraint, loose=loosematch)

lib/spack/spack/architecture.py

@@ -6,7 +6,7 @@
 """
 This module contains all the elements that are required to create an
 architecture object. These include, the target processor, the operating system,
-and the architecture platform (i.e. cray, darwin, linux, bgq, etc) classes.
+and the architecture platform (i.e. cray, darwin, linux, etc) classes.
 
 On a multiple architecture machine, the architecture spec field can be set to
 build a package against any target and operating system that is present on the
@@ -209,14 +209,15 @@ def optimization_flags(self, compiler):
         compiler_version = compiler.version
         version_number, suffix = cpu.version_components(compiler.version)
         if not version_number or suffix not in ('', 'apple'):
-            # Try to deduce the correct version. Depending on where this
-            # function is called we might get either a CompilerSpec or a
-            # fully fledged compiler object
+            # Try to deduce the underlying version of the compiler, regardless
+            # of its name in compilers.yaml. Depending on where this function
+            # is called we might get either a CompilerSpec or a fully fledged
+            # compiler object.
             import spack.spec
             if isinstance(compiler, spack.spec.CompilerSpec):
                 compiler = spack.compilers.compilers_for_spec(compiler).pop()
             try:
-                compiler_version = compiler.cc_version(compiler.cc)
+                compiler_version = compiler.real_version
             except spack.util.executable.ProcessError as e:
                 # log this and just return compiler.version instead
                 tty.debug(str(e))
@@ -232,10 +233,14 @@ class Platform(object):
         Will return a instance of it once it is returned.
     """
 
-    priority        = None  # Subclass sets number. Controls detection order
+    priority        = None   # Subclass sets number. Controls detection order
+
+    #: binary formats used on this platform; used by relocation logic
+    binary_formats  = ['elf']
+
     front_end       = None
     back_end        = None
-    default         = None  # The default back end target. On cray ivybridge
+    default         = None   # The default back end target. On cray ivybridge
 
     front_os        = None
     back_os         = None
@@ -435,6 +440,12 @@ def to_dict(self):
             ('target', self.target.to_dict_or_value())])
         return syaml_dict([('arch', d)])
 
+    def to_spec(self):
+        """Convert this Arch to an anonymous Spec with architecture defined."""
+        spec = spack.spec.Spec()
+        spec.architecture = spack.spec.ArchSpec(str(self))
+        return spec
+
     @staticmethod
     def from_dict(d):
         spec = spack.spec.ArchSpec.from_dict(d)
@@ -517,6 +528,14 @@ def platform():
 
 
 @memoized
+def default_arch():
+    """Default ``Arch`` object for this machine.
+
+    See ``sys_type()``.
+    """
+    return Arch(platform(), 'default_os', 'default_target')
+
+
 def sys_type():
     """Print out the "default" platform-os-target tuple for this machine.
 
@@ -529,8 +548,7 @@ def sys_type():
     architectures.
 
     """
-    arch = Arch(platform(), 'default_os', 'default_target')
-    return str(arch)
+    return str(default_arch())
 
 
 @memoized

lib/spack/spack/binary_distribution.py

@@ -10,6 +10,8 @@
 import shutil
 import tempfile
 import hashlib
+import glob
+
 from contextlib import closing
 import ruamel.yaml as yaml
 
@@ -18,10 +20,11 @@
 from six.moves.urllib.error import URLError
 
 import llnl.util.tty as tty
-from llnl.util.filesystem import mkdirp, install_tree
+from llnl.util.filesystem import mkdirp
 
 import spack.cmd
 import spack.config as config
+import spack.database as spack_db
 import spack.fetch_strategy as fs
 import spack.util.gpg
 import spack.relocate as relocate
@@ -29,11 +32,9 @@
 import spack.mirror
 import spack.util.url as url_util
 import spack.util.web as web_util
-
 from spack.spec import Spec
 from spack.stage import Stage
 from spack.util.gpg import Gpg
-import spack.architecture as architecture
 
 _build_cache_relative_path = 'build_cache'
 
@@ -53,7 +54,7 @@
 BUILD_CACHE_INDEX_ENTRY_TEMPLATE = '  <li><a href="{path}">{path}</a></li>'
 
 
-class NoOverwriteException(Exception):
+class NoOverwriteException(spack.error.SpackError):
     """
     Raised when a file exists and must be overwritten.
     """
@@ -68,14 +69,18 @@ class NoGpgException(spack.error.SpackError):
     """
     Raised when gpg2 is not in PATH
     """
-    pass
+
+    def __init__(self, msg):
+        super(NoGpgException, self).__init__(msg)
 
 
 class NoKeyException(spack.error.SpackError):
     """
     Raised when gpg has no default key added.
     """
-    pass
+
+    def __init__(self, msg):
+        super(NoKeyException, self).__init__(msg)
 
 
 class PickKeyException(spack.error.SpackError):
@@ -84,7 +89,7 @@ class PickKeyException(spack.error.SpackError):
     """
 
     def __init__(self, keys):
-        err_msg = "Multi keys available for signing\n%s\n" % keys
+        err_msg = "Multiple keys available for signing\n%s\n" % keys
         err_msg += "Use spack buildcache create -k <key hash> to pick a key."
         super(PickKeyException, self).__init__(err_msg)
 
@@ -107,7 +112,9 @@ class NewLayoutException(spack.error.SpackError):
     """
     Raised if directory layout is different from buildcache.
     """
-    pass
+
+    def __init__(self, msg):
+        super(NewLayoutException, self).__init__(msg)
 
 
 def build_cache_relative_path():
@@ -137,15 +144,21 @@ def read_buildinfo_file(prefix):
     return buildinfo
 
 
-def write_buildinfo_file(prefix, workdir, rel=False):
+def write_buildinfo_file(spec, workdir, rel=False):
     """
     Create a cache file containing information
     required for the relocation
     """
+    prefix = spec.prefix
     text_to_relocate = []
     binary_to_relocate = []
     link_to_relocate = []
     blacklist = (".spack", "man")
+    prefix_to_hash = dict()
+    prefix_to_hash[str(spec.package.prefix)] = spec.dag_hash()
+    deps = spack.build_environment.get_rpath_deps(spec.package)
+    for d in deps:
+        prefix_to_hash[str(d.prefix)] = d.dag_hash()
     # Do this at during tarball creation to save time when tarball unpacked.
     # Used by make_package_relative to determine binaries to change.
     for root, dirs, files in os.walk(prefix, topdown=True):
@@ -162,8 +175,8 @@ def write_buildinfo_file(prefix, workdir, rel=False):
                         link_to_relocate.append(rel_path_name)
                     else:
                         msg = 'Absolute link %s to %s ' % (path_name, link)
-                        msg += 'outside of stage %s ' % prefix
-                        msg += 'cannot be relocated.'
+                        msg += 'outside of prefix %s ' % prefix
+                        msg += 'should not be relocated.'
                         tty.warn(msg)
 
             if relocate.needs_binary_relocation(m_type, m_subtype):
@@ -184,6 +197,7 @@ def write_buildinfo_file(prefix, workdir, rel=False):
     buildinfo['relocate_textfiles'] = text_to_relocate
     buildinfo['relocate_binaries'] = binary_to_relocate
     buildinfo['relocate_links'] = link_to_relocate
+    buildinfo['prefix_to_hash'] = prefix_to_hash
     filename = buildinfo_file_name(workdir)
     with open(filename, 'w') as outfile:
         outfile.write(syaml.dump(buildinfo, default_flow_style=True))
@@ -266,31 +280,47 @@ def sign_tarball(key, force, specfile_path):
 def generate_package_index(cache_prefix):
     """Create the build cache index page.
 
-    Creates (or replaces) the "index.html" page at the location given in
+    Creates (or replaces) the "index.json" page at the location given in
     cache_prefix.  This page contains a link for each binary package (*.yaml)
     and public key (*.key) under cache_prefix.
     """
     tmpdir = tempfile.mkdtemp()
-    try:
-        index_html_path = os.path.join(tmpdir, 'index.html')
-        file_list = (
-            entry
-            for entry in web_util.list_url(cache_prefix)
-            if (entry.endswith('.yaml')
-                or entry.endswith('.key')))
+    db_root_dir = os.path.join(tmpdir, 'db_root')
+    db = spack_db.Database(None, db_dir=db_root_dir,
+                           enable_transaction_locking=False,
+                           record_fields=['spec', 'ref_count'])
 
-        with open(index_html_path, 'w') as f:
-            f.write(BUILD_CACHE_INDEX_TEMPLATE.format(
-                title='Spack Package Index',
-                path_list='\n'.join(
-                    BUILD_CACHE_INDEX_ENTRY_TEMPLATE.format(path=path)
-                    for path in file_list)))
+    file_list = (
+        entry
+        for entry in web_util.list_url(cache_prefix)
+        if entry.endswith('.yaml'))
+
+    tty.debug('Retrieving spec.yaml files from {0} to build index'.format(
+        cache_prefix))
+    for file_path in file_list:
+        try:
+            yaml_url = url_util.join(cache_prefix, file_path)
+            tty.debug('fetching {0}'.format(yaml_url))
+            _, _, yaml_file = web_util.read_from_url(yaml_url)
+            yaml_contents = codecs.getreader('utf-8')(yaml_file).read()
+            # yaml_obj = syaml.load(yaml_contents)
+            # s = Spec.from_yaml(yaml_obj)
+            s = Spec.from_yaml(yaml_contents)
+            db.add(s, None)
+        except (URLError, web_util.SpackWebError) as url_err:
+            tty.error('Error reading spec.yaml: {0}'.format(file_path))
+            tty.error(url_err)
+
+    try:
+        index_json_path = os.path.join(db_root_dir, 'index.json')
+        with open(index_json_path, 'w') as f:
+            db._write_to_file(f)
 
         web_util.push_to_url(
-            index_html_path,
-            url_util.join(cache_prefix, 'index.html'),
+            index_json_path,
+            url_util.join(cache_prefix, 'index.json'),
             keep_original=False,
-            extra_args={'ContentType': 'text/html'})
+            extra_args={'ContentType': 'application/json'})
     finally:
         shutil.rmtree(tmpdir)
 
@@ -342,11 +372,21 @@ def build_tarball(spec, outdir, force=False, rel=False, unsigned=False,
             raise NoOverwriteException(url_util.format(remote_specfile_path))
 
     # make a copy of the install directory to work with
-    workdir = os.path.join(tempfile.mkdtemp(), os.path.basename(spec.prefix))
-    install_tree(spec.prefix, workdir, symlinks=True)
+    workdir = os.path.join(tmpdir, os.path.basename(spec.prefix))
+    # install_tree copies hardlinks
+    # create a temporary tarfile from prefix and exract it to workdir
+    # tarfile preserves hardlinks
+    temp_tarfile_name = tarball_name(spec, '.tar')
+    temp_tarfile_path = os.path.join(tarfile_dir, temp_tarfile_name)
+    with closing(tarfile.open(temp_tarfile_path, 'w')) as tar:
+        tar.add(name='%s' % spec.prefix,
+                arcname='.')
+    with closing(tarfile.open(temp_tarfile_path, 'r')) as tar:
+        tar.extractall(workdir)
+    os.remove(temp_tarfile_path)
 
     # create info for later relocation and create tar
-    write_buildinfo_file(spec.prefix, workdir, rel=rel)
+    write_buildinfo_file(spec, workdir, rel)
 
     # optionally make the paths in the binaries relative to each other
     # in the spack install tree before creating tarball
@@ -360,14 +400,14 @@ def build_tarball(spec, outdir, force=False, rel=False, unsigned=False,
             tty.die(e)
     else:
         try:
-            make_package_placeholder(workdir, spec, allow_root)
+            check_package_relocatable(workdir, spec, allow_root)
         except Exception as e:
             shutil.rmtree(workdir)
             shutil.rmtree(tarfile_dir)
             shutil.rmtree(tmpdir)
             tty.die(e)
 
-    # create compressed tarball of the install prefix
+    # create gzip compressed tarball of the install prefix
     with closing(tarfile.open(tarfile_path, 'w:gz')) as tar:
         tar.add(name='%s' % workdir,
                 arcname='%s' % os.path.basename(spec.prefix))
@@ -390,6 +430,7 @@ def build_tarball(spec, outdir, force=False, rel=False, unsigned=False,
     buildinfo = {}
     buildinfo['relative_prefix'] = os.path.relpath(
         spec.prefix, spack.store.layout.root)
+    buildinfo['relative_rpaths'] = rel
     spec_dict['buildinfo'] = buildinfo
     spec_dict['full_hash'] = spec.full_hash()
 
@@ -407,8 +448,8 @@ def build_tarball(spec, outdir, force=False, rel=False, unsigned=False,
         sign_tarball(key, force, specfile_path)
     # put tarball, spec and signature files in .spack archive
     with closing(tarfile.open(spackfile_path, 'w')) as tar:
-        tar.add(name='%s' % tarfile_path, arcname='%s' % tarfile_name)
-        tar.add(name='%s' % specfile_path, arcname='%s' % specfile_name)
+        tar.add(name=tarfile_path, arcname='%s' % tarfile_name)
+        tar.add(name=specfile_path, arcname='%s' % specfile_name)
         if not unsigned:
             tar.add(name='%s.asc' % specfile_path,
                     arcname='%s.asc' % specfile_name)
@@ -423,6 +464,9 @@ def build_tarball(spec, outdir, force=False, rel=False, unsigned=False,
     web_util.push_to_url(
         specfile_path, remote_specfile_path, keep_original=False)
 
+    tty.debug('Buildcache for "{0}" written to \n {1}'
+              .format(spec, remote_spackfile_path))
+
     try:
         # create an index.html for the build_cache directory so specs can be
         # found
@@ -452,6 +496,7 @@ def download_tarball(spec):
 
         # stage the tarball into standard place
         stage = Stage(url, name="build_cache", keep=True)
+        stage.create()
         try:
             stage.fetch()
             return stage.save_filename
@@ -468,100 +513,156 @@ def make_package_relative(workdir, spec, allow_root):
     """
     prefix = spec.prefix
     buildinfo = read_buildinfo_file(workdir)
-    old_path = buildinfo['buildpath']
+    old_layout_root = buildinfo['buildpath']
     orig_path_names = list()
     cur_path_names = list()
     for filename in buildinfo['relocate_binaries']:
         orig_path_names.append(os.path.join(prefix, filename))
         cur_path_names.append(os.path.join(workdir, filename))
-    if spec.architecture.platform == 'darwin':
-        relocate.make_macho_binaries_relative(cur_path_names, orig_path_names,
-                                              old_path, allow_root)
-    else:
-        relocate.make_elf_binaries_relative(cur_path_names, orig_path_names,
-                                            old_path, allow_root)
+
+    platform = spack.architecture.get_platform(spec.platform)
+    if 'macho' in platform.binary_formats:
+        relocate.make_macho_binaries_relative(
+            cur_path_names, orig_path_names, old_layout_root)
+
+    if 'elf' in platform.binary_formats:
+        relocate.make_elf_binaries_relative(
+            cur_path_names, orig_path_names, old_layout_root)
+
+    relocate.raise_if_not_relocatable(cur_path_names, allow_root)
     orig_path_names = list()
     cur_path_names = list()
-    for filename in buildinfo.get('relocate_links', []):
-        orig_path_names.append(os.path.join(prefix, filename))
-        cur_path_names.append(os.path.join(workdir, filename))
+    for linkname in buildinfo.get('relocate_links', []):
+        orig_path_names.append(os.path.join(prefix, linkname))
+        cur_path_names.append(os.path.join(workdir, linkname))
     relocate.make_link_relative(cur_path_names, orig_path_names)
 
 
-def make_package_placeholder(workdir, spec, allow_root):
+def check_package_relocatable(workdir, spec, allow_root):
     """
     Check if package binaries are relocatable.
     Change links to placeholder links.
     """
-    prefix = spec.prefix
     buildinfo = read_buildinfo_file(workdir)
     cur_path_names = list()
     for filename in buildinfo['relocate_binaries']:
         cur_path_names.append(os.path.join(workdir, filename))
-    relocate.check_files_relocatable(cur_path_names, allow_root)
-
-    cur_path_names = list()
-    for filename in buildinfo.get('relocate_links', []):
-        cur_path_names.append(os.path.join(workdir, filename))
-    relocate.make_link_placeholder(cur_path_names, workdir, prefix)
+    relocate.raise_if_not_relocatable(cur_path_names, allow_root)
 
 
-def relocate_package(workdir, spec, allow_root):
+def relocate_package(spec, allow_root):
     """
     Relocate the given package
     """
+    workdir = str(spec.prefix)
     buildinfo = read_buildinfo_file(workdir)
-    new_path = str(spack.store.layout.root)
-    new_prefix = str(spack.paths.prefix)
-    old_path = str(buildinfo['buildpath'])
-    old_prefix = str(buildinfo.get('spackprefix',
-                                   '/not/in/buildinfo/dictionary'))
-    rel = buildinfo.get('relative_rpaths', False)
+    new_layout_root = str(spack.store.layout.root)
+    new_prefix = str(spec.prefix)
+    new_rel_prefix = str(os.path.relpath(new_prefix, new_layout_root))
+    new_spack_prefix = str(spack.paths.prefix)
+    old_layout_root = str(buildinfo['buildpath'])
+    old_spack_prefix = str(buildinfo.get('spackprefix'))
+    old_rel_prefix = buildinfo.get('relative_prefix')
+    old_prefix = os.path.join(old_layout_root, old_rel_prefix)
+    rel = buildinfo.get('relative_rpaths')
+    prefix_to_hash = buildinfo.get('prefix_to_hash', None)
+    if (old_rel_prefix != new_rel_prefix and not prefix_to_hash):
+        msg = "Package tarball was created from an install "
+        msg += "prefix with a different directory layout and an older "
+        msg += "buildcache create implementation. It cannot be relocated."
+        raise NewLayoutException(msg)
+    # older buildcaches do not have the prefix_to_hash dictionary
+    # need to set an empty dictionary and add one entry to
+    # prefix_to_prefix to reproduce the old behavior
+    if not prefix_to_hash:
+        prefix_to_hash = dict()
+    hash_to_prefix = dict()
+    hash_to_prefix[spec.format('{hash}')] = str(spec.package.prefix)
+    new_deps = spack.build_environment.get_rpath_deps(spec.package)
+    for d in new_deps:
+        hash_to_prefix[d.format('{hash}')] = str(d.prefix)
+    prefix_to_prefix = dict()
+    for orig_prefix, hash in prefix_to_hash.items():
+        prefix_to_prefix[orig_prefix] = hash_to_prefix.get(hash, None)
+    prefix_to_prefix[old_prefix] = new_prefix
+    prefix_to_prefix[old_layout_root] = new_layout_root
 
-    tty.msg("Relocating package from",
-            "%s to %s." % (old_path, new_path))
-    path_names = set()
+    tty.debug("Relocating package from",
+              "%s to %s." % (old_layout_root, new_layout_root))
+
+    def is_backup_file(file):
+        return file.endswith('~')
+
+    # Text files containing the prefix text
+    text_names = list()
     for filename in buildinfo['relocate_textfiles']:
-        path_name = os.path.join(workdir, filename)
+        text_name = os.path.join(workdir, filename)
         # Don't add backup files generated by filter_file during install step.
-        if not path_name.endswith('~'):
-            path_names.add(path_name)
-    relocate.relocate_text(path_names, oldpath=old_path,
-                           newpath=new_path, oldprefix=old_prefix,
-                           newprefix=new_prefix)
-    # If the binary files in the package were not edited to use
-    # relative RPATHs, then the RPATHs need to be relocated
-    if rel:
-        if old_path != new_path:
-            files_to_relocate = list(filter(
-                lambda pathname: not relocate.file_is_relocatable(
-                    pathname, paths_to_relocate=[old_path, old_prefix]),
-                map(lambda filename: os.path.join(workdir, filename),
-                    buildinfo['relocate_binaries'])))
+        if not is_backup_file(text_name):
+            text_names.append(text_name)
 
-            if len(old_path) < len(new_path) and files_to_relocate:
-                tty.debug('Cannot do a binary string replacement with padding '
-                          'for package because %s is longer than %s.' %
-                          (new_path, old_path))
-            else:
-                for path_name in files_to_relocate:
-                    relocate.replace_prefix_bin(path_name, old_path, new_path)
+# If we are not installing back to the same install tree do the relocation
+    if old_layout_root != new_layout_root:
+        files_to_relocate = [os.path.join(workdir, filename)
+                             for filename in buildinfo.get('relocate_binaries')
+                             ]
+        # If the buildcache was not created with relativized rpaths
+        # do the relocation of path in binaries
+        platform = spack.architecture.get_platform(spec.platform)
+        if 'macho' in platform.binary_formats:
+            relocate.relocate_macho_binaries(files_to_relocate,
+                                             old_layout_root,
+                                             new_layout_root,
+                                             prefix_to_prefix, rel,
+                                             old_prefix,
+                                             new_prefix)
+
+        if 'elf' in platform.binary_formats:
+            relocate.relocate_elf_binaries(files_to_relocate,
+                                           old_layout_root,
+                                           new_layout_root,
+                                           prefix_to_prefix, rel,
+                                           old_prefix,
+                                           new_prefix)
+            # Relocate links to the new install prefix
+            links = [link for link in buildinfo.get('relocate_links', [])]
+            relocate.relocate_links(
+                links, old_layout_root, old_prefix, new_prefix
+            )
+
+        # For all buildcaches
+        # relocate the install prefixes in text files including dependencies
+        relocate.relocate_text(text_names,
+                               old_layout_root, new_layout_root,
+                               old_prefix, new_prefix,
+                               old_spack_prefix,
+                               new_spack_prefix,
+                               prefix_to_prefix)
+
+        paths_to_relocate = [old_prefix, old_layout_root]
+        paths_to_relocate.extend(prefix_to_hash.keys())
+        files_to_relocate = list(filter(
+            lambda pathname: not relocate.file_is_relocatable(
+                pathname, paths_to_relocate=paths_to_relocate),
+            map(lambda filename: os.path.join(workdir, filename),
+                buildinfo['relocate_binaries'])))
+        # relocate the install prefixes in binary files including dependencies
+        relocate.relocate_text_bin(files_to_relocate,
+                                   old_prefix, new_prefix,
+                                   old_spack_prefix,
+                                   new_spack_prefix,
+                                   prefix_to_prefix)
+
+# If we are installing back to the same location
+# relocate the sbang location if the spack directory changed
     else:
-        path_names = set()
-        for filename in buildinfo['relocate_binaries']:
-            path_name = os.path.join(workdir, filename)
-            path_names.add(path_name)
-        if spec.architecture.platform == 'darwin':
-            relocate.relocate_macho_binaries(path_names, old_path,
-                                             new_path, allow_root)
-        else:
-            relocate.relocate_elf_binaries(path_names, old_path,
-                                           new_path, allow_root)
-        path_names = set()
-        for filename in buildinfo.get('relocate_links', []):
-            path_name = os.path.join(workdir, filename)
-            path_names.add(path_name)
-        relocate.relocate_links(path_names, old_path, new_path)
+        if old_spack_prefix != new_spack_prefix:
+            relocate.relocate_text(text_names,
+                                   old_layout_root, new_layout_root,
+                                   old_prefix, new_prefix,
+                                   old_spack_prefix,
+                                   new_spack_prefix,
+                                   prefix_to_prefix)
 
 
 def extract_tarball(spec, filename, allow_root=False, unsigned=False,
@@ -586,6 +687,10 @@ def extract_tarball(spec, filename, allow_root=False, unsigned=False,
 
     with closing(tarfile.open(spackfile_path, 'r')) as tar:
         tar.extractall(tmpdir)
+    # some buildcache tarfiles use bzip2 compression
+    if not os.path.exists(tarfile_path):
+        tarfile_name = tarball_name(spec, '.tar.bz2')
+        tarfile_path = os.path.join(tmpdir, tarfile_name)
     if not unsigned:
         if os.path.exists('%s.asc' % specfile_path):
             try:
@@ -593,7 +698,7 @@ def extract_tarball(spec, filename, allow_root=False, unsigned=False,
                 Gpg.verify('%s.asc' % specfile_path, specfile_path, suppress)
             except Exception as e:
                 shutil.rmtree(tmpdir)
-                tty.die(e)
+                raise e
         else:
             shutil.rmtree(tmpdir)
             raise NoVerifyException(
@@ -622,33 +727,51 @@ def extract_tarball(spec, filename, allow_root=False, unsigned=False,
     # if the original relative prefix is in the spec file use it
     buildinfo = spec_dict.get('buildinfo', {})
     old_relative_prefix = buildinfo.get('relative_prefix', new_relative_prefix)
+    rel = buildinfo.get('relative_rpaths')
     # if the original relative prefix and new relative prefix differ the
     # directory layout has changed and the  buildcache cannot be installed
-    if old_relative_prefix != new_relative_prefix:
-        shutil.rmtree(tmpdir)
-        msg = "Package tarball was created from an install "
-        msg += "prefix with a different directory layout.\n"
-        msg += "It cannot be relocated."
-        raise NewLayoutException(msg)
+    # if it was created with relative rpaths
+    info = 'old relative prefix %s\nnew relative prefix %s\nrelative rpaths %s'
+    tty.debug(info %
+              (old_relative_prefix, new_relative_prefix, rel))
+#    if (old_relative_prefix != new_relative_prefix and (rel)):
+#        shutil.rmtree(tmpdir)
+#        msg = "Package tarball was created from an install "
+#        msg += "prefix with a different directory layout. "
+#        msg += "It cannot be relocated because it "
+#        msg += "uses relative rpaths."
+#        raise NewLayoutException(msg)
 
     # extract the tarball in a temp directory
     with closing(tarfile.open(tarfile_path, 'r')) as tar:
         tar.extractall(path=tmpdir)
-    # the base of the install prefix is used when creating the tarball
-    # so the pathname should be the same now that the directory layout
-    # is confirmed
-    workdir = os.path.join(tmpdir, os.path.basename(spec.prefix))
-    install_tree(workdir, spec.prefix, symlinks=True)
+    # get the parent directory of the file .spack/binary_distribution
+    # this should the directory unpacked from the tarball whose
+    # name is unknown because the prefix naming is unknown
+    bindist_file = glob.glob('%s/*/.spack/binary_distribution' % tmpdir)[0]
+    workdir = re.sub('/.spack/binary_distribution$', '', bindist_file)
+    tty.debug('workdir %s' % workdir)
+    # install_tree copies hardlinks
+    # create a temporary tarfile from prefix and exract it to workdir
+    # tarfile preserves hardlinks
+    temp_tarfile_name = tarball_name(spec, '.tar')
+    temp_tarfile_path = os.path.join(tmpdir, temp_tarfile_name)
+    with closing(tarfile.open(temp_tarfile_path, 'w')) as tar:
+        tar.add(name='%s' % workdir,
+                arcname='.')
+    with closing(tarfile.open(temp_tarfile_path, 'r')) as tar:
+        tar.extractall(spec.prefix)
+    os.remove(temp_tarfile_path)
 
     # cleanup
     os.remove(tarfile_path)
     os.remove(specfile_path)
 
     try:
-        relocate_package(spec.prefix, spec, allow_root)
+        relocate_package(spec, allow_root)
     except Exception as e:
         shutil.rmtree(spec.prefix)
-        tty.die(e)
+        raise e
     else:
         manifest_file = os.path.join(spec.prefix,
                                      spack.store.layout.metadata_dir,
@@ -658,6 +781,8 @@ def extract_tarball(spec, filename, allow_root=False, unsigned=False,
             tty.warn('No manifest file in tarball for spec %s' % spec_id)
     finally:
         shutil.rmtree(tmpdir)
+        if os.path.exists(filename):
+            os.remove(filename)
 
 
 # Internal cache for downloaded specs
@@ -705,7 +830,7 @@ def get_spec(spec=None, force=False):
         tty.debug("No Spack mirrors are currently configured")
         return {}
 
-    if spec in _cached_specs:
+    if _cached_specs and spec in _cached_specs:
         return _cached_specs
 
     for mirror in spack.mirror.MirrorCollection().values():
@@ -714,67 +839,69 @@ def get_spec(spec=None, force=False):
 
         mirror_dir = url_util.local_file_path(fetch_url_build_cache)
         if mirror_dir:
-            tty.msg("Finding buildcaches in %s" % mirror_dir)
+            tty.debug('Finding buildcaches in {0}'.format(mirror_dir))
             link = url_util.join(fetch_url_build_cache, specfile_name)
             urls.add(link)
 
         else:
-            tty.msg("Finding buildcaches at %s" %
-                    url_util.format(fetch_url_build_cache))
+            tty.debug('Finding buildcaches at {0}'
+                      .format(url_util.format(fetch_url_build_cache)))
             link = url_util.join(fetch_url_build_cache, specfile_name)
             urls.add(link)
 
     return try_download_specs(urls=urls, force=force)
 
 
-def get_specs(force=False, allarch=False):
+def get_specs():
     """
     Get spec.yaml's for build caches available on mirror
     """
-    arch = architecture.Arch(architecture.platform(),
-                             'default_os', 'default_target')
-    arch_pattern = ('([^-]*-[^-]*-[^-]*)')
-    if not allarch:
-        arch_pattern = '(%s-%s-[^-]*)' % (arch.platform, arch.os)
-
-    regex_pattern = '%s(.*)(spec.yaml$)' % (arch_pattern)
-    arch_re = re.compile(regex_pattern)
+    global _cached_specs
 
     if not spack.mirror.MirrorCollection():
         tty.debug("No Spack mirrors are currently configured")
         return {}
 
-    urls = set()
     for mirror in spack.mirror.MirrorCollection().values():
         fetch_url_build_cache = url_util.join(
             mirror.fetch_url, _build_cache_relative_path)
 
-        mirror_dir = url_util.local_file_path(fetch_url_build_cache)
-        if mirror_dir:
-            tty.msg("Finding buildcaches in %s" % mirror_dir)
-            if os.path.exists(mirror_dir):
-                files = os.listdir(mirror_dir)
-                for file in files:
-                    m = arch_re.search(file)
-                    if m:
-                        link = url_util.join(fetch_url_build_cache, file)
-                        urls.add(link)
-        else:
-            tty.msg("Finding buildcaches at %s" %
-                    url_util.format(fetch_url_build_cache))
-            p, links = web_util.spider(
-                url_util.join(fetch_url_build_cache, 'index.html'))
-            for link in links:
-                m = arch_re.search(link)
-                if m:
-                    urls.add(link)
+        tty.debug('Finding buildcaches at {0}'
+                  .format(url_util.format(fetch_url_build_cache)))
 
-    return try_download_specs(urls=urls, force=force)
+        index_url = url_util.join(fetch_url_build_cache, 'index.json')
+
+        try:
+            _, _, file_stream = web_util.read_from_url(
+                index_url, 'application/json')
+            index_object = codecs.getreader('utf-8')(file_stream).read()
+        except (URLError, web_util.SpackWebError) as url_err:
+            tty.debug('Failed to read index {0}'.format(index_url), url_err, 1)
+            # Continue on to the next mirror
+            continue
+
+        tmpdir = tempfile.mkdtemp()
+        index_file_path = os.path.join(tmpdir, 'index.json')
+        with open(index_file_path, 'w') as fd:
+            fd.write(index_object)
+
+        db_root_dir = os.path.join(tmpdir, 'db_root')
+        db = spack_db.Database(None, db_dir=db_root_dir,
+                               enable_transaction_locking=False)
+
+        db._read_from_file(index_file_path)
+        spec_list = db.query_local(installed=False)
+
+        for indexed_spec in spec_list:
+            _cached_specs.add(indexed_spec)
+
+    return _cached_specs
 
 
 def get_keys(install=False, trust=False, force=False):
     """
     Get pgp public keys available on mirror
+    with suffix .key or .pub
     """
     if not spack.mirror.MirrorCollection():
         tty.die("Please add a spack mirror to allow " +
@@ -788,19 +915,21 @@ def get_keys(install=False, trust=False, force=False):
 
         mirror_dir = url_util.local_file_path(fetch_url_build_cache)
         if mirror_dir:
-            tty.msg("Finding public keys in %s" % mirror_dir)
-            files = os.listdir(mirror_dir)
+            tty.debug('Finding public keys in {0}'.format(mirror_dir))
+            files = os.listdir(str(mirror_dir))
             for file in files:
-                if re.search(r'\.key', file):
+                if re.search(r'\.key', file) or re.search(r'\.pub', file):
                     link = url_util.join(fetch_url_build_cache, file)
                     keys.add(link)
         else:
-            tty.msg("Finding public keys at %s" %
-                    url_util.format(fetch_url_build_cache))
-            p, links = web_util.spider(fetch_url_build_cache, depth=1)
+            tty.debug('Finding public keys at {0}'
+                      .format(url_util.format(fetch_url_build_cache)))
+            # For s3 mirror need to request index.html directly
+            p, links = web_util.spider(
+                url_util.join(fetch_url_build_cache, 'index.html'))
 
             for link in links:
-                if re.search(r'\.key', link):
+                if re.search(r'\.key', link) or re.search(r'\.pub', link):
                     keys.add(link)
 
         for link in keys:
@@ -812,14 +941,14 @@ def get_keys(install=False, trust=False, force=False):
                         stage.fetch()
                     except fs.FetchError:
                         continue
-            tty.msg('Found key %s' % link)
+            tty.debug('Found key {0}'.format(link))
             if install:
                 if trust:
                     Gpg.trust(stage.save_filename)
-                    tty.msg('Added this key to trusted keys.')
+                    tty.debug('Added this key to trusted keys.')
                 else:
-                    tty.msg('Will not add this key to trusted keys.'
-                            'Use -t to install all downloaded keys')
+                    tty.debug('Will not add this key to trusted keys.'
+                              'Use -t to install all downloaded keys')
 
 
 def needs_rebuild(spec, mirror_url, rebuild_on_errors=False):
@@ -906,7 +1035,7 @@ def check_specs_against_mirrors(mirrors, specs, output_file=None,
     """
     rebuilds = {}
     for mirror in spack.mirror.MirrorCollection(mirrors).values():
-        tty.msg('Checking for built specs at %s' % mirror.fetch_url)
+        tty.debug('Checking for built specs at {0}'.format(mirror.fetch_url))
 
         rebuild_list = []
 

lib/spack/spack/build_environment.py

@@ -32,7 +32,7 @@
 Skimming this module is a nice way to get acquainted with the types of
 calls you can make from within the install() function.
 """
-import inspect
+import re
 import multiprocessing
 import os
 import shutil
@@ -44,15 +44,19 @@
 import llnl.util.tty as tty
 from llnl.util.tty.color import cescape, colorize
 from llnl.util.filesystem import mkdirp, install, install_tree
-from llnl.util.lang import dedupe
+from llnl.util.lang import dedupe, fork_context
 
 import spack.build_systems.cmake
 import spack.build_systems.meson
 import spack.config
 import spack.main
 import spack.paths
+import spack.package
 import spack.schema.environment
 import spack.store
+import spack.install_test
+import spack.architecture as arch
+import spack.util.path
 from spack.util.string import plural
 from spack.util.environment import (
     env_flag, filter_system_paths, get_path, is_system_path,
@@ -60,7 +64,7 @@
 from spack.util.environment import system_dirs
 from spack.error import NoLibrariesError, NoHeadersError
 from spack.util.executable import Executable
-from spack.util.module_cmd import load_module, get_path_from_module
+from spack.util.module_cmd import load_module, path_from_modules, module
 from spack.util.log_parse import parse_log_events, make_log_context
 
 
@@ -145,6 +149,40 @@ def clean_environment():
     env.unset('CPATH')
     env.unset('LD_RUN_PATH')
     env.unset('DYLD_LIBRARY_PATH')
+    env.unset('DYLD_FALLBACK_LIBRARY_PATH')
+
+    # On Cray "cluster" systems, unset CRAY_LD_LIBRARY_PATH to avoid
+    # interference with Spack dependencies.
+    # CNL requires these variables to be set (or at least some of them,
+    # depending on the CNL version).
+    hostarch = arch.Arch(arch.platform(), 'default_os', 'default_target')
+    on_cray = str(hostarch.platform) == 'cray'
+    using_cnl = re.match(r'cnl\d+', str(hostarch.os))
+    if on_cray and not using_cnl:
+        env.unset('CRAY_LD_LIBRARY_PATH')
+        for varname in os.environ.keys():
+            if 'PKGCONF' in varname:
+                env.unset(varname)
+
+    # Unset the following variables because they can affect installation of
+    # Autotools and CMake packages.
+    build_system_vars = [
+        'CC', 'CFLAGS', 'CPP', 'CPPFLAGS',  # C variables
+        'CXX', 'CCC', 'CXXFLAGS', 'CXXCPP',  # C++ variables
+        'F77', 'FFLAGS', 'FLIBS',  # Fortran77 variables
+        'FC', 'FCFLAGS', 'FCLIBS',  # Fortran variables
+        'LDFLAGS', 'LIBS'  # linker variables
+    ]
+    for v in build_system_vars:
+        env.unset(v)
+
+    # Unset mpi environment vars. These flags should only be set by
+    # mpi providers for packages with mpi dependencies
+    mpi_vars = [
+        'MPICC', 'MPICXX', 'MPIFC', 'MPIF77', 'MPIF90'
+    ]
+    for v in mpi_vars:
+        env.unset(v)
 
     build_lang = spack.config.get('config:build_language')
     if build_lang:
@@ -170,6 +208,9 @@ def set_compiler_environment_variables(pkg, env):
     compiler = pkg.compiler
     spec = pkg.spec
 
+    # Make sure the executables for this compiler exist
+    compiler.verify_executables()
+
     # Set compiler variables used by CMake and autotools
     assert all(key in compiler.link_paths for key in (
         'cc', 'cxx', 'f77', 'fc'))
@@ -348,10 +389,6 @@ def set_build_environment_variables(pkg, env, dirty):
         extra_rpaths = ':'.join(compiler.extra_rpaths)
         env.set('SPACK_COMPILER_EXTRA_RPATHS', extra_rpaths)
 
-    implicit_rpaths = compiler.implicit_rpaths()
-    if implicit_rpaths:
-        env.set('SPACK_COMPILER_IMPLICIT_RPATHS', ':'.join(implicit_rpaths))
-
     # Add bin directories from dependencies to the PATH for the build.
     for prefix in build_prefixes:
         for dirname in ['bin', 'bin64']:
@@ -414,9 +451,8 @@ def _set_variables_for_single_module(pkg, module):
     if getattr(module, marker, False):
         return
 
-    jobs = spack.config.get('config:build_jobs') if pkg.parallel else 1
+    jobs = spack.config.get('config:build_jobs', 16) if pkg.parallel else 1
     jobs = min(jobs, multiprocessing.cpu_count())
-    assert jobs is not None, "no default set for config:build_jobs"
 
     m = module
     m.make_jobs = jobs
@@ -531,7 +567,7 @@ def _static_to_shared_library(arch, compiler, static_lib, shared_lib=None,
 
     # TODO: Compiler arguments should not be hardcoded but provided by
     #       the different compiler classes.
-    if 'linux' in arch:
+    if 'linux' in arch or 'cray' in arch:
         soname = os.path.basename(shared_lib)
 
         if compat_version:
@@ -607,8 +643,8 @@ def get_rpaths(pkg):
     # Second module is our compiler mod name. We use that to get rpaths from
     # module show output.
     if pkg.compiler.modules and len(pkg.compiler.modules) > 1:
-        rpaths.append(get_path_from_module(pkg.compiler.modules[1]))
-    return rpaths
+        rpaths.append(path_from_modules([pkg.compiler.modules[1]]))
+    return list(dedupe(filter_system_paths(rpaths)))
 
 
 def get_std_cmake_args(pkg):
@@ -671,32 +707,48 @@ def load_external_modules(pkg):
         pkg (PackageBase): package to load deps for
     """
     for dep in list(pkg.spec.traverse()):
-        if dep.external_module:
-            load_module(dep.external_module)
+        external_modules = dep.external_modules or []
+        for external_module in external_modules:
+            load_module(external_module)
 
 
-def setup_package(pkg, dirty):
+def setup_package(pkg, dirty, context='build'):
     """Execute all environment setup routines."""
-    build_env = EnvironmentModifications()
+    env = EnvironmentModifications()
 
+    # clean environment
     if not dirty:
         clean_environment()
 
-    set_compiler_environment_variables(pkg, build_env)
-    set_build_environment_variables(pkg, build_env, dirty)
-    pkg.architecture.platform.setup_platform_environment(pkg, build_env)
+    # setup compilers and build tools for build contexts
+    need_compiler = context == 'build' or (context == 'test' and
+                                           pkg.test_requires_compiler)
+    if need_compiler:
+        set_compiler_environment_variables(pkg, env)
+        set_build_environment_variables(pkg, env, dirty)
 
-    build_env.extend(
-        modifications_from_dependencies(pkg.spec, context='build')
-    )
+    # architecture specific setup
+    pkg.architecture.platform.setup_platform_environment(pkg, env)
 
-    if (not dirty) and (not build_env.is_unset('CPATH')):
-        tty.debug("A dependency has updated CPATH, this may lead pkg-config"
-                  " to assume that the package is part of the system"
-                  " includes and omit it when invoked with '--cflags'.")
+    if context == 'build':
+        # recursive post-order dependency information
+        env.extend(
+            modifications_from_dependencies(pkg.spec, context=context)
+        )
 
-    set_module_variables_for_package(pkg)
-    pkg.setup_build_environment(build_env)
+        if (not dirty) and (not env.is_unset('CPATH')):
+            tty.debug("A dependency has updated CPATH, this may lead pkg-"
+                      "config to assume that the package is part of the system"
+                      " includes and omit it when invoked with '--cflags'.")
+
+        # setup package itself
+        set_module_variables_for_package(pkg)
+        pkg.setup_build_environment(env)
+    elif context == 'test':
+        import spack.user_environment as uenv  # avoid circular import
+        env.extend(uenv.environment_modifications_for_spec(pkg.spec))
+        set_module_variables_for_package(pkg)
+        env.prepend_path('PATH', '.')
 
     # Loading modules, in particular if they are meant to be used outside
     # of Spack, can change environment variables that are relevant to the
@@ -706,24 +758,35 @@ def setup_package(pkg, dirty):
     # unnecessary. Modules affecting these variables will be overwritten anyway
     with preserve_environment('CC', 'CXX', 'FC', 'F77'):
         # All module loads that otherwise would belong in previous
-        # functions have to occur after the build_env object has its
+        # functions have to occur after the env object has its
         # modifications applied. Otherwise the environment modifications
         # could undo module changes, such as unsetting LD_LIBRARY_PATH
         # after a module changes it.
-        for mod in pkg.compiler.modules:
-            # Fixes issue https://github.com/spack/spack/issues/3153
-            if os.environ.get("CRAY_CPU_TARGET") == "mic-knl":
-                load_module("cce")
-            load_module(mod)
+        if need_compiler:
+            for mod in pkg.compiler.modules:
+                # Fixes issue https://github.com/spack/spack/issues/3153
+                if os.environ.get("CRAY_CPU_TARGET") == "mic-knl":
+                    load_module("cce")
+                load_module(mod)
+
+        # kludge to handle cray libsci being automatically loaded by PrgEnv
+        # modules on cray platform. Module unload does no damage when
+        # unnecessary
+        module('unload', 'cray-libsci')
 
         if pkg.architecture.target.module_name:
             load_module(pkg.architecture.target.module_name)
 
         load_external_modules(pkg)
 
+    implicit_rpaths = pkg.compiler.implicit_rpaths()
+    if implicit_rpaths:
+        env.set('SPACK_COMPILER_IMPLICIT_RPATHS',
+                ':'.join(implicit_rpaths))
+
     # Make sure nothing's strange about the Spack environment.
-    validate(build_env, tty.warn)
-    build_env.apply_modifications()
+    validate(env, tty.warn)
+    env.apply_modifications()
 
 
 def modifications_from_dependencies(spec, context):
@@ -743,7 +806,8 @@ def modifications_from_dependencies(spec, context):
     deptype_and_method = {
         'build': (('build', 'link', 'test'),
                   'setup_dependent_build_environment'),
-        'run': (('link', 'run'), 'setup_dependent_run_environment')
+        'run': (('link', 'run'), 'setup_dependent_run_environment'),
+        'test': (('link', 'run', 'test'), 'setup_dependent_run_environment')
     }
     deptype, method = deptype_and_method[context]
 
@@ -757,7 +821,7 @@ def modifications_from_dependencies(spec, context):
     return env
 
 
-def fork(pkg, function, dirty, fake):
+def fork(pkg, function, dirty, fake, context='build', **kwargs):
     """Fork a child process to do part of a spack build.
 
     Args:
@@ -769,6 +833,8 @@ def fork(pkg, function, dirty, fake):
         dirty (bool): If True, do NOT clean the environment before
             building.
         fake (bool): If True, skip package setup b/c it's not a real build
+        context (string): If 'build', setup build environment. If 'test', setup
+            test environment.
 
     Usage::
 
@@ -797,15 +863,14 @@ def child_process(child_pipe, input_stream):
 
         try:
             if not fake:
-                setup_package(pkg, dirty=dirty)
+                setup_package(pkg, dirty=dirty, context=context)
             return_value = function()
             child_pipe.send(return_value)
-        except StopIteration as e:
-            # StopIteration is used to stop installations
-            # before the final stage, mainly for debug purposes
-            tty.msg(e)
-            child_pipe.send(None)
 
+        except StopPhase as e:
+            # Do not create a full ChildError from this, it's not an error
+            # it's a control statement.
+            child_pipe.send(e)
         except BaseException:
             # catch ANYTHING that goes wrong in the child process
             exc_type, exc, tb = sys.exc_info()
@@ -816,19 +881,29 @@ def child_process(child_pipe, input_stream):
 
             # build up some context from the offending package so we can
             # show that, too.
-            package_context = get_package_context(tb)
+            if exc_type is not spack.install_test.TestFailure:
+                package_context = get_package_context(traceback.extract_tb(tb))
+            else:
+                package_context = []
 
             build_log = None
-            if hasattr(pkg, 'log_path'):
+            if context == 'build' and hasattr(pkg, 'log_path'):
                 build_log = pkg.log_path
 
+            test_log = None
+            if context == 'test':
+                test_log = os.path.join(
+                    pkg.test_suite.stage,
+                    spack.install_test.TestSuite.test_log_name(pkg.spec))
+
             # make a pickleable exception to send to parent.
             msg = "%s: %s" % (exc_type.__name__, str(exc))
 
             ce = ChildError(msg,
                             exc_type.__module__,
                             exc_type.__name__,
-                            tb_string, build_log, package_context)
+                            tb_string, package_context,
+                            build_log, test_log)
             child_pipe.send(ce)
 
         finally:
@@ -841,7 +916,7 @@ def child_process(child_pipe, input_stream):
         if sys.stdin.isatty() and hasattr(sys.stdin, 'fileno'):
             input_stream = os.fdopen(os.dup(sys.stdin.fileno()))
 
-        p = multiprocessing.Process(
+        p = fork_context.Process(
             target=child_process, args=(child_pipe, input_stream))
         p.start()
 
@@ -857,15 +932,20 @@ def child_process(child_pipe, input_stream):
     child_result = parent_pipe.recv()
     p.join()
 
+    # If returns a StopPhase, raise it
+    if isinstance(child_result, StopPhase):
+        # do not print
+        raise child_result
+
     # let the caller know which package went wrong.
     if isinstance(child_result, InstallError):
         child_result.pkg = pkg
 
-    # If the child process raised an error, print its output here rather
-    # than waiting until the call to SpackError.die() in main(). This
-    # allows exception handling output to be logged from within Spack.
-    # see spack.main.SpackCommand.
     if isinstance(child_result, ChildError):
+        # If the child process raised an error, print its output here rather
+        # than waiting until the call to SpackError.die() in main(). This
+        # allows exception handling output to be logged from within Spack.
+        # see spack.main.SpackCommand.
         child_result.print_context()
         raise child_result
 
@@ -876,8 +956,8 @@ def get_package_context(traceback, context=3):
     """Return some context for an error message when the build fails.
 
     Args:
-        traceback (traceback): A traceback from some exception raised during
-            install
+        traceback (list of tuples): output from traceback.extract_tb() or
+            traceback.extract_stack()
         context (int): Lines of context to show before and after the line
             where the error happened
 
@@ -886,51 +966,44 @@ def get_package_context(traceback, context=3):
     from there.
 
     """
-    def make_stack(tb, stack=None):
-        """Tracebacks come out of the system in caller -> callee order.  Return
-        an array in callee -> caller order so we can traverse it."""
-        if stack is None:
-            stack = []
-        if tb is not None:
-            make_stack(tb.tb_next, stack)
-            stack.append(tb)
-        return stack
-
-    stack = make_stack(traceback)
-
-    for tb in stack:
-        frame = tb.tb_frame
-        if 'self' in frame.f_locals:
-            # Find the first proper subclass of PackageBase.
-            obj = frame.f_locals['self']
-            if isinstance(obj, spack.package.PackageBase):
+    for filename, lineno, function, text in reversed(traceback):
+        if 'package.py' in filename or 'spack/build_systems' in filename:
+            if function not in ('run_test', '_run_test_helper'):
+                # We are in a package and not one of the listed methods
+                # We exclude these methods because we expect errors in them to
+                # be the result of user tests failing, and we show the tests
+                # instead.
                 break
 
+    # Package files have a line added at import time, so we adjust the lineno
+    # when we are getting context from a package file instead of a base class
+    adjust = 1 if spack.paths.is_package_file(filename) else 0
+    lineno = lineno - adjust
+
     # We found obj, the Package implementation we care about.
     # Point out the location in the install method where we failed.
     lines = [
         '{0}:{1:d}, in {2}:'.format(
-            inspect.getfile(frame.f_code),
-            frame.f_lineno - 1,  # subtract 1 because f_lineno is 0-indexed
-            frame.f_code.co_name
+            filename,
+            lineno,
+            function
         )
     ]
 
     # Build a message showing context in the install method.
-    sourcelines, start = inspect.getsourcelines(frame)
-
-    # Calculate lineno of the error relative to the start of the function.
-    # Subtract 1 because f_lineno is 0-indexed.
-    fun_lineno = frame.f_lineno - start - 1
-    start_ctx = max(0, fun_lineno - context)
-    sourcelines = sourcelines[start_ctx:fun_lineno + context + 1]
+    # Adjust for import mangling of package files.
+    with open(filename, 'r') as f:
+        sourcelines = f.readlines()
+    start = max(0, lineno - context - 1)
+    sourcelines = sourcelines[start:lineno + context + 1]
 
     for i, line in enumerate(sourcelines):
-        is_error = start_ctx + i == fun_lineno
+        i = i + adjust  # adjusting for import munging again
+        is_error = start + i == lineno
         mark = '>> ' if is_error else '   '
         # Add start to get lineno relative to start of file, not function.
         marked = '  {0}{1:-6d}{2}'.format(
-            mark, start + start_ctx + i, line.rstrip())
+            mark, start + i, line.rstrip())
         if is_error:
             marked = colorize('@R{%s}' % cescape(marked))
         lines.append(marked)
@@ -984,14 +1057,15 @@ class ChildError(InstallError):
     # context instead of Python context.
     build_errors = [('spack.util.executable', 'ProcessError')]
 
-    def __init__(self, msg, module, classname, traceback_string, build_log,
-                 context):
+    def __init__(self, msg, module, classname, traceback_string, context,
+                 build_log, test_log):
         super(ChildError, self).__init__(msg)
         self.module = module
         self.name = classname
         self.traceback = traceback_string
-        self.build_log = build_log
         self.context = context
+        self.build_log = build_log
+        self.test_log = test_log
 
     @property
     def long_message(self):
@@ -1000,21 +1074,12 @@ def long_message(self):
 
         if (self.module, self.name) in ChildError.build_errors:
             # The error happened in some external executed process. Show
-            # the build log with errors or warnings highlighted.
+            # the log with errors or warnings highlighted.
             if self.build_log and os.path.exists(self.build_log):
-                errors, warnings = parse_log_events(self.build_log)
-                nerr = len(errors)
-                nwar = len(warnings)
-                if nerr > 0:
-                    # If errors are found, only display errors
-                    out.write(
-                        "\n%s found in build log:\n" % plural(nerr, 'error'))
-                    out.write(make_log_context(errors))
-                elif nwar > 0:
-                    # If no errors are found but warnings are, display warnings
-                    out.write(
-                        "\n%s found in build log:\n" % plural(nwar, 'warning'))
-                    out.write(make_log_context(warnings))
+                write_log_summary(out, 'build', self.build_log)
+
+            if self.test_log and os.path.exists(self.test_log):
+                write_log_summary(out, 'test', self.test_log)
 
         else:
             # The error happened in in the Python code, so try to show
@@ -1031,6 +1096,10 @@ def long_message(self):
             out.write('See build log for details:\n')
             out.write('  %s\n' % self.build_log)
 
+        if self.test_log and os.path.exists(self.test_log):
+            out.write('See test log for details:\n')
+            out.write('  %s\n' % self.test_log)
+
         return out.getvalue()
 
     def __str__(self):
@@ -1047,10 +1116,50 @@ def __reduce__(self):
             self.module,
             self.name,
             self.traceback,
+            self.context,
             self.build_log,
-            self.context)
+            self.test_log)
 
 
-def _make_child_error(msg, module, name, traceback, build_log, context):
+def _make_child_error(msg, module, name, traceback, context,
+                      build_log, test_log):
     """Used by __reduce__ in ChildError to reconstruct pickled errors."""
-    return ChildError(msg, module, name, traceback, build_log, context)
+    return ChildError(msg, module, name, traceback, context,
+                      build_log, test_log)
+
+
+class StopPhase(spack.error.SpackError):
+    """Pickle-able exception to control stopped builds."""
+    def __reduce__(self):
+        return _make_stop_phase, (self.message, self.long_message)
+
+
+def _make_stop_phase(msg, long_msg):
+    return StopPhase(msg, long_msg)
+
+
+def write_log_summary(out, log_type, log, last=None):
+    errors, warnings = parse_log_events(log)
+    nerr = len(errors)
+    nwar = len(warnings)
+
+    if nerr > 0:
+        if last and nerr > last:
+            errors = errors[-last:]
+            nerr = last
+
+        # If errors are found, only display errors
+        out.write(
+            "\n%s found in %s log:\n" %
+            (plural(nerr, 'error'), log_type))
+        out.write(make_log_context(errors))
+    elif nwar > 0:
+        if last and nwar > last:
+            warnings = warnings[-last:]
+            nwar = last
+
+        # If no errors are found but warnings are, display warnings
+        out.write(
+            "\n%s found in %s log:\n" %
+            (plural(nwar, 'warning'), log_type))
+        out.write(make_log_context(warnings))

lib/spack/spack/build_systems/autotools.py

@@ -11,6 +11,7 @@
 import shutil
 import stat
 import sys
+import re
 from subprocess import PIPE
 from subprocess import check_call
 
@@ -56,8 +57,9 @@ class AutotoolsPackage(PackageBase):
     #: This attribute is used in UI queries that need to know the build
     #: system base class
     build_system_class = 'AutotoolsPackage'
-    #: Whether or not to update ``config.guess`` on old architectures
-    patch_config_guess = True
+    #: Whether or not to update ``config.guess`` and ``config.sub`` on old
+    #: architectures
+    patch_config_files = True
     #: Whether or not to update ``libtool``
     #: (currently only for Arm/Clang/Fujitsu compilers)
     patch_libtool = True
@@ -86,72 +88,107 @@ def archive_files(self):
         return [os.path.join(self.build_directory, 'config.log')]
 
     @run_after('autoreconf')
-    def _do_patch_config_guess(self):
-        """Some packages ship with an older config.guess and need to have
-        this updated when installed on a newer architecture. In particular,
-        config.guess fails for PPC64LE for version prior to a 2013-06-10
-        build date (automake 1.13.4) and for ARM (aarch64)."""
+    def _do_patch_config_files(self):
+        """Some packages ship with older config.guess/config.sub files and
+        need to have these updated when installed on a newer architecture.
+        In particular, config.guess fails for PPC64LE for version prior
+        to a 2013-06-10 build date (automake 1.13.4) and for ARM (aarch64)."""
 
-        if not self.patch_config_guess or (
+        if not self.patch_config_files or (
                 not self.spec.satisfies('target=ppc64le:') and
                 not self.spec.satisfies('target=aarch64:')
         ):
             return
-        my_config_guess = None
-        config_guess = None
-        if os.path.exists('config.guess'):
-            # First search the top-level source directory
-            my_config_guess = 'config.guess'
+
+        # TODO: Expand this to select the 'config.sub'-compatible architecture
+        # for each platform (e.g. 'config.sub' doesn't accept 'power9le', but
+        # does accept 'ppc64le').
+        if self.spec.satisfies('target=ppc64le:'):
+            config_arch = 'ppc64le'
+        elif self.spec.satisfies('target=aarch64:'):
+            config_arch = 'aarch64'
         else:
-            # Then search in all sub directories.
-            # We would like to use AC_CONFIG_AUX_DIR, but not all packages
-            # ship with their configure.in or configure.ac.
-            d = '.'
-            dirs = [os.path.join(d, o) for o in os.listdir(d)
-                    if os.path.isdir(os.path.join(d, o))]
-            for dirname in dirs:
-                path = os.path.join(dirname, 'config.guess')
+            config_arch = 'local'
+
+        my_config_files = {'guess': None, 'sub': None}
+        config_files = {'guess': None, 'sub': None}
+        config_args = {'guess': [], 'sub': [config_arch]}
+
+        for config_name in config_files.keys():
+            config_file = 'config.{0}'.format(config_name)
+            if os.path.exists(config_file):
+                # First search the top-level source directory
+                my_config_files[config_name] = os.path.abspath(config_file)
+            else:
+                # Then search in all sub directories recursively.
+                # We would like to use AC_CONFIG_AUX_DIR, but not all packages
+                # ship with their configure.in or configure.ac.
+                config_path = next((os.path.abspath(os.path.join(r, f))
+                                    for r, ds, fs in os.walk('.') for f in fs
+                                    if f == config_file), None)
+                my_config_files[config_name] = config_path
+
+            if my_config_files[config_name] is not None:
+                try:
+                    config_path = my_config_files[config_name]
+                    check_call([config_path] + config_args[config_name],
+                               stdout=PIPE, stderr=PIPE)
+                    # The package's config file already runs OK, so just use it
+                    continue
+                except Exception as e:
+                    tty.debug(e)
+            else:
+                continue
+
+            # Look for a spack-installed automake package
+            if 'automake' in self.spec:
+                automake_dir = 'automake-' + str(self.spec['automake'].version)
+                automake_path = os.path.join(self.spec['automake'].prefix,
+                                             'share', automake_dir)
+                path = os.path.join(automake_path, config_file)
                 if os.path.exists(path):
-                    my_config_guess = path
+                    config_files[config_name] = path
+            # Look for the system's config.guess
+            if (config_files[config_name] is None and
+                    os.path.exists('/usr/share')):
+                automake_dir = [s for s in os.listdir('/usr/share') if
+                                "automake" in s]
+                if automake_dir:
+                    automake_path = os.path.join('/usr/share', automake_dir[0])
+                    path = os.path.join(automake_path, config_file)
+                    if os.path.exists(path):
+                        config_files[config_name] = path
+            if config_files[config_name] is not None:
+                try:
+                    config_path = config_files[config_name]
+                    my_config_path = my_config_files[config_name]
 
-        if my_config_guess is not None:
-            try:
-                check_call([my_config_guess], stdout=PIPE, stderr=PIPE)
-                # The package's config.guess already runs OK, so just use it
-                return
-            except Exception as e:
-                tty.debug(e)
-        else:
-            return
+                    check_call([config_path] + config_args[config_name],
+                               stdout=PIPE, stderr=PIPE)
 
-        # Look for a spack-installed automake package
-        if 'automake' in self.spec:
-            automake_path = os.path.join(self.spec['automake'].prefix, 'share',
-                                         'automake-' +
-                                         str(self.spec['automake'].version))
-            path = os.path.join(automake_path, 'config.guess')
-            if os.path.exists(path):
-                config_guess = path
-        # Look for the system's config.guess
-        if config_guess is None and os.path.exists('/usr/share'):
-            automake_dir = [s for s in os.listdir('/usr/share') if
-                            "automake" in s]
-            if automake_dir:
-                automake_path = os.path.join('/usr/share', automake_dir[0])
-                path = os.path.join(automake_path, 'config.guess')
-                if os.path.exists(path):
-                    config_guess = path
-        if config_guess is not None:
-            try:
-                check_call([config_guess], stdout=PIPE, stderr=PIPE)
-                mod = os.stat(my_config_guess).st_mode & 0o777 | stat.S_IWUSR
-                os.chmod(my_config_guess, mod)
-                shutil.copyfile(config_guess, my_config_guess)
-                return
-            except Exception as e:
-                tty.debug(e)
+                    m = os.stat(my_config_path).st_mode & 0o777 | stat.S_IWUSR
+                    os.chmod(my_config_path, m)
+                    shutil.copyfile(config_path, my_config_path)
+                    continue
+                except Exception as e:
+                    tty.debug(e)
 
-        raise RuntimeError('Failed to find suitable config.guess')
+            raise RuntimeError('Failed to find suitable ' + config_file)
+
+    @run_before('configure')
+    def _set_autotools_environment_variables(self):
+        """Many autotools builds use a version of mknod.m4 that fails when
+        running as root unless FORCE_UNSAFE_CONFIGURE is set to 1.
+
+        We set this to 1 and expect the user to take responsibility if
+        they are running as root. They have to anyway, as this variable
+        doesn't actually prevent configure from doing bad things as root.
+        Without it, configure just fails halfway through, but it can
+        still run things *before* this check. Forcing this just removes a
+        nuisance -- this is not circumventing any real protection.
+
+        """
+        os.environ["FORCE_UNSAFE_CONFIGURE"] = "1"
 
     @run_after('configure')
     def _do_patch_libtool(self):
@@ -169,7 +206,9 @@ def _do_patch_libtool(self):
                         line = 'wl="-Wl,"\n'
                     if line == 'pic_flag=""\n':
                         line = 'pic_flag="{0}"\n'\
-                               .format(self.compiler.pic_flag)
+                               .format(self.compiler.cc_pic_flag)
+                    if self.spec.satisfies('%fj') and 'fjhpctag.o' in line:
+                        line = re.sub(r'/\S*/fjhpctag.o', '', line)
                     sys.stdout.write(line)
 
     @property
@@ -219,11 +258,11 @@ def autoreconf(self, spec, prefix):
             # This line is what is needed most of the time
             # --install, --verbose, --force
             autoreconf_args = ['-ivf']
-            if 'pkgconfig' in spec:
-                autoreconf_args += [
-                    '-I',
-                    os.path.join(spec['pkgconfig'].prefix, 'share', 'aclocal'),
-                ]
+            for dep in spec.dependencies(deptype='build'):
+                if os.path.exists(dep.prefix.share.aclocal):
+                    autoreconf_args.extend([
+                        '-I', dep.prefix.share.aclocal
+                    ])
             autoreconf_args += self.autoreconf_extra_args
             m.autoreconf(*autoreconf_args)
 
@@ -263,6 +302,12 @@ def flags_to_build_system_args(self, flags):
             if values:
                 values_str = '{0}={1}'.format(flag.upper(), ' '.join(values))
                 self.configure_flag_args.append(values_str)
+        # Spack's fflags are meant for both F77 and FC, therefore we
+        # additionaly set FCFLAGS if required.
+        values = flags.get('fflags', None)
+        if values:
+            values_str = 'FCFLAGS={0}'.format(' '.join(values))
+            self.configure_flag_args.append(values_str)
 
     def configure(self, spec, prefix):
         """Runs configure with the arguments specified in

lib/spack/spack/build_systems/cmake.py

@@ -147,33 +147,129 @@ def _std_args(pkg):
         except KeyError:
             build_type = 'RelWithDebInfo'
 
+        define = CMakePackage.define
         args = [
             '-G', generator,
-            '-DCMAKE_INSTALL_PREFIX:PATH={0}'.format(pkg.prefix),
-            '-DCMAKE_BUILD_TYPE:STRING={0}'.format(build_type),
+            define('CMAKE_INSTALL_PREFIX', pkg.prefix),
+            define('CMAKE_BUILD_TYPE', build_type),
         ]
 
         if primary_generator == 'Unix Makefiles':
-            args.append('-DCMAKE_VERBOSE_MAKEFILE:BOOL=ON')
+            args.append(define('CMAKE_VERBOSE_MAKEFILE', True))
 
         if platform.mac_ver()[0]:
             args.extend([
-                '-DCMAKE_FIND_FRAMEWORK:STRING=LAST',
-                '-DCMAKE_FIND_APPBUNDLE:STRING=LAST'
+                define('CMAKE_FIND_FRAMEWORK', "LAST"),
+                define('CMAKE_FIND_APPBUNDLE', "LAST"),
             ])
 
         # Set up CMake rpath
-        args.append('-DCMAKE_INSTALL_RPATH_USE_LINK_PATH:BOOL=FALSE')
-        rpaths = ';'.join(spack.build_environment.get_rpaths(pkg))
-        args.append('-DCMAKE_INSTALL_RPATH:STRING={0}'.format(rpaths))
+        args.extend([
+            define('CMAKE_INSTALL_RPATH_USE_LINK_PATH', False),
+            define('CMAKE_INSTALL_RPATH',
+                   spack.build_environment.get_rpaths(pkg)),
+        ])
         # CMake's find_package() looks in CMAKE_PREFIX_PATH first, help CMake
         # to find immediate link dependencies in right places:
         deps = [d.prefix for d in
                 pkg.spec.dependencies(deptype=('build', 'link'))]
         deps = filter_system_paths(deps)
-        args.append('-DCMAKE_PREFIX_PATH:STRING={0}'.format(';'.join(deps)))
+        args.append(define('CMAKE_PREFIX_PATH', deps))
         return args
 
+    @staticmethod
+    def define(cmake_var, value):
+        """Return a CMake command line argument that defines a variable.
+
+        The resulting argument will convert boolean values to OFF/ON
+        and lists/tuples to CMake semicolon-separated string lists. All other
+        values will be interpreted as strings.
+
+        Examples:
+
+            .. code-block:: python
+
+                [define('BUILD_SHARED_LIBS', True),
+                 define('CMAKE_CXX_STANDARD', 14),
+                 define('swr', ['avx', 'avx2'])]
+
+            will generate the following configuration options:
+
+            .. code-block:: console
+
+                ["-DBUILD_SHARED_LIBS:BOOL=ON",
+                 "-DCMAKE_CXX_STANDARD:STRING=14",
+                 "-DSWR:STRING=avx;avx2]
+
+        """
+        # Create a list of pairs. Each pair includes a configuration
+        # option and whether or not that option is activated
+        if isinstance(value, bool):
+            kind = 'BOOL'
+            value = "ON" if value else "OFF"
+        else:
+            kind = 'STRING'
+            if isinstance(value, (list, tuple)):
+                value = ";".join(str(v) for v in value)
+            else:
+                value = str(value)
+
+        return "".join(["-D", cmake_var, ":", kind, "=", value])
+
+    def define_from_variant(self, cmake_var, variant=None):
+        """Return a CMake command line argument from the given variant's value.
+
+        The optional ``variant`` argument defaults to the lower-case transform
+        of ``cmake_var``.
+
+        This utility function is similar to
+        :py:meth:`~.AutotoolsPackage.with_or_without`.
+
+        Examples:
+
+            Given a package with:
+
+            .. code-block:: python
+
+                variant('cxxstd', default='11', values=('11', '14'),
+                        multi=False, description='')
+                variant('shared', default=True, description='')
+                variant('swr', values=any_combination_of('avx', 'avx2'),
+                        description='')
+
+            calling this function like:
+
+            .. code-block:: python
+
+                [define_from_variant('BUILD_SHARED_LIBS', 'shared'),
+                 define_from_variant('CMAKE_CXX_STANDARD', 'cxxstd'),
+                 define_from_variant('SWR')]
+
+            will generate the following configuration options:
+
+            .. code-block:: console
+
+                ["-DBUILD_SHARED_LIBS:BOOL=ON",
+                 "-DCMAKE_CXX_STANDARD:STRING=14",
+                 "-DSWR:STRING=avx;avx2]
+
+            for ``<spec-name> cxxstd=14 +shared swr=avx,avx2``
+        """
+
+        if variant is None:
+            variant = cmake_var.lower()
+
+        if variant not in self.variants:
+            raise KeyError(
+                '"{0}" is not a variant of "{1}"'.format(variant, self.name))
+
+        value = self.spec.variants[variant].value
+        if isinstance(value, (tuple, list)):
+            # Sort multi-valued variants for reproducibility
+            value = sorted(value)
+
+        return self.define(cmake_var, value)
+
     def flags_to_build_system_args(self, flags):
         """Produces a list of all command line arguments to pass the specified
         compiler flags to cmake. Note CMAKE does not have a cppflags option,
@@ -212,13 +308,21 @@ def flags_to_build_system_args(self, flags):
                 self.cmake_flag_args.append(libs_string.format(lang,
                                                                libs_flags))
 
+    @property
+    def build_dirname(self):
+        """Returns the directory name to use when building the package
+
+        :return: name of the subdirectory for building the package
+        """
+        return 'spack-build-%s' % self.spec.dag_hash(7)
+
     @property
     def build_directory(self):
         """Returns the directory to use when building the package
 
         :return: directory where to build the package
         """
-        return os.path.join(self.stage.path, 'spack-build')
+        return os.path.join(self.stage.path, self.build_dirname)
 
     def cmake_args(self):
         """Produces a list containing all the arguments that must be passed to
@@ -235,9 +339,9 @@ def cmake_args(self):
 
     def cmake(self, spec, prefix):
         """Runs ``cmake`` in the build directory"""
-        options = [os.path.abspath(self.root_cmakelists_dir)]
-        options += self.std_cmake_args
+        options = self.std_cmake_args
         options += self.cmake_args()
+        options.append(os.path.abspath(self.root_cmakelists_dir))
         with working_dir(self.build_directory, create=True):
             inspect.getmodule(self).cmake(*options)
 

lib/spack/spack/build_systems/cuda.py

@@ -12,40 +12,71 @@
 class CudaPackage(PackageBase):
     """Auxiliary class which contains CUDA variant, dependencies and conflicts
     and is meant to unify and facilitate its usage.
+
+    Maintainers: ax3l, svenevs
     """
 
-    # FIXME: keep cuda and cuda_arch separate to make usage easier untill
+    # https://docs.nvidia.com/cuda/cuda-compiler-driver-nvcc/index.html#gpu-feature-list
+    # https://developer.nvidia.com/cuda-gpus
+    # https://en.wikipedia.org/wiki/CUDA#GPUs_supported
+    cuda_arch_values = [
+        '10', '11', '12', '13',
+        '20', '21',
+        '30', '32', '35', '37',
+        '50', '52', '53',
+        '60', '61', '62',
+        '70', '72', '75',
+        '80',
+    ]
+
+    # FIXME: keep cuda and cuda_arch separate to make usage easier until
     # Spack has depends_on(cuda, when='cuda_arch!=None') or alike
     variant('cuda', default=False,
             description='Build with CUDA')
-    # see http://docs.nvidia.com/cuda/cuda-compiler-driver-nvcc/index.html#gpu-feature-list
-    # https://developer.nvidia.com/cuda-gpus
+
     variant('cuda_arch',
             description='CUDA architecture',
-            values=spack.variant.any_combination_of(
-                '20', '30', '32', '35', '50', '52', '53', '60', '61',
-                '62', '70', '72', '75'
-            ))
+            values=spack.variant.any_combination_of(*cuda_arch_values))
 
-    # see http://docs.nvidia.com/cuda/cuda-compiler-driver-nvcc/index.html#nvcc-examples
-    # and http://llvm.org/docs/CompileCudaWithLLVM.html#compiling-cuda-code
+    # https://docs.nvidia.com/cuda/cuda-compiler-driver-nvcc/index.html#nvcc-examples
+    # https://llvm.org/docs/CompileCudaWithLLVM.html#compiling-cuda-code
     @staticmethod
     def cuda_flags(arch_list):
         return [('--generate-code arch=compute_{0},code=sm_{0} '
                  '--generate-code arch=compute_{0},code=compute_{0}').format(s)
                 for s in arch_list]
 
-    depends_on("cuda@7:", when='+cuda')
+    depends_on('cuda', when='+cuda')
 
     # CUDA version vs Architecture
-    depends_on("cuda@8:", when='cuda_arch=60')
-    depends_on("cuda@8:", when='cuda_arch=61')
-    depends_on("cuda@8:", when='cuda_arch=62')
-    depends_on("cuda@9:", when='cuda_arch=70')
-    depends_on("cuda@9:", when='cuda_arch=72')
-    depends_on("cuda@10:", when='cuda_arch=75')
+    # https://en.wikipedia.org/wiki/CUDA#GPUs_supported
+    # https://docs.nvidia.com/cuda/cuda-toolkit-release-notes/index.html#deprecated-features
+    depends_on('cuda@:6.0',     when='cuda_arch=10')
+    depends_on('cuda@:6.5',     when='cuda_arch=11')
+    depends_on('cuda@2.1:6.5',  when='cuda_arch=12')
+    depends_on('cuda@2.1:6.5',  when='cuda_arch=13')
 
-    depends_on('cuda@:8', when='cuda_arch=20')
+    depends_on('cuda@3.0:8.0',  when='cuda_arch=20')
+    depends_on('cuda@3.2:8.0',  when='cuda_arch=21')
+
+    depends_on('cuda@5.0:10.2', when='cuda_arch=30')
+    depends_on('cuda@5.0:10.2', when='cuda_arch=32')
+    depends_on('cuda@5.0:',     when='cuda_arch=35')
+    depends_on('cuda@6.5:',     when='cuda_arch=37')
+
+    depends_on('cuda@6.0:',     when='cuda_arch=50')
+    depends_on('cuda@6.5:',     when='cuda_arch=52')
+    depends_on('cuda@6.5:',     when='cuda_arch=53')
+
+    depends_on('cuda@8.0:',     when='cuda_arch=60')
+    depends_on('cuda@8.0:',     when='cuda_arch=61')
+    depends_on('cuda@8.0:',     when='cuda_arch=62')
+
+    depends_on('cuda@9.0:',     when='cuda_arch=70')
+    depends_on('cuda@9.0:',     when='cuda_arch=72')
+    depends_on('cuda@10.0:',    when='cuda_arch=75')
+
+    depends_on('cuda@11.0:',    when='cuda_arch=80')
 
     # There are at least three cases to be aware of for compiler conflicts
     # 1. Linux x86_64
@@ -62,12 +93,15 @@ def cuda_flags(arch_list):
     conflicts('%gcc@7:', when='+cuda ^cuda@:9.1' + arch_platform)
     conflicts('%gcc@8:', when='+cuda ^cuda@:10.0.130' + arch_platform)
     conflicts('%gcc@9:', when='+cuda ^cuda@:10.2.89' + arch_platform)
+    conflicts('%gcc@:4,10:', when='+cuda ^cuda@:11.0.2' + arch_platform)
     conflicts('%pgi@:14.8', when='+cuda ^cuda@:7.0.27' + arch_platform)
     conflicts('%pgi@:15.3,15.5:', when='+cuda ^cuda@7.5' + arch_platform)
     conflicts('%pgi@:16.2,16.0:16.3', when='+cuda ^cuda@8' + arch_platform)
     conflicts('%pgi@:15,18:', when='+cuda ^cuda@9.0:9.1' + arch_platform)
-    conflicts('%pgi@:16', when='+cuda ^cuda@9.2.88:10' + arch_platform)
-    conflicts('%pgi@:17', when='+cuda ^cuda@10.2.89' + arch_platform)
+    conflicts('%pgi@:16,19:', when='+cuda ^cuda@9.2.88:10' + arch_platform)
+    conflicts('%pgi@:17,20:',
+              when='+cuda ^cuda@10.1.105:10.2.89' + arch_platform)
+    conflicts('%pgi@:17,20.2:', when='+cuda ^cuda@11.0.2' + arch_platform)
     conflicts('%clang@:3.4', when='+cuda ^cuda@:7.5' + arch_platform)
     conflicts('%clang@:3.7,4:',
               when='+cuda ^cuda@8.0:9.0' + arch_platform)
@@ -78,7 +112,8 @@ def cuda_flags(arch_list):
     conflicts('%clang@:3.7,7.1:', when='+cuda ^cuda@10.1.105' + arch_platform)
     conflicts('%clang@:3.7,8.1:',
               when='+cuda ^cuda@10.1.105:10.1.243' + arch_platform)
-    conflicts('%clang@:3.2,9.0:', when='+cuda ^cuda@10.2.89' + arch_platform)
+    conflicts('%clang@:3.2,9:', when='+cuda ^cuda@10.2.89' + arch_platform)
+    conflicts('%clang@:5,10:', when='+cuda ^cuda@11.0.2' + arch_platform)
 
     # x86_64 vs. ppc64le differ according to NVidia docs
     # Linux ppc64le compiler conflicts from Table from the docs below:
@@ -93,6 +128,8 @@ def cuda_flags(arch_list):
     conflicts('%gcc@6:', when='+cuda ^cuda@:9' + arch_platform)
     conflicts('%gcc@8:', when='+cuda ^cuda@:10.0.130' + arch_platform)
     conflicts('%gcc@9:', when='+cuda ^cuda@:10.1.243' + arch_platform)
+    # officially, CUDA 11.0.2 only supports the system GCC 8.3 on ppc64le
+    conflicts('%gcc@:4,10:', when='+cuda ^cuda@:11.0.2' + arch_platform)
     conflicts('%pgi', when='+cuda ^cuda@:8' + arch_platform)
     conflicts('%pgi@:16', when='+cuda ^cuda@:9.1.185' + arch_platform)
     conflicts('%pgi@:17', when='+cuda ^cuda@:10' + arch_platform)
@@ -102,6 +139,7 @@ def cuda_flags(arch_list):
     conflicts('%clang@7:', when='+cuda ^cuda@10.0.130' + arch_platform)
     conflicts('%clang@7.1:', when='+cuda ^cuda@:10.1.105' + arch_platform)
     conflicts('%clang@8.1:', when='+cuda ^cuda@:10.2.89' + arch_platform)
+    conflicts('%clang@:5,10.0:', when='+cuda ^cuda@11.0.2' + arch_platform)
 
     # Intel is mostly relevant for x86_64 Linux, even though it also
     # exists for Mac OS X. No information prior to CUDA 3.2 or Intel 11.1
@@ -114,12 +152,14 @@ def cuda_flags(arch_list):
     conflicts('%intel@16.0:', when='+cuda ^cuda@:8.0.43')
     conflicts('%intel@17.0:', when='+cuda ^cuda@:8.0.60')
     conflicts('%intel@18.0:', when='+cuda ^cuda@:9.9')
-    conflicts('%intel@19.0:', when='+cuda ^cuda@:10.2.89')
+    conflicts('%intel@19.0:', when='+cuda ^cuda@:10.0')
+    conflicts('%intel@19.1:', when='+cuda ^cuda@:10.1')
+    conflicts('%intel@19.2:', when='+cuda ^cuda@:11.0.2')
 
     # XL is mostly relevant for ppc64le Linux
     conflicts('%xl@:12,14:', when='+cuda ^cuda@:9.1')
     conflicts('%xl@:12,14:15,17:', when='+cuda ^cuda@9.2')
-    conflicts('%xl@17:', when='+cuda ^cuda@10.0.130:10.2.89')
+    conflicts('%xl@:12,17:', when='+cuda ^cuda@:11.0.2')
 
     # Mac OS X
     # platform = ' platform=darwin'
@@ -130,18 +170,8 @@ def cuda_flags(arch_list):
     # `clang-apple@x.y.z as a possible fix.
     # Compiler conflicts will be eventual taken from here:
     # https://docs.nvidia.com/cuda/cuda-installation-guide-mac-os-x/index.html#abstract
+    conflicts('platform=darwin', when='+cuda ^cuda@11.0.2:')
 
     # Make sure cuda_arch can not be used without +cuda
-    conflicts('~cuda', when='cuda_arch=20')
-    conflicts('~cuda', when='cuda_arch=30')
-    conflicts('~cuda', when='cuda_arch=32')
-    conflicts('~cuda', when='cuda_arch=35')
-    conflicts('~cuda', when='cuda_arch=50')
-    conflicts('~cuda', when='cuda_arch=52')
-    conflicts('~cuda', when='cuda_arch=53')
-    conflicts('~cuda', when='cuda_arch=60')
-    conflicts('~cuda', when='cuda_arch=61')
-    conflicts('~cuda', when='cuda_arch=62')
-    conflicts('~cuda', when='cuda_arch=70')
-    conflicts('~cuda', when='cuda_arch=72')
-    conflicts('~cuda', when='cuda_arch=75')
+    for value in cuda_arch_values:
+        conflicts('~cuda', when='cuda_arch=' + value)

lib/spack/spack/build_systems/intel.py

@@ -1017,6 +1017,15 @@ def setup_run_environment(self, env):
 
         env.extend(EnvironmentModifications.from_sourcing_file(f, *args))
 
+        if self.spec.name in ('intel', 'intel-parallel-studio'):
+            # this package provides compilers
+            # TODO: fix check above when compilers are dependencies
+            env.set('CC', self.prefix.bin.icc)
+            env.set('CXX', self.prefix.bin.icpc)
+            env.set('FC', self.prefix.bin.ifort)
+            env.set('F77', self.prefix.bin.ifort)
+            env.set('F90', self.prefix.bin.ifort)
+
     def setup_dependent_build_environment(self, env, dependent_spec):
         # NB: This function is overwritten by 'mpi' provider packages:
         #
@@ -1073,6 +1082,15 @@ def _setup_dependent_env_callback(
                 # which performs dizzyingly similar but necessarily different
                 # actions, and (b) function code leaves a bit more breathing
                 # room within the suffocating corset of flake8 line length.
+
+                # Intel MPI since 2019 depends on libfabric which is not in the
+                # lib directory but in a directory of its own which should be
+                # included in the rpath
+                if self.version >= ver('2019'):
+                    d = ancestor(self.component_lib_dir('mpi'))
+                    libfabrics_path = os.path.join(d, 'libfabric', 'lib')
+                    env.append_path('SPACK_COMPILER_EXTRA_RPATHS',
+                                    libfabrics_path)
             else:
                 raise InstallError('compilers_of_client arg required for MPI')
 

lib/spack/spack/build_systems/maven.py

@@ -0,0 +1,55 @@
+# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Spack Project Developers. See the top-level COPYRIGHT file for details.
+#
+# SPDX-License-Identifier: (Apache-2.0 OR MIT)
+
+
+from llnl.util.filesystem import install_tree, working_dir
+from spack.directives import depends_on
+from spack.package import PackageBase, run_after
+from spack.util.executable import which
+
+
+class MavenPackage(PackageBase):
+    """Specialized class for packages that are built using the
+    Maven build system. See https://maven.apache.org/index.html
+    for more information.
+
+    This class provides the following phases that can be overridden:
+
+    * build
+    * install
+    """
+    # Default phases
+    phases = ['build', 'install']
+
+    # To be used in UI queries that require to know which
+    # build-system class we are using
+    build_system_class = 'MavenPackage'
+
+    depends_on('java', type=('build', 'run'))
+    depends_on('maven', type='build')
+
+    @property
+    def build_directory(self):
+        """The directory containing the ``pom.xml`` file."""
+        return self.stage.source_path
+
+    def build(self, spec, prefix):
+        """Compile code and package into a JAR file."""
+
+        with working_dir(self.build_directory):
+            mvn = which('mvn')
+            if self.run_tests:
+                mvn('verify')
+            else:
+                mvn('package', '-DskipTests')
+
+    def install(self, spec, prefix):
+        """Copy to installation prefix."""
+
+        with working_dir(self.build_directory):
+            install_tree('.', prefix)
+
+    # Check that self.prefix is there after installation
+    run_after('install')(PackageBase.sanity_check_prefix)

lib/spack/spack/build_systems/python.py

@@ -91,7 +91,7 @@ def configure(self, spec, prefix):
     build_system_class = 'PythonPackage'
 
     #: Callback names for build-time test
-    build_time_test_callbacks = ['test']
+    build_time_test_callbacks = ['build_test']
 
     #: Callback names for install-time test
     install_time_test_callbacks = ['import_module_test']
@@ -192,6 +192,10 @@ def build_scripts(self, spec, prefix):
 
         self.setup_py('build_scripts', *args)
 
+    def build_scripts_args(self, spec, prefix):
+        """Arguments to pass to build_scripts."""
+        return []
+
     def clean(self, spec, prefix):
         """Clean up temporary files from 'build' command."""
         args = self.clean_args(spec, prefix)
@@ -357,7 +361,7 @@ def check_args(self, spec, prefix):
 
     # Testing
 
-    def test(self):
+    def build_test(self):
         """Run unit tests after in-place build.
 
         These tests are only run if the package actually has a 'test' command.

lib/spack/spack/build_systems/ruby.py

@@ -0,0 +1,59 @@
+# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Spack Project Developers. See the top-level COPYRIGHT file for details.
+#
+# SPDX-License-Identifier: (Apache-2.0 OR MIT)
+
+import glob
+import inspect
+
+from spack.directives import depends_on, extends
+from spack.package import PackageBase, run_after
+
+
+class RubyPackage(PackageBase):
+    """Specialized class for building Ruby gems.
+
+    This class provides two phases that can be overridden if required:
+
+    #. :py:meth:`~.RubyPackage.build`
+    #. :py:meth:`~.RubyPackage.install`
+    """
+    #: Phases of a Ruby package
+    phases = ['build', 'install']
+
+    #: This attribute is used in UI queries that need to know the build
+    #: system base class
+    build_system_class = 'RubyPackage'
+
+    extends('ruby')
+
+    depends_on('ruby', type=('build', 'run'))
+
+    def build(self, spec, prefix):
+        """Build a Ruby gem."""
+
+        # ruby-rake provides both rake.gemspec and Rakefile, but only
+        # rake.gemspec can be built without an existing rake installation
+        gemspecs = glob.glob('*.gemspec')
+        rakefiles = glob.glob('Rakefile')
+        if gemspecs:
+            inspect.getmodule(self).gem('build', '--norc', gemspecs[0])
+        elif rakefiles:
+            jobs = inspect.getmodule(self).make_jobs
+            inspect.getmodule(self).rake('package', '-j{0}'.format(jobs))
+        else:
+            # Some Ruby packages only ship `*.gem` files, so nothing to build
+            pass
+
+    def install(self, spec, prefix):
+        """Install a Ruby gem.
+
+        The ruby package sets ``GEM_HOME`` to tell gem where to install to."""
+
+        gems = glob.glob('*.gem')
+        if gems:
+            inspect.getmodule(self).gem(
+                'install', '--norc', '--ignore-dependencies', gems[0])
+
+    # Check that self.prefix is there after installation
+    run_after('install')(PackageBase.sanity_check_prefix)

lib/spack/spack/build_systems/scons.py

@@ -33,7 +33,7 @@ class SConsPackage(PackageBase):
     build_system_class = 'SConsPackage'
 
     #: Callback names for build-time test
-    build_time_test_callbacks = ['test']
+    build_time_test_callbacks = ['build_test']
 
     depends_on('scons', type='build')
 
@@ -59,7 +59,7 @@ def install(self, spec, prefix):
 
     # Testing
 
-    def test(self):
+    def build_test(self):
         """Run unit tests after build.
 
         By default, does nothing. Override this if you want to

lib/spack/spack/build_systems/sip.py

@@ -5,9 +5,10 @@
 
 import inspect
 
-from llnl.util.filesystem import working_dir
-from spack.directives import depends_on, extends, resource
-from spack.package import PackageBase, run_before, run_after
+from llnl.util.filesystem import working_dir, join_path
+from spack.directives import depends_on, extends
+from spack.package import PackageBase, run_after
+import os
 
 
 class SIPPackage(PackageBase):
@@ -40,33 +41,12 @@ class SIPPackage(PackageBase):
     extends('python')
 
     depends_on('qt')
-
-    resource(name='sip',
-             url='https://www.riverbankcomputing.com/static/Downloads/sip/4.19.18/sip-4.19.18.tar.gz',
-             sha256='c0bd863800ed9b15dcad477c4017cdb73fa805c25908b0240564add74d697e1e',
-             destination='.')
+    depends_on('py-sip')
 
     def python(self, *args, **kwargs):
         """The python ``Executable``."""
         inspect.getmodule(self).python(*args, **kwargs)
 
-    @run_before('configure')
-    def install_sip(self):
-        args = [
-            '--sip-module={0}'.format(self.sip_module),
-            '--bindir={0}'.format(self.prefix.bin),
-            '--destdir={0}'.format(inspect.getmodule(self).site_packages_dir),
-            '--incdir={0}'.format(inspect.getmodule(self).python_include_dir),
-            '--sipdir={0}'.format(self.prefix.share.sip),
-            '--stubsdir={0}'.format(inspect.getmodule(self).site_packages_dir),
-        ]
-
-        with working_dir('sip-4.19.18'):
-            self.python('configure.py', *args)
-
-            inspect.getmodule(self).make()
-            inspect.getmodule(self).make('install')
-
     def configure_file(self):
         """Returns the name of the configure file to use."""
         return 'configure.py'
@@ -77,12 +57,15 @@ def configure(self, spec, prefix):
 
         args = self.configure_args()
 
+        python_include_dir = 'python' + str(spec['python'].version.up_to(2))
+
         args.extend([
             '--verbose',
             '--confirm-license',
             '--qmake', spec['qt'].prefix.bin.qmake,
-            '--sip', prefix.bin.sip,
-            '--sip-incdir', inspect.getmodule(self).python_include_dir,
+            '--sip', spec['py-sip'].prefix.bin.sip,
+            '--sip-incdir', join_path(spec['py-sip'].prefix.include,
+                                      python_include_dir),
             '--bindir', prefix.bin,
             '--destdir', inspect.getmodule(self).site_packages_dir,
         ])
@@ -131,3 +114,14 @@ def import_module_test(self):
 
     # Check that self.prefix is there after installation
     run_after('install')(PackageBase.sanity_check_prefix)
+
+    @run_after('install')
+    def extend_path_setup(self):
+        # See github issue #14121 and PR #15297
+        module = self.spec['py-sip'].variants['module'].value
+        if module != 'sip':
+            module = module.split('.')[0]
+            with working_dir(inspect.getmodule(self).site_packages_dir):
+                with open(os.path.join(module, '__init__.py'), 'a') as f:
+                    f.write('from pkgutil import extend_path\n')
+                    f.write('__path__ = extend_path(__path__, __name__)\n')

lib/spack/spack/build_systems/sourceforge.py

@@ -0,0 +1,40 @@
+# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Spack Project Developers. See the top-level COPYRIGHT file for details.
+#
+# SPDX-License-Identifier: (Apache-2.0 OR MIT)
+
+import spack.util.url
+import spack.package
+
+
+class SourceforgePackage(spack.package.PackageBase):
+    """Mixin that takes care of setting url and mirrors for Sourceforge
+       packages."""
+    #: Path of the package in a Sourceforge mirror
+    sourceforge_mirror_path = None
+
+    #: List of Sourceforge mirrors used by Spack
+    base_mirrors = [
+        'https://prdownloads.sourceforge.net/',
+        'https://freefr.dl.sourceforge.net/',
+        'https://netcologne.dl.sourceforge.net/',
+        'https://pilotfiber.dl.sourceforge.net/',
+        'https://downloads.sourceforge.net/',
+        'http://kent.dl.sourceforge.net/sourceforge/'
+    ]
+
+    @property
+    def urls(self):
+        self._ensure_sourceforge_mirror_path_is_set_or_raise()
+        return [
+            spack.util.url.join(m, self.sourceforge_mirror_path,
+                                resolve_href=True)
+            for m in self.base_mirrors
+        ]
+
+    def _ensure_sourceforge_mirror_path_is_set_or_raise(self):
+        if self.sourceforge_mirror_path is None:
+            cls_name = type(self).__name__
+            msg = ('{0} must define a `sourceforge_mirror_path` attribute'
+                   ' [none defined]')
+            raise AttributeError(msg.format(cls_name))

lib/spack/spack/build_systems/sourceware.py

@@ -0,0 +1,37 @@
+# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Spack Project Developers. See the top-level COPYRIGHT file for details.
+#
+# SPDX-License-Identifier: (Apache-2.0 OR MIT)
+
+import spack.util.url
+import spack.package
+
+
+class SourcewarePackage(spack.package.PackageBase):
+    """Mixin that takes care of setting url and mirrors for Sourceware.org
+       packages."""
+    #: Path of the package in a Sourceware mirror
+    sourceware_mirror_path = None
+
+    #: List of Sourceware mirrors used by Spack
+    base_mirrors = [
+        'https://sourceware.org/pub/',
+        'https://mirrors.kernel.org/sourceware/',
+        'https://ftp.gwdg.de/pub/linux/sources.redhat.com/'
+    ]
+
+    @property
+    def urls(self):
+        self._ensure_sourceware_mirror_path_is_set_or_raise()
+        return [
+            spack.util.url.join(m, self.sourceware_mirror_path,
+                                resolve_href=True)
+            for m in self.base_mirrors
+        ]
+
+    def _ensure_sourceware_mirror_path_is_set_or_raise(self):
+        if self.sourceware_mirror_path is None:
+            cls_name = type(self).__name__
+            msg = ('{0} must define a `sourceware_mirror_path` attribute'
+                   ' [none defined]')
+            raise AttributeError(msg.format(cls_name))

lib/spack/spack/build_systems/waf.py

@@ -47,10 +47,10 @@ class WafPackage(PackageBase):
     build_system_class = 'WafPackage'
 
     # Callback names for build-time test
-    build_time_test_callbacks = ['test']
+    build_time_test_callbacks = ['build_test']
 
     # Callback names for install-time test
-    install_time_test_callbacks = ['installtest']
+    install_time_test_callbacks = ['install_test']
 
     # Much like AutotoolsPackage does not require automake and autoconf
     # to build, WafPackage does not require waf to build. It only requires
@@ -75,13 +75,14 @@ def waf(self, *args, **kwargs):
 
     def configure(self, spec, prefix):
         """Configures the project."""
-        args = self.configure_args()
+        args = ['--prefix={0}'.format(self.prefix)]
+        args += self.configure_args()
 
         self.waf('configure', *args)
 
     def configure_args(self):
         """Arguments to pass to configure."""
-        return ['--prefix={0}'.format(self.prefix)]
+        return []
 
     def build(self, spec, prefix):
         """Executes the build."""
@@ -105,7 +106,7 @@ def install_args(self):
 
     # Testing
 
-    def test(self):
+    def build_test(self):
         """Run unit tests after build.
 
         By default, does nothing. Override this if you want to
@@ -115,7 +116,7 @@ def test(self):
 
     run_after('build')(PackageBase._run_default_build_time_test_callbacks)
 
-    def installtest(self):
+    def install_test(self):
         """Run unit tests after install.
 
         By default, does nothing. Override this if you want to

lib/spack/spack/build_systems/xorg.py

@@ -0,0 +1,42 @@
+# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Spack Project Developers. See the top-level COPYRIGHT file for details.
+#
+# SPDX-License-Identifier: (Apache-2.0 OR MIT)
+
+import spack.util.url
+import spack.package
+
+
+class XorgPackage(spack.package.PackageBase):
+    """Mixin that takes care of setting url and mirrors for x.org
+       packages."""
+    #: Path of the package in a x.org mirror
+    xorg_mirror_path = None
+
+    #: List of x.org mirrors used by Spack
+    #  Note: x.org mirrors are a bit tricky, since many are out-of-sync or off.
+    #        A good package to test with is `util-macros`, which had a "recent"
+    #        release.
+    base_mirrors = [
+        'https://www.x.org/archive/individual/',
+        'https://mirrors.ircam.fr/pub/x.org/individual/',
+        'https://mirror.transip.net/xorg/individual/',
+        'ftp://ftp.freedesktop.org/pub/xorg/individual/',
+        'http://xorg.mirrors.pair.com/individual/'
+    ]
+
+    @property
+    def urls(self):
+        self._ensure_xorg_mirror_path_is_set_or_raise()
+        return [
+            spack.util.url.join(m, self.xorg_mirror_path,
+                                resolve_href=True)
+            for m in self.base_mirrors
+        ]
+
+    def _ensure_xorg_mirror_path_is_set_or_raise(self):
+        if self.xorg_mirror_path is None:
+            cls_name = type(self).__name__
+            msg = ('{0} must define a `xorg_mirror_path` attribute'
+                   ' [none defined]')
+            raise AttributeError(msg.format(cls_name))

lib/spack/spack/caches.py

@@ -42,7 +42,6 @@ def _fetch_cache():
     building the same package different ways or multiple times.
     """
     path = spack.config.get('config:source_cache')
-
     if not path:
         path = os.path.join(spack.paths.var_path, "cache")
     path = spack.util.path.canonicalize_path(path)
@@ -51,8 +50,9 @@ def _fetch_cache():
 
 
 class MirrorCache(object):
-    def __init__(self, root):
+    def __init__(self, root, skip_unstable_versions):
         self.root = os.path.abspath(root)
+        self.skip_unstable_versions = skip_unstable_versions
 
     def store(self, fetcher, relative_dest):
         """Fetch and relocate the fetcher's target into our mirror cache."""
@@ -85,5 +85,3 @@ def symlink(self, mirror_ref):
 
 #: Spack's local cache for downloaded source archives
 fetch_cache = llnl.util.lang.Singleton(_fetch_cache)
-
-mirror_cache = None

lib/spack/spack/ci.py

@@ -4,9 +4,11 @@
 # SPDX-License-Identifier: (Apache-2.0 OR MIT)
 
 import base64
+import copy
 import datetime
 import json
 import os
+import re
 import shutil
 import tempfile
 import zlib
@@ -24,18 +26,21 @@
 import spack.compilers as compilers
 import spack.config as cfg
 import spack.environment as ev
-from spack.dependency import all_deptypes
 from spack.error import SpackError
 import spack.hash_types as ht
-from spack.main import SpackCommand
+import spack.main
 import spack.repo
 from spack.spec import Spec
 import spack.util.spack_yaml as syaml
 import spack.util.web as web_util
 
 
-spack_gpg = SpackCommand('gpg')
-spack_compiler = SpackCommand('compiler')
+JOB_RETRY_CONDITIONS = [
+    'always',
+]
+
+spack_gpg = spack.main.SpackCommand('gpg')
+spack_compiler = spack.main.SpackCommand('compiler')
 
 
 class TemporaryDirectory(object):
@@ -342,25 +347,24 @@ def compute_spec_deps(spec_list):
            ],
            "specs": [
                {
-                 "root_spec": "readline@7.0%clang@9.1.0-apple arch=darwin-...",
-                 "spec": "readline@7.0%clang@9.1.0-apple arch=darwin-highs...",
+                 "root_spec": "readline@7.0%apple-clang@9.1.0 arch=darwin-...",
+                 "spec": "readline@7.0%apple-clang@9.1.0 arch=darwin-highs...",
                  "label": "readline/ip6aiun"
                },
                {
-                 "root_spec": "readline@7.0%clang@9.1.0-apple arch=darwin-...",
-                 "spec": "ncurses@6.1%clang@9.1.0-apple arch=darwin-highsi...",
+                 "root_spec": "readline@7.0%apple-clang@9.1.0 arch=darwin-...",
+                 "spec": "ncurses@6.1%apple-clang@9.1.0 arch=darwin-highsi...",
                  "label": "ncurses/y43rifz"
                },
                {
-                 "root_spec": "readline@7.0%clang@9.1.0-apple arch=darwin-...",
-                 "spec": "pkgconf@1.5.4%clang@9.1.0-apple arch=darwin-high...",
+                 "root_spec": "readline@7.0%apple-clang@9.1.0 arch=darwin-...",
+                 "spec": "pkgconf@1.5.4%apple-clang@9.1.0 arch=darwin-high...",
                  "label": "pkgconf/eg355zb"
                }
            ]
        }
 
     """
-    deptype = all_deptypes
     spec_labels = {}
 
     specs = []
@@ -380,7 +384,7 @@ def append_dep(s, d):
 
         rkey, rlabel = spec_deps_key_label(spec)
 
-        for s in spec.traverse(deptype=deptype):
+        for s in spec.traverse(deptype=all):
             if s.external:
                 tty.msg('Will not stage external pkg: {0}'.format(s))
                 continue
@@ -392,7 +396,7 @@ def append_dep(s, d):
             }
             append_dep(rlabel, slabel)
 
-            for d in s.dependencies(deptype=deptype):
+            for d in s.dependencies(deptype=all):
                 dkey, dlabel = spec_deps_key_label(d)
                 if d.external:
                     tty.msg('Will not stage external dep: {0}'.format(d))
@@ -400,11 +404,11 @@ def append_dep(s, d):
 
                 append_dep(slabel, dlabel)
 
-    for l, d in spec_labels.items():
+    for spec_label, spec_holder in spec_labels.items():
         specs.append({
-            'label': l,
-            'spec': d['spec'],
-            'root_spec': d['root'],
+            'label': spec_label,
+            'spec': spec_holder['spec'],
+            'root_spec': spec_holder['root'],
         })
 
     deps_json_obj = {
@@ -419,20 +423,76 @@ def spec_matches(spec, match_string):
     return spec.satisfies(match_string)
 
 
-def find_matching_config(spec, ci_mappings):
+def copy_attributes(attrs_list, src_dict, dest_dict):
+    for runner_attr in attrs_list:
+        if runner_attr in src_dict:
+            if runner_attr in dest_dict and runner_attr == 'tags':
+                # For 'tags', we combine the lists of tags, while
+                # avoiding duplicates
+                for tag in src_dict[runner_attr]:
+                    if tag not in dest_dict[runner_attr]:
+                        dest_dict[runner_attr].append(tag)
+            elif runner_attr in dest_dict and runner_attr == 'variables':
+                # For 'variables', we merge the dictionaries.  Any conflicts
+                # (i.e. 'runner-attributes' has same variable key as the
+                # higher level) we resolve by keeping the more specific
+                # 'runner-attributes' version.
+                for src_key, src_val in src_dict[runner_attr].items():
+                    dest_dict[runner_attr][src_key] = copy.deepcopy(
+                        src_dict[runner_attr][src_key])
+            else:
+                dest_dict[runner_attr] = copy.deepcopy(src_dict[runner_attr])
+
+
+def find_matching_config(spec, gitlab_ci):
+    runner_attributes = {}
+    overridable_attrs = [
+        'image',
+        'tags',
+        'variables',
+        'before_script',
+        'script',
+        'after_script',
+    ]
+
+    copy_attributes(overridable_attrs, gitlab_ci, runner_attributes)
+
+    ci_mappings = gitlab_ci['mappings']
     for ci_mapping in ci_mappings:
         for match_string in ci_mapping['match']:
             if spec_matches(spec, match_string):
-                return ci_mapping['runner-attributes']
-    return None
+                if 'runner-attributes' in ci_mapping:
+                    copy_attributes(overridable_attrs,
+                                    ci_mapping['runner-attributes'],
+                                    runner_attributes)
+                return runner_attributes
+    else:
+        return None
+
+    return runner_attributes
 
 
 def pkg_name_from_spec_label(spec_label):
     return spec_label[:spec_label.index('/')]
 
 
+def format_job_needs(phase_name, strip_compilers, dep_jobs,
+                     osname, build_group, enable_artifacts_buildcache):
+    needs_list = []
+    for dep_job in dep_jobs:
+        needs_list.append({
+            'job': get_job_name(phase_name,
+                                strip_compilers,
+                                dep_job,
+                                osname,
+                                build_group),
+            'artifacts': enable_artifacts_buildcache,
+        })
+    return needs_list
+
+
 def generate_gitlab_ci_yaml(env, print_summary, output_file,
-                            custom_spack_repo=None, custom_spack_ref=None):
+                            run_optimizer=False, use_dependencies=False):
     # FIXME: What's the difference between one that opens with 'spack'
     # and one that opens with 'env'?  This will only handle the former.
     with spack.concretize.disable_compiler_existence_check():
@@ -444,7 +504,6 @@ def generate_gitlab_ci_yaml(env, print_summary, output_file,
         tty.die('Environment yaml does not have "gitlab-ci" section')
 
     gitlab_ci = yaml_root['gitlab-ci']
-    ci_mappings = gitlab_ci['mappings']
 
     final_job_config = None
     if 'final-stage-rebuild-index' in gitlab_ci:
@@ -466,22 +525,9 @@ def generate_gitlab_ci_yaml(env, print_summary, output_file,
             tty.verbose("Using CDash auth token from environment")
             cdash_auth_token = os.environ.get('SPACK_CDASH_AUTH_TOKEN')
 
-    # Make sure we use a custom spack if necessary
-    before_script = None
-    after_script = None
-    if custom_spack_repo:
-        if not custom_spack_ref:
-            custom_spack_ref = 'master'
-        before_script = [
-            ('git clone "{0}" --branch "{1}" --depth 1 '
-             '--single-branch'.format(custom_spack_repo, custom_spack_ref)),
-            # Next line just shows spack version in pipeline output
-            'pushd ./spack && git rev-parse HEAD && popd',
-            '. "./spack/share/spack/setup-env.sh"',
-        ]
-        after_script = [
-            'rm -rf "./spack"'
-        ]
+    is_pr_pipeline = (
+        os.environ.get('SPACK_IS_PR_PIPELINE', '').lower() == 'true'
+    )
 
     ci_mirrors = yaml_root['mirrors']
     mirror_urls = [url for url in ci_mirrors.values()]
@@ -538,6 +584,9 @@ def generate_gitlab_ci_yaml(env, print_summary, output_file,
 
     stage_names = []
 
+    max_length_needs = 0
+    max_needs_job = ''
+
     for phase in phases:
         phase_name = phase['name']
         strip_compilers = phase['strip-compilers']
@@ -556,7 +605,7 @@ def generate_gitlab_ci_yaml(env, print_summary, output_file,
                 release_spec = root_spec[pkg_name]
 
                 runner_attribs = find_matching_config(
-                    release_spec, ci_mappings)
+                    release_spec, gitlab_ci)
 
                 if not runner_attribs:
                     tty.warn('No match found for {0}, skipping it'.format(
@@ -580,16 +629,27 @@ def generate_gitlab_ci_yaml(env, print_summary, output_file,
                     except AttributeError:
                         image_name = build_image
 
+                job_script = [
+                    'spack env activate --without-view .',
+                    'spack ci rebuild',
+                ]
+                if 'script' in runner_attribs:
+                    job_script = [s for s in runner_attribs['script']]
+
+                before_script = None
+                if 'before_script' in runner_attribs:
+                    before_script = [
+                        s for s in runner_attribs['before_script']
+                    ]
+
+                after_script = None
+                if 'after_script' in runner_attribs:
+                    after_script = [s for s in runner_attribs['after_script']]
+
                 osname = str(release_spec.architecture)
                 job_name = get_job_name(phase_name, strip_compilers,
                                         release_spec, osname, build_group)
 
-                debug_flag = ''
-                if 'enable-debug-messages' in gitlab_ci:
-                    debug_flag = '-d '
-
-                job_scripts = ['spack {0}ci rebuild'.format(debug_flag)]
-
                 compiler_action = 'NONE'
                 if len(phases) > 1:
                     compiler_action = 'FIND_ANY'
@@ -601,25 +661,35 @@ def generate_gitlab_ci_yaml(env, print_summary, output_file,
                         root_spec, main_phase, strip_compilers),
                     'SPACK_JOB_SPEC_PKG_NAME': release_spec.name,
                     'SPACK_COMPILER_ACTION': compiler_action,
+                    'SPACK_IS_PR_PIPELINE': str(is_pr_pipeline),
                 }
 
                 job_dependencies = []
                 if spec_label in dependencies:
-                    for dep_label in dependencies[spec_label]:
-                        dep_pkg = pkg_name_from_spec_label(dep_label)
-                        dep_spec = spec_labels[dep_label]['rootSpec'][dep_pkg]
-                        dep_job_name = get_job_name(
-                            phase_name, strip_compilers, dep_spec, osname,
-                            build_group)
-                        job_dependencies.append(dep_job_name)
+                    if enable_artifacts_buildcache:
+                        dep_jobs = [
+                            d for d in release_spec.traverse(deptype=all,
+                                                             root=False)
+                        ]
+                    else:
+                        dep_jobs = []
+                        for dep_label in dependencies[spec_label]:
+                            dep_pkg = pkg_name_from_spec_label(dep_label)
+                            dep_root = spec_labels[dep_label]['rootSpec']
+                            dep_jobs.append(dep_root[dep_pkg])
+
+                    job_dependencies.extend(
+                        format_job_needs(phase_name, strip_compilers, dep_jobs,
+                                         osname, build_group,
+                                         enable_artifacts_buildcache))
 
                 # This next section helps gitlab make sure the right
                 # bootstrapped compiler exists in the artifacts buildcache by
                 # creating an artificial dependency between this spec and its
                 # compiler.  So, if we are in the main phase, and if the
                 # compiler we are supposed to use is listed in any of the
-                # bootstrap spec lists, then we will add one more dependency to
-                # "job_dependencies" (that compiler).
+                # bootstrap spec lists, then we will add more dependencies to
+                # the job (that compiler and maybe it's dependencies as well).
                 if is_main_phase(phase_name):
                     compiler_pkg_spec = compilers.pkg_spec_for_compiler(
                         release_spec.compiler)
@@ -627,12 +697,25 @@ def generate_gitlab_ci_yaml(env, print_summary, output_file,
                         bs_arch = bs['spec'].architecture
                         if (bs['spec'].satisfies(compiler_pkg_spec) and
                             bs_arch == release_spec.architecture):
-                            c_job_name = get_job_name(bs['phase-name'],
-                                                      bs['strip-compilers'],
-                                                      bs['spec'],
-                                                      str(bs_arch),
-                                                      build_group)
-                            job_dependencies.append(c_job_name)
+                            # We found the bootstrap compiler this release spec
+                            # should be built with, so for DAG scheduling
+                            # purposes, we will at least add the compiler spec
+                            # to the jobs "needs".  But if artifact buildcache
+                            # is enabled, we'll have to add all transtive deps
+                            # of the compiler as well.
+                            dep_jobs = [bs['spec']]
+                            if enable_artifacts_buildcache:
+                                dep_jobs = [
+                                    d for d in bs['spec'].traverse(deptype=all)
+                                ]
+
+                            job_dependencies.extend(
+                                format_job_needs(bs['phase-name'],
+                                                 bs['strip-compilers'],
+                                                 dep_jobs,
+                                                 str(bs_arch),
+                                                 build_group,
+                                                 enable_artifacts_buildcache))
 
                 if enable_cdash_reporting:
                     cdash_build_name = get_cdash_build_name(
@@ -647,7 +730,7 @@ def generate_gitlab_ci_yaml(env, print_summary, output_file,
 
                     job_vars['SPACK_CDASH_BUILD_NAME'] = cdash_build_name
                     job_vars['SPACK_RELATED_BUILDS_CDASH'] = ';'.join(
-                        related_builds)
+                        sorted(related_builds))
 
                 variables.update(job_vars)
 
@@ -657,20 +740,34 @@ def generate_gitlab_ci_yaml(env, print_summary, output_file,
                 ]
 
                 if enable_artifacts_buildcache:
-                    artifact_paths.append('local_mirror/build_cache')
+                    bc_root = 'local_mirror/build_cache'
+                    artifact_paths.extend([os.path.join(bc_root, p) for p in [
+                        bindist.tarball_name(release_spec, '.spec.yaml'),
+                        bindist.tarball_name(release_spec, '.cdashid'),
+                        bindist.tarball_directory_name(release_spec),
+                    ]])
 
                 job_object = {
                     'stage': stage_name,
                     'variables': variables,
-                    'script': job_scripts,
+                    'script': job_script,
                     'tags': tags,
                     'artifacts': {
                         'paths': artifact_paths,
                         'when': 'always',
                     },
-                    'dependencies': job_dependencies,
+                    'needs': sorted(job_dependencies, key=lambda d: d['job']),
+                    'retry': {
+                        'max': 2,
+                        'when': JOB_RETRY_CONDITIONS,
+                    }
                 }
 
+                length_needs = len(job_dependencies)
+                if length_needs > max_length_needs:
+                    max_length_needs = length_needs
+                    max_needs_job = job_name
+
                 if before_script:
                     job_object['before_script'] = before_script
 
@@ -691,6 +788,9 @@ def generate_gitlab_ci_yaml(env, print_summary, output_file,
     tty.debug('{0} build jobs generated in {1} stages'.format(
         job_id, stage_id))
 
+    tty.debug('The max_needs_job is {0}, with {1} needs'.format(
+        max_needs_job, max_length_needs))
+
     # Use "all_job_names" to populate the build group for this set
     if enable_cdash_reporting and cdash_auth_token:
         try:
@@ -701,7 +801,7 @@ def generate_gitlab_ci_yaml(env, print_summary, output_file,
     else:
         tty.warn('Unable to populate buildgroup without CDash credentials')
 
-    if final_job_config:
+    if final_job_config and not is_pr_pipeline:
         # Add an extra, final job to regenerate the index
         final_stage = 'stage-rebuild-index'
         final_job = {
@@ -721,8 +821,42 @@ def generate_gitlab_ci_yaml(env, print_summary, output_file,
 
     output_object['stages'] = stage_names
 
+    # Capture the version of spack used to generate the pipeline, transform it
+    # into a value that can be passed to "git checkout", and save it in a
+    # global yaml variable
+    spack_version = spack.main.get_version()
+    version_to_clone = None
+    v_match = re.match(r"^\d+\.\d+\.\d+$", spack_version)
+    if v_match:
+        version_to_clone = 'v{0}'.format(v_match.group(0))
+    else:
+        v_match = re.match(r"^[^-]+-[^-]+-([a-f\d]+)$", spack_version)
+        if v_match:
+            version_to_clone = v_match.group(1)
+        else:
+            version_to_clone = spack_version
+
+    output_object['variables'] = {
+        'SPACK_VERSION': spack_version,
+        'SPACK_CHECKOUT_VERSION': version_to_clone,
+    }
+
+    sorted_output = {}
+    for output_key, output_value in sorted(output_object.items()):
+        sorted_output[output_key] = output_value
+
+    # TODO(opadron): remove this or refactor
+    if run_optimizer:
+        import spack.ci_optimization as ci_opt
+        sorted_output = ci_opt.optimizer(sorted_output)
+
+    # TODO(opadron): remove this or refactor
+    if use_dependencies:
+        import spack.ci_needs_workaround as cinw
+        sorted_output = cinw.needs_to_dependencies(sorted_output)
+
     with open(output_file, 'w') as outf:
-        outf.write(syaml.dump_config(output_object, default_flow_style=True))
+        outf.write(syaml.dump_config(sorted_output, default_flow_style=True))
 
 
 def url_encode_string(input_string):
@@ -947,8 +1081,9 @@ def read_cdashid_from_mirror(spec, mirror_url):
 def push_mirror_contents(env, spec, yaml_path, mirror_url, build_id):
     if mirror_url:
         tty.debug('Creating buildcache')
-        buildcache._createtarball(env, yaml_path, None, mirror_url, None,
-                                  True, True, False, False, True, False)
+        buildcache._createtarball(env, spec_yaml=yaml_path, add_deps=False,
+                                  output_location=mirror_url, force=True,
+                                  allow_root=True)
         if build_id:
             tty.debug('Writing cdashid ({0}) to remote mirror: {1}'.format(
                 build_id, mirror_url))
@@ -961,17 +1096,10 @@ def copy_stage_logs_to_artifacts(job_spec, job_log_dir):
         tty.debug('job package: {0}'.format(job_pkg))
         stage_dir = job_pkg.stage.path
         tty.debug('stage dir: {0}'.format(stage_dir))
-        build_env_src = os.path.join(stage_dir, 'spack-build-env.txt')
         build_out_src = os.path.join(stage_dir, 'spack-build-out.txt')
-        build_env_dst = os.path.join(
-            job_log_dir, 'spack-build-env.txt')
         build_out_dst = os.path.join(
             job_log_dir, 'spack-build-out.txt')
-        tty.debug('Copying logs to artifacts:')
-        tty.debug('  1: {0} -> {1}'.format(
-            build_env_src, build_env_dst))
-        shutil.copyfile(build_env_src, build_env_dst)
-        tty.debug('  2: {0} -> {1}'.format(
+        tty.debug('Copying build log ({0}) to artifacts ({1})'.format(
             build_out_src, build_out_dst))
         shutil.copyfile(build_out_src, build_out_dst)
     except Exception as inst:

lib/spack/spack/ci_needs_workaround.py

@@ -0,0 +1,47 @@
+# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Spack Project Developers. See the top-level COPYRIGHT file for details.
+#
+# SPDX-License-Identifier: (Apache-2.0 OR MIT)
+
+import collections
+
+try:
+    # dynamically import to keep vermin from complaining
+    collections_abc = __import__('collections.abc')
+except ImportError:
+    collections_abc = collections
+
+
+get_job_name = lambda needs_entry: (
+    needs_entry.get('job') if (
+        isinstance(needs_entry, collections_abc.Mapping) and
+        needs_entry.get('artifacts', True))
+
+    else
+
+    needs_entry if isinstance(needs_entry, str)
+
+    else None)
+
+
+def convert_job(job_entry):
+    if not isinstance(job_entry, collections_abc.Mapping):
+        return job_entry
+
+    needs = job_entry.get('needs')
+    if needs is None:
+        return job_entry
+
+    new_job = {}
+    new_job.update(job_entry)
+    del new_job['needs']
+
+    new_job['dependencies'] = list(filter(
+        (lambda x: x is not None),
+        (get_job_name(needs_entry) for needs_entry in needs)))
+
+    return new_job
+
+
+def needs_to_dependencies(yaml):
+    return dict((k, convert_job(v)) for k, v in yaml.items())

lib/spack/spack/ci_optimization.py

@@ -0,0 +1,394 @@
+# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Spack Project Developers. See the top-level COPYRIGHT file for details.
+#
+# SPDX-License-Identifier: (Apache-2.0 OR MIT)
+
+import collections
+
+try:
+    # dynamically import to keep vermin from complaining
+    collections_abc = __import__('collections.abc')
+except ImportError:
+    collections_abc = collections
+
+import copy
+import hashlib
+
+import spack.util.spack_yaml as syaml
+
+
+def sort_yaml_obj(obj):
+    if isinstance(obj, collections_abc.Mapping):
+        return syaml.syaml_dict(
+            (k, sort_yaml_obj(v))
+            for k, v in
+            sorted(obj.items(), key=(lambda item: str(item[0]))))
+
+    if isinstance(obj, collections_abc.Sequence) and not isinstance(obj, str):
+        return syaml.syaml_list(sort_yaml_obj(x) for x in obj)
+
+    return obj
+
+
+def matches(obj, proto):
+    """Returns True if the test object "obj" matches the prototype object
+    "proto".
+
+    If obj and proto are mappings, obj matches proto if (key in obj) and
+    (obj[key] matches proto[key]) for every key in proto.
+
+    If obj and proto are sequences, obj matches proto if they are of the same
+    length and (a matches b) for every (a,b) in zip(obj, proto).
+
+    Otherwise, obj matches proto if obj == proto.
+
+    Precondition: proto must not have any reference cycles
+    """
+    if isinstance(obj, collections_abc.Mapping):
+        if not isinstance(proto, collections_abc.Mapping):
+            return False
+
+        return all(
+            (key in obj and matches(obj[key], val))
+            for key, val in proto.items()
+        )
+
+    if (isinstance(obj, collections_abc.Sequence) and
+            not isinstance(obj, str)):
+
+        if not (isinstance(proto, collections_abc.Sequence) and
+                not isinstance(proto, str)):
+            return False
+
+        if len(obj) != len(proto):
+            return False
+
+        return all(
+            matches(obj[index], val)
+            for index, val in enumerate(proto)
+        )
+
+    return obj == proto
+
+
+def subkeys(obj, proto):
+    """Returns the test mapping "obj" after factoring out the items it has in
+    common with the prototype mapping "proto".
+
+    Consider a recursive merge operation, merge(a, b) on mappings a and b, that
+    returns a mapping, m, whose keys are the union of the keys of a and b, and
+    for every such key, "k", its corresponding value is:
+
+      - merge(a[key], b[key])  if a[key] and b[key] are mappings, or
+      - b[key]                 if (key in b) and not matches(a[key], b[key]),
+                               or
+      - a[key]                 otherwise
+
+
+    If obj and proto are mappings, the returned object is the smallest object,
+    "a", such that merge(a, proto) matches obj.
+
+    Otherwise, obj is returned.
+    """
+    if not (isinstance(obj, collections_abc.Mapping) and
+            isinstance(proto, collections_abc.Mapping)):
+        return obj
+
+    new_obj = {}
+    for key, value in obj.items():
+        if key not in proto:
+            new_obj[key] = value
+            continue
+
+        if (matches(value, proto[key]) and
+            matches(proto[key], value)):
+            continue
+
+        if isinstance(value, collections_abc.Mapping):
+            new_obj[key] = subkeys(value, proto[key])
+            continue
+
+        new_obj[key] = value
+
+    return new_obj
+
+
+def add_extends(yaml, key):
+    """Modifies the given object "yaml" so that it includes an "extends" key
+    whose value features "key".
+
+    If "extends" is not in yaml, then yaml is modified such that
+    yaml["extends"] == key.
+
+    If yaml["extends"] is a str, then yaml is modified such that
+    yaml["extends"] == [yaml["extends"], key]
+
+    If yaml["extends"] is a list that does not include key, then key is
+    appended to the list.
+
+    Otherwise, yaml is left unchanged.
+    """
+
+    has_key = ('extends' in yaml)
+    extends = yaml.get('extends')
+
+    if has_key and not isinstance(extends, (str, collections_abc.Sequence)):
+        return
+
+    if extends is None:
+        yaml['extends'] = key
+        return
+
+    if isinstance(extends, str):
+        if extends != key:
+            yaml['extends'] = [extends, key]
+        return
+
+    if key not in extends:
+        extends.append(key)
+
+
+def common_subobject(yaml, sub):
+    """Factor prototype object "sub" out of the values of mapping "yaml".
+
+    Consider a modified copy of yaml, "new", where for each key, "key" in yaml:
+
+      - If yaml[key] matches sub, then new[key] = subkeys(yaml[key], sub).
+      - Otherwise, new[key] = yaml[key].
+
+    If the above match criteria is not satisfied for any such key, then (yaml,
+    None) is returned. The yaml object is returned unchanged.
+
+    Otherwise, each matching value in new is modified as in
+    add_extends(new[key], common_key), and then new[common_key] is set to sub.
+    The common_key value is chosen such that it does not match any preexisting
+    key in new. In this case, (new, common_key) is returned.
+    """
+    match_list = set(k for k, v in yaml.items() if matches(v, sub))
+
+    if not match_list:
+        return yaml, None
+
+    common_prefix = '.c'
+    common_index = 0
+
+    while True:
+        common_key = ''.join((common_prefix, str(common_index)))
+        if common_key not in yaml:
+            break
+        common_index += 1
+
+    new_yaml = {}
+
+    for key, val in yaml.items():
+        new_yaml[key] = copy.deepcopy(val)
+
+        if not matches(val, sub):
+            continue
+
+        new_yaml[key] = subkeys(new_yaml[key], sub)
+        add_extends(new_yaml[key], common_key)
+
+    new_yaml[common_key] = sub
+
+    return new_yaml, common_key
+
+
+def print_delta(name, old, new, applied=None):
+    delta = new - old
+    reldelta = (1000 * delta) // old
+    reldelta = (reldelta // 10, reldelta % 10)
+
+    if applied is None:
+        applied = (new <= old)
+
+    print('\n'.join((
+        '{0} {1}:',
+        '  before: {2: 10d}',
+        '  after : {3: 10d}',
+        '  delta : {4:+10d} ({5:=+3d}.{6}%)',
+    )).format(
+        name,
+        ('+' if applied else 'x'),
+        old,
+        new,
+        delta,
+        reldelta[0],
+        reldelta[1]
+    ))
+
+
+def try_optimization_pass(name, yaml, optimization_pass, *args, **kwargs):
+    """Try applying an optimization pass and return information about the
+    result
+
+    "name" is a string describing the nature of the pass. If it is a non-empty
+    string, summary statistics are also printed to stdout.
+
+    "yaml" is the object to apply the pass to.
+
+    "optimization_pass" is the function implementing the pass to be applied.
+
+    "args" and "kwargs" are the additional arguments to pass to optimization
+    pass. The pass is applied as
+
+    >>> (new_yaml, *other_results) = optimization_pass(yaml, *args, **kwargs)
+
+    The pass's results are greedily rejected if it does not modify the original
+    yaml document, or if it produces a yaml document that serializes to a
+    larger string.
+
+    Returns (new_yaml, yaml, applied, other_results) if applied, or
+    (yaml, new_yaml, applied, other_results) otherwise.
+    """
+    result = optimization_pass(yaml, *args, **kwargs)
+    new_yaml, other_results = result[0], result[1:]
+
+    if new_yaml is yaml:
+        # pass was not applied
+        return (yaml, new_yaml, False, other_results)
+
+    pre_size = len(syaml.dump_config(
+        sort_yaml_obj(yaml), default_flow_style=True))
+    post_size = len(syaml.dump_config(
+        sort_yaml_obj(new_yaml), default_flow_style=True))
+
+    # pass makes the size worse: not applying
+    applied = (post_size <= pre_size)
+    if applied:
+        yaml, new_yaml = new_yaml, yaml
+
+    if name:
+        print_delta(name, pre_size, post_size, applied)
+
+    return (yaml, new_yaml, applied, other_results)
+
+
+def build_histogram(iterator, key):
+    """Builds a histogram of values given an iterable of mappings and a key.
+
+    For each mapping "m" with key "key" in iterator, the value m[key] is
+    considered.
+
+    Returns a list of tuples (hash, count, proportion, value), where
+
+      - "hash" is a sha1sum hash of the value.
+      - "count" is the number of occurences of values that hash to "hash".
+      - "proportion" is the proportion of all values considered above that
+        hash to "hash".
+      - "value" is one of the values considered above that hash to "hash".
+        Which value is chosen when multiple values hash to the same "hash" is
+        undefined.
+
+    The list is sorted in descending order by count, yielding the most
+    frequently occuring hashes first.
+    """
+    buckets = collections.defaultdict(int)
+    values = {}
+
+    num_objects = 0
+    for obj in iterator:
+        num_objects += 1
+
+        try:
+            val = obj[key]
+        except (KeyError, TypeError):
+            continue
+
+        value_hash = hashlib.sha1()
+        value_hash.update(syaml.dump_config(sort_yaml_obj(val)).encode())
+        value_hash = value_hash.hexdigest()
+
+        buckets[value_hash] += 1
+        values[value_hash] = val
+
+    return [(h, buckets[h], float(buckets[h]) / num_objects, values[h])
+            for h in sorted(buckets.keys(), key=lambda k: -buckets[k])]
+
+
+def optimizer(yaml):
+    original_size = len(syaml.dump_config(
+        sort_yaml_obj(yaml), default_flow_style=True))
+
+    # try factoring out commonly repeated portions
+    common_job = {
+        'variables': {
+            'SPACK_COMPILER_ACTION': 'NONE',
+            'SPACK_RELATED_BUILDS_CDASH': ''
+        },
+
+        'after_script': ['rm -rf "./spack"'],
+
+        'artifacts': {
+            'paths': ['jobs_scratch_dir', 'cdash_report'],
+            'when': 'always'
+        },
+    }
+
+    # look for a list of tags that appear frequently
+    _, count, proportion, tags = next(iter(
+        build_histogram(yaml.values(), 'tags')),
+        (None,) * 4)
+
+    # If a list of tags is found, and there are more than one job that uses it,
+    # *and* the jobs that do use it represent at least 70% of all jobs, then
+    # add the list to the prototype object.
+    if tags and count > 1 and proportion >= 0.70:
+        common_job['tags'] = tags
+
+    # apply common object factorization
+    yaml, other, applied, rest = try_optimization_pass(
+        'general common object factorization',
+        yaml, common_subobject, common_job)
+
+    # look for a common script, and try factoring that out
+    _, count, proportion, script = next(iter(
+        build_histogram(yaml.values(), 'script')),
+        (None,) * 4)
+
+    if script and count > 1 and proportion >= 0.70:
+        yaml, other, applied, rest = try_optimization_pass(
+            'script factorization',
+            yaml, common_subobject, {'script': script})
+
+    # look for a common before_script, and try factoring that out
+    _, count, proportion, script = next(iter(
+        build_histogram(yaml.values(), 'before_script')),
+        (None,) * 4)
+
+    if script and count > 1 and proportion >= 0.70:
+        yaml, other, applied, rest = try_optimization_pass(
+            'before_script factorization',
+            yaml, common_subobject, {'before_script': script})
+
+    # Look specifically for the SPACK_ROOT_SPEC environment variables.
+    # Try to factor them out.
+    h = build_histogram((
+        getattr(val, 'get', lambda *args: {})('variables')
+        for val in yaml.values()), 'SPACK_ROOT_SPEC')
+
+    # In this case, we try to factor out *all* instances of the SPACK_ROOT_SPEC
+    # environment variable; not just the one that appears with the greatest
+    # frequency. We only require that more than 1 job uses a given instance's
+    # value, because we expect the value to be very large, and so expect even
+    # few-to-one factorizations to yield large space savings.
+    counter = 0
+    for _, count, proportion, spec in h:
+        if count <= 1:
+            continue
+
+        counter += 1
+
+        yaml, other, applied, rest = try_optimization_pass(
+            'SPACK_ROOT_SPEC factorization ({count})'.format(count=counter),
+            yaml,
+            common_subobject,
+            {'variables': {'SPACK_ROOT_SPEC': spec}})
+
+    new_size = len(syaml.dump_config(
+        sort_yaml_obj(yaml), default_flow_style=True))
+
+    print('\n')
+    print_delta('overall summary', original_size, new_size)
+    print('\n')
+    return yaml

lib/spack/spack/cmd/__init__.py

@@ -9,6 +9,7 @@
 import re
 import sys
 import argparse
+import ruamel.yaml as yaml
 
 import six
 
@@ -16,7 +17,7 @@
 from llnl.util.lang import attr_setdefault, index_by
 from llnl.util.tty.colify import colify
 from llnl.util.tty.color import colorize
-from llnl.util.filesystem import working_dir
+from llnl.util.filesystem import join_path
 
 import spack.config
 import spack.error
@@ -26,6 +27,7 @@
 import spack.store
 import spack.util.spack_json as sjson
 import spack.util.string
+from ruamel.yaml.error import MarkedYAMLError
 
 
 # cmd has a submodule called "list" so preserve the python list module
@@ -43,11 +45,28 @@ def python_name(cmd_name):
     return cmd_name.replace("-", "_")
 
 
+def require_python_name(pname):
+    """Require that the provided name is a valid python name (per
+    python_name()). Useful for checking parameters for function
+    prerequisites."""
+    if python_name(pname) != pname:
+        raise PythonNameError(pname)
+
+
 def cmd_name(python_name):
     """Convert module name (with ``_``) to command name (with ``-``)."""
     return python_name.replace('_', '-')
 
 
+def require_cmd_name(cname):
+    """Require that the provided name is a valid command name (per
+    cmd_name()). Useful for checking parameters for function
+    prerequisites.
+    """
+    if cmd_name(cname) != cname:
+        raise CommandNameError(cname)
+
+
 #: global, cached list of all commands -- access through all_commands()
 _all_commands = None
 
@@ -91,6 +110,7 @@ def get_module(cmd_name):
         cmd_name (str): name of the command for which to get a module
             (contains ``-``, not ``_``).
     """
+    require_cmd_name(cmd_name)
     pname = python_name(cmd_name)
 
     try:
@@ -102,8 +122,6 @@ def get_module(cmd_name):
         tty.debug('Imported {0} from built-in commands'.format(pname))
     except ImportError:
         module = spack.extensions.get_module(cmd_name)
-        if not module:
-            raise
 
     attr_setdefault(module, SETUP_PARSER, lambda *args: None)  # null-op
     attr_setdefault(module, DESCRIPTION, "")
@@ -116,14 +134,16 @@ def get_module(cmd_name):
 
 
 def get_command(cmd_name):
-    """Imports the command's function from a module and returns it.
+    """Imports the command function associated with cmd_name.
+
+    The function's name is derived from cmd_name using python_name().
 
     Args:
-        cmd_name (str): name of the command for which to get a module
-            (contains ``-``, not ``_``).
+        cmd_name (str): name of the command (contains ``-``, not ``_``).
     """
+    require_cmd_name(cmd_name)
     pname = python_name(cmd_name)
-    return getattr(get_module(pname), pname)
+    return getattr(get_module(cmd_name), pname)
 
 
 def parse_specs(args, **kwargs):
@@ -177,7 +197,7 @@ def elide_list(line_list, max_num=10):
         return line_list
 
 
-def disambiguate_spec(spec, env, local=False, installed=True):
+def disambiguate_spec(spec, env, local=False, installed=True, first=False):
     """Given a spec, figure out which installed package it refers to.
 
     Arguments:
@@ -190,10 +210,11 @@ def disambiguate_spec(spec, env, local=False, installed=True):
             database query. See ``spack.database.Database._query`` for details.
     """
     hashes = env.all_hashes() if env else None
-    return disambiguate_spec_from_hashes(spec, hashes, local, installed)
+    return disambiguate_spec_from_hashes(spec, hashes, local, installed, first)
 
 
-def disambiguate_spec_from_hashes(spec, hashes, local=False, installed=True):
+def disambiguate_spec_from_hashes(spec, hashes, local=False,
+                                  installed=True, first=False):
     """Given a spec and a list of hashes, get concrete spec the spec refers to.
 
     Arguments:
@@ -213,6 +234,9 @@ def disambiguate_spec_from_hashes(spec, hashes, local=False, installed=True):
     if not matching_specs:
         tty.die("Spec '%s' matches no installed packages." % spec)
 
+    elif first:
+        return matching_specs[0]
+
     elif len(matching_specs) > 1:
         format_string = '{name}{@version}{%compiler}{arch=architecture}'
         args = ["%s matches multiple packages." % spec,
@@ -411,8 +435,39 @@ def format_list(specs):
 
 def spack_is_git_repo():
     """Ensure that this instance of Spack is a git clone."""
-    with working_dir(spack.paths.prefix):
-        return os.path.isdir('.git')
+    return is_git_repo(spack.paths.prefix)
+
+
+def is_git_repo(path):
+    dotgit_path = join_path(path, '.git')
+    if os.path.isdir(dotgit_path):
+        # we are in a regular git repo
+        return True
+    if os.path.isfile(dotgit_path):
+        # we might be in a git worktree
+        try:
+            with open(dotgit_path, "rb") as f:
+                dotgit_content = yaml.load(f)
+            return os.path.isdir(dotgit_content.get("gitdir", dotgit_path))
+        except MarkedYAMLError:
+            pass
+    return False
+
+
+class PythonNameError(spack.error.SpackError):
+    """Exception class thrown for impermissible python names"""
+    def __init__(self, name):
+        self.name = name
+        super(PythonNameError, self).__init__(
+            '{0} is not a permissible Python name.'.format(name))
+
+
+class CommandNameError(spack.error.SpackError):
+    """Exception class thrown for impermissible command names"""
+    def __init__(self, name):
+        self.name = name
+        super(CommandNameError, self).__init__(
+            '{0} is not a permissible Spack command name.'.format(name))
 
 
 ########################################

lib/spack/spack/cmd/bootstrap.py

@@ -1,80 +0,0 @@
-# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
-# Spack Project Developers. See the top-level COPYRIGHT file for details.
-#
-# SPDX-License-Identifier: (Apache-2.0 OR MIT)
-
-import llnl.util.cpu
-import llnl.util.tty as tty
-
-import spack.repo
-import spack.spec
-import spack.cmd.common.arguments as arguments
-
-description = "Bootstrap packages needed for spack to run smoothly"
-section = "admin"
-level = "long"
-
-
-def setup_parser(subparser):
-    arguments.add_common_arguments(subparser, ['jobs'])
-    subparser.add_argument(
-        '--keep-prefix', action='store_true', dest='keep_prefix',
-        help="don't remove the install prefix if installation fails")
-    subparser.add_argument(
-        '--keep-stage', action='store_true', dest='keep_stage',
-        help="don't remove the build stage if installation succeeds")
-    arguments.add_common_arguments(subparser, ['no_checksum'])
-    subparser.add_argument(
-        '-v', '--verbose', action='store_true', dest='verbose',
-        help="display verbose build output while installing")
-
-    cache_group = subparser.add_mutually_exclusive_group()
-    cache_group.add_argument(
-        '--use-cache', action='store_true', dest='use_cache', default=True,
-        help="check for pre-built Spack packages in mirrors (default)")
-    cache_group.add_argument(
-        '--no-cache', action='store_false', dest='use_cache', default=True,
-        help="do not check for pre-built Spack packages in mirrors")
-    cache_group.add_argument(
-        '--cache-only', action='store_true', dest='cache_only', default=False,
-        help="only install package from binary mirrors")
-
-    cd_group = subparser.add_mutually_exclusive_group()
-    arguments.add_common_arguments(cd_group, ['clean', 'dirty'])
-
-
-def bootstrap(parser, args, **kwargs):
-    kwargs.update({
-        'keep_prefix': args.keep_prefix,
-        'keep_stage': args.keep_stage,
-        'install_deps': 'dependencies',
-        'verbose': args.verbose,
-        'dirty': args.dirty,
-        'use_cache': args.use_cache,
-        'cache_only': args.cache_only
-    })
-
-    # Define requirement dictionary defining general specs which need
-    # to be satisfied, and the specs to install when the general spec
-    # isn't satisfied.
-    requirement_dict = {
-        # Install environment-modules with generic optimizations
-        'environment-modules': 'environment-modules~X target={0}'.format(
-            llnl.util.cpu.host().family
-        )
-    }
-
-    for requirement in requirement_dict:
-        installed_specs = spack.store.db.query(requirement)
-        if(len(installed_specs) > 0):
-            tty.msg("Requirement %s is satisfied with installed "
-                    "package %s" % (requirement, installed_specs[0]))
-        else:
-            # Install requirement
-            spec_to_install = spack.spec.Spec(requirement_dict[requirement])
-            spec_to_install.concretize()
-            tty.msg("Installing %s to satisfy requirement for %s" %
-                    (spec_to_install, requirement))
-            kwargs['explicit'] = True
-            package = spack.repo.get(spec_to_install)
-            package.do_install(**kwargs)

lib/spack/spack/cmd/build.py

@@ -1,45 +0,0 @@
-# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
-# Spack Project Developers. See the top-level COPYRIGHT file for details.
-#
-# SPDX-License-Identifier: (Apache-2.0 OR MIT)
-
-import spack.cmd.configure as cfg
-import llnl.util.tty as tty
-
-from spack.build_systems.autotools import AutotoolsPackage
-from spack.build_systems.cmake import CMakePackage
-from spack.build_systems.qmake import QMakePackage
-from spack.build_systems.scons import SConsPackage
-from spack.build_systems.waf import WafPackage
-from spack.build_systems.python import PythonPackage
-from spack.build_systems.perl import PerlPackage
-from spack.build_systems.meson import MesonPackage
-from spack.build_systems.sip import SIPPackage
-
-description = 'DEPRECATED: stops at build stage when installing a package'
-section = "build"
-level = "long"
-
-
-build_system_to_phase = {
-    AutotoolsPackage: 'build',
-    CMakePackage: 'build',
-    QMakePackage: 'build',
-    SConsPackage: 'build',
-    WafPackage: 'build',
-    PythonPackage: 'build',
-    PerlPackage: 'build',
-    MesonPackage: 'build',
-    SIPPackage: 'build',
-}
-
-
-def setup_parser(subparser):
-    cfg.setup_parser(subparser)
-
-
-def build(parser, args):
-    tty.warn("This command is deprecated. Use `spack install --until` to"
-             " select an end phase instead. The `spack build` command will be"
-             " removed in a future version of Spack")
-    cfg._stop_at_phase_during_install(args, build, build_system_to_phase)