ISC26: update the environments section (#542)

* Extend gitignore

* basics: split "Installing Packages" into subsections

* Add a paragraph explaining the overall spack architecture

This is so that audience is already aware
of where we are headin into, when we introduce
the various pieces (hash, store, etc.).

* Update releases/v1.1 -> releases/v1.2

* Move high-level highlights to introduction

* Minor fixes

* Shorten and improve "Installing Packages"

* Demote Compiler flags

* Reorder "Spec Syntax" subsections

* Move "Querying Installations" into its own section

Also, consolidate all the use of `spack find`

* Add intro to "Spec Syntax"

* Update output

* Fix "Installing Packages"

* Fix "Transitive Dependencies"

* Fix "Transitive Dependencies"

* Fix "Virtual Dependencies"

* First draft

* Add missing output

* Polish the section

* Polish the section

* Temporarily disable output generation

* Mechanical update of the environment section

* Minor fixes

* Don't use a non-matching temporary environment

* Shorten introduction, but maintain the same content

* Improved "Working with environments" section

* Improved "Working with environments" section

* Added an "Environment on disk" section

This section introduces manifest and lockfile early.

* Added an "Environment on disk" section

This section introduces manifest and lockfile early.

* Added an "Environment on disk" section

This section introduces manifest and lockfile early.

* Added a "Configuring environments" section

* Trimmed redundant section

* First complete draft of the "Environments" tutorial

* Minor fixes

* Minor fixes

* Less notes in the initial section

---------

Co-authored-by: Alec Scott <alec@llnl.gov>

Author: alalazo

outputs/environments.sh

@@ -11,34 +11,10 @@ export SPACK_COLOR=never
 . "$project/init_spack.sh"
 . share/spack/setup-env.sh
 
-####
-# Introduction for "basic" installation if basics section not being used
-####
-#example environments/clone           "git clone --depth=100 --branch=$tutorial_branch https://github.com/spack/spack.git ~/spack"
-#example environments/clone           "cd ~/spack"
-
-#cd ~/spack || exit
-#export SPACK_ROOT=~/spack
-
-#. share/spack/setup-env.sh
-#spack config add "config:suppress_gpg_warnings:true"
-
-#example environments/source-setup     ". share/spack/setup-env.sh"
-
-#example environments/gmake      "spack install gmake"
-
-#example environments/gmake-1    "spack install gmake@4.3"
-
-#example environments/find-gmake "spack find -p gmake"
-
-#example environments/ls-dot-spack 'ls "$(spack location -i gmake@4.4)/.spack"'
-
-#example environments/mirror     "spack mirror add tutorial /mirror"
+# spack mirror add --unsigned tutorial /mirror
 #example environments/mirror     "spack buildcache keys --install --trust"
 
-####
-# Usual Environment output
-####
+# Working with Environments
 
 example environments/find-no-env-1   "spack find"
 
@@ -58,64 +34,25 @@ spack env deactivate
 example environments/env-status-2    "spack env status"
 example environments/env-status-2    "spack find"
 
-example --tee environments/env-fail-install-1   "spack env activate myproject"
 spack env activate myproject
-example --expect-error environments/env-fail-install-1   "spack install tcl"
 
 example environments/env-add-1            "spack add tcl"
 example environments/env-add-1            "spack add trilinos"
-example environments/env-add-1            "spack find"
 
-example environments/env-install-1        "spack install"
+example environments/env-add-find-1       "spack find"
 
-example environments/find-env-2           "spack find"
+example environments/env-concretize-1     "spack concretize"
 
-example environments/use-tcl-1       "which tclsh"
+example environments/env-find-c-1         "spack find -c"
 
-example environments/env-create-2         "spack env create myproject2"
-example --tee environments/env-create-2    "spack env activate myproject2"
-spack env activate myproject2
-example environments/env-create-2    "spack add scr trilinos"
-example environments/env-create-2    "spack install"
-example environments/env-create-2    "spack find"
+example --tee environments/env-install-1        "spack install"
 
-example --expect-error environments/env-uninstall-1 "spack uninstall -y trilinos"
-example environments/env-uninstall-1 "spack find"
+example environments/find-env-2           "spack find"
 
-example environments/env-remove-1    "spack remove trilinos"
-example environments/env-remove-1    "spack find"
-example environments/env-remove-1    "spack concretize"
-example environments/env-remove-1    "spack find"
+example environments/use-tcl-1       "which tclsh"
 
-example --tee environments/env-swap-1      "spack env activate myproject"
+example --tee environments/show-mpicc-1      "spack env activate myproject"
 spack env activate myproject
-example environments/env-swap-1      "spack find"
-
-example environments/config-get-1    'EDITOR=cat spack config edit'
-
-# The file is edited by hand here
-# We mock that by using `spack config add`
-spack config add packages:mpi:require:[mpich]
-
-example environments/concretize-f-1 "spack concretize --force"
-# spack install
-
-example --tee environments/incremental-1 "spack env activate --temp"
-spack env activate --temp
-example environments/incremental-1 "spack install --add python"
-
-# v1.1: Spack concretizer regression causes the following command to hang
-# seemingly indefinitely. (Have tested waiting 1h 15m before giving up.)
-# example environments/incremental-1 "spack install --add py-numpy@1.20 2>&1 | tail -n1"
-
-# These commands should be fine, although we had a transient failure with them
-example environments/incremental-2 "spack add py-numpy@1.20"
-example environments/incremental-2 "spack concretize -f"
-
-spack env deactivate
-
-example --tee environments/show-mpicc-1      "spack env activate myproject2"
-spack env activate myproject2
 example environments/show-mpicc-1    "spack env status"
 example environments/show-mpicc-1    "which mpicc"
 
@@ -145,16 +82,55 @@ EOF
 example environments/use-mpi-1       'mpicc ./mpi-hello.c -I$(spack location -i zlib-ng)/include'
 example environments/use-mpi-1       "mpirun -n 2 ./a.out"
 
-example environments/myproject-zlib-ng-1     "spack find zlib-ng"
+example environments/env-create-2         "spack env create myproject2"
+example --tee environments/env-create-2    "spack env activate myproject2"
+spack env activate myproject2
+example environments/env-create-2    "spack add scr trilinos"
+# concretize + install are shown as a code-block in the docs; run them here without capturing
+spack concretize
+spack install
+
+example environments/env-create-2-find    "spack find"
+
+# Basic removal workflow on scr (used only by myproject2), split for the docs
+example environments/env-remove-scr-1    "spack remove scr"
+example environments/env-remove-scr-2    "spack find"
+example environments/env-remove-scr-3    "spack concretize"
+example environments/env-remove-scr-4    "spack find"
+
+# trilinos is shared with myproject: uninstalling it is refused
+example --expect-error environments/env-uninstall-1 "spack uninstall -y trilinos"
+
+# spack remove takes it out of myproject2 without deleting the shared install
+example environments/env-remove-1    "spack remove trilinos"
+example environments/env-remove-1    "spack concretize"
+
+example --tee environments/env-swap-1      "spack env activate myproject"
+spack env activate myproject
+example environments/env-swap-1      "spack find"
+
+# Environments on disk
 
 example --tee environments/filenames-1     "spack cd -e myproject"
 spack cd -e myproject
 example environments/filenames-1     "pwd"
 example environments/filenames-1     "ls"
-
+example environments/cat-config-1    "cat spack.yaml"
+example environments/lockfile-1      "jq < spack.lock | head -30"
 example environments/env-list-2      "spack env list"
+cd
+
+# Configuring environments
+
+# The file is edited by hand here
+# We mock that by using `spack config add`
+spack config add packages:mpi:require:[mpich]
 
-example environments/cat-config-1 "cat spack.yaml"
+example environments/concretize-1 "spack concretize"
+example environments/concretize-f-1 "spack concretize --force"
+# spack install
+
+# Reproducing builds
 
 example environments/independent-create-1 "cd"
 cd || exit
@@ -163,25 +139,12 @@ example environments/independent-create-1 "cd code"
 cd code || exit
 example environments/independent-create-1 "spack env create -d ."
 
-example environments/independent-create-2 "ls"
-example environments/independent-create-2 "cat spack.yaml"
-
-example environments/env-list-3      "spack env list"
-
 example --tee environments/install-independent-1 "spack env activate ."
 spack env activate .
 # mock a hand-edit from before we activated
 spack add trilinos
 spack add openmpi
-example environments/install-independent-1 "spack install"
-
-example environments/add-independent-1     "spack add hdf5@5.5.1"
-example environments/add-independent-1     "cat spack.yaml"
-
-example environments/remove-independent-1     "spack remove hdf5"
-example environments/remove-independent-1     "cat spack.yaml"
-
-example environments/lockfile-1          "jq < spack.lock | head -30"
+example --tee environments/install-independent-1 "spack install"
 
 example environments/create-from-file-1  "spack env create abstract spack.yaml"
 

outputs/environments/add-independent-1.out

@@ -11,6 +11,3 @@ spack:
   view: true
   concretizer:
     unify: true
-  packages:
-    mpi:
-      require: [mpich]

outputs/environments/cat-config-1.out

@@ -0,0 +1,2 @@
+$ spack concretize
+==> No new specs to concretize.