spack/lib/spack/docs
Harmen Stoppels 3489cc0a9b
Refer to mirrors by name, path, or url (#34891)
With this change we get the invariant that `mirror.fetch_url` and
`mirror.push_url` return valid URLs, even when the backing config
file is actually using (relative) paths with potentially `$spack` and
`$env` like variables.

Secondly it avoids expanding mirror path / URLs too early,
so if I say `spack mirror add name ./path`, it stays `./path` in my
config. When it's retrieved through MirrorCollection() we
exand it to say `file://<env dir>/path` if `./path` was set in an
environment scope.

Thirdly, the interface is simplified for the relevant buildcache
commands, so it's more like `git push`:

```
spack buildcache create [mirror] [specs...]
```

`mirror` is either a mirror name, a path, or a URL.

Resolving the relevant mirror goes as follows:
    
- If it contains either / or \ it is used as an anonymous mirror with
   path or url.
- Otherwise, it's interpreted as a named mirror, which must exist.

This helps to guard against typos, e.g. typing `my-mirror` when there
is no such named mirror now errors with:

```
$ spack -e . buildcache create my-mirror
==> Error: no mirror named "my-mirror". Did you mean ./my-mirror?
```

instead of creating a directory in the current working directory. I
think this is reasonable, as the alternative (requiring that a local dir
exists) feels a bit pendantic in the general case -- spack is happy to
create the build cache dir when needed, saving a `mkdir`.

The old (now deprecated) format will still be available in Spack 0.20,
but is scheduled to be removed in 0.21:

```
spack buildcache create (--directory | --mirror-url | --mirror-name) [specs...]
```

This PR also touches `tmp_scope` in tests, because it didn't really
work for me, since spack fixes the possible --scope values once and
for all across tests, so tests failed when run out of order.
2023-01-16 10:14:41 -08:00
..
_gh_pages_redirect Use https for links (#19244) 2020-10-09 11:24:09 -05:00
_static make empty _static directory "exist" to git 2014-01-09 14:03:32 +01:00
build_systems Build System docs: consistent headers (#34047) 2022-11-23 13:35:55 +01:00
example_files Implement an optional compiler bootstrapping phase 2019-09-13 22:57:15 -07:00
images Allow for packages with multiple build-systems (#30738) 2022-10-26 20:17:32 +02:00
tables Getting Started: Python 2 is no longer supported (#33927) 2022-11-16 08:36:49 +01:00
.gitignore tutorial: move tutorial to standalone site (#13450) 2019-10-25 21:49:27 -07:00
basic_usage.rst docs: fix typo (#33926) 2022-11-15 16:06:12 -08:00
binary_caches.rst Refer to mirrors by name, path, or url (#34891) 2023-01-16 10:14:41 -08:00
bootstrapping.rst Deprecate spack bootstrap trust/untrust (#33600) 2022-10-29 12:24:26 -07:00
build_settings.rst Fix incorrect configuration file name in docs (#34925) 2023-01-16 14:52:08 +01:00
build_systems.rst Allow for packages with multiple build-systems (#30738) 2022-10-26 20:17:32 +02:00
chain.rst Update copyright year to 2022 2022-01-14 22:50:21 -08:00
command_index.in Rework command reference in docs, add spack commands command 2018-02-12 20:25:17 -08:00
conf.py Fix building docs 2023-01-04 09:43:04 -08:00
config_yaml.rst Experimental binding of shared ELF libraries (#31948) 2022-11-03 17:34:00 -06:00
configuration.rst Docs: Minor change 'several'->'over a dozen' (#34274) 2022-12-02 10:27:37 -08:00
containers.rst containerize: fix concretization -> concretizer (#31594) 2022-07-26 08:56:24 -07:00
contribution_guide.rst remove activate/deactivate support in favor of environments (#29317) 2022-11-11 00:50:07 -08:00
developer_guide.rst Fix building docs 2023-01-04 09:43:04 -08:00
environments.rst docs updates for spack env depfile (#33937) 2022-11-16 15:47:31 +01:00
extensions.rst Support config variables in config.yaml extensions paths (#17772) 2022-02-07 11:40:52 +01:00
features.rst Allow for packages with multiple build-systems (#30738) 2022-10-26 20:17:32 +02:00
getting_started.rst docs: update info on XCode requirements (#34097) 2022-11-24 00:20:09 +01:00
index.rst docs: remove monitors and analyzers (#34358) 2022-12-22 11:47:13 +01:00
Makefile API Docs: fix broken reference targets 2021-07-16 08:30:56 -07:00
mirrors.rst docs: add (config.yaml) to sections for faster lookup by config file (#30157) 2022-04-20 15:00:43 +02:00
module_file_generation.svg SC17: reworked module file tutorial section (#5657) 2017-11-12 00:27:20 -08:00
module_file_support.rst Update module_file_support.rst (#32629) 2022-09-14 01:41:50 +00:00
package_list.rst Update copyright year to 2022 2022-01-14 22:50:21 -08:00
packaging_guide.rst Documentation: Add installation policy to packaging guide (#34878) 2023-01-12 11:01:35 -08:00
pipelines.rst Docs: Update pipeline ci rebuild to add --tests (plus fixed typos) (#32048) 2022-09-21 14:23:58 +02:00
replace_conda_homebrew.rst Add --fresh to docs to actually upgrade spack environments (#34433) 2022-12-22 11:19:24 +00:00
repositories.rst docs: add (config.yaml) to sections for faster lookup by config file (#30157) 2022-04-20 15:00:43 +02:00
requirements.txt Docs: Getting Started Dependencies (#32480) 2022-10-10 23:25:37 +00:00
spack.yaml Add missing upperbound to docs/spack.yaml (#33280) 2022-10-13 11:54:20 -07:00