Pipelines: pass relative artifact paths to child jobs (#24085)

Passing absolute paths from pipeline generate job to downstream rebuild jobs
causes problems when the CI_PROJECT_DIR is not the same for the generate and
rebuild jobs.  This has happened, for example, when gitlab checks out the
project into a runner-specific directory and different runners are chosen
for the generate and rebuild jobs.

.dockerignore

@@ -8,4 +8,4 @@ share/spack/dotkit/*
 share/spack/lmod/*
 share/spack/modules/*
 lib/spack/spack/test/*
-
+var/spack/cache/*

.flake8

@@ -27,6 +27,47 @@
 # - N813: camelcase imported as lowercase
 # - N814: camelcase imported as constant
 #
+# F4: pyflakes import checks, these are now checked by mypy more precisely
+# - F403: from module import *
+# - F405: undefined name or from *
+#
+# Black ignores, these are incompatible with black style and do not follow PEP-8
+# - E203: white space around slice operators can be required, ignore : warn
+# - W503: see above, already ignored for line-breaks
+#
 [flake8]
-ignore = E129,E221,E241,E272,E731,W503,W504,F999,N801,N813,N814
-max-line-length = 79
+ignore = E129,E221,E241,E272,E731,W503,W504,F999,N801,N813,N814,F403,F405
+max-line-length = 88
+
+# F4: Import
+# - F405: `name` may be undefined, or undefined from star imports: `module`
+#
+# F8: Name
+# - F821: undefined name `name`
+#
+per-file-ignores =
+  var/spack/repos/*/package.py:F405,F821
+
+# exclude things we usually do not want linting for.
+# These still get linted when passed explicitly, as when spack flake8 passes
+# them on the command line.
+exclude =
+  .git
+  etc/
+  opt/
+  share/
+  var/spack/cache/
+  var/spack/gpg*/
+  var/spack/junit-report/
+  var/spack/mock-configs/
+  lib/spack/external
+  __pycache__
+  var
+
+format = spack
+
+[flake8:local-plugins]
+report =
+  spack = flake8_formatter:SpackFormatter
+paths =
+  ./share/spack/qa/

.flake8_packages

@@ -1,24 +0,0 @@
-# -*- conf -*-
-# flake8 settings for Spack package files.
-#
-# This should include all the same exceptions that we use for core files.
-#
-# In Spack packages, we also allow the single `from spack import *`
-# wildcard import and dependencies can set globals for their
-# dependents. So we add exceptions for checks related to undefined names.
-#
-# 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 (because we *only* allow that wildcard).
-#
-# See .flake8 for regular exceptions.
-#
-# F4: Import
-# - F405: `name` may be undefined, or undefined from star imports: `module`
-#
-# F8: Name
-# - F821: undefined name `name`
-#
-[flake8]
-ignore = E129,E221,E241,E272,E731,W503,W504,F405,F821,F999,N801,N813,N814
-max-line-length = 79

.gitattributes

@@ -1 +1,3 @@
 *.py diff=python
+*.lp linguist-language=Prolog
+lib/spack/external/* linguist-vendored

.github/actions/add-maintainers-as-reviewers/entrypoint.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 #
-# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2021 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)

.github/dependabot.yml

@@ -0,0 +1,7 @@
+version: 2
+updates:
+  # Maintain dependencies for GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "daily"

.github/workflows/linux_build_tests.yaml

@@ -5,6 +5,18 @@ on:
     branches:
     - develop
     - releases/**
+    paths-ignore:
+      # Don't run if we only modified packages in the built-in repository
+      - 'var/spack/repos/builtin/**'
+      - '!var/spack/repos/builtin/packages/lz4/**'
+      - '!var/spack/repos/builtin/packages/mpich/**'
+      - '!var/spack/repos/builtin/packages/tut/**'
+      - '!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/**'
   pull_request:
     branches:
     - develop
@@ -30,14 +42,14 @@ jobs:
         package:
         - lz4  # MakefilePackage
         - mpich~fortran  # AutotoolsPackage
-        - tut  # WafPackage
+        - 'tut%gcc@:10.99.99'  # WafPackage
         - py-setuptools  # PythonPackage
         - openjpeg  # CMakePackage
         - r-rcpp  # RPackage
         - ruby-rake  # RubyPackage
     steps:
     - uses: actions/checkout@v2
-    - uses: actions/cache@v2
+    - uses: actions/cache@v2.1.6
       with:
         path: ~/.ccache
         key: ccache-build-${{ matrix.package }}

.github/workflows/linux_unit_tests.yaml

@@ -1,150 +0,0 @@
-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, 3.9]
-        concretizer: ['original', 'clingo']
-
-    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
-          # Needed for unit tests
-          sudo apt-get install -y coreutils gfortran graphviz gnupg2 mercurial
-          sudo apt-get install -y ninja-build patchelf
-          # Needed for kcov
-          sudo apt-get -y install cmake binutils-dev libcurl4-openssl-dev
-          sudo apt-get -y install 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: Bootstrap clingo from sources
-      if: ${{ matrix.concretizer == 'clingo' }}
-      run: |
-          . share/spack/setup-env.sh
-          spack external find --not-buildable cmake bison
-          spack -v solve zlib
-    - name: Run unit tests
-      env:
-          COVERAGE: true
-          SPACK_TEST_SOLVER: ${{ matrix.concretizer }}
-      run: |
-          share/spack/qa/run-unit-tests
-          coverage combine
-          coverage xml
-    - uses: codecov/codecov-action@v1
-      with:
-        flags: unittests,linux,${{ matrix.concretizer }}
-  shell:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v2
-      with:
-        fetch-depth: 0
-    - uses: actions/setup-python@v2
-      with:
-        python-version: 3.9
-    - name: Install System packages
-      run: |
-          sudo apt-get -y update
-          # Needed for shell tests
-          sudo apt-get install -y coreutils csh zsh tcsh fish dash bash
-          # Needed for kcov
-          sudo apt-get -y install cmake binutils-dev libcurl4-openssl-dev
-          sudo apt-get -y install 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
-
-  clingo-cffi:
-    # Test for the clingo based solver (using clingo-cffi)
-    runs-on: ubuntu-latest
-    container: spack/github-actions:clingo-cffi
-    steps:
-      - name: Run unit tests
-        run: |
-          whoami && echo PWD=$PWD && echo HOME=$HOME && echo SPACK_TEST_SOLVER=$SPACK_TEST_SOLVER
-          python3 -c "import clingo; print(hasattr(clingo.Symbol, '_rep'), clingo.__version__)"
-          git clone https://github.com/spack/spack.git && cd spack
-          git fetch origin ${{ github.ref }}:test-branch
-          git checkout test-branch
-          . share/spack/setup-env.sh
-          spack compiler find
-          spack solve mpileaks%gcc
-          coverage run $(which spack) unit-test -v
-          coverage combine
-          coverage xml
-      - uses: codecov/codecov-action@v1
-        with:
-          flags: unittests,linux,clingo

.github/workflows/macos_unit_tests.yaml

@@ -1,44 +0,0 @@
-name: macos tests
-
-on:
-  push:
-    branches:
-      - develop
-      - releases/**
-  pull_request:
-    branches:
-      - develop
-      - releases/**
-jobs:
-  build:
-    runs-on: macos-latest
-    strategy:
-      matrix:
-        python-version: [3.8]
-    steps:
-    - uses: actions/checkout@v2
-      with:
-        fetch-depth: 0
-    - uses: actions/setup-python@v2
-      with:
-        python-version: ${{ matrix.python-version }}
-    - 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 dash fish gcc gnupg2 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/style_and_docs.yaml

@@ -1,65 +0,0 @@
-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.9
-    - 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.9
-    - 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.9
-    - 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

.github/workflows/unit_tests.yaml

@@ -0,0 +1,389 @@
+name: linux tests
+
+on:
+  push:
+    branches:
+      - develop
+      - releases/**
+  pull_request:
+    branches:
+      - develop
+      - releases/**
+jobs:
+  # Validate that the code can be run on all the Python versions
+  # supported by Spack
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions/setup-python@v2
+      with:
+        python-version: 3.9
+    - name: Install Python Packages
+      run: |
+        pip install --upgrade pip
+        pip install --upgrade vermin
+    - name: vermin (Spack's Core)
+      run: vermin --backport argparse --backport typing -t=2.6- -t=3.5- -v lib/spack/spack/ lib/spack/llnl/ bin/
+    - name: vermin (Repositories)
+      run: vermin --backport argparse --backport typing -t=2.6- -t=3.5- -v var/spack/repos
+  # Run style checks on the files that have been changed
+  style:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+    - uses: actions/setup-python@v2
+      with:
+        python-version: 3.9
+    - name: Install Python packages
+      run: |
+        pip install --upgrade pip six setuptools flake8 mypy>=0.800 black
+    - name: Setup git configuration
+      run: |
+        # Need this for the git tests to succeed.
+        git --version
+        . .github/workflows/setup_git.sh
+    - name: Run style tests
+      run: |
+          share/spack/qa/run-style-tests
+  # Build the documentation
+  documentation:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions/setup-python@v2
+      with:
+        python-version: 3.9
+    - 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
+
+  # Check which files have been updated by the PR
+  changes:
+    runs-on: ubuntu-latest
+    # Set job outputs to values from filter step
+    outputs:
+      core: ${{ steps.filter.outputs.core }}
+      packages: ${{ steps.filter.outputs.packages }}
+      with_coverage: ${{ steps.coverage.outputs.with_coverage }}
+    steps:
+    - uses: actions/checkout@v2
+      if: ${{ github.event_name == 'push' }}
+      with:
+        fetch-depth: 0
+    # For pull requests it's not necessary to checkout the code
+    - uses: dorny/paths-filter@v2
+      id: filter
+      with:
+        # See https://github.com/dorny/paths-filter/issues/56 for the syntax used below
+        filters: |
+          core:
+          - './!(var/**)/**'
+          packages:
+          - 'var/**'
+    # Some links for easier reference:
+    #
+    # "github" context: https://docs.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions#github-context
+    # job outputs: https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idoutputs
+    # setting environment variables from earlier steps: https://docs.github.com/en/actions/reference/workflow-commands-for-github-actions#setting-an-environment-variable
+    #
+    - id: coverage
+      # Run the subsequent jobs with coverage if core has been modified,
+      # regardless of whether this is a pull request or a push to a branch
+      run: |
+        echo Core changes: ${{ steps.filter.outputs.core }}
+        echo Event name: ${{ github.event_name }}
+        if [ "${{ steps.filter.outputs.core }}" == "true" ]
+        then
+          echo "::set-output name=with_coverage::true"
+        else
+          echo "::set-output name=with_coverage::false"
+        fi
+
+  # Run unit tests with different configurations on linux
+  unittests:
+    needs: [ validate, style, documentation, changes ]
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [2.7, 3.5, 3.6, 3.7, 3.8, 3.9]
+        concretizer: ['original', 'clingo']
+    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
+          # Needed for unit tests
+          sudo apt-get install -y coreutils gfortran graphviz gnupg2 mercurial
+          sudo apt-get install -y ninja-build patchelf
+          # Needed for kcov
+          sudo apt-get -y install cmake binutils-dev libcurl4-openssl-dev
+          sudo apt-get -y install 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
+      if: ${{ needs.changes.outputs.with_coverage == 'true' }}
+      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: Bootstrap clingo from sources
+      if: ${{ matrix.concretizer == 'clingo' }}
+      run: |
+          . share/spack/setup-env.sh
+          spack external find --not-buildable cmake bison
+          spack -v solve zlib
+    - name: Run unit tests (full suite with coverage)
+      if: ${{ needs.changes.outputs.with_coverage == 'true' }}
+      env:
+          COVERAGE: true
+          SPACK_TEST_SOLVER: ${{ matrix.concretizer }}
+      run: |
+          share/spack/qa/run-unit-tests
+          coverage combine
+          coverage xml
+    - name: Run unit tests (reduced suite without coverage)
+      if: ${{ needs.changes.outputs.with_coverage == 'false' }}
+      env:
+          ONLY_PACKAGES: true
+          SPACK_TEST_SOLVER: ${{ matrix.concretizer }}
+      run: |
+          share/spack/qa/run-unit-tests
+    - uses: codecov/codecov-action@v1
+      if: ${{ needs.changes.outputs.with_coverage == 'true' }}
+      with:
+        flags: unittests,linux,${{ matrix.concretizer }}
+  # Test shell integration
+  shell:
+    needs: [ validate, style, documentation, changes ]
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+    - uses: actions/setup-python@v2
+      with:
+        python-version: 3.9
+    - name: Install System packages
+      run: |
+          sudo apt-get -y update
+          # Needed for shell tests
+          sudo apt-get install -y coreutils csh zsh tcsh fish dash bash
+          # Needed for kcov
+          sudo apt-get -y install cmake binutils-dev libcurl4-openssl-dev
+          sudo apt-get -y install 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
+      if: ${{ needs.changes.outputs.with_coverage == 'true' }}
+      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 (without coverage)
+      if: ${{ needs.changes.outputs.with_coverage == 'false' }}
+      run: |
+          share/spack/qa/run-shell-tests
+    - name: Run shell tests (with coverage)
+      if: ${{ needs.changes.outputs.with_coverage == 'true' }}
+      env:
+          COVERAGE: true
+      run: |
+          share/spack/qa/run-shell-tests
+    - uses: codecov/codecov-action@v1
+      if: ${{ needs.changes.outputs.with_coverage == 'true' }}
+      with:
+        flags: shelltests,linux
+  # Test for Python2.6 run on Centos 6
+  centos6:
+    needs: [ validate, style, documentation, changes ]
+    runs-on: ubuntu-latest
+    container: spack/github-actions:centos6
+    steps:
+    - name: Run unit tests (full test-suite)
+      # The CentOS 6 container doesn't run with coverage, but
+      # under the same conditions it runs the full test suite
+      if: ${{ needs.changes.outputs.with_coverage == 'true' }}
+      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
+    - name: Run unit tests (only package tests)
+      if: ${{ needs.changes.outputs.with_coverage == 'false' }}
+      env:
+          HOME: /home/spack-test
+          ONLY_PACKAGES: true
+      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
+
+  # Test RHEL8 UBI with platform Python. This job is run
+  # only on PRs modifying core Spack
+  rhel8-platform-python:
+    needs: [ validate, style, documentation, changes ]
+    runs-on: ubuntu-latest
+    if: ${{ needs.changes.outputs.with_coverage == 'true' }}
+    container: registry.access.redhat.com/ubi8/ubi
+    steps:
+    - name: Install dependencies
+      run: |
+          dnf install -y \
+              bzip2 curl file gcc-c++ gcc gcc-gfortran git gnupg2 gzip \
+              make patch tcl unzip which xz
+    - uses: actions/checkout@v2
+    - name: Setup repo and non-root user
+      run: |
+          git --version
+          git fetch --unshallow
+          . .github/workflows/setup_git.sh
+          useradd spack-test
+          chown -R spack-test .
+    - name: Run unit tests
+      shell: runuser -u spack-test -- bash {0}
+      run: |
+          source share/spack/setup-env.sh
+          spack unit-test -k 'not svn and not hg' -x --verbose
+  # Test for the clingo based solver (using clingo-cffi)
+  clingo-cffi:
+    needs: [ validate, style, documentation, changes ]
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+    - uses: actions/setup-python@v2
+      with:
+        python-version: 3.9
+    - name: Install System packages
+      run: |
+          sudo apt-get -y update
+          # Needed for unit tests
+          sudo apt-get install -y coreutils gfortran graphviz gnupg2 mercurial
+          sudo apt-get install -y ninja-build patchelf
+          # Needed for kcov
+          sudo apt-get -y install cmake binutils-dev libcurl4-openssl-dev
+          sudo apt-get -y install zlib1g-dev libdw-dev libiberty-dev
+    - name: Install kcov for bash script coverage
+      if: ${{ needs.changes.outputs.with_coverage == 'true' }}
+      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: Install Python packages
+      run: |
+          pip install --upgrade pip six setuptools codecov coverage clingo
+    - name: Setup git configuration
+      run: |
+          # Need this for the git tests to succeed.
+          git --version
+          . .github/workflows/setup_git.sh
+    - name: Run unit tests (full suite with coverage)
+      if: ${{ needs.changes.outputs.with_coverage == 'true' }}
+      env:
+          COVERAGE: true
+          SPACK_TEST_SOLVER: clingo
+      run: |
+          share/spack/qa/run-unit-tests
+          coverage combine
+          coverage xml
+    - name: Run unit tests (reduced suite without coverage)
+      if: ${{ needs.changes.outputs.with_coverage == 'false' }}
+      env:
+          ONLY_PACKAGES: true
+          SPACK_TEST_SOLVER: clingo
+      run: |
+          share/spack/qa/run-unit-tests
+    - uses: codecov/codecov-action@v1
+      if: ${{ needs.changes.outputs.with_coverage == 'true' }}
+      with:
+        flags: unittests,linux,clingo
+  # Run unit tests on MacOS
+  build:
+    needs: [ validate, style, documentation, changes ]
+    runs-on: macos-latest
+    strategy:
+      matrix:
+        python-version: [3.8]
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+    - uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install Python packages
+      run: |
+          pip install --upgrade pip six setuptools
+          pip install --upgrade codecov coverage
+          pip install --upgrade flake8 pep8-naming mypy
+    - name: Setup Homebrew packages
+      run: |
+        brew install dash fish gcc gnupg2 kcov
+    - name: Run unit tests
+      run: |
+        git --version
+        . .github/workflows/setup_git.sh
+        . share/spack/setup-env.sh
+        if [ "${{ needs.changes.outputs.with_coverage }}" == "true" ]
+        then
+          coverage run $(which spack) unit-test -x
+          coverage combine
+          coverage xml
+        else
+          echo "ONLY PACKAGE RECIPES CHANGED [skipping coverage]"
+          $(which spack) unit-test -x -m "not maybeslow" -k "package_sanity"
+        fi
+    - uses: codecov/codecov-action@v1
+      if: ${{ needs.changes.outputs.with_coverage == 'true' }}
+      with:
+        file: ./coverage.xml
+        flags: unittests,macos

.gitignore

@@ -1,40 +1,511 @@
-/db
+##########################
+# Spack-specific ignores #
+##########################
+
 /var/spack/stage
 /var/spack/cache
 /var/spack/environments
 /var/spack/repos/*/index.yaml
 /var/spack/repos/*/lock
-__pycache__/
-*.pyc
 /opt
-*~
-.DS_Store
-.idea
 # Ignore everything in /etc/spack except /etc/spack/defaults
 /etc/spack/*
 !/etc/spack/defaults
-/etc/spackconfig
-/share/spack/dotkit
 /share/spack/modules
 /share/spack/lmod
-/TAGS
-*.swp
-/htmlcov
-.coverage
-\#*
-.#*
-.cache
-lib/spack/spack/test/.cache
-/bin/spackc
+# Debug logs
+spack-db.*
 *.in.log
 *.out.log
-*.orig
 
-# Eclipse files
-.project
+###########################
+# Python-specific ignores #
+###########################
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+#lib/
+#lib64/
+parts/
+sdist/
+#var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+########################
+# Vim-specific ignores #
+########################
+
+# Swap
+[._]*.s[a-v][a-z]
+!*.svg  # comment out if you don't need vector files
+[._]*.sw[a-p]
+[._]s[a-rt-v][a-z]
+[._]ss[a-gi-z]
+[._]sw[a-p]
+
+# Session
+Session.vim
+Sessionx.vim
+
+# Temporary
+.netrwhist
+*~
+# Auto-generated tag files
+tags
+# Persistent undo
+[._]*.un~
+
+##########################
+# Emacs-specific ignores #
+##########################
+
+*~
+\#*\#
+/.emacs.desktop
+/.emacs.desktop.lock
+*.elc
+auto-save-list
+tramp
+.\#*
+
+# Org-mode
+.org-id-locations
+*_archive
+
+# flymake-mode
+*_flymake.*
+
+# eshell files
+/eshell/history
+/eshell/lastdir
+
+# elpa packages
+/elpa/
+
+# reftex files
+*.rel
+
+# AUCTeX auto folder
+/auto/
+
+# cask packages
+.cask/
+dist/
+
+# Flycheck
+flycheck_*.el
+
+# server auth directory
+/server/
+
+# projectiles files
+.projectile
+
+# directory configuration
+.dir-locals.el
+
+# network security
+/network-security.data
+
+############################
+# Eclipse-specific ignores #
+############################
+
+.metadata
+#bin/
+tmp/
+*.tmp
+*.bak
+*.swp
+*~.nib
+local.properties
+.settings/
+.loadpath
+.recommenders
+
+# External tool builders
+.externalToolBuilders/
+
+# Locally stored "Eclipse launch configurations"
+*.launch
+
+# PyDev specific (Python IDE for Eclipse)
+*.pydevproject
+
+# CDT-specific (C/C++ Development Tooling)
 .cproject
-.pydevproject
 
-# VSCode files
-.vscode
-.devcontainer
+# CDT- autotools
+.autotools
+
+# Java annotation processor (APT)
+.factorypath
+
+# PDT-specific (PHP Development Tools)
+.buildpath
+
+# sbteclipse plugin
+.target
+
+# Tern plugin
+.tern-project
+
+# TeXlipse plugin
+.texlipse
+
+# STS (Spring Tool Suite)
+.springBeans
+
+# Code Recommenders
+.recommenders/
+
+# Annotation Processing
+.apt_generated/
+.apt_generated_test/
+
+# Scala IDE specific (Scala & Java development for Eclipse)
+.cache-main
+.scala_dependencies
+.worksheet
+
+# Uncomment this line if you wish to ignore the project description file.
+# Typically, this file would be tracked if it contains build/dependency configurations:
+#.project
+
+##################################
+# Visual Studio-specific ignores #
+##################################
+
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+*.code-workspace
+
+# Local History for Visual Studio Code
+.history/
+
+#################################
+# Sublime Text-specific ignores #
+#################################
+
+# Cache files for Sublime Text
+*.tmlanguage.cache
+*.tmPreferences.cache
+*.stTheme.cache
+
+# Workspace files are user-specific
+*.sublime-workspace
+
+# Project files should be checked into the repository, unless a significant
+# proportion of contributors will probably not be using Sublime Text
+# *.sublime-project
+
+# SFTP configuration file
+sftp-config.json
+sftp-config-alt*.json
+
+# Package control specific files
+Package Control.last-run
+Package Control.ca-list
+Package Control.ca-bundle
+Package Control.system-ca-bundle
+Package Control.cache/
+Package Control.ca-certs/
+Package Control.merged-ca-bundle
+Package Control.user-ca-bundle
+oscrypto-ca-bundle.crt
+bh_unicode_properties.cache
+
+# Sublime-github package stores a github token in this file
+# https://packagecontrol.io/packages/sublime-github
+GitHub.sublime-settings
+
+##############################
+# JetBrains-specific ignores #
+##############################
+
+# Ignore the entire folder since it may conatin more files than
+# just the ones listed below
+.idea/
+
+# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
+# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
+
+# User-specific stuff
+.idea/**/workspace.xml
+.idea/**/tasks.xml
+.idea/**/usage.statistics.xml
+.idea/**/dictionaries
+.idea/**/shelf
+
+# Generated files
+.idea/**/contentModel.xml
+
+# Sensitive or high-churn files
+.idea/**/dataSources/
+.idea/**/dataSources.ids
+.idea/**/dataSources.local.xml
+.idea/**/sqlDataSources.xml
+.idea/**/dynamic.xml
+.idea/**/uiDesigner.xml
+.idea/**/dbnavigator.xml
+
+# Gradle
+.idea/**/gradle.xml
+.idea/**/libraries
+
+# Gradle and Maven with auto-import
+# When using Gradle or Maven with auto-import, you should exclude module files,
+# since they will be recreated, and may cause churn.  Uncomment if using
+# auto-import.
+# .idea/artifacts
+# .idea/compiler.xml
+# .idea/jarRepositories.xml
+# .idea/modules.xml
+# .idea/*.iml
+# .idea/modules
+# *.iml
+# *.ipr
+
+# CMake
+cmake-build-*/
+
+# Mongo Explorer plugin
+.idea/**/mongoSettings.xml
+
+# File-based project format
+*.iws
+
+# IntelliJ
+out/
+
+# mpeltonen/sbt-idea plugin
+.idea_modules/
+
+# JIRA plugin
+atlassian-ide-plugin.xml
+
+# Cursive Clojure plugin
+.idea/replstate.xml
+
+# Crashlytics plugin (for Android Studio and IntelliJ)
+com_crashlytics_export_strings.xml
+crashlytics.properties
+crashlytics-build.properties
+fabric.properties
+
+# Editor-based Rest Client
+.idea/httpRequests
+
+# Android studio 3.1+ serialized cache file
+.idea/caches/build_file_checksums.ser
+
+##########################
+# macOS-specific ignores #
+##########################
+
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+##########################
+# Linux-specific ignores #
+##########################
+
+*~
+
+# temporary files which can be created if a process still has a handle open of a deleted file
+.fuse_hidden*
+
+# KDE directory preferences
+.directory
+
+# Linux trash folder which might appear on any partition or disk
+.Trash-*
+
+# .nfs files are created when an open file is removed but is still being accessed
+.nfs*
+
+############################
+# Windows-specific ignores #
+############################
+
+# Windows thumbnail cache files
+Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+
+# Dump file
+*.stackdump
+
+# Folder config file
+[Dd]esktop.ini
+
+# Recycle Bin used on file shares
+$RECYCLE.BIN/
+
+# Windows Installer files
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+
+# Windows shortcuts
+*.lnk

.mailmap

@@ -3,7 +3,8 @@ Adam Moody            <moody20@llnl.gov>                Adam T. Moody
 Alfredo Gimenez       <gimenez1@llnl.gov>               Alfredo Gimenez         <alfredo.gimenez@gmail.com>
 Alfredo Gimenez       <gimenez1@llnl.gov>               Alfredo Adolfo Gimenez  <alfredo.gimenez@gmail.com>
 Andrew Williams       <williamsa89@cardiff.ac.uk>       Andrew Williams         <andrew@alshain.org.uk>
-Axel Huebl            <a.huebl@hzdr.de>                 Axel Huebl              <axel.huebl@plasma.ninja>
+Axel Huebl            <axelhuebl@lbl.gov>               Axel Huebl              <a.huebl@hzdr.de>
+Axel Huebl            <axelhuebl@lbl.gov>               Axel Huebl              <axel.huebl@plasma.ninja>
 Ben Boeckel           <ben.boeckel@kitware.com>         Ben Boeckel             <mathstuf@gmail.com>
 Ben Boeckel           <ben.boeckel@kitware.com>         Ben Boeckel             <mathstuf@users.noreply.github.com>
 Benedikt Hegner       <hegner@cern.ch>                  Benedikt Hegner         <benedikt.hegner@cern.ch>

.mypy.ini

@@ -0,0 +1,35 @@
+[mypy]
+python_version = 3.7
+files=lib/spack/llnl/**/*.py,lib/spack/spack/**/*.py
+mypy_path=bin,lib/spack,lib/spack/external,var/spack/repos/builtin
+# This and a generated import file allows supporting packages
+namespace_packages=True
+# To avoid re-factoring all the externals, ignore errors and missing imports
+# globally, then turn back on in spack and spack submodules
+ignore_errors=True
+ignore_missing_imports=True
+
+[mypy-spack.*]
+ignore_errors=False
+ignore_missing_imports=False
+
+[mypy-packages.*]
+ignore_errors=False
+ignore_missing_imports=False
+
+[mypy-llnl.*]
+ignore_errors=False
+ignore_missing_imports=False
+
+[mypy-spack.test.packages]
+ignore_errors=True
+
+# ignore errors in fake import path for packages
+[mypy-spack.pkg.*]
+ignore_errors=True
+ignore_missing_imports=True
+
+# jinja has syntax in it that requires python3 and causes a parse error
+# skip importing it
+[mypy-jinja2]
+follow_imports=skip

README.md

@@ -1,12 +1,11 @@
 # <img src="https://cdn.rawgit.com/spack/spack/develop/share/spack/logo/spack-logo.svg" width="64" valign="middle" alt="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)
+[![Unit 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)
+[![Slack](https://slack.spack.io/badge.svg)](https://slack.spack.io)
 
 Spack is a multi-platform package manager that builds and installs
 multiple versions and configurations of software. It works on Linux,
@@ -59,7 +58,7 @@ packages to bugfixes, documentation, or even new core features.
 Resources:
 
 * **Slack workspace**: [spackpm.slack.com](https://spackpm.slack.com).
-  To get an invitation, [**click here**](https://spackpm.herokuapp.com).
+  To get an invitation, visit [slack.spack.io](https://slack.spack.io).
 * **Mailing list**: [groups.google.com/d/forum/spack](https://groups.google.com/d/forum/spack)
 * **Twitter**: [@spackpm](https://twitter.com/spackpm). Be sure to
   `@mention` us!
@@ -73,7 +72,7 @@ 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 our CI process. To run these tests locally, and for 
+these guidelines with our CI process. To run these tests locally, and for
 helpful tips on git, see our
 [Contribution Guide](https://spack.readthedocs.io/en/latest/contribution_guide.html).
 

bin/sbang

@@ -1,6 +1,6 @@
 #!/bin/sh
 #
-# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2021 Lawrence Livermore National Security, LLC and other
 # sbang project developers. See the top-level COPYRIGHT file for details.
 #
 # SPDX-License-Identifier: (Apache-2.0 OR MIT)

bin/spack

@@ -1,7 +1,7 @@
 #!/bin/sh
 # -*- python -*-
 #
-# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2021 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)
@@ -10,9 +10,13 @@
 # Following line is a shell no-op, and starts a multi-line Python comment.
 # See https://stackoverflow.com/a/47886254
 """:"
-# prefer python3, then python, then python2
-for cmd in python3 python python2; do
-   command -v > /dev/null $cmd && exec $cmd $0 "$@"
+# prefer SPACK_PYTHON environment variable, python3, python, then python2
+SPACK_PREFERRED_PYTHONS="python3 python python2 /usr/libexec/platform-python"
+for cmd in "${SPACK_PYTHON:-}" ${SPACK_PREFERRED_PYTHONS}; do
+    if command -v > /dev/null "$cmd"; then
+        export SPACK_PYTHON="$(command -v "$cmd")"
+        exec "${SPACK_PYTHON}" "$0" "$@"
+    fi
 done
 
 echo "==> Error: spack could not find a python interpreter!" >&2
@@ -26,10 +30,15 @@ from __future__ import print_function
 import os
 import sys
 
-if sys.version_info[:2] < (2, 6):
+min_python3 = (3, 5)
+
+if sys.version_info[:2] < (2, 6) or (
+    sys.version_info[:2] >= (3, 0) and sys.version_info[:2] < min_python3
+):
     v_info = sys.version_info[:3]
-    sys.exit("Spack requires Python 2.6 or higher."
-             "This is Python %d.%d.%d." % v_info)
+    msg = "Spack requires Python 2.6, 2.7 or %d.%d or higher " % min_python3
+    msg += "You are running spack with Python %d.%d.%d." % v_info
+    sys.exit(msg)
 
 # Find spack's location and its prefix.
 spack_file = os.path.realpath(os.path.expanduser(__file__))
@@ -42,8 +51,10 @@ sys.path.insert(0, spack_lib_path)
 # Add external libs
 spack_external_libs = os.path.join(spack_lib_path, "external")
 
+if sys.version_info[:2] <= (2, 7):
+    sys.path.insert(0, os.path.join(spack_external_libs, "py2"))
 if sys.version_info[:2] == (2, 6):
-    sys.path.insert(0, os.path.join(spack_external_libs, 'py26'))
+    sys.path.insert(0, os.path.join(spack_external_libs, "py26"))
 
 sys.path.insert(0, spack_external_libs)
 
@@ -53,11 +64,11 @@ sys.path.insert(0, spack_external_libs)
 # Briefly: ruamel.yaml produces a .pth file when installed with pip that
 # makes the site installed package the preferred one, even though sys.path
 # is modified to point to another version of ruamel.yaml.
-if 'ruamel.yaml' in sys.modules:
-    del sys.modules['ruamel.yaml']
+if "ruamel.yaml" in sys.modules:
+    del sys.modules["ruamel.yaml"]
 
-if 'ruamel' in sys.modules:
-    del sys.modules['ruamel']
+if "ruamel" in sys.modules:
+    del sys.modules["ruamel"]
 
 import spack.main  # noqa
 

bin/spack-python

@@ -1,6 +1,6 @@
 #!/bin/sh
 #
-# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2021 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)

etc/spack/defaults/config.yaml

@@ -33,13 +33,6 @@ config:
   template_dirs:
     - $spack/share/spack/templates
 
-
-  # Locations where different types of modules should be installed.
-  module_roots:
-    tcl:    $spack/share/spack/modules
-    lmod:   $spack/share/spack/lmod
-
-
   # Temporary locations Spack can try to use for builds.
   #
   # Recommended options are given below.
@@ -107,7 +100,7 @@ config:
   # If set to true, Spack will attempt to build any compiler on the spec
   # that is not already available. If set to False, Spack will only use
   # compilers already configured in compilers.yaml
-  install_missing_compilers: False
+  install_missing_compilers: false
 
 
   # If set to true, Spack will always check checksums after downloading
@@ -115,6 +108,11 @@ config:
   checksum: true
 
 
+  # If set to true, Spack will fetch deprecated versions without warning.
+  # If false, Spack will raise an error when trying to install a deprecated version.
+  deprecated: false
+
+
   # If set to true, `spack install` and friends will NOT clean
   # potentially harmful variables from the build environment. Use wisely.
   dirty: false
@@ -137,11 +135,13 @@ config:
   locks: true
 
 
-  # The maximum number of jobs to use when running `make` in parallel,
-  # always limited by the number of cores available. For instance:
-  # - If set to 16 on a 4 cores machine `spack install` will run `make -j4`
-  # - If set to 16 on a 18 cores machine `spack install` will run `make -j16`
-  # If not set, Spack will use all available cores up to 16.
+  # The maximum number of jobs to use for the build system (e.g. `make`), when
+  # the -j flag is not given on the command line. Defaults to 16 when not set.
+  # Note that the maximum number of jobs is limited by the number of cores
+  # available, taking thread affinity into account when supported. For instance:
+  # - With `build_jobs: 16` and 4 cores available `spack install` will run `make -j4`
+  # - With `build_jobs: 16` and 32 cores available `spack install` will run `make -j16`
+  # - With `build_jobs: 2` and 4 cores available `spack install -j6` will run `make -j6`
   # build_jobs: 16
 
 

etc/spack/defaults/cray/modules.yaml

@@ -0,0 +1,21 @@
+# -------------------------------------------------------------------------
+# This is the default configuration for Spack's module file generation.
+#
+# Settings here are versioned with Spack and are intended to provide
+# sensible defaults out of the box. Spack maintainers should edit this
+# file to keep it current.
+#
+# Users can override these settings by editing the following files.
+#
+# Per-spack-instance settings (overrides defaults):
+#   $SPACK_ROOT/etc/spack/modules.yaml
+#
+# Per-user settings (overrides default and site settings):
+#   ~/.spack/modules.yaml
+# -------------------------------------------------------------------------
+modules:
+  prefix_inspections:
+    lib:
+      - LD_LIBRARY_PATH
+    lib64:
+      - LD_LIBRARY_PATH

etc/spack/defaults/darwin/packages.yaml

@@ -21,10 +21,10 @@ packages:
     - gcc
     - intel
     providers:
-      elf:
-      - libelf
-      unwind:
-      - apple-libunwind
+      elf: [libelf]
+      fuse: [macfuse]
+      unwind: [apple-libunwind]
+      uuid: [apple-libuuid]
   apple-libunwind:
     buildable: false
     externals:
@@ -32,3 +32,10 @@ packages:
     # although the version number used here isn't critical
     - spec: apple-libunwind@35.3
       prefix: /usr
+  apple-libuuid:
+    buildable: false
+    externals:
+    # Apple bundles libuuid in libsystem_c version 1353.100.2,
+    # although the version number used here isn't critical
+    - spec: apple-libuuid@1353.100.2
+      prefix: /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk

etc/spack/defaults/linux/modules.yaml

@@ -14,8 +14,9 @@
 #   ~/.spack/modules.yaml
 # -------------------------------------------------------------------------
 modules:
-  prefix_inspections:
-    lib:
-      - LD_LIBRARY_PATH
-    lib64:
-      - LD_LIBRARY_PATH
+  default:
+    prefix_inspections:
+      lib:
+        - LD_LIBRARY_PATH
+      lib64:
+        - LD_LIBRARY_PATH

etc/spack/defaults/mirrors.yaml

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

etc/spack/defaults/modules.yaml

@@ -14,8 +14,7 @@
 #   ~/.spack/modules.yaml
 # -------------------------------------------------------------------------
 modules:
-  enable:
-    - tcl
+  # Paths to check when creating modules for all module sets
   prefix_inspections:
     bin:
       - PATH
@@ -25,16 +24,6 @@ modules:
       - MANPATH
     share/aclocal:
       - ACLOCAL_PATH
-    lib:
-      - LIBRARY_PATH
-    lib64:
-      - LIBRARY_PATH
-    include:
-      - 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:
@@ -44,6 +33,20 @@ modules:
     '':
       - CMAKE_PREFIX_PATH
 
-  lmod:
-    hierarchy:
-      - mpi
+  # These are configurations for the module set named "default"
+  default:
+    # These values are defaulted in the code. They are not defaulted here so
+    # that we can enable backwards compatibility with the old syntax more
+    # easily (old value is in the config yaml, config:module_roots)
+    # Where to install modules
+    # roots:
+    #  tcl:    $spack/share/spack/modules
+    #  lmod:   $spack/share/spack/lmod
+    # What type of modules to use
+    enable:
+      - tcl
+
+    # Default configurations if lmod is enabled
+    lmod:
+      hierarchy:
+        - mpi

etc/spack/defaults/packages.yaml

@@ -17,15 +17,17 @@ packages:
   all:
     compiler: [gcc, intel, pgi, clang, xl, nag, fj, aocc]
     providers:
-      D: [ldc]
       awk: [gawk]
       blas: [openblas, amdblis]
+      D: [ldc]
       daal: [intel-daal]
       elf: [elfutils]
       fftw-api: [fftw, amdfftw]
-      gl: [mesa+opengl, mesa18+opengl, opengl]
-      glx: [mesa+glx, mesa18+glx, opengl]
+      flame: [libflame, amdlibflame]
+      fuse: [libfuse]
+      gl: [mesa+opengl, mesa18, opengl]
       glu: [mesa-glu, openglu]
+      glx: [mesa+glx, mesa18+glx, opengl]
       golang: [gcc]
       iconv: [libiconv]
       ipp: [intel-ipp]
@@ -47,8 +49,10 @@ packages:
       szip: [libszip, libaec]
       tbb: [intel-tbb]
       unwind: [libunwind]
+      uuid: [util-linux-uuid, libuuid]
+      xxd: [xxd-standalone, vim]
       yacc: [bison, byacc]
-      flame: [libflame, amdlibflame]
+      ziglang: [zig]
     permissions:
       read: world
       write: user

lib/spack/docs/analyze.rst

@@ -0,0 +1,162 @@
+.. Copyright 2013-2021 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)
+
+.. _analyze:
+
+=======
+Analyze
+=======
+
+
+The analyze command is a front-end to various tools that let us analyze
+package installations. Each analyzer is a module for a different kind
+of analysis that can be done on a package installation, including (but not
+limited to) binary, log, or text analysis. Thus, the analyze command group
+allows you to take an existing package install, choose an analyzer,
+and extract some output for the package using it.
+
+
+-----------------
+Analyzer Metadata
+-----------------
+
+For all analyzers, we write to an ``analyzers`` folder in ``~/.spack``, or the
+value that you specify in your spack config at ``config:analyzers_dir``. 
+For example, here we see the results of running an analysis on zlib:
+
+.. code-block:: console
+
+    $ tree ~/.spack/analyzers/
+    └── linux-ubuntu20.04-skylake
+        └── gcc-9.3.0
+            └── zlib-1.2.11-sl7m27mzkbejtkrajigj3a3m37ygv4u2
+                ├── environment_variables
+                │   └── spack-analyzer-environment-variables.json
+                ├── install_files
+                │   └── spack-analyzer-install-files.json
+                └── libabigail
+                    └── spack-analyzer-libabigail-libz.so.1.2.11.xml
+    
+
+This means that you can always find analyzer output in this folder, and it
+is organized with the same logic as the package install it was run for. 
+If you want to customize this top level folder, simply provide the ``--path``
+argument to ``spack analyze run``. The nested organization will be maintained
+within your custom root.
+
+-----------------
+Listing Analyzers
+-----------------
+
+If you aren't familiar with Spack's analyzers, you can quickly list those that 
+are available:
+
+.. code-block:: console
+
+    $ spack analyze list-analyzers
+    install_files            : install file listing read from install_manifest.json
+    environment_variables    : environment variables parsed from spack-build-env.txt
+    config_args              : config args loaded from spack-configure-args.txt
+    abigail                  : Application Binary Interface (ABI) features for objects
+
+
+In the above, the first three are fairly simple - parsing metadata files from
+a package install directory to save
+
+-------------------
+Analyzing a Package
+-------------------
+
+The analyze command, akin to install, will accept a package spec to perform
+an analysis for. The package must be installed. Let's walk through an example
+with zlib. We first ask to analyze it. However, since we have more than one
+install, we are asked to disambiguate:
+
+.. code-block:: console
+
+    $ spack analyze run zlib
+    ==> Error: zlib matches multiple packages.
+      Matching packages:
+        fz2bs56 zlib@1.2.11%gcc@7.5.0 arch=linux-ubuntu18.04-skylake
+        sl7m27m zlib@1.2.11%gcc@9.3.0 arch=linux-ubuntu20.04-skylake
+      Use a more specific spec.
+
+
+We can then specify the spec version that we want to analyze:
+
+.. code-block:: console
+
+    $ spack analyze run zlib/fz2bs56
+
+If you don't provide any specific analyzer names, by default all analyzers 
+(shown in the ``list-analyzers`` subcommand list) will be run. If an analyzer does not
+have any result, it will be skipped. For example, here is a result running for
+zlib:
+
+.. code-block:: console
+
+    $ ls ~/.spack/analyzers/linux-ubuntu20.04-skylake/gcc-9.3.0/zlib-1.2.11-sl7m27mzkbejtkrajigj3a3m37ygv4u2/
+    spack-analyzer-environment-variables.json
+    spack-analyzer-install-files.json
+    spack-analyzer-libabigail-libz.so.1.2.11.xml
+
+If you want to run a specific analyzer, ask for it with `--analyzer`. Here we run
+spack analyze on libabigail (already installed) _using_ libabigail1
+
+.. code-block:: console
+
+    $ spack analyze run --analyzer abigail libabigail
+
+
+.. _analyze_monitoring:
+
+----------------------
+Monitoring An Analysis
+----------------------
+
+For any kind of analysis, you can
+use a `spack monitor <https://github.com/spack/spack-monitor>`_ "Spackmon"
+as a server to upload the same run metadata to. You can
+follow the instructions in the `spack monitor documentation <https://spack-monitor.readthedocs.org>`_
+to first create a server along with a username and token for yourself.
+You can then use this guide to interact with the server.
+
+You should first export our spack monitor token and username to the environment:
+
+.. code-block:: console
+ 
+    $ export SPACKMON_TOKEN=50445263afd8f67e59bd79bff597836ee6c05438
+    $ export SPACKMON_USER=spacky
+
+
+By default, the host for your server is expected to be at ``http://127.0.0.1``
+with a prefix of ``ms1``, and if this is the case, you can simply add the
+``--monitor`` flag to the install command:
+
+.. code-block:: console
+
+    $ spack analyze run --monitor wget
+
+If you need to customize the host or the prefix, you can do that as well:
+
+.. code-block:: console
+
+    $ spack analyze run --monitor --monitor-prefix monitor --monitor-host https://monitor-service.io wget
+
+If your server doesn't have authentication, you can skip it:
+
+.. code-block:: console
+
+    $ spack analyze run --monitor --monitor-disable-auth wget
+    
+Regardless of your choice, when you run analyze on an installed package (whether
+it was installed with ``--monitor`` or not, you'll see the results generating as they did
+before, and a message that the monitor server was pinged:
+
+.. code-block:: console
+
+    $ spack analyze --monitor wget
+    ...
+    ==> Sending result for wget bin/wget to monitor.

lib/spack/docs/basic_usage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)
@@ -27,12 +27,18 @@ It is recommended that the following be put in your ``.bashrc`` file:
 
 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.
+colorized output with a flag
 
 .. code-block:: console
 
     $ spack --color always | less -R
 
+or an environment variable
+
+.. code-block:: console
+
+   $ SPACK_COLOR=always spack | less -R
+
 --------------------------
 Listing available packages
 --------------------------
@@ -133,8 +139,7 @@ dependencies first.  It then fetches the ``mpileaks`` tarball, expands
 it, verifies that it was downloaded without errors, builds it, and
 installs it in its own directory under ``$SPACK_ROOT/opt``. You'll see
 a number of messages from Spack, a lot of build output, and a message
-that the package is installed.  Add one or more debug options (``-d``)
-to get increasingly detailed output.
+that the package is installed.
 
 .. code-block:: console
 
@@ -151,8 +156,8 @@ to get increasingly detailed output.
 The last line, with the ``[+]``, indicates where the package is
 installed.
 
-Add the debug option -- ``spack  install -d mpileaks`` -- to get additional
-output.
+Add the Spack debug option (one or more times) -- ``spack -d install
+mpileaks`` -- to get additional (and even more verbose) output.
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Building a specific version
@@ -964,7 +969,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 built with debug
+``spack install mercury debug=True`` will install mercury 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.
@@ -972,11 +977,11 @@ provide information on what build variants are available.
 For compatibility with earlier versions, variants which happen to be
 boolean in nature can be specified by a syntax that represents turning
 options on and off. For example, in the previous spec we could have
-supplied ``libelf +debug`` with the same effect of enabling the debug
+supplied ``mercury +debug`` with the same effect of enabling the debug
 compile time option for the libelf package.
 
 Depending on the package a variant may have any default value.  For
-``libelf`` here, ``debug`` is ``False`` by default, and we turned it on
+``mercury`` here, ``debug`` is ``False`` by default, and we turned it on
 with ``debug=True`` or ``+debug``.  If a variant is ``True`` by default
 you can turn it off by either adding ``-name`` or ``~name`` to the spec.
 

lib/spack/docs/binary_caches.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)

lib/spack/docs/build_settings.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)

lib/spack/docs/build_systems.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)
@@ -59,7 +59,9 @@ on these ideas for each distinct build system that Spack supports:
 
    build_systems/bundlepackage
    build_systems/cudapackage
+   build_systems/inteloneapipackage
    build_systems/intelpackage
+   build_systems/rocmpackage
    build_systems/custompackage
 
 For reference, the :py:mod:`Build System API docs <spack.build_systems>`

lib/spack/docs/build_systems/autotoolspackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)
@@ -155,7 +155,7 @@ version, this can be done like so:
 
    @property
    def force_autoreconf(self):
-       return self.version == Version('1.2.3'):
+       return self.version == Version('1.2.3')
 
 ^^^^^^^^^^^^^^^^^^^^^^^
 Finding configure flags

lib/spack/docs/build_systems/bundlepackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)

lib/spack/docs/build_systems/cmakepackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)

lib/spack/docs/build_systems/cudapackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)
@@ -9,35 +9,120 @@
 CudaPackage
 -----------
 
-Different from other packages, ``CudaPackage`` does not represent a build
-system. Instead its goal is to simplify and unify usage of ``CUDA`` in other
-packages.
+Different from other packages, ``CudaPackage`` does not represent a build system.
+Instead its goal is to simplify and unify usage of ``CUDA`` in other packages by providing a `mixin-class <https://en.wikipedia.org/wiki/Mixin>`_.
 
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Provided variants and dependencies
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+You can find source for the package at
+`<https://github.com/spack/spack/blob/develop/lib/spack/spack/build_systems/cuda.py>`__.
 
-``CudaPackage`` provides ``cuda`` variant (default to ``off``) to enable/disable
-``CUDA``, and ``cuda_arch`` variant to optionally specify the architecture.
-It also declares dependencies on the ``CUDA`` package ``depends_on('cuda@...')``
-based on the architecture as well as specifies conflicts for certain compiler versions.
+^^^^^^^^
+Variants
+^^^^^^^^
+
+This package provides the following variants:
+
+* **cuda**
+
+  This variant is used to enable/disable building with ``CUDA``. The default
+  is disabled (or ``False``).
+
+* **cuda_arch**
+
+  This variant supports the optional specification of the architecture.
+  Valid values are maintained in the ``cuda_arch_values`` property and
+  are the numeric character equivalent of the compute capability version
+  (e.g., '10' for version 1.0). Each provided value affects associated
+  ``CUDA`` dependencies and compiler conflicts.
+
+  GPUs and their compute capability versions are listed at
+  https://developer.nvidia.com/cuda-gpus .
+
+^^^^^^^^^
+Conflicts
+^^^^^^^^^
+
+Conflicts are used to prevent builds with known bugs or issues. While
+base ``CUDA`` conflicts have been included with this package, you may
+want to add more for your software.
+
+For example, if your package requires ``cuda_arch`` to be specified when
+``cuda`` is enabled, you can add the following conflict to your package
+to terminate such build attempts with a suitable message:
+
+.. code-block:: python
+
+    conflicts('cuda_arch=none', when='+cuda',
+              msg='CUDA architecture is required')
+
+Similarly, if your software does not support all versions of the property,
+you could add ``conflicts`` to your package for those versions.  For example,
+suppose your software does not work with CUDA compute capability versions
+prior to SM 5.0 (``50``).  You can add the following code to display a
+custom message should a user attempt such a build:
+
+.. code-block:: python
+
+    unsupported_cuda_archs = [
+        '10', '11', '12', '13',
+        '20', '21',
+        '30', '32', '35', '37'
+    ]
+    for value in unsupported_cuda_archs:
+        conflicts('cuda_arch={0}'.format(value), when='+cuda',
+                  msg='CUDA architecture {0} is not supported'.format(value))
+
+^^^^^^^
+Methods
+^^^^^^^
+
+This package provides one custom helper method, which is used to build
+standard CUDA compiler flags.
+
+**cuda_flags**
+
+    This built-in static method returns a list of command line flags 
+    for the chosen ``cuda_arch`` value(s).  The flags are intended to
+    be passed to the CUDA compiler driver (i.e., ``nvcc``).
+
+    This method must be explicitly called when you are creating the
+    arguments for your build in order to use the values.
 
 ^^^^^
 Usage
 ^^^^^
 
-In order to use it, just add another base class to your package, for example:
+This helper package can be added to your package by adding it as a base
+class of your package.  For example, you can add it to your
+:ref:`CMakePackage <cmakepackage>`-based package as follows:
 
 .. code-block:: python
+   :emphasize-lines: 1,7-16
 
-    class MyPackage(CMakePackage, CudaPackage):
+    class MyCudaPackage(CMakePackage, CudaPackage):
         ...
         def cmake_args(self):
             spec = self.spec
+            args = []
+            ...
             if '+cuda' in spec:
-                options.append('-DWITH_CUDA=ON')
-                cuda_arch = spec.variants['cuda_arch'].value
+                # Set up the cuda macros needed by the build
+                args.append('-DWITH_CUDA=ON')
+                cuda_arch_list = spec.variants['cuda_arch'].value
+                cuda_arch = cuda_arch_list[0]
                 if cuda_arch != 'none':
-                    options.append('-DCUDA_FLAGS=-arch=sm_{0}'.format(cuda_arch[0]))
+                    args.append('-DCUDA_FLAGS=-arch=sm_{0}'.format(cuda_arch))
             else:
-                options.append('-DWITH_CUDA=OFF')
+                # Ensure build with cuda is disabled
+                args.append('-DWITH_CUDA=OFF')
+            ...
+            return args
+
+assuming only the ``WITH_CUDA`` and ``CUDA_FLAGS`` flags are required.
+You will need to customize options as needed for your build.
+
+This example also illustrates how to check for the ``cuda`` variant using
+``self.spec`` and how to retrieve the ``cuda_arch`` variant's value, which
+is a list, using ``self.spec.variants['cuda_arch'].value``.
+
+With over 70 packages using ``CudaPackage`` as of January 2021 there are
+lots of examples to choose from to get more ideas for using this package.

lib/spack/docs/build_systems/custompackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)
@@ -9,7 +9,7 @@
 Custom Build Systems
 --------------------
 
-While the build systems listed above should meet your needs for the
+While the built-in build systems should meet your needs for the
 vast majority of packages, some packages provide custom build scripts.
 This guide is intended for the following use cases:
 
@@ -31,7 +31,7 @@ installation. Both of these packages require custom build systems.
 Base class
 ^^^^^^^^^^
 
-If your package does not belong to any of the aforementioned build
+If your package does not belong to any of the built-in build
 systems that Spack already supports, you should inherit from the
 ``Package`` base class. ``Package`` is a simple base class with a
 single phase: ``install``. If your package is simple, you may be able
@@ -168,7 +168,8 @@ if and only if this flag is set, we would use the following line:
 Testing
 ^^^^^^^
 
-Let's put everything together and add unit tests to our package.
+Let's put everything together and add unit tests to be optionally run
+during the installation of our package.
 In the ``perl`` package, we can see:
 
 .. code-block:: python
@@ -182,12 +183,6 @@ As you can guess, this runs ``make test`` *after* building the package,
 if and only if testing is requested. Again, this is not specific to
 custom build systems, it can be added to existing build systems as well.
 
-Ideally, every package in Spack will have some sort of test to ensure
-that it was built correctly. It is up to the package authors to make
-sure this happens. If you are adding a package for some software and
-the developers list commands to test the installation, please add these
-tests to your ``package.py``.
-
 .. warning::
 
    The order of decorators matters. The following ordering:
@@ -207,3 +202,12 @@ tests to your ``package.py``.
    the tests will always be run regardless of whether or not
    ``--test=root`` is requested. See https://github.com/spack/spack/issues/3833
    for more information
+
+Ideally, every package in Spack will have some sort of test to ensure
+that it was built correctly. It is up to the package authors to make
+sure this happens. If you are adding a package for some software and
+the developers list commands to test the installation, please add these
+tests to your ``package.py``.
+
+For more information on other forms of package testing, refer to
+:ref:`Checking an installation <checking_an_installation>`.

lib/spack/docs/build_systems/inteloneapipackage.rst

@@ -0,0 +1,155 @@
+.. Copyright 2013-2021 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)
+
+.. _inteloneapipackage:
+
+
+====================
+ IntelOneapiPackage
+====================
+
+
+.. contents::
+
+
+oneAPI packages in Spack
+========================
+
+Spack can install and use the Intel oneAPI products. You may either
+use spack to install the oneAPI tools or use the `Intel
+installers`_. After installation, you may use the tools directly, or
+use Spack to build packages with the tools.
+
+The Spack Python class ``IntelOneapiPackage`` is a base class that is
+used by ``IntelOneapiCompilers``, ``IntelOneapiMkl``,
+``IntelOneapiTbb`` and other classes to implement the oneAPI
+packages. See the :ref:`package-list` for the full list of available
+oneAPI packages or use::
+
+  spack list -d oneAPI
+
+For more information on a specific package, do::
+
+  spack info <package-name>
+
+Intel no longer releases new versions of Parallel Studio, which can be
+used in Spack via the :ref:`intelpackage`. All of its components can
+now be found in oneAPI. 
+
+Examples
+========
+
+Building a Package With icx
+---------------------------
+
+In this example, we build patchelf with ``icc`` and ``icx``. The
+compilers are installed with spack.
+
+Install the oneAPI compilers::
+
+  spack install intel-oneapi-compilers
+
+Add the compilers to your ``compilers.yaml`` so spack can use them::
+
+  spack compiler add `spack location -i intel-oneapi-compilers`/compiler/latest/linux/bin/intel64
+  spack compiler add `spack location -i intel-oneapi-compilers`/compiler/latest/linux/bin
+
+Verify that the compilers are available::
+
+  spack compiler list
+
+The ``intel-oneapi-compilers`` package includes 2 families of
+compilers:
+
+* ``intel``: ``icc``, ``icpc``, ``ifort``. Intel's *classic*
+  compilers.
+* ``oneapi``: ``icx``, ``icpx``, ``ifx``. Intel's new generation of
+  compilers based on LLVM.
+
+To build the ``patchelf`` Spack package with ``icc``, do::
+
+  spack install patchelf%intel
+
+To build with with ``icx``, do ::
+
+  spack install patchelf%oneapi
+
+Using oneAPI MPI to Satisfy a Virtual Dependence
+------------------------------------------------------
+
+The ``hdf5`` package works with any compatible MPI implementation. To
+build ``hdf5`` with Intel oneAPI MPI do::
+
+  spack install hdf5 +mpi ^intel-oneapi-mpi
+
+Using an Externally Installed oneAPI
+====================================
+
+Spack can also use oneAPI tools that are manually installed with
+`Intel Installers`_.  The procedures for configuring Spack to use
+external compilers and libraries are different.
+
+Compilers
+---------
+
+To use the compilers, add some information about the installation to
+``compilers.yaml``. For most users, it is sufficient to do::
+
+  spack compiler add /opt/intel/oneapi/compiler/latest/linux/bin/intel64
+  spack compiler add /opt/intel/oneapi/compiler/latest/linux/bin
+
+Adapt the paths above if you did not install the tools in the default
+location. After adding the compilers, using them is the same
+as if you had installed the ``intel-oneapi-compilers`` package.
+Another option is to manually add the configuration to
+``compilers.yaml`` as described in :ref:`Compiler configuration
+<compiler-config>`.
+
+Libraries
+---------
+
+If you want Spack to use MKL that you have installed without Spack in
+the default location, then add the following to
+``~/.spack/packages.yaml``, adjusting the version as appropriate::
+
+  intel-oneapi-mkl:
+    externals:
+    - spec: intel-oneapi-mkl@2021.1.1
+      prefix: /opt/intel/oneapi/
+
+
+Using oneAPI Tools Installed by Spack
+=====================================
+
+Spack can be a convenient way to install and configure compilers and
+libaries, even if you do not intend to build a Spack package. If you
+want to build a Makefile project using Spack-installed oneAPI compilers,
+then use spack to configure your environment::
+
+  spack load intel-oneapi-compilers
+
+And then you can build with::
+
+  CXX=icpx make
+
+You can also use Spack-installed libraries. For example::
+
+  spack load intel-oneapi-mkl
+
+Will update your environment CPATH, LIBRARY_PATH, and other
+environment variables for building an application with MKL.
+
+More information
+================
+
+This section describes basic use of oneAPI, especially if it has
+changed compared to Parallel Studio. See :ref:`intelpackage` for more
+information on :ref:`intel-virtual-packages`,
+:ref:`intel-unrelated-packages`,
+:ref:`intel-integrating-external-libraries`, and
+:ref:`using-mkl-tips`.
+
+
+.. _`Intel installers`: https://software.intel.com/content/www/us/en/develop/documentation/installation-guide-for-intel-oneapi-toolkits-linux/top.html

lib/spack/docs/build_systems/intelpackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)
@@ -137,6 +137,7 @@ If you need to save disk space or installation time, you could install the
 ``intel`` compilers-only subset (0.6 GB) and just the library packages you
 need, for example ``intel-mpi`` (0.5 GB) and ``intel-mkl`` (2.5 GB).
 
+.. _intel-unrelated-packages:
 
 """"""""""""""""""""
 Unrelated packages
@@ -358,6 +359,8 @@ affected by an advanced third method:
 Next, visit section `Selecting Intel Compilers`_ to learn how to tell
 Spack to use the newly configured compilers.
 
+.. _intel-integrating-external-libraries:
+
 """"""""""""""""""""""""""""""""""
 Integrating external libraries
 """"""""""""""""""""""""""""""""""
@@ -558,43 +561,29 @@ follow `the next section <intel-install-libs_>`_ instead.
              modules:    []
              spec:       intel@18.0.3
              paths:
-               cc:       stub
-               cxx:      stub
-               f77:      stub
-               fc:       stub
+               cc:       /usr/bin/true
+               cxx:      /usr/bin/true
+               f77:      /usr/bin/true
+               fc:       /usr/bin/true
 
       Replace ``18.0.3`` with the version that you determined in the preceding
-      step. The contents under ``paths:`` do not matter yet.
+      step. The exact contents under ``paths:`` do not matter yet, but the paths must exist.
 
-   You are right to ask: "Why on earth is that necessary?" [fn8]_.
-   The answer lies in Spack striving for strict compiler consistency.
-   Consider what happens without such a pre-declared compiler stub:
-   Say, you ask Spack to install a particular version
-   ``intel-parallel-studio@edition.V``.  Spack will apply an unrelated compiler
-   spec to concretize and install your request, resulting in
-   ``intel-parallel-studio@edition.V %X``. That compiler ``%X`` is not going to
-   be the version that this new package itself provides. Rather, it would
-   typically be ``%gcc@...`` in a default Spack installation or possibly indeed
-   ``%intel@...``, but at a version that precedes ``V``.
+   This temporary stub is required such that the ``intel-parallel-studio`` package
+   can be installed for the ``intel`` compiler (which the package itself is going
+   to provide after the installation) rather than an arbitrary system compiler.
+   The paths given in ``cc``, ``cxx``, ``f77``, ``fc`` must exist, but will
+   never be used to build anything during the installation of ``intel-parallel-studio``.
 
-   The problem comes to the fore as soon as you try to use any virtual ``mkl``
-   or ``mpi`` packages that you would expect to now be provided by
-   ``intel-parallel-studio@edition.V``.  Spack will indeed see those virtual
-   packages, but only as being tied to the compiler that the package
-   ``intel-parallel-studio@edition.V`` was concretized with *at installation*.
-   If you were to install a client package with the new compilers now available
-   to you, you would naturally run ``spack install foo +mkl %intel@V``, yet
-   Spack will either complain about ``mkl%intel@V`` being missing (because it
-   only knows about ``mkl%X``) or it will go and attempt to install *another
-   instance* of ``intel-parallel-studio@edition.V %intel@V`` so as to match the
-   compiler spec ``%intel@V`` that you gave for your client package ``foo``.
-   This will be unexpected and will quickly get annoying because each
-   reinstallation takes up time and extra disk space.
+   The reason for this stub is that ``intel-parallel-studio`` also provides the
+   ``mpi`` and ``mkl`` packages and when concretizing a spec, Spack ensures
+   strong consistency of the used compiler across all dependencies:  [fn8]_.
+   Installing a package ``foo +mkl %intel`` will make Spack look for a package
+   ``mkl %intel``, which can be provided by ``intel-parallel-studio+mkl %intel``,
+   but not by ``intel-parallel-studio+mkl %gcc``.
 
-   To escape this trap, put the compiler stub declaration shown here in place,
-   then use that pre-declared compiler spec to install the actual package, as
-   shown next.  This approach works because during installation only the
-   package's own self-sufficient installer will be used, not any compiler.
+   Failure to do so may result in additional installations of ``mkl``, ``intel-mpi`` or
+   even ``intel-parallel-studio`` as dependencies for other packages.
 
    .. _`verify-compiler-anticipated`:
 
@@ -645,11 +634,25 @@ follow `the next section <intel-install-libs_>`_ instead.
      want to use the ``intel64`` variant.  The ``icpc`` and ``ifort`` compilers
      will be located in the same directory as ``icc``.
 
-   * Use the ``modules:`` and/or ``cflags:`` tokens to specify a suitable accompanying
+   * Make sure to specify ``modules: ['intel-parallel-studio-cluster2018.3-intel-18.0.3-HASH']``
+     (with ``HASH`` being the short hash as displayed when running
+     ``spack find -l intel-parallel-studio@cluster.2018.3`` and the versions adapted accordingly)
+     to ensure that the correct and complete environment for the Intel compilers gets
+     loaded when running them. With modern versions of the Intel compiler you may otherwise see
+     issues about missing libraries. Please also note that module name must exactly match
+     the name as returned by ``module avail`` (and shown in the example above).
+
+   * Use the ``modules:`` and/or ``cflags:`` tokens to further specify a suitable accompanying
      ``gcc`` version to help pacify picky client packages that ask for C++
      standards more recent than supported by your system-provided ``gcc`` and its
      ``libstdc++.so``.
 
+   * If you specified a custom variant (for example ``+vtune``) you may want to add this as your
+     preferred variant in the packages configuration for the ``intel-parallel-studio`` package
+     as described in :ref:`concretization-preferences`. Otherwise you will have to specify
+     the variant everytime ``intel-parallel-studio`` is being used as ``mkl``, ``fftw`` or ``mpi``
+     implementation to avoid pulling in a different variant.
+
    * To set the Intel compilers for default use in Spack, instead of the usual ``%gcc``,
      follow section `Selecting Intel compilers`_.
 
@@ -834,6 +837,7 @@ for example:
       compiler: [ intel@18, intel@17, gcc@4.4.7, gcc@4.9.3, gcc@7.3.0, ]
 
 
+.. _intel-virtual-packages:
 
 """"""""""""""""""""""""""""""""""""""""""""""""
 Selecting libraries to satisfy virtual packages
@@ -907,6 +911,7 @@ With the proper installation as detailed above, no special steps should be
 required when a client package specifically (and thus deliberately) requests an
 Intel package as dependency, this being one of the target use cases for Spack.
 
+.. _using-mkl-tips:
 
 """""""""""""""""""""""""""""""""""""""""""""""
 Tips for configuring client packages to use MKL

lib/spack/docs/build_systems/makefilepackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)
@@ -147,8 +147,10 @@ and a ``filter_file`` method to help with this. For example:
    def edit(self, spec, prefix):
        makefile = FileFilter('Makefile')
 
-       makefile.filter('CC = gcc',  'CC = cc')
-       makefile.filter('CXX = g++', 'CC = c++')
+       makefile.filter(r'^\s*CC\s*=.*',  'CC = '  + spack_cc)
+       makefile.filter(r'^\s*CXX\s*=.*', 'CXX = ' + spack_cxx)
+       makefile.filter(r'^\s*F77\s*=.*', 'F77 = ' + spack_f77)
+       makefile.filter(r'^\s*FC\s*=.*',  'FC = '  + spack_fc)
 
 
 `stream <https://github.com/spack/spack/blob/develop/var/spack/repos/builtin/packages/stream/package.py>`_

lib/spack/docs/build_systems/mavenpackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)

lib/spack/docs/build_systems/mesonpackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)
@@ -121,11 +121,15 @@ override the ``meson_args`` method like so:
 .. code-block:: python
 
    def meson_args(self):
-       return ['--default-library=both']
+       return ['--warnlevel=3']
 
 
 This method can be used to pass flags as well as variables.
 
+Note that the ``MesonPackage`` base class already defines variants for
+``buildtype``, ``default_library`` and ``strip``, which are mapped to default
+Meson arguments, meaning that you don't have to specify these.
+
 ^^^^^^^^^^^^^^^^^^^^^^
 External documentation
 ^^^^^^^^^^^^^^^^^^^^^^

lib/spack/docs/build_systems/octavepackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)

lib/spack/docs/build_systems/perlpackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)
@@ -120,8 +120,6 @@ so ``PerlPackage`` contains:
 
    extends('perl')
 
-   depends_on('perl', type=('build', 'run'))
-
 
 If your package requires a specific version of Perl, you should
 specify this.

lib/spack/docs/build_systems/pythonpackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)
@@ -23,20 +23,11 @@ can be overridden:
 * ``build_ext``
 * ``build_clib``
 * ``build_scripts``
-* ``clean``
 * ``install``
 * ``install_lib``
 * ``install_headers``
 * ``install_scripts``
 * ``install_data``
-* ``sdist``
-* ``register``
-* ``bdist``
-* ``bdist_dumb``
-* ``bdist_rpm``
-* ``bdist_wininst``
-* ``upload``
-* ``check``
 
 These are all standard ``setup.py`` commands and can be found by running:
 
@@ -55,7 +46,7 @@ If for whatever reason you need to run more phases, simply modify your
 
 .. code-block:: python
 
-   phases = ['build_ext', 'install', 'bdist']
+   phases = ['build_ext', 'install']
 
 
 Each phase provides a function ``<phase>`` that runs:
@@ -90,7 +81,7 @@ Instead of using the ``PythonPackage`` base class, you should extend
 the ``Package`` base class and implement the following custom installation
 procedure:
 
-.. code-block::
+.. code-block:: python
 
    def install(self, spec, prefix):
        pip = which('pip')
@@ -134,9 +125,9 @@ 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
-^^^^^^^^^^^^^^^^^^^^^^^
+^^^^
+PyPI
+^^^^
 
 The vast majority of Python packages are hosted on PyPI - The Python
 Package Index. ``pip`` only supports packages hosted on PyPI, making
@@ -148,6 +139,26 @@ if a newer version is available. The download page is usually at::
 
    https://pypi.org/project/<package-name>
 
+
+Since PyPI is so common, the ``PythonPackage`` base class has a
+``pypi`` attribute that can be set. Once set, ``pypi`` will be used
+to define the ``homepage``, ``url``, and ``list_url``. For example,
+the following:
+
+.. code-block:: python
+
+   homepage = 'https://pypi.org/project/setuptools/'
+   url      = 'https://pypi.org/packages/source/s/setuptools/setuptools-49.2.0.zip'
+   list_url = 'https://pypi.org/simple/setuptools/'
+
+
+is equivalent to:
+
+.. code-block:: python
+
+   pypi = 'setuptools/setuptools-49.2.0.zip'
+
+
 ^^^^^^^^^^^
 Description
 ^^^^^^^^^^^
@@ -184,50 +195,11 @@ also get the homepage on the command-line by running:
 URL
 ^^^
 
-You may have noticed that Spack allows you to add multiple versions of
-the same package without adding multiple versions of the download URL.
-It does this by guessing what the version string in the URL is and
-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
-
-
-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
-
-
-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
-
-
-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``.
+If ``pypi`` is set as mentioned above, ``url`` and ``list_url`` will
+be automatically set for you. 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
@@ -237,10 +209,9 @@ 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:
+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
 
@@ -255,7 +226,7 @@ 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:
 
-#. PyPI contains the bare minimum of files to install the package.
+#. PyPI contains the bare minimum number of files needed to install the package.
 
    You may notice that the tarball you download from PyPI does not
    have the same checksum as the tarball you download from GitHub.
@@ -292,19 +263,6 @@ location, but PyPI is preferred for the following reasons:
    PyPI is nice because it makes it physically impossible to
    re-release the same version of a package with a different checksum.
 
-There are some reasons to prefer downloading from GitHub:
-
-#. 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
-   developers, it will not contain development files like unit tests.
-   If you desire to run the unit tests during installation, you should
-   use the GitHub tarball instead.
-
-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.
-
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 Build system dependencies
 ^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -569,7 +527,8 @@ If the package uses ``setuptools``, check for the following clues:
 
   These are packages that are required to run the unit tests for the
   package. These dependencies can be specified using the
-  ``type='test'`` dependency type.
+  ``type='test'`` dependency type. However, the PyPI tarballs rarely
+  contain unit tests, so there is usually no reason to add these.
 
 In the root directory of the package, you may notice a
 ``requirements.txt`` file. It may look like this file contains a list
@@ -625,7 +584,8 @@ add run-time dependencies if they aren't needed, so you need to
 determine whether or not setuptools is needed. Grep the installation
 directory for any files containing a reference to ``setuptools`` or
 ``pkg_resources``. Both modules come from ``py-setuptools``.
-``pkg_resources`` is particularly common in scripts in ``prefix/bin``.
+``pkg_resources`` is particularly common in scripts found in
+``prefix/bin``.
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Passing arguments to setup.py
@@ -667,7 +627,8 @@ adds:
 Testing
 ^^^^^^^
 
-``PythonPackage`` provides a couple of options for testing packages.
+``PythonPackage`` provides a couple of options for testing packages
+both during and after the installation process.
 
 """"""""""""
 Import tests
@@ -699,49 +660,75 @@ a "package" is a directory containing files like:
    foo/baz.py
 
 
-whereas a "module" is a single Python file. Since ``find_packages``
-only returns packages, you'll have to determine the correct module
-names yourself. You can now add these packages and modules to the
-package like so:
+whereas a "module" is a single Python file.
+
+The ``PythonPackage`` base class automatically detects these module
+names for you. If, for whatever reason, the module names detected
+are wrong, you can provide the names yourself by overriding
+``import_modules`` like so:
 
 .. code-block:: python
 
    import_modules = ['six']
 
 
-When you run ``spack install --test=root py-six``, Spack will attempt
-to import the ``six`` module after installation.
+Sometimes the list of module names to import depends on how the
+package was built. For example, the ``py-pyyaml`` package has a
+``+libyaml`` variant that enables the build of a faster optimized
+version of the library. If the user chooses ``~libyaml``, only the
+``yaml`` library will be importable. If the user chooses ``+libyaml``,
+both the ``yaml`` and ``yaml.cyaml`` libraries will be available.
+This can be expressed like so:
 
-These tests most often catch missing dependencies and non-RPATHed
+.. code-block:: python
+
+   @property
+   def import_modules(self):
+       modules = ['yaml']
+
+       if '+libyaml' in self.spec:
+           modules.append('yaml.cyaml')
+
+       return modules
+
+
+These tests often catch missing dependencies and non-RPATHed
 libraries. Make sure not to add modules/packages containing the word
-"test", as these likely won't end up in installation directory.
+"test", as these likely won't end up in the installation directory,
+or may require test dependencies like pytest to be installed.
+
+Import tests can be run during the installation using ``spack install
+--test=root`` or at any time after the installation using
+``spack test run``.
 
 """"""""""
 Unit tests
 """"""""""
 
-The package you want to install may come with additional unit tests.
-By default, Spack runs:
+The package may have its own unit or regression tests. Spack can
+run these tests during the installation by adding phase-appropriate
+test methods.
 
-.. code-block:: console
-
-   $ python setup.py test
-
-
-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`` or adding a custom install-time test function. For example,
-``py-numpy`` adds:
+For example, ``py-numpy`` adds the following as a check to run 
+after the ``install`` phase:
 
 .. code-block:: python
 
-   install_time_test_callbacks = ['install_test', 'import_module_test']
-
+   @run_after('install')
+   @on_package_attributes(run_tests=True)
    def install_test(self):
-        with working_dir('..'):
-            python('-c', 'import numpy; numpy.test("full", verbose=2)')
+       with working_dir('spack-test', create=True):
+           python('-c', 'import numpy; numpy.test("full", verbose=2)')
 
 
+when testing is enabled during the installation (i.e., ``spack install
+--test=root``).
+
+.. note::
+
+   Additional information is available on :ref:`install phase tests
+   <install_phase-tests>`.
+
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Setup file in a sub-directory
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -781,7 +768,7 @@ PythonPackage vs. packages that use Python
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 There are many packages that make use of Python, but packages that depend
-on Python are not necessarily ``PythonPackages``.
+on Python are not necessarily ``PythonPackage``'s.
 
 """""""""""""""""""""""
 Choosing a build system
@@ -878,8 +865,8 @@ and ``pip`` may be a perfectly valid alternative to using Spack. The
 main advantage of Spack over ``pip`` is its ability to compile
 non-Python dependencies. It can also build cythonized versions of a
 package or link to an optimized BLAS/LAPACK library like MKL,
-resulting in calculations that run orders of magnitude faster.
-Spack does not offer a significant advantage to other python-management
+resulting in calculations that run orders of magnitudes faster.
+Spack does not offer a significant advantage over other python-management
 systems for installing and using tools like flake8 and sphinx.
 But if you need packages with non-Python dependencies like
 numpy and scipy, Spack will be very valuable to you.

lib/spack/docs/build_systems/qmakepackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)
@@ -108,6 +108,19 @@ override the ``qmake_args`` method like so:
 
 This method can be used to pass flags as well as variables.
 
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+``*.pro`` file in a sub-directory
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If the ``*.pro`` file used to tell QMake how to build the package is
+found in a sub-directory, you can tell Spack to run all phases in this
+sub-directory by adding the following to the package:
+
+.. code-block:: python
+
+   build_directory = 'src'
+
+
 ^^^^^^^^^^^^^^^^^^^^^^
 External documentation
 ^^^^^^^^^^^^^^^^^^^^^^

lib/spack/docs/build_systems/rocmpackage.rst

@@ -0,0 +1,122 @@
+.. Copyright 2013-2021 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)
+
+.. _rocmpackage:
+
+-----------
+ROCmPackage
+-----------
+
+The ``ROCmPackage`` is not a build system but a helper package. Like ``CudaPackage``,
+it provides standard variants, dependencies, and conflicts to facilitate building
+packages using GPUs though for AMD in this case.
+
+You can find the source for this package (and suggestions for setting up your
+``compilers.yaml`` and ``packages.yaml`` files) at
+`<https://github.com/spack/spack/blob/develop/lib/spack/spack/build_systems/rocm.py>`__.
+
+^^^^^^^^
+Variants
+^^^^^^^^
+
+This package provides the following variants:
+
+* **rocm**
+
+  This variant is used to enable/disable building with ``rocm``.  
+  The default is disabled (or ``False``).
+
+* **amdgpu_target**
+
+  This variant supports the optional specification of the AMD GPU architecture.
+  Valid values are the names of the GPUs (e.g., ``gfx701``), which are maintained
+  in the ``amdgpu_targets`` property.
+
+^^^^^^^^^^^^
+Dependencies
+^^^^^^^^^^^^
+
+This package defines basic ``rocm`` dependencies, including ``llvm`` and ``hip``.
+
+^^^^^^^^^
+Conflicts
+^^^^^^^^^
+
+Conflicts are used to prevent builds with known bugs or issues. This package
+already requires that the ``amdgpu_target`` always be specified for ``rocm``
+builds. It also defines a conflict that prevents builds with an ``amdgpu_target``
+when ``rocm`` is disabled.
+
+Refer to `Conflicts <https://spack.readthedocs.io/en/latest/packaging_guide.html?highlight=conflicts#conflicts>`__
+for more information on package conflicts.
+
+^^^^^^^
+Methods
+^^^^^^^
+
+This package provides one custom helper method, which is used to build
+standard AMD hip compiler flags.
+
+**hip_flags**
+
+    This built-in static method returns the appropriately formatted
+    ``--amdgpu-target`` build option for ``hipcc``.
+
+    This method must be explicitly called when you are creating the
+    arguments for your build in order to use the values.
+
+^^^^^
+Usage
+^^^^^
+
+This helper package can be added to your package by adding it as a base
+class of your package.  For example, you can add it to your
+:ref:`CMakePackage <cmakepackage>`-based package as follows:
+
+.. code-block:: python
+   :emphasize-lines: 1,3-7,14-25
+
+    class MyRocmPackage(CMakePackage, ROCmPackage):
+        ...
+        # Ensure +rocm and amdgpu_targets are passed to dependencies
+        depends_on('mydeppackage', when='+rocm')
+        for val in ROCmPackage.amdgpu_targets:
+            depends_on('mydeppackage amdgpu_target={0}'.format(val),
+                       when='amdgpu_target={0}'.format(val))
+        ...
+
+        def cmake_args(self):
+            spec = self.spec
+            args = []
+            ...
+            if '+rocm' in spec:
+                # Set up the hip macros needed by the build
+                args.extend([
+                    '-DENABLE_HIP=ON',
+                    '-DHIP_ROOT_DIR={0}'.format(spec['hip'].prefix])
+                rocm_archs = spec.variants['amdgpu_target'].value
+                if 'none' not in rocm_archs:
+                    args.append('-DHIP_HIPCC_FLAGS=--amdgpu-target={0}'
+                                .format(",".join(rocm_archs)))
+            else:
+                # Ensure build with hip is disabled
+                args.append('-DENABLE_HIP=OFF')
+            ...
+            return args
+        ...
+
+assuming only on the ``ENABLE_HIP``, ``HIP_ROOT_DIR``, and ``HIP_HIPCC_FLAGS``
+macros are required to be set and the only dependency needing rocm options
+is ``mydeppackage``. You will need to customize the flags as needed for your
+build.
+
+This example also illustrates how to check for the ``rocm`` variant using
+``self.spec`` and how to retrieve the ``amdgpu_target`` variant's value
+using ``self.spec.variants['amdgpu_target'].value``.
+
+All five packages using ``ROCmPackage`` as of January 2021 also use the
+:ref:`CudaPackage <cudapackage>`. So it is worth looking at those packages
+to get ideas for creating a package that can support both ``cuda`` and
+``rocm``.

lib/spack/docs/build_systems/rpackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)
@@ -79,12 +79,14 @@ Description
 The first thing you'll need to add to your new package is a description.
 The top of the homepage for ``caret`` lists the following description:
 
-   caret: Classification and Regression Training
+   Classification and Regression Training
 
    Misc functions for training and plotting classification and regression models.
 
-You can either use the short description (first line), long description
-(second line), or both depending on what you feel is most appropriate.
+The first line is a short description (title) and the second line is a long
+description. In this case the description is only one line but often the
+description is several lines. Spack makes use of both short and long
+descriptions and convention is to use both when creating an R  package.
 
 ^^^^^^^^
 Homepage
@@ -124,6 +126,67 @@ If you only specify the URL for the latest release, your package will
 no longer be able to fetch that version as soon as a new release comes
 out. To get around this, add the archive directory as a ``list_url``.
 
+^^^^^^^^^^^^^^^^^^^^^
+Bioconductor packages
+^^^^^^^^^^^^^^^^^^^^^
+
+Bioconductor packages are set up in a similar way to CRAN packages, but there
+are some very important distinctions. Bioconductor packages can be found at:
+https://bioconductor.org/. Bioconductor packages are R packages and so follow
+the same packaging scheme as CRAN packages. What is different is that
+Bioconductor itself is versioned and released. This scheme, using the
+Bioconductor package installer, allows further specification of the minimum
+version of R as well as further restrictions on the dependencies between
+packages than what is possible with the native R packaging system. Spack can
+not replicate these extra features and thus Bioconductor packages in Spack need
+to be managed as a group during updates in order to maintain package
+consistency with Bioconductor itself.
+
+Another key difference is that, while previous versions of packages are
+available, they are not available from a site that can be programmatically set,
+thus a ``list_url`` attribute can not be used. However, each package is also
+available in a git repository, with branches corresponding to each Bioconductor
+release. Thus, it is always possible to retrieve the version of any package
+corresponding to a Bioconductor release simply by fetching the branch that
+corresponds to the Bioconductor release of the package repository. For this
+reason, spack Bioconductor R packages use the git repository, with the commit
+of the respective branch used in the ``version()`` attribute of the package.
+
+^^^^^^^^^^^^^^^^^^^^^^^^
+cran and bioc attributes
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Much like the ``pypi`` attribute for python packages, due to the fact that R
+packages are obtained from specific repositories, it is possible to set up shortcut
+attributes that can be used to set ``homepage``, ``url``, ``list_url``, and
+``git``. For example, the following ``cran`` attribute:
+
+.. code-block:: python
+
+   cran = 'caret'
+
+is equivalent to:
+
+.. code-block:: python
+
+   homepage = 'https://cloud.r-project.org/package=caret'
+   url      = 'https://cloud.r-project.org/src/contrib/caret_6.0-86.tar.gz'
+   list_url = 'https://cloud.r-project.org/src/contrib/Archive/caret'
+
+Likewise, the following ``bioc`` attribute:
+
+.. code-block:: python
+
+   bioc = 'BiocVersion'
+
+is equivalent to:
+
+.. code-block:: python
+
+   homepage = 'https://bioconductor.org/packages/BiocVersion/'
+   git      = 'https://git.bioconductor.org/packages/BiocVersion'
+
+
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 Build system dependencies
 ^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -138,7 +201,6 @@ every R package needs this, the ``RPackage`` base class contains:
 .. code-block:: python
 
    extends('r')
-   depends_on('r', type=('build', 'run'))
 
 
 Take a close look at the homepage for ``caret``. If you look at the
@@ -157,7 +219,7 @@ R dependencies
 R packages are often small and follow the classic Unix philosophy
 of doing one thing well. They are modular and usually depend on
 several other packages. You may find a single package with over a
-hundred dependencies. Luckily, CRAN packages are well-documented
+hundred dependencies. Luckily, R packages are well-documented
 and list all of their dependencies in the following sections:
 
 * Depends
@@ -298,8 +360,8 @@ like so:
 
 .. code-block:: python
 
-   def configure_args(self, spec, prefix):
-       mpi_name = spec['mpi'].name
+   def configure_args(self):
+       mpi_name = self.spec['mpi'].name
 
        # The type of MPI. Supported values are:
        # OPENMPI, LAM, MPICH, MPICH2, or CRAY

lib/spack/docs/build_systems/rubypackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)
@@ -113,7 +113,6 @@ the base class contains:
 .. code-block:: python
 
    extends('ruby')
-   depends_on('ruby', type=('build', 'run'))
 
 
 The ``*.gemspec`` file may contain something like:

lib/spack/docs/build_systems/sconspackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)

lib/spack/docs/build_systems/sippackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)
@@ -93,10 +93,17 @@ in the site-packages directory:
    $ python
    >>> import setuptools
    >>> setuptools.find_packages()
-   ['QtPy5']
+   [
+       'PyQt5', 'PyQt5.QtCore', 'PyQt5.QtGui', 'PyQt5.QtHelp',
+       'PyQt5.QtMultimedia', 'PyQt5.QtMultimediaWidgets', 'PyQt5.QtNetwork',
+       'PyQt5.QtOpenGL', 'PyQt5.QtPrintSupport', 'PyQt5.QtQml',
+       'PyQt5.QtQuick', 'PyQt5.QtSvg', 'PyQt5.QtTest', 'PyQt5.QtWebChannel',
+       'PyQt5.QtWebSockets', 'PyQt5.QtWidgets', 'PyQt5.QtXml',
+       'PyQt5.QtXmlPatterns'
+    ]
 
 
-Large, complex packages like ``QtPy5`` will return a long list of
+Large, complex packages like ``py-pyqt5`` will return a long list of
 packages, while other packages may return an empty list. These packages
 only install a single ``foo.py`` file. In Python packaging lingo,
 a "package" is a directory containing files like:
@@ -108,21 +115,25 @@ a "package" is a directory containing files like:
    foo/baz.py
 
 
-whereas a "module" is a single Python file. Since ``find_packages``
-only returns packages, you'll have to determine the correct module
-names yourself. You can now add these packages and modules to the
-package like so:
+whereas a "module" is a single Python file.
+
+The ``SIPPackage`` base class automatically detects these module
+names for you. If, for whatever reason, the module names detected
+are wrong, you can provide the names yourself by overriding
+``import_modules`` like so:
 
 .. code-block:: python
 
    import_modules = ['PyQt5']
 
 
-When you run ``spack install --test=root py-pyqt5``, Spack will attempt
-to import the ``PyQt5`` module after installation.
+These tests often catch missing dependencies and non-RPATHed
+libraries. Make sure not to add modules/packages containing the word
+"test", as these likely won't end up in the installation directory,
+or may require test dependencies like pytest to be installed.
 
-These tests most often catch missing dependencies and non-RPATHed
-libraries.
+These tests can be triggered by running ``spack install --test=root``
+or by running ``spack test run`` after the installation has finished.
 
 ^^^^^^^^^^^^^^^^^^^^^^
 External documentation

lib/spack/docs/build_systems/wafpackage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)

lib/spack/docs/chain.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)

lib/spack/docs/conf.py

@@ -1,4 +1,4 @@
-# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2021 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)
@@ -128,7 +128,7 @@ def setup(sphinx):
 
 # General information about the project.
 project = u'Spack'
-copyright = u'2013-2019, Lawrence Livermore National Laboratory.'
+copyright = u'2013-2021, Lawrence Livermore National Laboratory.'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

lib/spack/docs/config_yaml.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)
@@ -202,21 +202,23 @@ of builds.
 
 Unless overridden in a package or on the command line, Spack builds all
 packages in parallel. The default parallelism is equal to the number of
-cores on your machine, up to 16. Parallelism cannot exceed the number of
-cores available on the host. For a build system that uses Makefiles, this
-means running:
+cores available to the process, up to 16 (the default of ``build_jobs``).
+For a build system that uses Makefiles, this ``spack install`` runs:
 
 - ``make -j<build_jobs>``, when ``build_jobs`` is less than the number of
-  cores on the machine
+  cores available
 - ``make -j<ncores>``, when ``build_jobs`` is greater or equal to the
-  number of cores on the machine
+  number of cores available
 
 If you work on a shared login node or have a strict ulimit, it may be
 necessary to set the default to a lower value. By setting ``build_jobs``
 to 4, for example, commands like ``spack install`` will run ``make -j4``
-instead of hogging every core.
+instead of hogging every core. To build all software in serial,
+set ``build_jobs`` to 1.
 
-To build all software in serial, set ``build_jobs`` to 1.
+Note that specifying the number of jobs on the command line always takes
+priority, so that ``spack install -j<n>`` always runs `make -j<n>`, even
+when that exceeds the number of cores available.
 
 --------------------
 ``ccache``

lib/spack/docs/configuration.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)
@@ -78,6 +78,13 @@ are six configuration scopes. From lowest to highest:
    If multiple scopes are listed on the command line, they are ordered
    from lowest to highest precedence.
 
+#. **environment**: When using Spack :ref:`environments`, Spack reads
+   additional configuration from the environment file. See
+   :ref:`environment-configuration` for further details on these
+   scopes. Environment scopes can be referenced from the command line
+   as ``env:name`` (to reference environment ``foo``, use
+   ``env:foo``).
+
 #. **command line**: Build settings specified on the command line take
    precedence over all other scopes.
 
@@ -192,10 +199,11 @@ with MPICH. You can create different configuration scopes for use with
 Platform-specific Scopes
 ------------------------
 
-For each scope above, there can also be platform-specific settings.
-For example, on most platforms, GCC is the preferred compiler.
-However, on macOS (darwin), Clang often works for more packages,
-and is set as the default compiler. This configuration is set in
+For each scope above (excluding environment scopes), there can also be
+platform-specific settings.  For example, on most platforms, GCC is
+the preferred compiler.  However, on macOS (darwin), Clang often works
+for more packages, and is set as the default compiler. This
+configuration is set in
 ``$(prefix)/etc/spack/defaults/darwin/packages.yaml``. It will take
 precedence over settings in the ``defaults`` scope, but can still be
 overridden by settings in ``system``, ``system/darwin``, ``site``,

lib/spack/docs/containers.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)
@@ -227,7 +227,7 @@ following ``spack.yaml``:
 
      container:
        images:
-         os: centos/7
+         os: centos:7
          spack: 0.15.4
 
 uses ``spack/centos7:0.15.4``  and ``centos:7`` for the stages where the

lib/spack/docs/contribution_guide.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)
@@ -179,24 +179,26 @@ how to write tests!
    run the unit tests yourself, we suggest you use ``spack unit-test``.
 
 ^^^^^^^^^^^^
-Flake8 Tests
+Style Tests
 ^^^^^^^^^^^^
 
 Spack uses `Flake8 <http://flake8.pycqa.org/en/latest/>`_ to test for
-`PEP 8 <https://www.python.org/dev/peps/pep-0008/>`_ conformance. PEP 8 is
+`PEP 8 <https://www.python.org/dev/peps/pep-0008/>`_ conformance and
+`mypy <https://mypy.readthedocs.io/en/stable/>` for type checking. PEP 8 is
 a series of style guides for Python that provide suggestions for everything
 from variable naming to indentation. In order to limit the number of PRs that
 were mostly style changes, we decided to enforce PEP 8 conformance. Your PR
-needs to comply with PEP 8 in order to be accepted.
+needs to comply with PEP 8 in order to be accepted, and if it modifies the
+spack library it needs to successfully type-check with mypy as well.
 
-Testing for PEP 8 compliance is easy. Simply run the ``spack flake8``
+Testing for compliance with spack's style is easy. Simply run the ``spack style``
 command:
 
 .. code-block:: console
 
-   $ spack flake8
+   $ spack style
 
-``spack flake8`` has a couple advantages over running ``flake8`` by hand:
+``spack style`` has a couple advantages over running the tools by hand:
 
 #. It only tests files that you have modified since branching off of
    ``develop``.
@@ -207,7 +209,9 @@ command:
    checks. For example, URLs are often longer than 80 characters, so we
    exempt them from line length checks. We also exempt lines that start
    with "homepage", "url", "version", "variant", "depends_on", and
-   "extends" in ``package.py`` files.
+   "extends" in ``package.py`` files.  This is now also possible when directly
+   running flake8 if you can use the ``spack`` formatter plugin included with
+   spack.
 
 More approved flake8 exemptions can be found
 `here <https://github.com/spack/spack/blob/develop/.flake8>`_.
@@ -240,13 +244,13 @@ However, if you aren't compliant with PEP 8, flake8 will complain:
 
 Most of the error messages are straightforward, but if you don't understand what
 they mean, just ask questions about them when you submit your PR. The line numbers
-will change if you add or delete lines, so simply run ``spack flake8`` again
+will change if you add or delete lines, so simply run ``spack style`` again
 to update them.
 
 .. tip::
 
    Try fixing flake8 errors in reverse order. This eliminates the need for
-   multiple runs of ``spack flake8`` just to re-compute line numbers and
+   multiple runs of ``spack style`` just to re-compute line numbers and
    makes it much easier to fix errors directly off of the CI output.
 
 .. warning::

lib/spack/docs/developer_guide.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)
@@ -106,11 +106,21 @@ with a high level view of Spack's directory structure:
             external/      <- external libs included in Spack distro
             llnl/          <- some general-use libraries
 
-            spack/         <- spack module; contains Python code
-               cmd/        <- each file in here is a spack subcommand
-               compilers/  <- compiler description files
-               test/       <- unit test modules
-               util/       <- common code
+            spack/                <- spack module; contains Python code
+               analyzers/         <- modules to run analysis on installed packages
+               build_systems/     <- modules for different build systems 
+               cmd/               <- each file in here is a spack subcommand
+               compilers/         <- compiler description files          
+               container/         <- module for spack containerize
+               hooks/             <- hook modules to run at different points
+               modules/           <- modules for lmod, tcl, etc.
+               operating_systems/ <- operating system modules
+               platforms/         <- different spack platforms
+               reporters/         <- reporters like cdash, junit
+               schema/            <- schemas to validate data structures
+               solver/            <- the spack solver
+               test/              <- unit test modules
+               util/              <- common code
 
 Spack is designed so that it could live within a `standard UNIX
 directory hierarchy <http://linux.die.net/man/7/hier>`_, so ``lib``,
@@ -251,6 +261,22 @@ Unit tests
   This is a fake package hierarchy used to mock up packages for
   Spack's test suite.
 
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Research and Monitoring Modules
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:mod:`spack.monitor`
+  Contains :class:`SpackMonitor <spack.monitor.SpackMonitor>`. This is accessed
+  from the ``spack install`` and ``spack analyze`` commands to send build
+  and package metadada up to a `Spack Monitor <https://github.com/spack/spack-monitor>`_ server. 
+
+
+:mod:`spack.analyzers`
+  A module folder with a :class:`AnalyzerBase <spack.analyzers.analyzer_base.AnalyzerBase>`
+  that provides base functions to run, save, and (optionally) upload analysis
+  results to a `Spack Monitor <https://github.com/spack/spack-monitor>`_ server.
+
+
 ^^^^^^^^^^^^^
 Other Modules
 ^^^^^^^^^^^^^
@@ -299,6 +325,235 @@ Conceptually, packages are overloaded.  They contain:
 Stage objects
 -------------
 
+
+.. _writing-analyzers:
+
+-----------------
+Writing analyzers
+-----------------
+
+To write an analyzer, you should add a new python file to the
+analyzers module directory at ``lib/spack/spack/analyzers`` .
+Your analyzer should be a subclass of the :class:`AnalyzerBase <spack.analyzers.analyzer_base.AnalyzerBase>`. For example, if you want
+to add an analyzer class ``Myanalyzer`` you woul write to 
+``spack/analyzers/myanalyzer.py`` and import and 
+use the base as follows:
+
+.. code-block:: python
+
+    from .analyzer_base import AnalyzerBase
+
+    class Myanalyzer(AnalyzerBase):
+
+
+Note that the class name is your module file name, all lowercase
+except for the first capital letter. You can  look at other analyzers in 
+that analyzer directory for examples. The guide here will tell you about the basic functions needed.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^
+Analyzer Output Directory
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, when you run ``spack analyze run`` an analyzer output directory will
+be created in your spack user directory in your ``$HOME``. The reason we output here
+is because the install directory might not always be writable. 
+
+.. code-block:: console
+
+    ~/.spack/
+      analyzers
+      
+Result files will be written here, organized in subfolders in the same structure
+as the package, with each analyzer owning it's own subfolder. for example:
+
+
+.. code-block:: console
+
+    $ tree ~/.spack/analyzers/
+    /home/spackuser/.spack/analyzers/
+    └── linux-ubuntu20.04-skylake
+        └── gcc-9.3.0
+            └── zlib-1.2.11-sl7m27mzkbejtkrajigj3a3m37ygv4u2
+                ├── environment_variables
+                │   └── spack-analyzer-environment-variables.json
+                ├── install_files
+                │   └── spack-analyzer-install-files.json
+                └── libabigail
+                    └── lib
+                        └── spack-analyzer-libabigail-libz.so.1.2.11.xml 
+
+
+Notice that for the libabigail analyzer, since results are generated per object,
+we honor the object's folder in case there are equivalently named files in 
+different folders. The result files are typically written as json so they can be easily read and  uploaded in a future interaction with a monitor.
+
+
+^^^^^^^^^^^^^^^^^
+Analyzer Metadata
+^^^^^^^^^^^^^^^^^
+
+Your analyzer is required to have the class attributes ``name``, ``outfile``,
+and ``description``. These are printed to the user with they use the subcommand
+``spack analyze list-analyzers``.  Here is an example.
+As we mentioned above, note that this analyzer would live in a module named
+``libabigail.py`` in the analyzers folder so that the class can be discovered.
+
+
+.. code-block:: python
+
+    class Libabigail(AnalyzerBase):
+
+        name = "libabigail"
+        outfile = "spack-analyzer-libabigail.json"
+        description = "Application Binary Interface (ABI) features for objects"
+
+
+This means that the name and output file should be unique for your analyzer.
+Note that "all" cannot be the name of an analyzer, as this key is used to indicate
+that the user wants to run all analyzers.
+
+.. _analyzer_run_function:
+
+
+^^^^^^^^^^^^^^^^^^^^^^^^
+An analyzer run Function
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The core of an analyzer is its ``run()`` function, which should accept no
+arguments. You can assume your analyzer has the package spec of interest at ``self.spec``
+and it's up to the run function to generate whatever analysis data you need,
+and then return the object with a key as the analyzer name. The result data
+should be a list of objects, each with a name, ``analyzer_name``, ``install_file``,
+and one of ``value`` or ``binary_value``. The install file should be for a relative
+path, and not the absolute path. For example, let's say we extract a metric called
+``metric`` for ``bin/wget`` using our analyzer ``thebest-analyzer``. 
+We might have data that looks like this:
+
+.. code-block:: python
+
+    result = {"name": "metric", "analyzer_name": "thebest-analyzer", "value": "1", "install_file": "bin/wget"}
+
+
+We'd then return it as follows - note that they key is the analyzer name at ``self.name``.
+
+.. code-block:: python
+
+    return {self.name: result}
+
+This will save the complete result to the analyzer metadata folder, as described
+previously. If you want support for adding a different kind of metadata (e.g.,
+not associated with an install file) then the monitor server would need to be updated
+to support this first.
+
+
+^^^^^^^^^^^^^^^^^^^^^^^^^
+An analyzer init Function
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you don't need any extra dependencies or checks, you can skip defining an analyzer
+init function, as the base class will handle it. Typically, it will accept
+a spec, and an optional output directory (if the user does not want the default
+metadata folder for analyzer results). The analyzer init function should call
+it's parent init, and then do any extra checks or validation that are required to
+work. For example:
+
+.. code-block:: python
+
+    def __init__(self, spec, dirname=None):
+        super(Myanalyzer, self).__init__(spec, dirname)
+
+        # install extra dependencies, do extra preparation and checks here
+
+
+At the end of the init, you will have available to you:
+
+ - **self.spec**: the spec object
+ - **self.dirname**: an optional directory name the user as provided at init to save
+ - **self.output_dir**: the analyzer metadata directory, where we save by default
+ - **self.meta_dir**: the path to the package metadata directory (.spack) if you need it
+
+And can proceed to write your analyzer.
+
+
+^^^^^^^^^^^^^^^^^^^^^^^
+Saving Analyzer Results
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The analyzer will have ``save_result`` called, with the result object generated
+to save it to the filesystem, and if the user has added the ``--monitor`` flag
+to upload it to a monitor server. If your result follows an accepted result
+format and you don't need to parse it further, you don't need to add this 
+function to your class. However, if your result data is large or otherwise
+needs additional parsing, you can define it. If you define the function, it
+is useful to know about the ``output_dir`` property, which you can join
+with your output file relative path of choice:
+
+.. code-block:: python
+
+    outfile = os.path.join(self.output_dir, "my-output-file.txt")
+
+
+The directory will be provided by the ``output_dir`` property but it won't exist,
+so you should create it:
+
+
+.. code::block:: python
+
+    # Create the output directory
+    if not os.path.exists(self._output_dir):
+        os.makedirs(self._output_dir)
+
+
+If you are generating results that match to specific files in the package
+install directory, you should try to maintain those paths in the case that
+there are equivalently named files in different directories that would
+overwrite one another. As an example of an analyzer with a custom save,
+the Libabigail analyzer saves ``*.xml`` files to the analyzer metadata
+folder in ``run()``, as they are either binaries, or as xml (text) would
+usually be too big to pass in one request. For this reason, the files
+are saved during ``run()`` and the filenames added to the result object,
+and then when the result object is passed back into ``save_result()``,
+we skip saving to the filesystem, and instead read the file and send
+each one (separately) to the monitor:
+
+
+.. code-block:: python
+
+    def save_result(self, result, monitor=None, overwrite=False):
+        """ABI results are saved to individual files, so each one needs to be
+        read and uploaded. Result here should be the lookup generated in run(),
+        the key is the analyzer name, and each value is the result file.
+        We currently upload the entire xml as text because libabigail can't
+        easily read gzipped xml, but this will be updated when it can.
+        """
+        if not monitor:
+            return
+
+        name = self.spec.package.name
+
+        for obj, filename in result.get(self.name, {}).items():
+
+            # Don't include the prefix
+            rel_path = obj.replace(self.spec.prefix + os.path.sep, "")
+
+            # We've already saved the results to file during run
+            content = spack.monitor.read_file(filename)
+
+            # A result needs an analyzer, value or binary_value, and name
+            data = {"value": content, "install_file": rel_path, "name": "abidw-xml"}
+            tty.info("Sending result for %s %s to monitor." % (name, rel_path))
+            monitor.send_analyze_metadata(self.spec.package, {"libabigail": [data]})
+
+
+
+Notice that this function, if you define it, requires a result object (generated by
+``run()``, a monitor (if you want to send), and a boolean ``overwrite`` to be used
+to check if a result exists first, and not write to it if the result exists and 
+overwrite is False. Also notice that since we already saved these files to the analyzer metadata folder, we return early if a monitor isn't defined, because this function serves to send  results to the monitor. If you haven't saved anything to the analyzer metadata folder
+yet, you might want to do that here. You should also use ``tty.info`` to give
+the user a message of "Writing result to $DIRNAME."
+
+
 .. _writing-commands:
 
 ----------------
@@ -345,6 +600,183 @@ Whenever you add/remove/rename a command or flags for an existing command,
 make sure to update Spack's `Bash tab completion script
 <https://github.com/adamjstewart/spack/blob/develop/share/spack/spack-completion.bash>`_.
 
+
+-------------
+Writing Hooks
+-------------
+
+A hook is a callback that makes it easy to design functions that run
+for different events. We do this by way of defining hook types, and then
+inserting them at different places in the spack code base. Whenever a hook
+type triggers by way of a function call, we find all the hooks of that type,
+and run them.
+
+Spack defines hooks by way of a module at ``lib/spack/spack/hooks`` where we can define
+types of hooks in the ``__init__.py``, and then python files in that folder
+can use hook functions. The files are automatically parsed, so if you write
+a new file for some integration (e.g., ``lib/spack/spack/hooks/myintegration.py``
+you can then write hook functions in that file that will be automatically detected,
+and run whenever your hook is called. This section will cover the basic kind 
+of hooks, and how to write them.
+
+^^^^^^^^^^^^^^
+Types of Hooks
+^^^^^^^^^^^^^^
+
+The following hooks are currently implemented to make it easy for you,
+the developer, to add hooks at different stages of a spack install or similar. 
+If there is a hook that you would like and is missing, you can propose to add a new one.
+
+"""""""""""""""""""""
+``pre_install(spec)``
+"""""""""""""""""""""
+
+A ``pre_install`` hook is run within an install subprocess, directly before
+the install starts. It expects a single argument of a spec, and is run in 
+a multiprocessing subprocess. Note that if you see ``pre_install`` functions associated with packages these are not hooks
+as we have defined them here, but rather callback functions associated with 
+a package install.
+
+
+""""""""""""""""""""""
+``post_install(spec)``
+""""""""""""""""""""""
+
+A ``post_install`` hook is run within an install subprocess, directly after
+the install finishes, but before the build stage is removed. If you
+write one of these hooks, you should expect it to accept a spec as the only
+argument. This is run in a multiprocessing subprocess. This ``post_install`` is
+also seen in packages, but in this context not related to the hooks described
+here.
+
+
+""""""""""""""""""""""""""
+``on_install_start(spec)``
+""""""""""""""""""""""""""
+
+This hook is run at the beginning of ``lib/spack/spack/installer.py``,
+in the install function of a ``PackageInstaller``,
+and importantly is not part of a build process, but before it. This is when
+we have just newly grabbed the task, and are preparing to install. If you 
+write a hook of this type, you should provide the spec to it.
+
+.. code-block:: python
+
+    def on_install_start(spec):
+        """On start of an install, we want to...
+        """
+        print('on_install_start')
+    
+
+""""""""""""""""""""""""""""
+``on_install_success(spec)``
+""""""""""""""""""""""""""""
+
+This hook is run on a successful install, and is also run inside the build
+process, akin to ``post_install``. The main difference is that this hook
+is run outside of the context of the stage directory, meaning after the
+build stage has been removed and the user is alerted that the install was
+successful. If you need to write a hook that is run on success of a particular
+phase, you should use ``on_phase_success``.
+
+""""""""""""""""""""""""""""
+``on_install_failure(spec)``
+""""""""""""""""""""""""""""
+
+This hook is run given an install failure that happens outside of the build
+subprocess, but somewhere in ``installer.py`` when something else goes wrong.
+If you need to write a hook that is relevant to a failure within a build
+process, you would want to instead use ``on_phase_failure``.
+
+
+"""""""""""""""""""""""""""""""""""""""""""""""
+``on_phase_success(pkg, phase_name, log_file)``
+"""""""""""""""""""""""""""""""""""""""""""""""
+
+This hook is run within the install subprocess, and specifically when a phase
+successfully finishes. Since we are interested in the package, the name of
+the phase, and any output from it, we require:
+
+ - **pkg**: the package variable, which also has the attached spec at ``pkg.spec``
+ - **phase_name**: the name of the phase that was successful (e.g., configure)
+ - **log_file**: the path to the file with output, in case you need to inspect or otherwise interact with it.
+
+"""""""""""""""""""""""""""""""""""""""""""""
+``on_phase_error(pkg, phase_name, log_file)``
+"""""""""""""""""""""""""""""""""""""""""""""
+
+In the case of an error during a phase, we might want to trigger some event
+with a hook, and this is the purpose of this particular hook. Akin to
+``on_phase_success`` we require the same variables - the package that failed,
+the name of the phase, and the log file where we might find errors.
+
+"""""""""""""""""""""""""""""""""
+``on_analyzer_save(pkg, result)``
+"""""""""""""""""""""""""""""""""
+
+After an analyzer has saved some result for a package, this hook is called,
+and it provides the package that we just ran the analysis for, along with
+the loaded result. Typically, a result is structured to have the name
+of the analyzer as key, and the result object that is defined in detail in
+:ref:`analyzer_run_function`.
+
+.. code-block:: python
+
+    def on_analyzer_save(pkg, result):
+        """given a package and a result...
+        """
+        print('Do something extra with a package analysis result here')
+
+
+^^^^^^^^^^^^^^^^^^^^^^
+Adding a New Hook Type
+^^^^^^^^^^^^^^^^^^^^^^
+
+Adding a new hook type is very simple!  In ``lib/spack/spack/hooks/__init__.py``
+you can simply create a new ``HookRunner`` that is named to match your new hook.
+For example, let's say you want to add a new hook called ``post_log_write``
+to trigger after anything is written to a logger. You would add it as follows:
+
+.. code-block:: python
+
+    # pre/post install and run by the install subprocess
+    pre_install = HookRunner('pre_install')
+    post_install = HookRunner('post_install')
+
+    # hooks related to logging
+    post_log_write = HookRunner('post_log_write') # <- here is my new hook! 
+    
+
+You then need to decide what arguments my hook would expect. Since this is
+related to logging, let's say that you want a message and level. That means
+that when you add a python file to the ``lib/spack/spack/hooks``
+folder with one or more callbacks intended to be triggered by this hook. You might
+use my new hook as follows:
+
+.. code-block:: python
+
+    def post_log_write(message, level):
+        """Do something custom with the messsage and level every time we write
+        to the log
+        """
+        print('running post_log_write!')
+
+
+To use the hook, we would call it as follows somewhere in the logic to do logging.
+In this example, we use it outside of a logger that is already defined:
+
+.. code-block:: python
+
+    import spack.hooks
+
+    # We do something here to generate a logger and message
+    spack.hooks.post_log_write(message, logger.level)
+
+
+This is not to say that this would be the best way to implement an integration
+with the logger (you'd probably want to write a custom logger, or you could
+have the hook defined within the logger) but serves as an example of writing a hook. 
+
 ----------
 Unit tests
 ----------
@@ -396,23 +828,89 @@ other Spack modules:
    True
    >>>
 
-You can also run a single command:
+If you prefer using an IPython interpreter, given that IPython is installed
+you can specify the interpreter with ``-i``:
+
+.. code-block:: console
+
+   $ spack python -i ipython
+   Python 3.8.3 (default, May 19 2020, 18:47:26)
+   Type 'copyright', 'credits' or 'license' for more information
+   IPython 7.17.0 -- An enhanced Interactive Python. Type '?' for help.
+
+
+   Spack version 0.16.0
+   Python 3.8.3, Linux x86_64
+
+   In [1]:
+
+
+With either interpreter you can run a single command:
 
 .. code-block:: console
 
    $ spack python -c 'import distro; distro.linux_distribution()'
-   ('Fedora', '25', 'Workstation Edition')
+   ('Ubuntu', '18.04', 'Bionic Beaver')
+
+   $ spack python -i ipython -c 'import distro; distro.linux_distribution()'
+   Out[1]: ('Ubuntu', '18.04', 'Bionic Beaver')
 
 or a file:
 
 .. code-block:: console
 
    $ spack python ~/test_fetching.py
+   $ spack python -i ipython ~/test_fetching.py
 
 just like you would with the normal ``python`` command.
 
+
 .. _cmd-spack-url:
 
+
+^^^^^^^^^^^^^^^
+``spack blame``
+^^^^^^^^^^^^^^^
+
+Spack blame is a way to quickly see contributors to packages or files
+in the spack repository. You should provide a target package name or 
+file name to the command. Here is an example asking to see contributions
+for the package "python":
+
+.. code-block:: console
+
+    $ spack blame python
+    LAST_COMMIT  LINES  %      AUTHOR            EMAIL
+    2 weeks ago  3      0.3    Mickey Mouse   <cheddar@gmouse.org>
+    a month ago  927    99.7   Minnie Mouse   <swiss@mouse.org>
+                                        
+    2 weeks ago  930    100.0  
+
+
+By default, you will get a table view (shown above) sorted by date of contribution,
+with the most recent contribution at the top.  If you want to sort instead
+by percentage of code contribution, then add ``-p``:
+
+.. code-block:: console
+
+    $ spack blame -p python
+
+
+And to see the git blame view, add ``-g`` instead:
+
+
+.. code-block:: console
+
+    $ spack blame -g python
+
+
+Finally, to get a json export of the data, add ``--json``:
+
+.. code-block:: console
+
+    $ spack blame --json python
+
+
 ^^^^^^^^^^^^^
 ``spack url``
 ^^^^^^^^^^^^^
@@ -553,8 +1051,10 @@ 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
+**should not** make changes that would change the concretization of
 packages. They should generally only contain fixes to the Spack core.
+However, sometimes priorities are such that new functionality needs to
+be added to a minor release.
 
 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
@@ -563,50 +1063,51 @@ 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
+several open release projects. For example, below 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
+This image shows 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
+Spack's project boards are not firm commitments so 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
+yet done, we will simply move them to the 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
+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:
+Assuming a project board has already been created and all required work
+completed, the steps to make the major release are:
 
 #. 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.
+#. Move any optional tasks that are not done to one of the new project boards.
+
+   In general, 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``:
 
@@ -618,11 +1119,14 @@ for a major release, the steps to make the release are as follows:
    ``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
+#. Bump the version in ``lib/spack/spack/__init__.py``.
+
+   See `this example from 0.13.0
    <https://github.com/spack/spack/commit/8eeb64096c98b8a43d1c587f13ece743c864fba9>`_
 
-#. Update ``CHANGELOG.md`` with major highlights in bullet form. Use
-   proper markdown formatting, like `this example from 0.15.0
+#. 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.
@@ -646,33 +1150,33 @@ for a major release, the steps to make the release are as follows:
 .. _point-releases:
 
 ^^^^^^^^^^^^^^^^^^^^^
-Making 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:
+Assuming a project board has already been created and all required work
+completed, the steps to make the point release are:
 
-#. Create one new project board for the next point release.
+#. Create a new project board for the next point release.
 
-#. Move any cards that aren't done yet to the next project board.
+#. Move any optional tasks that are not done 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``:
+#. 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.
+   project board 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
+   vast majority of pull requests. That 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
+   they were squashed into a single commit on merge. You can see the
    commit that was created here:
 
    .. image:: images/pr-commit.png
@@ -684,9 +1188,8 @@ release:
 
       $ 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.
+   For pull requests that were rebased (or not squashed), you'll need to
+   cherry-pick each associated commit individually.
 
    .. warning::
 
@@ -699,30 +1202,35 @@ release:
       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:
+      call regarding those pull requests.  Consider the number of affected
+      files and or the resulting differences.
 
-      1. If the dependency is small, you might just cherry-pick it, too.
-         If you do this, add it to the release board.
+      1. If the dependency changes are small, you might just cherry-pick it,
+         too. If you do this, add the task 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.
+      2. If the changes are large, then you may decide that this fix is not
+         worth including in a point release, in which case you should remove
+         the task 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
+#. Bump the version in ``lib/spack/spack/__init__.py``.
+
+   See `this example from 0.14.1
    <https://github.com/spack/spack/commit/ff0abb9838121522321df2a054d18e54b566b44a>`_.
 
-#. 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
+#. Update ``CHANGELOG.md`` with a list of the changes.
+
+   This is typically 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>`_
@@ -745,23 +1253,26 @@ release:
 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:
+#. Create the release in GitHub.
 
-   * ``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.
+   * Go to 
+     `github.com/spack/spack/releases <https://github.com/spack/spack/releases>`_
+     and click ``Draft a new release``.
 
-   * ``Target`` should be the ``releases/vX.Y`` branch (e.g., ``releases/v0.15``).
+   * Set ``Tag version`` to the name of the tag that will be created.
 
-   * ``Release title`` should be ``vX.Y.Z`` (To match the tag, e.g., ``v0.15.1``).
+     The name should start with ``v`` and contain *all three*
+     parts of the version (e.g. ``v0.15.0`` or ``v0.15.1``).
 
-   * For the text, paste the latest release markdown from your ``CHANGELOG.md``.
+   * Set ``Target`` to the ``releases/vX.Y`` branch (e.g., ``releases/v0.15``).
 
-   You can save the draft and keep coming back to this as you prepare the release.
+   * Set ``Release title`` to ``vX.Y.Z`` to match the tag (e.g., ``v0.15.1``).
 
-#. When you are done, click ``Publish release``.
+   * Paste the latest release markdown from your ``CHANGELOG.md`` file as the text.
+
+   * Save the draft so you can keep coming back to it as you prepare the release.
+
+#. When you are ready to finalize the release, click ``Publish release``.
 
 #. Immediately after publishing, go back to
    `github.com/spack/spack/releases
@@ -769,22 +1280,26 @@ Publishing a release on GitHub
    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
+#. Click ``Edit`` on the release you just made 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
+   #. Makes sure that the hash of our releases does not change over time.
+
+      GitHub sometimes annoyingly changes the way they generate tarballs
+      that can result in the hashes changing 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
+   #. Gets 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
+#. 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.
 
 
@@ -798,23 +1313,23 @@ 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 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).
+* 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:
+To tag ``releases/latest``, do this:
 
-   .. code-block:: console
+.. code-block:: console
 
-      $ git checkout releases/vX.Y     # vX.Y is the new release's branch
-      $ git tag --force releases/latest
-      $ git push --tags
+   $ git checkout releases/vX.Y     # vX.Y is the new release's branch
+   $ git tag --force releases/latest
+   $ git push --force --tags
 
-   The ``--force`` argument makes ``git`` overwrite the existing
-   ``releases/latest`` tag with the new one.
+The ``--force`` argument to ``git tag`` 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:
@@ -822,17 +1337,17 @@ 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 merge --no-ff -s ours 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``.
+  * updates the version and ``CHANGELOG.md`` on ``develop``; and
   * ensures that your release tag is reachable from the head of
-    ``develop``
+    ``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``.
+We *must* use a real merge commit (via the ``--no-ff`` option) to
+ensure 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:
@@ -850,6 +1365,7 @@ 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:
 
 ^^^^^^^^^^^^^^^^^^^^
@@ -860,20 +1376,40 @@ 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>`_.
+#. Announce the release on Twitter.
 
-#. 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.
+   * Compose the tweet on the ``@spackpm`` account per the
+     ``spack-twitter`` slack channel.
 
-#. 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>`_.
+   * Be sure to include a link to the release's page on GitHub.
 
-Once you've announced the release, congratulations, you're done! You've
-finished making the release!
+     You can base the tweet on `this
+     example <https://twitter.com/spackpm/status/1231761858182307840>`_.
+
+#. Announce the release on Slack.
+
+   * Compose a message in the ``#general`` Slack channel
+     (`spackpm.slack.com <https://spackpm.slack.com>`_).
+
+   * Preface the message with ``@channel`` to notify even those
+     people not currently logged in.
+
+   * Be sure to include a link to the tweet above.
+
+   The tweet will be shown inline so that you do not have to retype
+   your release announcement.
+
+#. Announce the release on the Spack mailing list.
+
+   * Compose an email to the Spack mailing list.
+
+   * Be sure to include a link to the release's page on GitHub.
+
+   * It is also helpful to include some information directly in the
+     email.
+
+   You can base your announcement on this `example
+   email <https://groups.google.com/forum/#!topic/spack/WT4CT9i_X4s>`_.
+
+Once you've completed the above steps, congratulations, you're done!
+You've finished making the release!

lib/spack/docs/environments.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)
@@ -248,9 +248,9 @@ Users can add abstract specs to an Environment using the ``spack add``
 command. The most important component of an Environment is a list of
 abstract specs.
 
-Adding a spec adds to the manifest (the ``spack.yaml`` file) and to
-the roots of the Environment, but does not affect the concrete specs
-in the lockfile, nor does it install the spec.
+Adding a spec adds to the manifest (the ``spack.yaml`` file), which is
+used to define the roots of the Environment, but does not affect the
+concrete specs 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
@@ -356,6 +356,18 @@ command also stores a Spack repo containing the ``package.py`` file
 used at install time for each package in the ``repos/`` directory in
 the Environment.
 
+The ``--no-add`` option can be used in a concrete environment to tell
+spack to install specs already present in the environment but not to
+add any new root specs to the environment.  For root specs provided
+to ``spack install`` on the command line, ``--no-add`` is the default,
+while for dependency specs on the other hand, it is optional.  In other
+words, if there is an unambiguous match in the active concrete environment
+for a root spec provided to ``spack install`` on the command line, spack
+does not require you to specify the ``--no-add` option to prevent the spec
+from being added again.  At the same time, a spec that already exists in the
+environment, but only as a dependency, will be added to the environment as a
+root spec without the ``--no-add`` option.
+
 ^^^^^^^
 Loading
 ^^^^^^^
@@ -399,6 +411,12 @@ There are two ways to include configuration information in a Spack Environment:
 
 #. Included in the ``spack.yaml`` file from another file.
 
+Many Spack commands also affect configuration information in files
+automatically. Those commands take a ``--scope`` argument, and the
+environment can be specified by ``env:NAME`` (to affect environment
+``foo``, set ``--scope env:foo``). These commands will automatically
+manipulate configuration inline in the ``spack.yaml`` file.
+
 """""""""""""""""""""
 Inline configurations
 """""""""""""""""""""
@@ -441,8 +459,8 @@ Environments can include files with either relative or absolute
 paths. Inline configurations take precedence over included
 configurations, so you don't have to change shared configuration files
 to make small changes to an individual Environment. Included configs
-listed later will have higher precedence, as the included configs are
-applied in order.
+listed earlier will have higher precedence, as the included configs are
+applied in reverse order.
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Manually Editing the Specs List
@@ -705,6 +723,8 @@ Spack Environment managed views are updated every time the environment
 is written out to the lock file ``spack.lock``, so the concrete
 environment and the view are always compatible.
 
+.. _configuring_environment_views:
+
 """""""""""""""""""""""""""""
 Configuring environment views
 """""""""""""""""""""""""""""

lib/spack/docs/extensions.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)

lib/spack/docs/features.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)

lib/spack/docs/getting_started.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)
@@ -19,7 +19,7 @@ before Spack is run:
 #. Python 2 (2.6 or 2.7) or 3 (3.5 - 3.9) to run Spack
 #. A C/C++ compiler for building
 #. The ``make`` executable for building
-#. The ``tar``, ``gzip``, ``bzip2``, ``xz`` and optionally ``zstd``
+#. The ``tar``, ``gzip``, ``unzip``, ``bzip2``, ``xz`` and optionally ``zstd``
    executables for extracting source code
 #. The ``patch`` command to apply patches
 #. The ``git`` and ``curl`` commands for fetching
@@ -75,6 +75,14 @@ shell integration for :ref:`certain commands <packaging-shell-support>`,
 If you do not want to use Spack's shell support, you can always just run
 the ``spack`` command directly from ``spack/bin/spack``.
 
+When the ``spack`` command is executed it searches for an appropriate
+Python interpreter to use, which can be explicitly overridden by setting
+the ``SPACK_PYTHON`` environment variable.  When sourcing the appropriate shell
+setup script, ``SPACK_PYTHON`` will be set to the interpreter found at
+sourcing time, ensuring future invocations of the ``spack`` command will
+continue to use the same consistent python version regardless of changes in
+the environment.
+
 
 ^^^^^^^^^^^^^^^^^^
 Check Installation
@@ -1111,6 +1119,33 @@ Secret keys may also be later exported using the
       <https://www.digitalocean.com/community/tutorials/how-to-setup-additional-entropy-for-cloud-servers-using-haveged>`_
       provides a good overview of sources of randomness.
 
+Here is an example of creating a key. Note that we provide a name for the key first
+(which we can use to reference the key later) and an email address:
+
+.. code-block:: console
+
+    $ spack gpg create dinosaur dinosaur@thedinosaurthings.com
+
+
+If you want to export the key as you create it:
+
+
+.. code-block:: console
+
+    $ spack gpg create --export key.pub dinosaur dinosaur@thedinosaurthings.com
+
+Or the private key:
+
+
+.. code-block:: console
+
+    $ spack gpg create --export-secret key.priv dinosaur dinosaur@thedinosaurthings.com
+
+
+You can include both ``--export`` and ``--export-secret``, each with
+an output file of choice, to export both.
+
+
 ^^^^^^^^^^^^
 Listing keys
 ^^^^^^^^^^^^
@@ -1119,7 +1154,22 @@ In order to list the keys available in the keyring, the
 ``spack gpg list`` command will list trusted keys with the ``--trusted`` flag
 and keys available for signing using ``--signing``. If you would like to
 remove keys from your keyring, ``spack gpg untrust <keyid>``. Key IDs can be
-email addresses, names, or (best) fingerprints.
+email addresses, names, or (best) fingerprints. Here is an example of listing
+the key that we just created:
+
+.. code-block:: console
+
+    gpgconf: socketdir is '/run/user/1000/gnupg'
+    /home/spackuser/spack/opt/spack/gpg/pubring.kbx
+    ----------------------------------------------------------
+    pub   rsa4096 2021-03-25 [SC]
+          60D2685DAB647AD4DB54125961E09BB6F2A0ADCB
+    uid           [ultimate] dinosaur (GPG created for Spack) <dinosaur@thedinosaurthings.com>
+
+    
+Note that the name "dinosaur" can be seen under the uid, which is the unique
+id. We might need this reference if we want to export or otherwise reference the key.
+
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Signing and Verifying Packages
@@ -1134,6 +1184,38 @@ may also be used to create a signed file which contains the contents, but it
 is not recommended. Signed packages may be verified by using
 ``spack gpg verify <file>``.
 
+
+^^^^^^^^^^^^^^
+Exporting Keys
+^^^^^^^^^^^^^^
+
+You likely might want to export a public key, and that looks like this. Let's
+use the previous example and ask spack to export the key with uid "dinosaur."
+We will provide an output location (typically a `*.pub` file) and the name of
+the key.
+
+.. code-block:: console
+
+    $ spack gpg export dinosaur.pub dinosaur
+
+You can then look at the created file, `dinosaur.pub`, to see the exported key.
+If you want to include the private key, then just add `--secret`:
+
+.. code-block:: console
+
+    $ spack gpg export --secret dinosaur.priv dinosaur
+
+This will write the private key to the file `dinosaur.priv`. 
+
+.. warning::
+
+    You should be very careful about exporting private keys. You likely would
+    only want to do this in the context of moving your spack installation to
+    a different server, and wanting to preserve keys for a buildcache. If you
+    are unsure about exporting, you can ask your local system administrator
+    or for help on an issue or the Spack slack.
+
+
 .. _cray-support:
 
 -------------

lib/spack/docs/index.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)
@@ -67,6 +67,7 @@ or refer to the full manual below.
    build_settings
    environments
    containers
+   monitoring
    mirrors
    module_file_support
    repositories
@@ -77,6 +78,12 @@ or refer to the full manual below.
    extensions
    pipelines
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Research
+
+   analyze
+
 .. toctree::
    :maxdepth: 2
    :caption: Contributing

lib/spack/docs/known_issues.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)

lib/spack/docs/mirrors.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)
@@ -159,6 +159,27 @@ can supply a file with specs in it, one per line:
 This is useful if there is a specific suite of software managed by
 your site.
 
+^^^^^^^^^^^^^^^^^^
+Mirror environment
+^^^^^^^^^^^^^^^^^^
+
+To create a mirror of all packages required by a concerte environment, activate the environment and call ``spack mirror create -a``.
+This is especially useful to create a mirror of an environment concretized on another machine.
+
+.. code-block:: console
+
+   [remote] $ spack env create myenv
+   [remote] $ spack env activate myenv
+   [remote] $ spack add ...
+   [remote] $ spack concretize
+   
+   $ sftp remote:/spack/var/environment/myenv/spack.lock
+   $ spack env create myenv spack.lock
+   $ spack env activate myenv
+   $ spack mirror create -a
+  
+
+
 .. _cmd-spack-mirror-add:
 
 --------------------

lib/spack/docs/module_file_support.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)
@@ -71,9 +71,24 @@ Module file customization
 -------------------------
 
 Module files are generated by post-install hooks after the successful
-installation of a package. The table below summarizes the essential
-information associated with the different file formats
-that can be generated by Spack:
+installation of a package.
+
+.. note::
+
+   Spack only generates modulefiles when a package is installed. If
+   you attempt to install a package and it is already installed, Spack
+   will not regenerate modulefiles for the package. This may to
+   inconsistent modulefiles if the Spack module configuration has
+   changed since the package was installed, either by editing a file
+   or changing scopes or environments.
+
+   Later in this section there is a subsection on :ref:`regenerating
+   modules <cmd-spack-module-refresh>` that will allow you to bring
+   your modules to a consistent state.
+
+The table below summarizes the essential information associated with
+the different file formats that can be generated by Spack:
+
 
   +-----------------------------+--------------------+-------------------------------+----------------------------------------------+----------------------+
   |                             | **Hook name**      |  **Default root directory**   | **Default template file**                    | **Compatible tools** |
@@ -130,9 +145,8 @@ list of environment modifications.
   to the corresponding environment variables:
 
   ================== =================================
-   LIBRARY_PATH       ``self.prefix/rlib/R/lib``
    LD_LIBRARY_PATH    ``self.prefix/rlib/R/lib``
-   CPATH              ``self.prefix/rlib/R/include``
+   PKG_CONFIG_PATH    ``self.prefix/rlib/pkgconfig``
   ================== =================================
 
   with the following snippet:
@@ -164,6 +178,46 @@ the installation folder of each package for the presence of a set of subdirector
 (``bin``, ``man``, ``share/man``, etc.). If any is found its full path is prepended
 to the environment variables listed below the folder name.
 
+Spack modules can be configured for multiple module sets. The default
+module set is named ``default``. All Spack commands which operate on
+modules default to apply the ``default`` module set, but can be
+applied to any module set in the configuration. Settings applied at
+the root of the configuration (e.g. ``modules:enable`` rather than
+``modules:default:enable``) are applied to the default module set for
+backwards compatibility.
+
+"""""""""""""""""""""""""
+Changing the modules root
+"""""""""""""""""""""""""
+
+As shown in the table above, the default module root for ``lmod`` is
+``$spack/share/spack/lmod`` and the default root for ``tcl`` is
+``$spack/share/spack/modules``. This can be overridden for any module
+set by changing the ``roots`` key of the configuration.
+
+.. code-block:: yaml
+
+   modules:
+     default:
+       roots:
+         tcl: /path/to/install/tcl/modules
+     my_custom_lmod_modules:
+       roots:
+         lmod: /path/to/install/custom/lmod/modules
+         ...
+
+This configuration will create two module sets. The default module set
+will install its ``tcl`` modules to ``/path/to/install/tcl/modules``
+(and still install its lmod modules, if any, to the default
+location). The set ``my_custom_lmod_modules`` will install its lmod
+modules to ``/path/to/install/custom/lmod/modules`` (and still install
+its tcl modules, if any, to the default location).
+
+Obviously, having multiple module sets install modules to the default
+location could be confusing to users of your modules. In the next
+section, we will discuss enabling and disabling module types (module
+file generators) for each module set.
+
 """"""""""""""""""""
 Activate other hooks
 """"""""""""""""""""
@@ -179,13 +233,14 @@ to the generator being customized:
 .. code-block:: yaml
 
    modules:
-     enable:
-       - tcl
-       - lmod
-     tcl:
-       # contains environment modules specific customizations
-     lmod:
-       # contains lmod specific customizations
+     default:
+       enable:
+         - tcl
+         - lmod
+       tcl:
+         # contains environment modules specific customizations
+       lmod:
+         # contains lmod specific customizations
 
 In general, the configuration options that you can use in ``modules.yaml`` will
 either change the layout of the module files on the filesystem, or they will affect
@@ -400,10 +455,16 @@ that are already in the LMod hierarchy.
 Customize environment modifications
 """""""""""""""""""""""""""""""""""
 
-You can control which prefixes in a Spack package are added to environment
-variables with the ``prefix_inspections`` section; this section maps relative
-prefixes to the list of environment variables which should be updated with
-those prefixes.
+You can control which prefixes in a Spack package are added to
+environment variables with the ``prefix_inspections`` section; this
+section maps relative prefixes to the list of environment variables
+which should be updated with those prefixes.
+
+The ``prefix_inspections`` configuration is different from other
+settings in that a ``prefix_inspections`` configuration at the
+``modules`` level of the configuration file applies to all module
+sets. This allows users to make general overrides to the default
+inspections and customize them per-module-set.
 
 .. code-block:: yaml
 
@@ -416,10 +477,66 @@ those prefixes.
       '':
         - CMAKE_PREFIX_PATH
 
-In this case, for a Spack package ``foo`` installed to ``/spack/prefix/foo``,
-the generated module file for ``foo`` would update ``PATH`` to contain
+Prefix inspections are only applied if the relative path inside the
+installation prefix exists. In this case, for a Spack package ``foo``
+installed to ``/spack/prefix/foo``, if ``foo`` installs executables to
+``bin`` but no libraries in ``lib``, the generated module file for
+``foo`` would update ``PATH`` to contain ``/spack/prefix/foo/bin`` and
+``CMAKE_PREFIX_PATH`` to contain ``/spack/prefix/foo``, but would not
+update ``LIBRARY_PATH``.
+
+There is a special case for prefix inspections relative to environment
+views. If all of the following conditions hold for a module set
+configuration:
+
+#. The configuration is for an :ref:`environment <environments>` and
+   will never be applied outside the environment,
+#. The environment in question is configured to use a :ref:`view
+   <filesystem-views>`,
+#. The :ref:`environment view is configured
+   <configuring_environment_views>` with a projection that ensures
+   every package is linked to a unique directory,
+
+then the module set may be configured to create modules relative to
+the environment view. This is specified by the ``use_view``
+configuration option in the module set. If ``True``, the module set is
+constructed relative to the default view of the
+environment. Otherwise, the value must be the name of the environment
+view relative to which to construct modules, or ``False-ish`` to
+disable the feature explicitly (the default is ``False``).
+
+If the ``use_view`` value is set in the config, then the prefix
+inspections for the package are done relative to the package's path in
+the view.
+
+.. code-block:: yaml
+
+   spack:
+     modules:
+       view_relative_modules:
+         use_view: my_view
+       prefix_inspections:
+         bin:
+           - PATH
+     view:
+       my_view:
+         projections:
+           root: /path/to/my/view
+           all:  '{name}-{hash}'
+
+The ``spack`` key is relevant to :ref:`environment <environments>`
+configuration, and the view key is discussed in detail in the section
+on :ref:`Configuring environment views
+<configuring_environment_views>`. With this configuration the
+generated module for package ``foo`` would set ``PATH`` to include
+``/path/to/my/view/foo-<hash>/bin`` instead of
 ``/spack/prefix/foo/bin``.
 
+The ``use_view`` option is useful when deploying a large software
+stack to users who are likely to inspect the modules to find full
+paths to software, when it is desirable to present the users with a
+simpler set of paths than those generated by the Spack install tree.
+
 """"""""""""""""""""""""""""""""""""
 Filter out environment modifications
 """"""""""""""""""""""""""""""""""""

lib/spack/docs/monitoring.rst

@@ -0,0 +1,120 @@
+.. Copyright 2013-2021 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)
+
+.. _monitoring:
+
+==========
+Monitoring
+==========
+
+You can use a `spack monitor <https://github.com/spack/spack-monitor>`_ "Spackmon"
+server to store a database of your packages, builds, and associated metadata 
+for provenance, research, or some other kind of development. You should
+follow the instructions in the `spack monitor documentation <https://spack-monitor.readthedocs.org>`_
+to first create a server along with a username and token for yourself.
+You can then use this guide to interact with the server.
+
+-------------------
+Analysis Monitoring
+-------------------
+
+To read about how to monitor an analysis (meaning you want to send analysis results
+to a server) see :ref:`analyze_monitoring`.
+
+---------------------
+Monitoring An Install
+---------------------
+
+Since an install is typically when you build packages, we logically want
+to tell spack to monitor during this step. Let's start with an example
+where we want to monitor the install of hdf5. Unless you have disabled authentication
+for the server, we first want to export our spack monitor token and username to the environment:
+
+.. code-block:: console
+ 
+    $ export SPACKMON_TOKEN=50445263afd8f67e59bd79bff597836ee6c05438
+    $ export SPACKMON_USER=spacky
+
+
+By default, the host for your server is expected to be at ``http://127.0.0.1``
+with a prefix of ``ms1``, and if this is the case, you can simply add the
+``--monitor`` flag to the install command:
+
+.. code-block:: console
+
+    $ spack install --monitor hdf5
+
+
+If you need to customize the host or the prefix, you can do that as well:
+
+.. code-block:: console
+
+    $ spack install --monitor --monitor-prefix monitor --monitor-host https://monitor-service.io hdf5
+
+
+As a precaution, we cut out early in the spack client if you have not provided
+authentication credentials. For example, if you run the command above without
+exporting your username or token, you'll see:
+
+.. code-block:: console
+
+    ==> Error: You are required to export SPACKMON_TOKEN and SPACKMON_USER
+
+This extra check is to ensure that we don't start any builds,
+and then discover that you forgot to export your token. However, if 
+your monitoring server has authentication disabled, you can tell this to
+the client to skip this step:
+
+.. code-block:: console
+
+    $ spack install --monitor --monitor-disable-auth hdf5
+
+If the service is not running, you'll cleanly exit early - the install will
+not continue if you've asked it to monitor and there is no service.
+For example, here is what you'll see if the monitoring service is not running:
+
+.. code-block:: console
+
+    [Errno 111] Connection refused
+
+
+If you want to continue builds (and stop monitoring) you can set the ``--monitor-keep-going``
+flag. 
+
+.. code-block:: console
+
+    $ spack install --monitor --monitor-keep-going hdf5
+
+This could mean that if a request fails, you only have partial or no data
+added to your monitoring database. This setting will not be applied to the
+first request to check if the server is running, but to subsequent requests.
+If you don't have a monitor server running and you want to build, simply
+don't provide the ``--monitor`` flag! Finally, if you want to provide one or
+more tags to your build, you can do:
+
+.. code-block:: console
+
+    # Add one tag, "pizza"
+    $ spack install --monitor --monitor-tags pizza hdf5
+
+    # Add two tags, "pizza" and "pasta"
+    $ spack install --monitor --monitor-tags pizza,pasta hdf5
+
+
+------------------
+Monitoring Offline
+------------------
+
+In the case that you want to save monitor results to your filesystem
+and then upload them later (perhaps you are in an environment where you don't
+have credentials or it isn't safe to use them) you can use the ``--monitor-save-local``
+flag.
+
+.. code-block:: console
+
+    $ spack install --monitor --monitor-save-local hdf5 
+
+This will save results in a subfolder, "monitor" in your designated spack
+reports folder, which defaults to ``$HOME/.spack/reports/monitor``.

lib/spack/docs/package_list.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)

lib/spack/docs/pipelines.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2019 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)
@@ -30,52 +30,18 @@ at least one `runner <https://docs.gitlab.com/runner/>`_.  Then the basic steps
 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 ``spack.yaml`` at the root containing your pipeline environment
 #. 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
-
-      stages: [generate, build]
-
-      generate-pipeline:
-        stage: generate
-        tags:
-          - <custom-tag>
-        script:
-          - 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
+   the pipeline dynamically, and one to run the generated jobs).
 #. 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 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.
+See the :ref:`functional_example` section for a minimal working example.  See also
+the :ref:`custom_Workflow` section for a link to an example of a custom workflow
+based on spack pipelines.
 
-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
+While it is possible to set up pipelines on gitlab.com, as illustrated above, the
+builds there are limited to 60 minutes and generic hardware.  It is also possible to
 `hook up <https://about.gitlab.com/blog/2018/04/24/getting-started-gitlab-ci-gcp>`_
 Gitlab to Google Kubernetes Engine (`GKE <https://cloud.google.com/kubernetes-engine/>`_)
 or Amazon Elastic Kubernetes Service (`EKS <https://aws.amazon.com/eks>`_), though those
@@ -88,21 +54,127 @@ dynamically generated
 Note that the use of dynamic child pipelines requires running Gitlab version
 ``>= 12.9``.
 
+.. _functional_example:
+
+------------------
+Functional Example
+------------------
+
+The simplest fully functional standalone example of a working pipeline can be
+examined live at this example `project <https://gitlab.com/scott.wittenburg/spack-pipeline-demo>`_
+on gitlab.com.
+
+Here's the ``.gitlab-ci.yml`` file from that example that builds and runs the
+pipeline:
+
+.. code-block:: yaml
+
+   stages: [generate, build]
+
+   variables:
+     SPACK_REPO: https://github.com/scottwittenburg/spack.git
+     SPACK_REF: pipelines-reproducible-builds
+
+   generate-pipeline:
+     stage: generate
+     tags:
+       - docker
+     image:
+       name: ghcr.io/scottwittenburg/ecpe4s-ubuntu18.04-runner-x86_64:2020-09-01
+       entrypoint: [""]
+     before_script:
+       - git clone ${SPACK_REPO}
+       - pushd spack && git checkout ${SPACK_REF} && popd
+       - . "./spack/share/spack/setup-env.sh"
+     script:
+       - spack env activate --without-view .
+       - spack -d ci generate
+         --artifacts-root "${CI_PROJECT_DIR}/jobs_scratch_dir"
+         --output-file "${CI_PROJECT_DIR}/jobs_scratch_dir/pipeline.yml"
+     artifacts:
+       paths:
+         - "${CI_PROJECT_DIR}/jobs_scratch_dir"
+
+   build-jobs:
+     stage: build
+     trigger:
+       include:
+         - artifact: "jobs_scratch_dir/pipeline.yml"
+           job: generate-pipeline
+       strategy: depend
+
+The key thing to note above is that there are two jobs: The first job to run,
+``generate-pipeline``, runs the ``spack ci generate`` command to generate a
+dynamic child pipeline and write it to a yaml file, which is then picked up
+by the second job, ``build-jobs``, and used to trigger the downstream pipeline.
+
+And here's the spack environment built by the pipeline represented as a
+``spack.yaml`` file:
+
+.. code-block:: yaml
+
+   spack:
+     view: false
+     concretization: separately
+
+     definitions:
+     - pkgs:
+       - zlib
+       - bzip2
+     - arch:
+       - '%gcc@7.5.0 arch=linux-ubuntu18.04-x86_64'
+
+     specs:
+     - matrix:
+       - - $pkgs
+       - - $arch
+
+     mirrors: { "mirror": "s3://spack-public/mirror" }
+
+     gitlab-ci:
+       before_script:
+         - git clone ${SPACK_REPO}
+         - pushd spack && git checkout ${SPACK_CHECKOUT_VERSION} && popd
+         - . "./spack/share/spack/setup-env.sh"
+       script:
+         - pushd ${SPACK_CONCRETE_ENV_DIR} && spack env activate --without-view . && popd
+         - spack -d ci rebuild
+       mappings:
+         - match: ["os=ubuntu18.04"]
+           runner-attributes:
+             image:
+               name: ghcr.io/scottwittenburg/ecpe4s-ubuntu18.04-runner-x86_64:2020-09-01
+               entrypoint: [""]
+             tags:
+               - docker
+       enable-artifacts-buildcache: True
+       rebuild-index: False
+
+The elements of this file important to spack ci pipelines are described in more
+detail below, but there are a couple of things to note about the above working
+example:
+
+Normally ``enable-artifacts-buildcache`` is not recommended in production as it
+results in large binary artifacts getting transferred back and forth between
+gitlab and the runners.  But in this example on gitlab.com where there is no
+shared, persistent file system, and where no secrets are stored for giving
+permission to write to an S3 bucket, ``enabled-buildcache-artifacts`` is the only
+way to propagate binaries from jobs to their dependents.
+
+Also, it is usually a good idea to let the pipeline generate a final "rebuild the
+buildcache index" job, so that subsequent pipeline generation can quickly determine
+which specs are up to date and which need to be rebuilt (it's a good idea for other
+reasons as well, but those are out of scope for this discussion).  In this case we
+have disabled it (using ``rebuild-index: False``) because the index would only be
+generated in the artifacts mirror anyway, and consequently would not be available
+during subesequent pipeline runs.
+
 -----------------------------------
 Spack commands supporting pipelines
 -----------------------------------
 
-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`.
+Spack provides a command ``ci`` command with a few sub-commands supporting spack
+ci pipelines.  These commands are covered in more detail in this section.
 
 .. _cmd-spack-ci:
 
@@ -121,24 +193,107 @@ pipeline jobs.
 
 Concretizes the specs in the active environment, stages them (as described in
 :ref:`staging_algorithm`), and writes the resulting ``.gitlab-ci.yml`` to disk.
+During concretization of the environment, ``spack ci generate`` also writes a
+``spack.lock`` file which is then provided to generated child jobs and made
+available in all generated job artifacts to aid in reproducing failed builds
+in a local environment.  This means there are two artifacts that need to be
+exported in your pipeline generation job (defined in your ``.gitlab-ci.yml``).
+The first is the output yaml file of ``spack ci generate``, and the other is
+the directory containing the concrete environment files.  In the
+:ref:`functional_example` section, we only mentioned one path in the
+``artifacts`` ``paths`` list because we used ``--artifacts-root`` as the
+top level directory containing both the generated pipeline yaml and the
+concrete environment.
 
-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.
+Using ``--prune-dag`` or ``--no-prune-dag`` configures whether or not jobs are
+generated for specs that are already up to date on the mirror.   If enabling
+DAG pruning using ``--prune-dag``, more information may be required in your
+``spack.yaml`` file, see the :ref:`noop_jobs` section below regarding
+``service-job-attributes``.
+
+The optional ``--check-index-only`` argument can be used to speed up pipeline
+generation by telling spack to consider only remote buildcache indices when
+checking the remote mirror to determine if each spec in the DAG is up to date
+or not.  The default behavior is for spack to fetch the index and check it,
+but if the spec is not found in the index, to also perform a direct check for
+the spec on the mirror.  If the remote buildcache index is out of date, which
+can easily happen if it is not updated frequently, this behavior ensures that
+spack has a way to know for certain about the status of any concrete spec on
+the remote mirror, but can slow down pipeline generation significantly.
+
+The ``--optimize`` argument is experimental and runs the generated pipeline
+document through a series of optimization passes designed to reduce the size
+of the generated file.
+
+The ``--dependencies`` is also experimental and disables what in Gitlab is
+referred to as DAG scheduling, internally using the ``dependencies`` keyword
+rather than ``needs`` to list dependency jobs.  The drawback of using this option
+is that before any job can begin, all jobs in previous stages must first
+complete.  The benefit is that Gitlab allows more dependencies to be listed
+when using ``dependencies`` instead of ``needs``.
+
+The optional ``--output-file`` argument should be an absolute path (including
+file name) to the generated pipeline, and if not given, the default is
+``./.gitlab-ci.yml``.
+
+While optional, the ``--artifacts-root`` argument is used to determine where
+the concretized environment directory should be located.  This directory will
+be created by ``spack ci generate`` and will contain the ``spack.yaml`` and
+generated ``spack.lock`` which are then passed to all child jobs as an
+artifact.  This directory will also be the root directory for all artifacts
+generated by jobs in the pipeline.
 
 .. _cmd-spack-ci-rebuild:
 
-^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^
 ``spack ci rebuild``
-^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^
 
-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.
+The purpose of the ``spack ci rebuild`` is straightforward: take its assigned
+spec job, check whether the target mirror already has a binary for that spec,
+and if not, build the spec from source and push the binary to the mirror.  To
+accomplish this in a reproducible way, the sub-command prepares a ``spack install``
+command line to build a single spec in the DAG, saves that command in a
+shell script, ``install.sh``, in the current working directory, and then runs
+it to install the spec.  The shell script is also exported as an artifact to
+aid in reproducing the build outside of the CI environment.
 
-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``.
+If it was necessary to install the spec from source, ``spack ci rebuild`` will
+also subsequently create a binary package for the spec and try to push it to the
+mirror.
+
+The ``spack ci rebuild`` sub-command mainly expects its "input" to come either
+from environment variables or from the ``gitlab-ci`` section of the ``spack.yaml``
+environment file.  There are two main sources of the environment variables, some
+are written into ``.gitlab-ci.yml`` by ``spack ci generate``, and some are
+provided by the GitLab CI runtime.
+
+.. _cmd-spack-ci-rebuild-index:
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+``spack ci rebuild-index``
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This is a convenience command to rebuild the buildcache index associated with
+the mirror in the active, gitlab-enabled environment (specifying the mirror
+url or name is not required).
+
+.. _cmd-spack-ci-reproduce-build:
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+``spack ci reproduce-build``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Given the url to a gitlab pipeline rebuild job, downloads and unzips the
+artifacts into a local directory (which can be specified with the optional
+``--working-dir`` argument), then finds the target job in the generated
+pipeline to extract details about how it was run.  Assuming the job used a
+docker image, the command prints a ``docker run`` command line and some basic
+instructions on how to reproduce the build locally.
+
+Note that jobs failing in the pipeline will print messages giving the
+arguments you can pass to ``spack ci reproduce-build`` in order to reproduce
+a particular build locally.
 
 ------------------------------------
 A pipeline-enabled spack environment
@@ -223,20 +378,12 @@ 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
-``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
-will re-generate the mirror's buildcache index after the buildcache entry for that
-job has been created and pushed to the mirror.  Since jobs in the same stage can run in
-parallel, there is the possibility that at the end of some stage, the index may not
-reflect all the binaries in the buildcache.  Adding the ``final-stage-rebuild-index``
-section ensures that at the end of the pipeline, the index will be in sync with the
-binaries on the mirror.  If the mirror lives in an S3 bucket, this job will need to
-run on a machine with the Python ``boto3`` module installed, and consequently the
-``final-stage-rebuild-index`` needs to specify a list of ``tags`` to pick a runner
-satisfying that condition.  It can also take an ``image`` key so Docker executor type
-runners can pick the right image for the index regeneration job.
+The optional ``broken-specs-url`` key tells Spack to check against a list of
+specs that are known to be currently broken in ``develop``. If any such specs
+are found, the ``spack ci generate`` command will fail with an error message
+informing the user what broken specs were encountered. This allows the pipeline
+to fail early and avoid wasting compute resources attempting to build packages
+that will not succeed.
 
 The optional ``cdash`` section provides information that will be used by the
 ``spack ci generate`` command (invoked by ``spack ci start``) for reporting
@@ -251,6 +398,76 @@ Take a look at the
 for the gitlab-ci section of the spack environment file, to see precisely what
 syntax is allowed there.
 
+.. _rebuild_index:
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Note about rebuilding buildcache index
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, while a pipeline job may rebuild a package, create a buildcache
+entry, and push it to the mirror, it does not automatically re-generate the
+mirror's buildcache index afterward.  Because the index is not needed by the
+default rebuild jobs in the pipeline, not updating the index at the end of
+each job avoids possible race conditions between simultaneous jobs, and it
+avoids the computational expense of regenerating the index.  This potentially
+saves minutes per job, depending on the number of binary packages in the
+mirror.  As a result, the default is that the mirror's buildcache index may
+not correctly reflect the mirror's contents at the end of a pipeline.
+
+To make sure the buildcache index is up to date at the end of your pipeline,
+spack generates a job to update the buildcache index of the target mirror
+at the end of each pipeline by default.  You can disable this behavior by
+adding ``rebuild-index: False`` inside the ``gitlab-ci`` section of your
+spack environment.  Spack will assign the job any runner attributes found
+on the ``service-job-attributes``, if you have provided that in your
+``spack.yaml``.
+
+.. _noop_jobs:
+
+^^^^^^^^^^^^^^^^^^^^^^^
+Note about "no-op" jobs
+^^^^^^^^^^^^^^^^^^^^^^^
+
+If no specs in an environment need to be rebuilt during a given pipeline run
+(meaning all are already up to date on the mirror), a single succesful job
+(a NO-OP) is still generated to avoid an empty pipeline (which GitLab
+considers to be an error).  An optional ``service-job-attributes`` section
+can be added to your ``spack.yaml`` where you can provide ``tags`` and
+``image`` or ``variables`` for the generated NO-OP job.  This section also
+supports providing ``before_script``, ``script``, and ``after_script``, in
+case you want to take some custom actions in the case of any empty pipeline.
+
+Following is an example of this section added to a ``spack.yaml``:
+
+.. code-block:: yaml
+
+   spack:
+     specs:
+       - openmpi
+     mirrors:
+       cloud_gitlab: https://mirror.spack.io
+     gitlab-ci:
+       mappings:
+         - match:
+             - os=centos8
+           runner-attributes:
+             tags:
+               - custom
+               - tag
+             image: spack/centos7
+       service-job-attributes:
+         tags: ['custom', 'tag']
+         image:
+           name: 'some.image.registry/custom-image:latest'
+           entrypoint: ['/bin/bash']
+         script:
+           - echo "Custom message in a custom script"
+
+The example above illustrates how you can provide the attributes used to run
+the NO-OP job in the case of an empty pipeline.  The only field for the NO-OP
+job that might be generated for you is ``script``, but that will only happen
+if you do not provide one yourself.
+
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Assignment of specs to runners
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -285,8 +502,9 @@ 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
+a custom ``script``, spack will generate one for you that assumes the concrete
+environment directory is located within your ``--artifacts_root`` (or if not
+provided, within your ``$CI_PROJECT_DIR``), activates that environment for
 you, and invokes ``spack ci rebuild``.
 
 .. _staging_algorithm:
@@ -411,14 +629,15 @@ 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 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
+user-provided pipeline scripts to accomplish this fairly simply.  First, consider
+specifying the source and version of spack you want to use with variables, either
+written directly into your ``.gitlab-ci.yml``, or provided by CI variables defined
+in the gitlab UI or from some upstream pipeline.  Let's say you choose the variable
+names ``SPACK_REPO`` and ``SPACK_REF`` to refer to the particular fork of spack
+and branch you want for running your pipeline.  You can then refer to those in a
+custom shell script invoked both from your pipeline generation job and 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:
+updated to clone and source a custom spack:
 
 .. code-block:: yaml
 
@@ -426,34 +645,24 @@ spack:
      tags:
        - <some-other-tag>
    before_script:
-     - ./cloneSpack.sh
+     - git clone ${SPACK_REPO}
+     - pushd spack && git checkout ${SPACK_REF} && popd
+     - . "./spack/share/spack/setup-env.sh"
    script:
      - spack env activate --without-view .
-     - spack ci generate
+     - spack ci generate --check-index-only
+       --artifacts-root "${CI_PROJECT_DIR}/jobs_scratch_dir"
        --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"
+       - "${CI_PROJECT_DIR}/jobs_scratch_dir"
 
-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:
+That takes care of getting the desired version of spack when your pipeline is
+generated by ``spack ci generate``.  You also want your generated rebuild jobs
+(all of them) to clone that version of spack, so next you would update your
+``spack.yaml`` from above as follows:
 
 .. code-block:: yaml
 
@@ -468,21 +677,21 @@ of spack, so you would update your ``spack.yaml`` from above as follows:
                - spack-kube
              image: spack/ubuntu-bionic
              before_script:
-               - ./cloneSpack.sh
+               - git clone ${SPACK_REPO}
+               - pushd spack && git checkout ${SPACK_REF} && popd
+               - . "./spack/share/spack/setup-env.sh"
              script:
-               - spack env activate --without-view .
+               - spack env activate --without-view ${SPACK_CONCRETE_ENV_DIR}
                - 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.
+spack before running their actual workload.
 
 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
+frequently, such as the main repo and its ``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
@@ -492,13 +701,32 @@ 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}``.
+simply replace ``git checkout ${SPACK_REF}`` in the example ``spack.yaml``
+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``).
+and you can instead just clone using the variables you define (``SPACK_REPO``
+and ``SPACK_REF`` in the example aboves).
+
+.. _custom_workflow:
+
+---------------
+Custom Workflow
+---------------
+
+There are many ways to take advantage of spack CI pipelines to achieve custom
+workflows for building packages or other resources.  One example of a custom
+pipelines workflow is the spack tutorial container
+`repo <https://github.com/spack/spack-tutorial-container>`_.  This project uses
+GitHub (for source control), GitLab (for automated spack ci pipelines), and
+DockerHub automated builds to build Docker images (complete with fully populate
+binary mirror) used by instructors and participants of a spack tutorial.
+
+Take a look a the repo to see how it is accomplished using spack CI pipelines,
+and see the following markdown files at the root of the repository for
+descriptions and documentation describing the workflow: ``DESCRIPTION.md``,
+``DOCKERHUB_SETUP.md``, ``GITLAB_SETUP.md``, and ``UPDATING.md``.
 
 .. _ci_environment_variables:
 
@@ -515,28 +743,33 @@ environment variables used by the pipeline infrastructure are described here.
 AWS_ACCESS_KEY_ID
 ^^^^^^^^^^^^^^^^^
 
-Needed when binary mirror is an S3 bucket.
+Optional.  Only needed when binary mirror is an S3 bucket.
 
 ^^^^^^^^^^^^^^^^^^^^^
 AWS_SECRET_ACCESS_KEY
 ^^^^^^^^^^^^^^^^^^^^^
 
-Needed when binary mirror is an S3 bucket.
+Optional.  Only needed when binary mirror is an S3 bucket.
 
 ^^^^^^^^^^^^^^^
 S3_ENDPOINT_URL
 ^^^^^^^^^^^^^^^
 
-Needed when binary mirror is an S3 bucket that is *not* on AWS.
+Optional.  Only needed when binary mirror is an S3 bucket that is *not* on AWS.
 
 ^^^^^^^^^^^^^^^^^
 CDASH_AUTH_TOKEN
 ^^^^^^^^^^^^^^^^^
 
-Needed in order to report build groups to CDash.
+Optional. Only needed in order to report build groups to CDash.
 
 ^^^^^^^^^^^^^^^^^
 SPACK_SIGNING_KEY
 ^^^^^^^^^^^^^^^^^
 
-Needed to sign/verify binary packages from the remote binary mirror.
+Optional.  Only needed if you want ``spack ci rebuild`` to trust the key you
+store in this variable, in which case, it will subsequently be used to sign and
+verify binary packages (when installing or creating buildcaches).  You could
+also have already trusted a key spack know about, or if no key is present anywhere,
+spack will install specs using ``--no-check-signature`` and create buildcaches
+using ``-u`` (for unsigned binaries).

lib/spack/docs/repositories.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)
@@ -9,7 +9,7 @@
 Package Repositories
 =============================
 
-Spack comes with over 1,000 built-in package recipes in
+Spack comes with thousands of built-in package recipes in
 ``var/spack/repos/builtin/``.  This is a **package repository** -- a
 directory that Spack searches when it needs to find a package by name.
 You may need to maintain packages for restricted, proprietary or

lib/spack/docs/spack.yaml

@@ -1,4 +1,4 @@
-# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2021 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)

lib/spack/docs/workflows.rst

@@ -1,4 +1,4 @@
-.. Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+.. Copyright 2013-2021 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)

lib/spack/env/cc

@@ -1,6 +1,6 @@
 #!/bin/bash
 #
-# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2021 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)
@@ -125,7 +125,7 @@ case "$command" in
         comp="FC"
         lang_flags=F
         ;;
-    f77|xlf|xlf_r|pgf77|frt|flang)
+    f77|xlf|xlf_r|pgf77)
         command="$SPACK_F77"
         language="Fortran 77"
         comp="F77"
@@ -277,14 +277,22 @@ other_args=()
 isystem_system_includes=()
 isystem_includes=()
 
-while [ -n "$1" ]; do
+while [ $# -ne 0 ]; do
+
     # an RPATH to be added after the case statement.
     rp=""
 
+    # Multiple consecutive spaces in the command line can
+    # result in blank arguments
+    if [ -z "$1" ]; then
+        shift
+        continue
+    fi
+
     case "$1" in
         -isystem*)
             arg="${1#-isystem}"
-	    isystem_was_used=true
+            isystem_was_used=true
             if [ -z "$arg" ]; then shift; arg="$1"; fi
             if system_dir "$arg"; then
                 isystem_system_includes+=("$arg")
@@ -311,6 +319,16 @@ while [ -n "$1" ]; do
             fi
             ;;
         -l*)
+            # -loopopt=0 is generated erroneously in autoconf <= 2.69,
+            # and passed by ifx to the linker, which confuses it with a 
+            # library. Filter it out.
+            # TODO: generalize filtering of args with an env var, so that
+            # TODO: we do not have to special case this here.
+            if { [ "$mode" = "ccld" ] || [ $mode = "ld" ]; } \
+                && [ "$1" != "${1#-loopopt}" ]; then
+                shift
+                continue
+            fi
             arg="${1#-l}"
             if [ -z "$arg" ]; then shift; arg="$1"; fi
             other_args+=("-l$arg")
@@ -320,9 +338,13 @@ while [ -n "$1" ]; do
             if [ -z "$arg" ]; then shift; arg="$1"; fi
             if [[ "$arg" = -rpath=* ]]; then
                 rp="${arg#-rpath=}"
+            elif [[ "$arg" = --rpath=* ]]; then
+                rp="${arg#--rpath=}"
             elif [[ "$arg" = -rpath,* ]]; then
                 rp="${arg#-rpath,}"
-            elif [[ "$arg" = -rpath ]]; then
+            elif [[ "$arg" = --rpath,* ]]; then
+                rp="${arg#--rpath,}"
+            elif [[ "$arg" =~ ^-?-rpath$ ]]; then
                 shift; arg="$1"
                 if [[ "$arg" != -Wl,* ]]; then
                     die "-Wl,-rpath was not followed by -Wl,*"
@@ -339,7 +361,9 @@ while [ -n "$1" ]; do
             if [ -z "$arg" ]; then shift; arg="$1"; fi
             if [[ "$arg" = -rpath=* ]]; then
                 rp="${arg#-rpath=}"
-            elif [[ "$arg" = -rpath ]]; then
+            elif [[ "$arg" = --rpath=* ]]; then
+                rp="${arg#--rpath=}"
+            elif [[ "$arg" = -rpath  ]] || [[ "$arg" = --rpath ]]; then
                 shift; arg="$1"
                 if [[ "$arg" != -Xlinker,* ]]; then
                     die "-Xlinker,-rpath was not followed by -Xlinker,*"
@@ -434,7 +458,7 @@ then
         ld)
             flags=("${flags[@]}" -headerpad_max_install_names) ;;
         ccld)
-            flags=("${flags[@]}" -Wl,-headerpad_max_install_names) ;;
+            flags=("${flags[@]}" "-Wl,-headerpad_max_install_names") ;;
     esac
 fi
 
@@ -491,19 +515,19 @@ args+=("${flags[@]}")
 # 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
+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
+        for dir in "${spack_include_dirs[@]}";  do args+=("-isystem" "$dir"); done
     else
-	for dir in "${spack_include_dirs[@]}";  do args+=("-I$dir"); done
+        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
+for dir in "${isystem_system_includes[@]}";  do args+=("-isystem" "$dir"); done
 
 # Library search paths
 for dir in "${libdirs[@]}";          do args+=("-L$dir"); done
@@ -512,12 +536,12 @@ for dir in "${system_libdirs[@]}";   do args+=("-L$dir"); done
 # RPATHs arguments
 case "$mode" in
     ccld)
-        if [ ! -z "$dtags_to_add" ] ; then args+=("$linker_arg$dtags_to_add") ; fi
+        if [ -n "$dtags_to_add" ] ; then args+=("$linker_arg$dtags_to_add") ; fi
         for dir in "${rpaths[@]}";        do args+=("$rpath$dir"); done
         for dir in "${system_rpaths[@]}"; do args+=("$rpath$dir"); done
         ;;
     ld)
-        if [ ! -z "$dtags_to_add" ] ; then args+=("$dtags_to_add") ; fi
+        if [ -n "$dtags_to_add" ] ; then args+=("$dtags_to_add") ; fi
         for dir in "${rpaths[@]}";        do args+=("-rpath" "$dir"); done
         for dir in "${system_rpaths[@]}"; do args+=("-rpath" "$dir"); done
         ;;

lib/spack/external/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2021 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)
@@ -11,7 +11,7 @@
 
 * Homepage: https://pypi.python.org/pypi/archspec
 * Usage: Labeling, comparison and detection of microarchitectures
-* Version: 0.1.2 (commit 2846749dc5b12ae2b30ff1d3f0270a4a5954710d)
+* Version: 0.1.2 (commit 130607c373fd88cd3c43da94c0d3afd3a44084b0)
 
 argparse
 --------

lib/spack/external/archspec/__init__.py

@@ -1,2 +1,2 @@
 """Init file to avoid namespace packages"""
-__version__ = "0.1.1"
+__version__ = "0.1.2"

lib/spack/external/archspec/cpu/detect.py

@@ -99,17 +99,29 @@ def sysctl_info_dict():
     def sysctl(*args):
         return _check_output(["sysctl"] + list(args), env=child_environment).strip()
 
-    flags = (
-        sysctl("-n", "machdep.cpu.features").lower()
-        + " "
-        + sysctl("-n", "machdep.cpu.leaf7_features").lower()
-    )
-    info = {
-        "vendor_id": sysctl("-n", "machdep.cpu.vendor"),
-        "flags": flags,
-        "model": sysctl("-n", "machdep.cpu.model"),
-        "model name": sysctl("-n", "machdep.cpu.brand_string"),
-    }
+    if platform.machine() == "x86_64":
+        flags = (
+            sysctl("-n", "machdep.cpu.features").lower()
+            + " "
+            + sysctl("-n", "machdep.cpu.leaf7_features").lower()
+        )
+        info = {
+            "vendor_id": sysctl("-n", "machdep.cpu.vendor"),
+            "flags": flags,
+            "model": sysctl("-n", "machdep.cpu.model"),
+            "model name": sysctl("-n", "machdep.cpu.brand_string"),
+        }
+    else:
+        model = (
+            "m1" if "Apple" in sysctl("-n", "machdep.cpu.brand_string") else "unknown"
+        )
+        info = {
+            "vendor_id": "Apple",
+            "flags": [],
+            "model": model,
+            "CPU implementer": "Apple",
+            "model name": sysctl("-n", "machdep.cpu.brand_string"),
+        }
     return info
 
 
@@ -173,6 +185,11 @@ def compatible_microarchitectures(info):
         info (dict): dictionary containing information on the host cpu
     """
     architecture_family = platform.machine()
+    # On Apple M1 platform.machine() returns "arm64" instead of "aarch64"
+    # so we should normalize the name here
+    if architecture_family == "arm64":
+        architecture_family = "aarch64"
+
     # If a tester is not registered, be conservative and assume no known
     # target is compatible with the host
     tester = COMPATIBILITY_CHECKS.get(architecture_family, lambda x, y: False)

lib/spack/external/archspec/json/cpu/microarchitectures.json

@@ -75,6 +75,13 @@
             "flags": "-march={name} -mtune=generic"
           }
         ],
+        "aocc": [
+          {
+            "versions": "2.2:",
+            "name": "x86-64",
+            "flags": "-march={name} -mtune=generic"
+          }
+        ],
         "intel": [
           {
             "versions": ":",
@@ -84,6 +91,166 @@
         ]
       }
     },
+    "x86_64_v2": {
+      "from": ["x86_64"],
+      "vendor": "generic",
+      "features": [
+        "cx16",
+        "lahf_lm",
+        "mmx",
+        "sse",
+        "sse2",
+        "ssse3",
+        "sse4_1",
+        "sse4_2",
+        "popcnt"
+      ],
+      "compilers": {
+        "gcc": [
+          {
+            "versions": "11.1:",
+            "name": "x86-64-v2",
+            "flags": "-march={name} -mtune=generic"
+          },
+          {
+            "versions": "4.6:11.0",
+            "name": "x86-64",
+            "flags": "-march={name} -mtune=generic -mcx16 -msahf -mpopcnt -msse3 -msse4.1 -msse4.2 -mssse3"
+          }
+        ],
+        "clang": [
+          {
+            "versions": "12.0:",
+            "name": "x86-64-v2",
+            "flags": "-march={name} -mtune=generic"
+          },
+          {
+            "versions": "3.9:11.1",
+            "name": "x86-64",
+            "flags": "-march={name} -mtune=generic -mcx16 -msahf -mpopcnt -msse3 -msse4.1 -msse4.2 -mssse3"
+          }
+        ]
+      }
+    },
+    "x86_64_v3": {
+      "from": ["x86_64_v2"],
+      "vendor": "generic",
+      "features": [
+        "cx16",
+        "lahf_lm",
+        "mmx",
+        "sse",
+        "sse2",
+        "ssse3",
+        "sse4_1",
+        "sse4_2",
+        "popcnt",
+        "avx",
+        "avx2",
+        "bmi1",
+        "bmi2",
+        "f16c",
+        "fma",
+        "abm",
+        "movbe",
+        "xsave"
+      ],
+      "compilers": {
+        "gcc": [
+          {
+            "versions": "11.1:",
+            "name": "x86-64-v3",
+            "flags": "-march={name} -mtune=generic"
+          },
+          {
+            "versions": "4.8:11.0",
+            "name": "x86-64",
+            "flags": "-march={name} -mtune=generic -mcx16 -msahf -mpopcnt -msse3 -msse4.1 -msse4.2 -mssse3 -mavx -mavx2 -mbmi -mbmi2 -mf16c -mfma -mlzcnt -mmovbe -mxsave"
+          }
+        ],
+        "clang": [
+          {
+            "versions": "12.0:",
+            "name": "x86-64-v3",
+            "flags": "-march={name} -mtune=generic"
+          },
+          {
+            "versions": "3.9:11.1",
+            "name": "x86-64",
+            "flags": "-march={name} -mtune=generic -mcx16 -msahf -mpopcnt -msse3 -msse4.1 -msse4.2 -mssse3 -mavx -mavx2 -mbmi -mbmi2 -mf16c -mfma -mlzcnt -mmovbe -mxsave"
+          }
+        ],
+        "apple-clang": [
+          {
+            "versions": "8.0:",
+            "name": "x86-64",
+            "flags": "-march={name} -mtune=generic -mcx16 -msahf -mpopcnt -msse3 -msse4.1 -msse4.2 -mssse3 -mavx -mavx2 -mbmi -mbmi2 -mf16c -mfma -mlzcnt -mmovbe -mxsave"
+          }
+        ]
+      }
+    },
+    "x86_64_v4": {
+      "from": ["x86_64_v3"],
+      "vendor": "generic",
+      "features": [
+        "cx16",
+        "lahf_lm",
+        "mmx",
+        "sse",
+        "sse2",
+        "ssse3",
+        "sse4_1",
+        "sse4_2",
+        "popcnt",
+        "avx",
+        "avx2",
+        "bmi1",
+        "bmi2",
+        "f16c",
+        "fma",
+        "abm",
+        "movbe",
+        "xsave",
+        "avx512f",
+        "avx512bw",
+        "avx512cd",
+        "avx512dq",
+        "avx512vl"
+      ],
+      "compilers": {
+        "gcc": [
+          {
+            "versions": "11.1:",
+            "name": "x86-64-v4",
+            "flags": "-march={name} -mtune=generic"
+          },
+          {
+            "versions": "6.0:11.0",
+            "name": "x86-64",
+            "flags": "-march={name} -mtune=generic -mcx16 -msahf -mpopcnt -msse3 -msse4.1 -msse4.2 -mssse3 -mavx -mavx2 -mbmi -mbmi2 -mf16c -mfma -mlzcnt -mmovbe -mxsave -mavx512f -mavx512bw -mavx512cd -mavx512dq -mavx512vl"
+          }
+        ],
+        "clang": [
+          {
+            "versions": "12.0:",
+            "name": "x86-64-v4",
+            "flags": "-march={name} -mtune=generic"
+          },
+          {
+            "versions": "3.9:11.1",
+            "name": "x86-64",
+            "flags": "-march={name} -mtune=generic -mcx16 -msahf -mpopcnt -msse3 -msse4.1 -msse4.2 -mssse3 -mavx -mavx2 -mbmi -mbmi2 -mf16c -mfma -mlzcnt -mmovbe -mxsave -mavx512f -mavx512bw -mavx512cd -mavx512dq -mavx512vl"
+          }
+        ],
+        "apple-clang": [
+          {
+            "versions": "8.0:",
+            "name": "x86-64",
+            "flags": "-march={name} -mtune=generic -mcx16 -msahf -mpopcnt -msse3 -msse4.1 -msse4.2 -mssse3 -mavx -mavx2 -mbmi -mbmi2 -mf16c -mfma -mlzcnt -mmovbe -mxsave -mavx512f -mavx512bw -mavx512cd -mavx512dq -mavx512vl"
+          }
+        ]
+      }
+    },
     "nocona": {
       "from": ["x86_64"],
       "vendor": "GenuineIntel",
@@ -106,6 +273,12 @@
             "flags": "-march={name} -mtune={name}"
           }
         ],
+        "aocc": [
+          {
+            "versions": "2.2:",
+            "flags": "-march={name} -mtune=generic"
+          }
+        ],
         "apple-clang": [
           {
             "versions": "8.0:",
@@ -143,6 +316,12 @@
             "flags": "-march={name} -mtune={name}"
           }
         ],
+        "aocc": [
+          {
+            "versions": "2.2:",
+            "flags": "-march={name} -mtune=generic"
+          }
+        ],
         "apple-clang": [
           {
             "versions": "8.0:",
@@ -152,13 +331,13 @@
         "intel": [
           {
             "versions": "16.0:",
-            "flags": "-march={name} -mtune={name}}"
+            "flags": "-march={name} -mtune={name}"
           }
         ]
       }
     },
     "nehalem": {
-      "from": ["core2"],
+      "from": ["core2", "x86_64_v2"],
       "vendor": "GenuineIntel",
       "features": [
         "mmx",
@@ -187,6 +366,12 @@
             "flags": "-march={name} -mtune={name}"
           }
         ],
+        "aocc": [
+          {
+            "versions": "2.2:",
+            "flags": "-march={name} -mtune=generic"
+          }
+        ],
         "apple-clang": [
           {
             "versions": "8.0:",
@@ -229,6 +414,12 @@
             "flags": "-march={name} -mtune={name}"
           }
         ],
+        "aocc": [
+          {
+            "versions": "2.2:",
+            "flags": "-march={name} -mtune=generic"
+          }
+        ],
         "apple-clang": [
           {
             "versions": "8.0:",
@@ -277,6 +468,12 @@
             "flags": "-march={name} -mtune={name}"
           }
         ],
+        "aocc": [
+          {
+            "versions": "2.2:",
+            "flags": "-march={name} -mtune={name}"
+          }
+        ],
         "apple-clang": [
           {
             "versions": "8.0:",
@@ -331,6 +528,12 @@
             "flags": "-march={name} -mtune={name}"
           }
         ],
+        "aocc": [
+          {
+            "versions": "2.2:",
+            "flags": "-march={name} -mtune={name}"
+          }
+        ],
         "apple-clang": [
           {
             "versions": "8.0:",
@@ -351,7 +554,7 @@
       }
     },
     "haswell": {
-      "from": ["ivybridge"],
+      "from": ["ivybridge", "x86_64_v3"],
       "vendor": "GenuineIntel",
       "features": [
         "mmx",
@@ -390,6 +593,12 @@
             "flags": "-march={name} -mtune={name}"
           }
         ],
+        "aocc": [
+          {
+            "versions": "2.2:",
+            "flags": "-march={name} -mtune={name}"
+          }
+        ],
         "apple-clang": [
           {
             "versions": "8.0:",
@@ -446,6 +655,12 @@
             "flags": "-march={name} -mtune={name}"
           }
         ],
+        "aocc": [
+          {
+            "versions": "2.2:",
+            "flags": "-march={name} -mtune={name}"
+          }
+        ],
         "apple-clang": [
           {
             "versions": "8.0:",
@@ -500,6 +715,12 @@
             "flags": "-march={name} -mtune={name}"
           }
         ],
+        "aocc": [
+          {
+            "versions": "2.2:",
+            "flags": "-march={name} -mtune={name}"
+          }
+        ],
         "apple-clang": [
           {
             "versions": "8.0:",
@@ -558,6 +779,13 @@
             "flags": "-march={name} -mtune={name}"
           }
         ],
+        "aocc": [
+          {
+            "versions": "2.2:",
+            "name": "knl",
+            "flags": "-march={name} -mtune=generic"
+          }
+        ],
         "apple-clang": [
           {
             "versions": "8.0:",
@@ -574,7 +802,7 @@
       }
     },
     "skylake_avx512": {
-      "from": ["skylake"],
+      "from": ["skylake", "x86_64_v4"],
       "vendor": "GenuineIntel",
       "features": [
         "mmx",
@@ -621,6 +849,13 @@
             "flags": "-march={name} -mtune={name}"
           }
         ],
+        "aocc": [
+          {
+            "versions": "2.2:",
+            "name": "skylake-avx512",
+            "flags": "-march={name} -mtune=generic"
+          }
+        ],
         "apple-clang": [
           {
             "versions": "8.0:",
@@ -685,6 +920,12 @@
             "flags": "-march={name} -mtune={name}"
           }
         ],
+        "aocc": [
+          {
+            "versions": "2.2:",
+            "flags": "-march={name} -mtune={name}"
+          }
+        ],
         "apple-clang": [
           {
             "versions": "8.0:",
@@ -746,6 +987,12 @@
             "flags": "-march={name} -mtune={name}"
           }
         ],
+        "aocc": [
+          {
+            "versions": "2.2:",
+            "flags": "-march={name} -mtune={name}"
+          }
+        ],
         "apple-clang": [
           {
             "versions": "11.0:",
@@ -754,7 +1001,7 @@
         ],
         "intel": [
           {
-            "versions": "19.0:",
+            "versions": "19.0.1:",
             "flags": "-march={name} -mtune={name}"
           }
         ]
@@ -827,6 +1074,13 @@
             "flags": "-march={name} -mtune={name}"
           }
         ],
+        "aocc": [
+          {
+            "versions": "2.2:",
+            "name": "icelake-client",
+            "flags": "-march={name} -mtune={name}"
+          }
+        ],
         "apple-clang": [
           {
             "versions": "10.0.1:",
@@ -875,6 +1129,13 @@
             "flags": "-march={name} -mtune={name}"
           }
         ],
+        "aocc": [
+          {
+            "versions": "2.2:",
+            "name": "amdfam10",
+            "flags": "-march={name} -mtune={name}"
+          }
+        ],
         "intel": [
           {
             "versions": "16.0:",
@@ -885,7 +1146,7 @@
       }
     },
     "bulldozer": {
-      "from": ["x86_64"],
+      "from": ["x86_64_v2"],
       "vendor": "AuthenticAMD",
       "features": [
         "mmx",
@@ -918,6 +1179,13 @@
             "flags": "-march={name} -mtune={name}"
           }
         ],
+        "aocc": [
+          {
+            "versions": "2.2:",
+            "name": "bdver1",
+            "flags": "-march={name} -mtune={name}"
+          }
+        ],
         "intel": [
           {
             "versions": "16.0:",
@@ -965,6 +1233,13 @@
             "flags": "-march={name} -mtune={name}"
           }
         ],
+        "aocc": [
+          {
+            "versions": "2.2:",
+            "name": "bdver2",
+            "flags": "-march={name} -mtune={name}"
+          }
+        ],
         "intel": [
           {
             "versions": "16.0:",
@@ -1013,6 +1288,13 @@
             "flags": "-march={name} -mtune={name}"
           }
         ],
+        "aocc": [
+          {
+            "versions": "2.2:",
+            "name": "bdver3",
+            "flags": "-march={name} -mtune={name}"
+          }
+        ],
         "intel": [
           {
             "versions": "16.0:",
@@ -1023,7 +1305,7 @@
       }
     },
     "excavator": {
-      "from": ["steamroller"],
+      "from": ["steamroller", "x86_64_v3"],
       "vendor": "AuthenticAMD",
       "features": [
         "mmx",
@@ -1064,6 +1346,13 @@
             "flags": "-march={name} -mtune={name}"
           }
         ],
+        "aocc": [
+          {
+            "versions": "2.2:",
+            "name": "bdver4",
+            "flags": "-march={name} -mtune={name}"
+          }
+        ],
         "intel": [
           {
             "versions": "16.0:",
@@ -1075,7 +1364,7 @@
       }
     },
     "zen": {
-      "from": ["x86_64"],
+      "from": ["x86_64_v3"],
       "vendor": "AuthenticAMD",
       "features": [
         "bmi1",
@@ -1119,6 +1408,13 @@
             "flags": "-march={name} -mtune={name}"
           }
         ],
+        "aocc": [
+          {
+            "versions": "2.2:",
+            "name": "znver1",
+            "flags": "-march={name} -mtune={name}"
+          }
+        ],
         "intel": [
           {
             "versions": "16.0:",
@@ -1175,6 +1471,13 @@
             "flags": "-march={name} -mtune={name}"
           }
         ],
+        "aocc": [
+          {
+            "versions": "2.2:",
+            "name": "znver2",
+            "flags": "-march={name} -mtune={name}"
+          }
+        ],
         "intel": [
           {
             "versions": "16.0:",
@@ -1185,6 +1488,64 @@
         ]
       }
     },
+    "zen3": {
+      "from": ["zen2"],
+      "vendor": "AuthenticAMD",
+      "features": [
+        "bmi1",
+        "bmi2",
+        "f16c",
+        "fma",
+        "fsgsbase",
+        "avx",
+        "avx2",
+        "rdseed",
+        "clzero",
+        "aes",
+        "pclmulqdq",
+        "cx16",
+        "movbe",
+        "mmx",
+        "sse",
+        "sse2",
+        "sse4a",
+        "ssse3",
+        "sse4_1",
+        "sse4_2",
+        "abm",
+        "xsavec",
+        "xsaveopt",
+        "clflushopt",
+        "popcnt",
+        "clwb",
+        "vaes",
+        "vpclmulqdq",
+        "pku"
+      ],
+      "compilers": {
+        "gcc": [
+          {
+            "versions": "10.3:",
+            "name": "znver3",
+            "flags": "-march={name} -mtune={name}"
+          }
+        ],
+        "clang": [
+          {
+            "versions": "12.0:",
+            "name": "znver3",
+            "flags": "-march={name} -mtune={name}"
+          }
+        ],
+        "aocc": [
+          {
+            "versions": "3.0:",
+            "name": "znver3",
+            "flags": "-march={name} -mtune={name}"
+          }
+        ]
+      }
+    },
     "ppc64": {
       "from": [],
       "vendor": "generic",
@@ -1358,6 +1719,12 @@
             "versions": ":",
             "flags": "-march=armv8-a -mtune=generic"
           }
+        ],
+        "apple-clang": [
+          {
+            "versions": ":",
+            "flags": "-march=armv8-a -mtune=generic"
+          }
         ]
       }
     },
@@ -1566,6 +1933,31 @@
           ]
       }
     },
+    "m1": {
+      "from": ["aarch64"],
+      "vendor": "Apple",
+      "features": [],
+      "compilers": {
+        "gcc": [
+          {
+            "versions": "8.0:",
+            "flags" : "-march=armv8.4-a -mtune=generic"
+          }
+        ],
+        "clang" : [
+          {
+            "versions": "9.0:",
+            "flags" : "-march=armv8.4-a"
+          }
+        ],
+        "apple-clang": [
+          {
+            "versions": "11.0:",
+            "flags" : "-march=armv8.4-a"
+          }
+        ]
+      }
+    },
     "arm": {
       "from": [],
       "vendor": "generic",

lib/spack/external/ordereddict_backport.py

@@ -1,4 +1,4 @@
-# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2021 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)

lib/spack/external/py2/typing.py

@@ -0,0 +1,84 @@
+# Copyright 2013-2021 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)
+"""
+This is a fake set of symbols to allow spack to import typing in python
+versions where we do not support type checking (<3)
+"""
+Annotated = None
+Any = None
+Callable = None
+ForwardRef = None
+Generic = None
+Literal = None
+Optional = None
+Tuple = None
+TypeVar = None
+Union = None
+AbstractSet = None
+ByteString = None
+Container = None
+Hashable = None
+ItemsView = None
+Iterable = None
+Iterator = None
+KeysView = None
+Mapping = None
+MappingView = None
+MutableMapping = None
+MutableSequence = None
+MutableSet = None
+Sequence = None
+Sized = None
+ValuesView = None
+Awaitable = None
+AsyncIterator = None
+AsyncIterable = None
+Coroutine = None
+Collection = None
+AsyncGenerator = None
+AsyncContextManager = None
+Reversible = None
+SupportsAbs = None
+SupportsBytes = None
+SupportsComplex = None
+SupportsFloat = None
+SupportsInt = None
+SupportsRound = None
+ChainMap = None
+Dict = None
+List = None
+OrderedDict = None
+Set = None
+FrozenSet = None
+NamedTuple = None
+Generator = None
+AnyStr = None
+cast = None
+get_args = None
+get_origin = None
+get_type_hints = None
+no_type_check = None
+no_type_check_decorator = None
+NoReturn = None
+
+# these are the typing extension symbols
+ClassVar = None
+Final = None
+Protocol = None
+Type = None
+TypedDict = None
+ContextManager = None
+Counter = None
+Deque = None
+DefaultDict = None
+SupportsIndex = None
+final = None
+IntVar = None
+Literal = None
+NewType = None
+overload = None
+runtime_checkable = None
+Text = None
+TYPE_CHECKING = None

lib/spack/llnl/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2021 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)

lib/spack/llnl/util/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2021 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)

lib/spack/llnl/util/argparsewriter.py

@@ -1,4 +1,4 @@
-# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2021 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)

lib/spack/llnl/util/filesystem.py

@@ -1,4 +1,4 @@
-# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2021 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)
@@ -69,7 +69,8 @@
     'touchp',
     'traverse_tree',
     'unset_executable_mode',
-    'working_dir'
+    'working_dir',
+    'keep_modification_time'
 ]
 
 
@@ -1825,3 +1826,24 @@ def remove_directory_contents(dir):
                 os.unlink(entry)
             else:
                 shutil.rmtree(entry)
+
+
+@contextmanager
+def keep_modification_time(*filenames):
+    """
+    Context manager to keep the modification timestamps of the input files.
+    Tolerates and has no effect on non-existent files and files that are
+    deleted by the nested code.
+
+    Parameters:
+        *filenames: one or more files that must have their modification
+            timestamps unchanged
+    """
+    mtimes = {}
+    for f in filenames:
+        if os.path.exists(f):
+            mtimes[f] = os.path.getmtime(f)
+    yield
+    for f, mtime in mtimes.items():
+        if os.path.exists(f):
+            os.utime(f, (os.path.getatime(f), mtime))

lib/spack/llnl/util/lang.py

@@ -1,4 +1,4 @@
-# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2021 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)
@@ -14,6 +14,11 @@
 from six import string_types
 import sys
 
+if sys.version_info < (3, 0):
+    from itertools import izip_longest  # novm
+    zip_longest = izip_longest
+else:
+    from itertools import zip_longest  # novm
 
 if sys.version_info >= (3, 3):
     from collections.abc import Hashable, MutableMapping  # novm
@@ -227,48 +232,222 @@ def list_modules(directory, **kwargs):
                 yield re.sub('.py$', '', name)
 
 
-def key_ordering(cls):
-    """Decorates a class with extra methods that implement rich comparison
-       operations and ``__hash__``.  The decorator assumes that the class
-       implements a function called ``_cmp_key()``.  The rich comparison
-       operations will compare objects using this key, and the ``__hash__``
-       function will return the hash of this key.
+def decorator_with_or_without_args(decorator):
+    """Allows a decorator to be used with or without arguments, e.g.::
 
-       If a class already has ``__eq__``, ``__ne__``, ``__lt__``, ``__le__``,
-       ``__gt__``, or ``__ge__`` defined, this decorator will overwrite them.
+        # Calls the decorator function some args
+        @decorator(with, arguments, and=kwargs)
+
+    or::
+
+        # Calls the decorator function with zero arguments
+        @decorator
 
-       Raises:
-           TypeError: If the class does not have a ``_cmp_key`` method
     """
-    def setter(name, value):
-        value.__name__ = name
-        setattr(cls, name, value)
+    # See https://stackoverflow.com/questions/653368 for more on this
+    @functools.wraps(decorator)
+    def new_dec(*args, **kwargs):
+        if len(args) == 1 and len(kwargs) == 0 and callable(args[0]):
+            # actual decorated function
+            return decorator(args[0])
+        else:
+            # decorator arguments
+            return lambda realf: decorator(realf, *args, **kwargs)
 
-    if not has_method(cls, '_cmp_key'):
-        raise TypeError("'%s' doesn't define _cmp_key()." % cls.__name__)
+    return new_dec
 
-    setter('__eq__',
-           lambda s, o:
-           (s is o) or (o is not None and s._cmp_key() == o._cmp_key()))
-    setter('__lt__',
-           lambda s, o: o is not None and s._cmp_key() < o._cmp_key())
-    setter('__le__',
-           lambda s, o: o is not None and s._cmp_key() <= o._cmp_key())
 
-    setter('__ne__',
-           lambda s, o:
-           (s is not o) and (o is None or s._cmp_key() != o._cmp_key()))
-    setter('__gt__',
-           lambda s, o: o is None or s._cmp_key() > o._cmp_key())
-    setter('__ge__',
-           lambda s, o: o is None or s._cmp_key() >= o._cmp_key())
+#: sentinel for testing that iterators are done in lazy_lexicographic_ordering
+done = object()
 
-    setter('__hash__', lambda self: hash(self._cmp_key()))
+
+def tuplify(seq):
+    """Helper for lazy_lexicographic_ordering()."""
+    return tuple((tuplify(x) if callable(x) else x) for x in seq())
+
+
+def lazy_eq(lseq, rseq):
+    """Equality comparison for two lazily generated sequences.
+
+    See ``lazy_lexicographic_ordering``.
+    """
+    liter = lseq()  # call generators
+    riter = rseq()
+
+    # zip_longest is implemented in native code, so use it for speed.
+    # use zip_longest instead of zip because it allows us to tell
+    # which iterator was longer.
+    for left, right in zip_longest(liter, riter, fillvalue=done):
+        if (left is done) or (right is done):
+            return False
+
+        # recursively enumerate any generators, otherwise compare
+        equal = lazy_eq(left, right) if callable(left) else left == right
+        if not equal:
+            return False
+
+    return True
+
+
+def lazy_lt(lseq, rseq):
+    """Less-than comparison for two lazily generated sequences.
+
+    See ``lazy_lexicographic_ordering``.
+    """
+    liter = lseq()
+    riter = rseq()
+
+    for left, right in zip_longest(liter, riter, fillvalue=done):
+        if (left is done) or (right is done):
+            return left is done  # left was shorter than right
+
+        sequence = callable(left)
+        equal = lazy_eq(left, right) if sequence else left == right
+        if equal:
+            continue
+
+        if sequence:
+            return lazy_lt(left, right)
+        if left is None:
+            return True
+        if right is None:
+            return False
+
+        return left < right
+
+    return False  # if equal, return False
+
+
+@decorator_with_or_without_args
+def lazy_lexicographic_ordering(cls, set_hash=True):
+    """Decorates a class with extra methods that implement rich comparison.
+
+    This is a lazy version of the tuple comparison used frequently to
+    implement comparison in Python. Given some objects with fields, you
+    might use tuple keys to implement comparison, e.g.::
+
+        class Widget:
+            def _cmp_key(self):
+                return (
+                    self.a,
+                    self.b,
+                    (self.c, self.d),
+                    self.e
+                )
+
+            def __eq__(self, other):
+                return self._cmp_key() == other._cmp_key()
+
+            def __lt__(self):
+                return self._cmp_key() < other._cmp_key()
+
+            # etc.
+
+    Python would compare ``Widgets`` lexicographically based on their
+    tuples. The issue there for simple comparators is that we have to
+    bulid the tuples *and* we have to generate all the values in them up
+    front. When implementing comparisons for large data structures, this
+    can be costly.
+
+    Lazy lexicographic comparison maps the tuple comparison shown above
+    to generator functions. Instead of comparing based on pre-constructed
+    tuple keys, users of this decorator can compare using elements from a
+    generator. So, you'd write::
+
+        @lazy_lexicographic_ordering
+        class Widget:
+            def _cmp_iter(self):
+                yield a
+                yield b
+                def cd_fun():
+                    yield c
+                    yield d
+                yield cd_fun
+                yield e
+
+            # operators are added by decorator
+
+    There are no tuples preconstructed, and the generator does not have
+    to complete. Instead of tuples, we simply make functions that lazily
+    yield what would've been in the tuple. The
+    ``@lazy_lexicographic_ordering`` decorator handles the details of
+    implementing comparison operators, and the ``Widget`` implementor
+    only has to worry about writing ``_cmp_iter``, and making sure the
+    elements in it are also comparable.
+
+    Some things to note:
+
+      * If a class already has ``__eq__``, ``__ne__``, ``__lt__``,
+        ``__le__``, ``__gt__``, ``__ge__``, or ``__hash__`` defined, this
+        decorator will overwrite them.
+
+      * If ``set_hash`` is ``False``, this will not overwrite
+        ``__hash__``.
+
+      * This class uses Python 2 None-comparison semantics. If you yield
+        None and it is compared to a non-None type, None will always be
+        less than the other object.
+
+    Raises:
+        TypeError: If the class does not have a ``_cmp_iter`` method
+
+    """
+    if not has_method(cls, "_cmp_iter"):
+        raise TypeError("'%s' doesn't define _cmp_iter()." % cls.__name__)
+
+    # comparison operators are implemented in terms of lazy_eq and lazy_lt
+    def eq(self, other):
+        if self is other:
+            return True
+        return (other is not None) and lazy_eq(self._cmp_iter, other._cmp_iter)
+
+    def lt(self, other):
+        if self is other:
+            return False
+        return (other is not None) and lazy_lt(self._cmp_iter, other._cmp_iter)
+
+    def ne(self, other):
+        if self is other:
+            return False
+        return (other is None) or not lazy_eq(self._cmp_iter, other._cmp_iter)
+
+    def gt(self, other):
+        if self is other:
+            return False
+        return (other is None) or lazy_lt(other._cmp_iter, self._cmp_iter)
+
+    def le(self, other):
+        if self is other:
+            return True
+        return (other is not None) and not lazy_lt(other._cmp_iter,
+                                                   self._cmp_iter)
+
+    def ge(self, other):
+        if self is other:
+            return True
+        return (other is None) or not lazy_lt(self._cmp_iter, other._cmp_iter)
+
+    def h(self):
+        return hash(tuplify(self._cmp_iter))
+
+    def add_func_to_class(name, func):
+        """Add a function to a class with a particular name."""
+        func.__name__ = name
+        setattr(cls, name, func)
+
+    add_func_to_class("__eq__", eq)
+    add_func_to_class("__ne__", ne)
+    add_func_to_class("__lt__", lt)
+    add_func_to_class("__le__", le)
+    add_func_to_class("__gt__", gt)
+    add_func_to_class("__ge__", ge)
+    if set_hash:
+        add_func_to_class("__hash__", h)
 
     return cls
 
 
-@key_ordering
+@lazy_lexicographic_ordering
 class HashableMap(MutableMapping):
     """This is a hashable, comparable dictionary.  Hash is performed on
        a tuple of the values in the dictionary."""
@@ -291,8 +470,9 @@ def __len__(self):
     def __delitem__(self, key):
         del self.dict[key]
 
-    def _cmp_key(self):
-        return tuple(sorted(self.values()))
+    def _cmp_iter(self):
+        for _, v in sorted(self.items()):
+            yield v
 
     def copy(self):
         """Type-agnostic clone method.  Preserves subclass type."""
@@ -624,6 +804,9 @@ def __repr__(self):
 def load_module_from_file(module_name, module_path):
     """Loads a python module from the path of the corresponding file.
 
+    If the module is already in ``sys.modules`` it will be returned as
+    is and not reloaded.
+
     Args:
         module_name (str): namespace where the python module will be loaded,
             e.g. ``foo.bar``
@@ -636,12 +819,28 @@ def load_module_from_file(module_name, module_path):
         ImportError: when the module can't be loaded
         FileNotFoundError: when module_path doesn't exist
     """
+    if module_name in sys.modules:
+        return sys.modules[module_name]
+
+    # This recipe is adapted from https://stackoverflow.com/a/67692/771663
     if sys.version_info[0] == 3 and sys.version_info[1] >= 5:
         import importlib.util
         spec = importlib.util.spec_from_file_location(  # novm
             module_name, module_path)
         module = importlib.util.module_from_spec(spec)  # novm
-        spec.loader.exec_module(module)
+        # The module object needs to exist in sys.modules before the
+        # loader executes the module code.
+        #
+        # See https://docs.python.org/3/reference/import.html#loading
+        sys.modules[spec.name] = module
+        try:
+            spec.loader.exec_module(module)
+        except BaseException:
+            try:
+                del sys.modules[spec.name]
+            except KeyError:
+                pass
+            raise
     elif sys.version_info[0] == 3 and sys.version_info[1] < 5:
         import importlib.machinery
         loader = importlib.machinery.SourceFileLoader(  # novm

lib/spack/llnl/util/link_tree.py

@@ -1,4 +1,4 @@
-# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2021 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)

lib/spack/llnl/util/lock.py

@@ -1,4 +1,4 @@
-# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2021 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)
@@ -264,7 +264,7 @@ def _write_log_debug_data(self):
         self.old_host = self.host
 
         self.pid = os.getpid()
-        self.host = socket.getfqdn()
+        self.host = socket.gethostname()
 
         # write pid, host to disk to sync over FS
         self._file.seek(0)

lib/spack/llnl/util/multiproc.py

@@ -1,4 +1,4 @@
-# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2021 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)

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

@@ -1,4 +1,4 @@
-# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2021 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)

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

@@ -1,4 +1,4 @@
-# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2021 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)

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

@@ -1,4 +1,4 @@
-# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2021 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)

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

@@ -1,4 +1,4 @@
-# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2021 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)
@@ -20,12 +20,17 @@
 from six import string_types
 from six import StringIO
 
+from typing import Optional  # novm
+from types import ModuleType  # novm
+
 import llnl.util.tty as tty
 
+termios = None  # type: Optional[ModuleType]
 try:
-    import termios
+    import termios as term_mod
+    termios = term_mod
 except ImportError:
-    termios = None
+    pass
 
 
 # Use this to strip escape sequences
@@ -316,7 +321,10 @@ def __init__(self, file_like):
     def unwrap(self):
         if self.open:
             if self.file_like:
-                self.file = open(self.file_like, 'w')
+                if sys.version_info < (3,):
+                    self.file = open(self.file_like, 'w')
+                else:
+                    self.file = open(self.file_like, 'w', encoding='utf-8')
             else:
                 self.file = StringIO()
             return self.file
@@ -717,7 +725,11 @@ def _writer_daemon(stdin_multiprocess_fd, read_multiprocess_fd, write_fd, echo,
 
     # Use line buffering (3rd param = 1) since Python 3 has a bug
     # that prevents unbuffered text I/O.
-    in_pipe = os.fdopen(read_multiprocess_fd.fd, 'r', 1)
+    if sys.version_info < (3,):
+        in_pipe = os.fdopen(read_multiprocess_fd.fd, 'r', 1)
+    else:
+        # Python 3.x before 3.7 does not open with UTF-8 encoding by default
+        in_pipe = os.fdopen(read_multiprocess_fd.fd, 'r', 1, encoding='utf-8')
 
     if stdin_multiprocess_fd:
         stdin = os.fdopen(stdin_multiprocess_fd.fd)
@@ -759,28 +771,39 @@ def _writer_daemon(stdin_multiprocess_fd, read_multiprocess_fd, write_fd, echo,
                                 raise
 
                 if in_pipe in rlist:
-                    # Handle output from the calling process.
-                    line = _retry(in_pipe.readline)()
-                    if not line:
-                        break
+                    line_count = 0
+                    try:
+                        while line_count < 100:
+                            # Handle output from the calling process.
+                            line = _retry(in_pipe.readline)()
+                            if not line:
+                                return
+                            line_count += 1
 
-                    # find control characters and strip them.
-                    controls = control.findall(line)
-                    line = control.sub('', line)
+                            # find control characters and strip them.
+                            clean_line, num_controls = control.subn('', line)
 
-                    # Echo to stdout if requested or forced.
-                    if echo or force_echo:
-                        sys.stdout.write(line)
-                        sys.stdout.flush()
+                            # Echo to stdout if requested or forced.
+                            if echo or force_echo:
+                                sys.stdout.write(clean_line)
 
-                    # Stripped output to log file.
-                    log_file.write(_strip(line))
-                    log_file.flush()
+                            # Stripped output to log file.
+                            log_file.write(_strip(clean_line))
 
-                    if xon in controls:
-                        force_echo = True
-                    if xoff in controls:
-                        force_echo = False
+                            if num_controls > 0:
+                                controls = control.findall(line)
+                                if xon in controls:
+                                    force_echo = True
+                                if xoff in controls:
+                                    force_echo = False
+
+                            if not _input_available(in_pipe):
+                                break
+                    finally:
+                        if line_count > 0:
+                            if echo or force_echo:
+                                sys.stdout.flush()
+                            log_file.flush()
 
     except BaseException:
         tty.error("Exception occurred in writer daemon!")
@@ -832,3 +855,7 @@ def wrapped(*args, **kwargs):
                     continue
                 raise
     return wrapped
+
+
+def _input_available(f):
+    return f in select.select([f], [], [], 0)[0]

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

@@ -1,4 +1,4 @@
-# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2021 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)

lib/spack/spack/__init__.py

@@ -1,11 +1,11 @@
-# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2021 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)
 
 
 #: major, minor, patch version for Spack, in a tuple
-spack_version_info = (0, 16, 2)
+spack_version_info = (0, 16, 1)
 
 #: String containing Spack version joined with .'s
 spack_version = '.'.join(str(v) for v in spack_version_info)

lib/spack/spack/abi.py

@@ -1,4 +1,4 @@
-# Copyright 2013-2020 Lawrence Livermore National Security, LLC and other
+# Copyright 2013-2021 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)

lib/spack/spack/analyzers/__init__.py

@@ -0,0 +1,43 @@
+# Copyright 2013-2021 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)
+
+"""This package contains code for creating analyzers to extract Application
+Binary Interface (ABI) information, along with simple analyses that just load
+existing metadata.
+"""
+
+from __future__ import absolute_import
+
+import spack.util.classes
+import spack.paths
+
+import llnl.util.tty as tty
+
+
+mod_path = spack.paths.analyzers_path
+analyzers = spack.util.classes.list_classes("spack.analyzers", mod_path)
+
+# The base analyzer does not have a name, and cannot do dict comprehension
+analyzer_types = {}
+for a in analyzers:
+    if not hasattr(a, "name"):
+        continue
+    analyzer_types[a.name] = a
+
+
+def list_all():
+    """A helper function to list all analyzers and their descriptions
+    """
+    for name, analyzer in analyzer_types.items():
+        print("%-25s: %-35s" % (name, analyzer.description))
+
+
+def get_analyzer(name):
+    """Courtesy function to retrieve an analyzer, and exit on error if it
+    does not exist.
+    """
+    if name in analyzer_types:
+        return analyzer_types[name]
+    tty.die("Analyzer %s does not exist" % name)

lib/spack/spack/analyzers/analyzer_base.py

@@ -0,0 +1,115 @@
+# Copyright 2013-2021 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)
+
+"""An analyzer base provides basic functions to run the analysis, save results,
+and (optionally) interact with a Spack Monitor
+"""
+
+import spack.monitor
+import spack.hooks
+import llnl.util.tty as tty
+import spack.util.path
+import spack.config
+
+import os
+
+
+def get_analyzer_dir(spec, analyzer_dir=None):
+    """
+    Given a spec, return the directory to save analyzer results.
+
+    We create the directory if it does not exist. We also check that the
+    spec has an associated package. An analyzer cannot be run if the spec isn't
+    associated with a package. If the user provides a custom analyzer_dir,
+    we use it over checking the config and the default at ~/.spack/analyzers
+    """
+    # An analyzer cannot be run if the spec isn't associated with a package
+    if not hasattr(spec, "package") or not spec.package:
+        tty.die("A spec can only be analyzed with an associated package.")
+
+    # The top level directory is in the user home, or a custom location
+    if not analyzer_dir:
+        analyzer_dir = spack.util.path.canonicalize_path(
+            spack.config.get('config:analyzers_dir', '~/.spack/analyzers'))
+
+    # We follow the same convention as the spec install (this could be better)
+    package_prefix = os.sep.join(spec.package.prefix.split('/')[-3:])
+    meta_dir = os.path.join(analyzer_dir, package_prefix)
+    return meta_dir
+
+
+class AnalyzerBase(object):
+
+    def __init__(self, spec, dirname=None):
+        """
+        Verify that the analyzer has correct metadata.
+
+        An Analyzer is intended to run on one spec install, so the spec
+        with its associated package is required on init. The child analyzer
+        class should define an init function that super's the init here, and
+        also check that the analyzer has all dependencies that it
+        needs. If an analyzer subclass does not have dependencies, it does not
+        need to define an init. An Analyzer should not be allowed to proceed
+        if one or more dependencies are missing. The dirname, if defined,
+        is an optional directory name to save to (instead of the default meta
+        spack directory).
+        """
+        self.spec = spec
+        self.dirname = dirname
+        self.meta_dir = os.path.dirname(spec.package.install_log_path)
+
+        for required in ["name", "outfile", "description"]:
+            if not hasattr(self, required):
+                tty.die("Please add a %s attribute on the analyzer." % required)
+
+    def run(self):
+        """
+        Given a spec with an installed package, run the analyzer on it.
+        """
+        raise NotImplementedError
+
+    @property
+    def output_dir(self):
+        """
+        The full path to the output directory.
+
+        This includes the nested analyzer directory structure. This function
+        does not create anything.
+        """
+        if not hasattr(self, "_output_dir"):
+            output_dir = get_analyzer_dir(self.spec, self.dirname)
+            self._output_dir = os.path.join(output_dir, self.name)
+
+        return self._output_dir
+
+    def save_result(self, result, overwrite=False):
+        """
+        Save a result to the associated spack monitor, if defined.
+
+        This function is on the level of the analyzer because it might be
+        the case that the result is large (appropriate for a single request)
+        or that the data is organized differently (e.g., more than one
+        request per result). If an analyzer subclass needs to over-write
+        this function with a custom save, that is appropriate to do (see abi).
+        """
+        # We maintain the structure in json with the analyzer as key so
+        # that in the future, we could upload to a monitor server
+        if result[self.name]:
+
+            outfile = os.path.join(self.output_dir, self.outfile)
+
+            # Only try to create the results directory if we have a result
+            if not os.path.exists(self._output_dir):
+                os.makedirs(self._output_dir)
+
+            # Don't overwrite an existing result if overwrite is False
+            if os.path.exists(outfile) and not overwrite:
+                tty.info("%s exists and overwrite is False, skipping." % outfile)
+            else:
+                tty.info("Writing result to %s" % outfile)
+                spack.monitor.write_json(result[self.name], outfile)
+
+        # This hook runs after a save result
+        spack.hooks.on_analyzer_save(self.spec.package, result)

lib/spack/spack/analyzers/config_args.py

@@ -0,0 +1,32 @@
+# Copyright 2013-2021 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)
+
+"""A configargs analyzer is a class of analyzer that typically just uploads
+already existing metadata about config args from a package spec install
+directory."""
+
+
+import spack.monitor
+from .analyzer_base import AnalyzerBase
+
+import os
+
+
+class ConfigArgs(AnalyzerBase):
+
+    name = "config_args"
+    outfile = "spack-analyzer-config-args.json"
+    description = "config args loaded from spack-configure-args.txt"
+
+    def run(self):
+        """
+        Load the configure-args.txt and save in json.
+
+        The run function will find the spack-config-args.txt file in the
+        package install directory, and read it into a json structure that has
+        the name of the analyzer as the key.
+        """
+        config_file = os.path.join(self.meta_dir, "spack-configure-args.txt")
+        return {self.name: spack.monitor.read_file(config_file)}

lib/spack/spack/analyzers/environment_variables.py

@@ -0,0 +1,51 @@
+# Copyright 2013-2021 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)
+
+"""An environment analyzer will read and parse the environment variables
+file in the installed package directory, generating a json file that has
+an index of key, value pairs for environment variables."""
+
+
+from .analyzer_base import AnalyzerBase
+from spack.util.environment import EnvironmentModifications
+
+
+import os
+
+
+class EnvironmentVariables(AnalyzerBase):
+
+    name = "environment_variables"
+    outfile = "spack-analyzer-environment-variables.json"
+    description = "environment variables parsed from spack-build-env.txt"
+
+    def run(self):
+        """
+        Load, parse, and save spack-build-env.txt to analyzers.
+
+        Read in the spack-build-env.txt file from the package install
+        directory and parse the environment variables into key value pairs.
+        The result should have the key for the analyzer, the name.
+        """
+        env_file = os.path.join(self.meta_dir, "spack-build-env.txt")
+        return {self.name: self._read_environment_file(env_file)}
+
+    def _read_environment_file(self, filename):
+        """
+        Read and parse the environment file.
+
+        Given an environment file, we want to read it, split by semicolons
+        and new lines, and then parse down to the subset of SPACK_* variables.
+        We assume that all spack prefix variables are not secrets, and unlike
+        the install_manifest.json, we don't (at least to start) parse the values
+        to remove path prefixes specific to user systems.
+        """
+        if not os.path.exists(filename):
+            return
+
+        mods = EnvironmentModifications.from_sourcing_file(filename)
+        env = {}
+        mods.apply_modifications(env)
+        return env

lib/spack/spack/analyzers/install_files.py

@@ -0,0 +1,30 @@
+# Copyright 2013-2021 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 install files json file (install_manifest.json) already exists in
+the package install folder, so this analyzer simply moves it to the user
+analyzer folder for further processing."""
+
+
+import spack.monitor
+from .analyzer_base import AnalyzerBase
+
+import os
+
+
+class InstallFiles(AnalyzerBase):
+
+    name = "install_files"
+    outfile = "spack-analyzer-install-files.json"
+    description = "install file listing read from install_manifest.json"
+
+    def run(self):
+        """
+        Load in the install_manifest.json and save to analyzers.
+
+        We write it out to the analyzers folder, with key as the analyzer name.
+        """
+        manifest_file = os.path.join(self.meta_dir, "install_manifest.json")
+        return {self.name: spack.monitor.read_json(manifest_file)}

lib/spack/spack/analyzers/libabigail.py

@@ -0,0 +1,116 @@
+# Copyright 2013-2021 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
+import spack.error
+import spack.bootstrap
+import spack.hooks
+import spack.monitor
+import spack.binary_distribution
+import spack.package
+import spack.repo
+
+import llnl.util.tty as tty
+
+from .analyzer_base import AnalyzerBase
+
+import os
+
+
+class Libabigail(AnalyzerBase):
+
+    name = "libabigail"
+    outfile = "spack-analyzer-libabigail.json"
+    description = "Application Binary Interface (ABI) features for objects"
+
+    def __init__(self, spec, dirname=None):
+        """
+        init for an analyzer ensures we have all needed dependencies.
+
+        For the libabigail analyzer, this means Libabigail.
+        Since the output for libabigail is one file per object, we communicate
+        with the monitor multiple times.
+        """
+        super(Libabigail, self).__init__(spec, dirname)
+
+        # This doesn't seem to work to import on the module level
+        tty.debug("Preparing to use Libabigail, will install if missing.")
+
+        with spack.bootstrap.ensure_bootstrap_configuration():
+
+            # libabigail won't install lib/bin/share without docs
+            spec = spack.spec.Spec("libabigail+docs")
+            spec.concretize()
+
+            self.abidw = spack.bootstrap.get_executable(
+                "abidw", spec=spec, install=True)
+
+    def run(self):
+        """
+        Run libabigail, and save results to filename.
+
+        This run function differs in that we write as we generate and then
+        return a dict with the analyzer name as the key, and the value of a
+        dict of results, where the key is the object name, and the value is
+        the output file written to.
+        """
+        manifest = spack.binary_distribution.get_buildfile_manifest(self.spec)
+
+        # This result will store a path to each file
+        result = {}
+
+        # Generate an output file for each binary or object
+        for obj in manifest.get("binary_to_relocate_fullpath", []):
+
+            # We want to preserve the path in the install directory in case
+            # a library has an equivalenly named lib or executable, for example
+            outdir = os.path.dirname(obj.replace(self.spec.package.prefix,
+                                     '').strip(os.path.sep))
+            outfile = "spack-analyzer-libabigail-%s.xml" % os.path.basename(obj)
+            outfile = os.path.join(self.output_dir, outdir, outfile)
+            outdir = os.path.dirname(outfile)
+
+            # Create the output directory
+            if not os.path.exists(outdir):
+                os.makedirs(outdir)
+
+            # Sometimes libabigail segfaults and dumps
+            try:
+                self.abidw(obj, "--out-file", outfile)
+                result[obj] = outfile
+                tty.info("Writing result to %s" % outfile)
+            except spack.error.SpackError:
+                tty.warn("Issue running abidw for %s" % obj)
+
+        return {self.name: result}
+
+    def save_result(self, result, overwrite=False):
+        """
+        Read saved ABI results and upload to monitor server.
+
+        ABI results are saved to individual files, so each one needs to be
+        read and uploaded. Result here should be the lookup generated in run(),
+        the key is the analyzer name, and each value is the result file.
+        We currently upload the entire xml as text because libabigail can't
+        easily read gzipped xml, but this will be updated when it can.
+        """
+        if not spack.monitor.cli:
+            return
+
+        name = self.spec.package.name
+
+        for obj, filename in result.get(self.name, {}).items():
+
+            # Don't include the prefix
+            rel_path = obj.replace(self.spec.prefix + os.path.sep, "")
+
+            # We've already saved the results to file during run
+            content = spack.monitor.read_file(filename)
+
+            # A result needs an analyzer, value or binary_value, and name
+            data = {"value": content, "install_file": rel_path, "name": "abidw-xml"}
+            tty.info("Sending result for %s %s to monitor." % (name, rel_path))
+            spack.hooks.on_analyzer_save(self.spec.package, {"libabigail": [data]})