WIP: restructuring

Signed-off-by: psakiev <psakiev@sandia.gov>

Author: psakievich

outputs/dev.sh

@@ -21,9 +21,11 @@ example dev/setup-scr "# for now, disable fortran support in all packages"
 example dev/setup-scr 'spack config add "packages:all:variants: ~fortran"'
 example dev/setup-scr "spack add macsio+scr"
 example dev/setup-scr "spack install"
+example dev/setup-scr "spack find -cv scr"
 
 example dev/develop-1 "spack develop scr"
 example dev/develop-1 "spack config blame develop"
+example dev/develop-1 "spack find -cv scr"
 
 example dev/develop-2 "spack install"
 
@@ -37,9 +39,16 @@ fake_example dev/develop-4 '$EDITOR scr/src/scr_copy.c' "/bin/true"
 sed -i~ s'|\(static char hostname\[256\] = "UNKNOWN_HOST"\)|\1;|' scr/src/scr_copy.c | head -n 70
 example dev/develop-4 "spack install"
 
-example dev/develop-5 "# This time let's leave off the version"
-example dev/develop-5 "spack develop macsio"
-example dev/develop-5 "spack concretize -f"
+example dev/develop-5 "spack develop --recursive scr"
+example dev/develop-5 "spack find -cv macsio"
+
+example dev/develop-6 "# This time let's add the version"
+example dev/develop-6 "spack change macsio@develop"
+example dev/develop-6 "spack concretize -f"
+example dev/develop-6 "spack develop macsio@develop"
+example dev/develop-6 "spack find -cv macsio"
+example dev/develop-6 "spack concretize -f"
+example dev/develop-6 "spack find -cv macsio"
 
 example dev/otherdevel "cd ~"
 cd ~ || exit

tutorial_developer_workflows.rst

@@ -139,7 +139,7 @@ Development iteration cycles
 -----------------------------
 
 Let's assume that ``scr`` has a bug, and we'd like to patch ``scr`` to find out what the problem is.
-First, we tell Spack that we'd like to check out the version of ``scr`` that we want to work on.
+First, we tell Spack that we'd like to check out the version of ``scr`` in our environment.
 In this case, it will be the 3.1.0 release that we want to write a patch for:
 
 .. literalinclude:: outputs/dev/develop-1.out
@@ -188,7 +188,7 @@ If the file times are newer, it will rebuild ``scr`` and any other package that
    :language: console
 
 Here, the build failed as expected.
-We can look at the output for the build in ``scr/spack-build-out.txt`` to find out why, or we can launch a shell directly with the appropriate environment variables to figure out what went wrong by using ``spack build-env scr@2.0 -- bash``.
+We can look at the output for the build in ``scr/spack-build-out.txt`` to find out why, or we can launch a shell directly with the appropriate environment variables to figure out what went wrong by using ``spack build-env scr -- bash``.
 If that's too much to remember, then sourcing ``scr/spack-build-env.txt`` will also set all the appropriate environment variables so we can diagnose the build ourselves.
 Now let's fix it and rebuild directly.
 
@@ -205,14 +205,33 @@ If your build system can take advantage of the previously compiled object files
 - If your package uses CMake with the typical ``cmake`` / ``build`` / ``install`` build stages, you'll get iterative builds for free with Spack because CMake doesn’t modify the filetime on the ``CMakeCache.txt`` file if your cmake flags haven't changed.
 - If your package uses autoconf, then rerunning the typical ``autoreconf`` stage typically modifies the filetime of ``config.h``, which can trigger a cascade of rebuilding.
 
-Multiple packages can also be marked as develop.
-If we were co-developing ``macsio``, we could run
+Multi-package development
+-------------------------
+
+You may have noticed that ``macsio`` is restaged and fully rebuilt each time we call ``spack install``.
+This is an unnecessary expense for cross package development.
+Luckily, Spack has tools to reduce this expense.
+We will use this as an opportunity to introduce another ``spack develop`` feature: the ``--recursive`` option.
 
 .. literalinclude:: outputs/dev/develop-5.out
    :language: console
 
-Note that we intentionally gave a different version and in the examples above ``macsio`` never received the ``dev_path`` variant.
-This example  is to show a few gotchas with the ``spack develop`` command
+``spack develop --recursive`` can only be used with a concrete environment.
+When called Spack traces the graph from the supplied develop spec to every root in the graph that transitivley depends on the develop package.
+Using ``--recursive`` can be very powerful wehn developing applications deep in a graph.
+In this case our development point is very close to the root spec so we could have called ``spack develop macsio`` and gotten the same result.
+
+Pre-configuring development environments
+----------------------------------------
+
+So far all of our calls to ``spack develop`` have been on a concretized environment, and we have allowed spack to automatically update the build specs for us.
+If we don't want Spack to update the concrete environment's specs we can pass the ``---no-modify-concrete-spec``.
+This will require you to force concretize an environment to have the develop specs take affect.
+
+.. literalinclude:: outputs/dev/develop-6.out
+   :language: console
+
+This example is to show a few gotchas with the ``spack develop`` command
 
 * You should ensure a spec for the package you are developing appears in the DAG of at least one of the roots of the environment with the same version that you are developing.
   ``spack add <package>`` with the matching version you want to develop is a way to ensure the develop spec is satisfied in the ``spack.yaml`` environments file.
@@ -222,13 +241,8 @@ This example  is to show a few gotchas with the ``spack develop`` command
 
 If we really wanted to change to developing ``macsio@develop`` we need to change the root spec in the environment and then reconcretize.
 
-In our case the ``1.1`` version is sufficient and we will use this as an opportunity to introduce another ``spack develop`` feature: the ``--recursive`` option.
-``spack develop --recursive`` can only be used with a concrete environment.
-When called Spack traces the graph from the supplied develop spec to every root in the graph that transitivley depends on the develop package.
-This is a nice way to ensure that all specs are skipping restages, and performing incremental builds if their build-system allows for it.
-
-.. literalinclude:: outputs/dev/develop-6.out
-   :language: console
+Sharing development environments
+--------------------------------
 
 Using development workflows also lets us ship our whole development process to another developer on the team.
 They can simply take our spack.yaml, create a new environment, and use this to replicate our build process.
@@ -244,13 +258,15 @@ When we're done developing, we simply tell Spack that it no longer needs to keep
 .. literalinclude:: outputs/dev/wrapup.out
    :language: console
 
+----------------
 Workflow Summary
 ----------------
 
 Use the ``spack develop`` command with an environment to make a reproducible build environment for your development workflow.
 Spack will set up all the dependencies for you and link all your packages together.
 Within a development environment, ``spack install`` works similarly to ``make`` in that it will check file times to rebuild the minimum number of Spack packages necessary to reflect the changes to your build.
 
+-------------------------
 Optional: Tips and Tricks
 -------------------------