@svenevs what was the difference between .bashrc and .bash_profile that you were explaining to me? It sounded like this would pertain to this PR.

.bash_profile is sourced on login (e.g., desktop login or via ssh). .bashrc is loaded every time a new shell is, e.g. a new tmux pane or a new terminal tab.

@MarquitoForrest you should simply set SPACK_ROOT and source setup-env.sh in your .bash_profile (assuming you are using bash, there are analogous ones for other shells e.g. .zsh_profile). Then log out and log back in to get it loaded. You now only pay the cost once at login.

With that, I don't think this should be merged in its current form. I can go into details if you need, but the short version: the spack function you created is not correct and won't enable the utilities setup-env.sh does (you source it but don't use it, because you named your function spack). Things like any potential auto-completion etc aren't going to be available.

To be clear, the fact that you are confused means the docs could be clearer. Maybe put a .. note:: admonition in instead that explains this setup-env.sh should ideally be loaded in your shells "profile" startup configuration file (~/.bash_profile, ~/.zsh_profile) and not the "run commands" file (~/.bashrc, ~/.zshrc). Explain that this will then only be loaded once at login, and remind them that they need to log out and log back in to have it available.

I am on Mac OS X / Darwin and I did not know about this difference regarding startup procedure of a terminal window until now! This answer explains it well I think: https://apple.stackexchange.com/a/119714

So on Darwin the problem is that users pay the cost of source setup-env.sh every time because the concept of a .bashrc file does not exist. To me this is not acceptable because I cannot wait a second every time I need a fresh terminal. My idea hence was to pay the cost only on those occasions when I actually need to touch my spack installation.

Further auto-completion worked equally well with my bash function overwriting the actual spack command. Hence my addition is not correct in the sense that it only makes sense on Darwin and must be considered an unnecessarily ugly hack on a Linux machine. Please correct me if I am still wrong ;)

Wow. This just killed me a little inside. Who do they think they are?!!! Thanks @MarquitoForrest, I'm surprised I haven't encountered this yet...and I'm sure many future spack users on MacOS will be very grateful for you figuring out this wonderful "hack"!!!

The changes in the latest commit are good progress, but I think the following would be a little nicer (it explains which file to use for which system, and why this happens):

.. tip::

   **Linux**
       On traditional Linux / Unix systems, the file you want to place

       .. code-block:: bash

          export SPACK_ROOT=/path/to/spack
          source $SPACK_ROOT/share/spack/setup-env.sh

       is in your shell's *profile* startup script.  For example, if ``bash`` is
       your shell, then place these two lines in ``~/.bash_profile``.  Placing
       it in the *profile* means that this will only be loaded **once** when you
       log into your machine (either via a graphical login, or via ``ssh``).

       Though you can place these two commands in your *run commands* file (such
       as ``~/.bashrc``), doing so means that ``setup-env.sh`` is sourced for
       *every* terminal you launch.  This is less convenient as you now must
       wait every time you launch a new terminal session, rather than just
       loading it once at login.

       **After editing your shell's profile startup script, make sure you log
       out and then log back in for the changes to take place.**

   **MacOS**
       MacOS, unfortunately, does not obey the startup conventions.  Files such
       as ``~/.bash_profile`` (when present), are loaded with each new shell
       rather than at login.  As such, there is little to no difference between
       your shell's *profile* and *run commands* files.

       To accommodate this, we encourage you to create your shell's *run
       commands* file (e.g., ``touch ~/.bashrc`` for ``bash``, which is the
       default shell on MacOS) and add the following using your favorite text
       editor:

       .. code-block:: bash

          export SPACK_ROOT=/path/to/spack
          function spack {
              # overwrites spack command
              # if not yet initialized, initialize spack's shell integration
              if [ -z ${SPACK_SHELL+x} ] ; then
                  source $SPACK_ROOT/share/spack/setup-env.sh
              fi
              # run the real spack command with all passed parameters
              $SPACK_ROOT/bin/spack "$@"
          }

       Since sourcing ``setup-env.sh`` for every terminal launched is not ideal,
       this function defers sourcing ``setup-env.sh`` until you need it.  The
       **first** time you execute ``spack`` in a terminal session will load
       ``setup-env.sh``.  Each subsequent call to ``spack`` *in the same
       terminal session* will skip sourcing ``setup-env.sh`` (since it has
       already been loaded for the current shell).

It's mostly the same as what you had, but it uses some reStructuredText syntax that makes it stick out more / easier to parse the differences between Linux and MacOS (and made that alphabetical). Attached is what it looks like rendered.

I only mention this for your benefit, when using teletype text in markdown you use a single back-tick, but in RST single back-ticks are hyperlinks (ugh). You have to use two. The implication is that when it sees single back-ticks but cannot evaluate a valid hyperlink target, it actually makes it italic (lol). Another one to look out for is the same as markdown, two asterisks are bold and a single asterisk is italic. However, underscores for italics are not allowed as they also have to do with how hyperlinks work.

Thanks for the positive feedback!
I only have to remark that ~/.bashrc is completely ignored on OS X. Hence, the proposed change, despite being more informative for the reader, is not entirely correct. I will merge the two approaches soon and make a new commit.

@svenevs @adamjstewart Please don't forget about this and consider my latest commit for the docs.

Hi @MarquitoForrest: thanks for the awesome PR!

I really like the lazy sourcing you added to setup-env.sh. Would you be willing to integrate that into setup-env.[c]sh and simplify the instructions? If not, then I think we really should, because I agree that the startup delay is really irritating.

@tgamblin
Hey Todd, I am not really sure what you want me to do. I have to say that I am not a bash-scripting expert. I'd rather not touch this file as long as I don't know exactly what I am doing.
I also thought this issue just fully pertains to Mac users and hence should maybe not solved directly within the setup-env script.
If you can give me more precise instructions I am willing to try my best but on my own what I did is about as good as I can for now.

@tgamblin you want it lazy-sourced for all platforms or just darwin? @MarquitoForrest I can help with this, I'll PR against your PR (on your fork) :)

Closing, since no activity has been done on this PR in a couple of years and changes seem outdated. If anybody thinks this should stay open, please undo this.