Normalize GitLab-CI *cache* parameter.

* Document in gitlab.rst
* Remove unnecessary indirection for null *cache* parameter.
* Remove *.pull-cache-template* no-op.
* Rename *.build-cache-template* to *.use-ccache*

Change-Id: I3623d6834360498c69bf968b926139c884cab867

diff --git a/admin/gitlab-ci/archive.gitlab-ci.yml b/admin/gitlab-ci/archive.gitlab-ci.yml
index 2ec33f3f9cb0f5ba66e41ed63a70fc08284eda97..1de06e00d576c77b0174d061dae8ac89af2a8b7d 100644 (file)
--- a/admin/gitlab-ci/archive.gitlab-ci.yml
+++ b/admin/gitlab-ci/archive.gitlab-ci.yml
@@ -124,8 +124,8 @@ prepare-release-version:
 
 .regressiontests-extends-template:
   extends:
-    - .no-cache-template
     - .variables:default
+  cache: {}
 
 prepare-regressiontests:
   extends:

diff --git a/admin/gitlab-ci/documentation.gitlab-ci.yml b/admin/gitlab-ci/documentation.gitlab-ci.yml
index 021acc0774ecfc1dc042c2dc3d9e587b4ed8cbdd..a80bdf0c46ed9924770958d103845fc06f7b2ac3 100644 (file)
--- a/admin/gitlab-ci/documentation.gitlab-ci.yml
+++ b/admin/gitlab-ci/documentation.gitlab-ci.yml
@@ -197,6 +197,7 @@
     - .configure-extends-template
     - .configure-docs-release-template
     - .documentation-before-script-template
+  cache: {}
 
 configure-docs:
   extends:
@@ -277,7 +278,7 @@ configure-docs-gmxapi:
 .build-docs-binary:
   extends:
     - .build-extends-template
-    - .build-cache-template
+    - .use-ccache
     - .build-docs-binary-template
     - .documentation-before-script-template
 
@@ -285,7 +286,6 @@ configure-docs-gmxapi:
   extends:
     - .binary-build-template
     - .variables:default
-    - .no-cache-template
     - .build-docs-webpage-template
     - .documentation-before-script-template
 
@@ -391,7 +391,7 @@ webpage-configure-release:
   extends:
     - .configure-docs-release
     - .configure-gmxapi-template
-    - .no-cache-template
+  cache: {}
   only:
     refs:
       - web

diff --git a/admin/gitlab-ci/global.gitlab-ci.yml b/admin/gitlab-ci/global.gitlab-ci.yml
index bc5a1b3091546fa9253792bb4222fbcd4c11c653..dc7c31140a74ae2acc8d3ca8616882575ab4f312 100644 (file)
--- a/admin/gitlab-ci/global.gitlab-ci.yml
+++ b/admin/gitlab-ci/global.gitlab-ci.yml
@@ -1,3 +1,7 @@
+# Mix-in job definitions.
+
+# Centralized definitions of common job parameter values.
+
 .variables:default:
   variables:
     KUBERNETES_CPU_LIMIT: 8
@@ -9,21 +13,15 @@
     BUILD_DIR: build
     INSTALL_DIR: install
 
-.build-cache-template:
+# Behavioral templates
+
+# Use a persistent compiler cache to speed up rebuilds for a single job.
+.use-ccache:
   cache:
     key: "$CI_JOB_NAME-$CI_JOB_STAGE-$CI_COMMIT_REF_SLUG"
     paths:
       - ccache/
 
-.pull-cache-template:
-  cache:
-    key: "$CI_JOB_NAME-$CI_JOB_STAGE-$CI_COMMIT_REF_SLUG"
-    # Read but don't update the cache
-    policy: pull
-
-.no-cache-template:
-  cache: {}
-
 
 .gmxapi-extra-installs:
   variables:

diff --git a/admin/gitlab-ci/lint.gitlab-ci.yml b/admin/gitlab-ci/lint.gitlab-ci.yml
index 3758efa4be12c4ed2dc25f88cff4ae9e8b309e5a..348ad79ca121bd047a9ddbf91d6a92466df64cf1 100644 (file)
--- a/admin/gitlab-ci/lint.gitlab-ci.yml
+++ b/admin/gitlab-ci/lint.gitlab-ci.yml
@@ -37,11 +37,11 @@ build-clang-tidy:
 run-clang-format:
   extends:
     - .binary-build-template
-    - .no-cache-template
     - .variables:default
     - .clang-before-script-template
     - .build-clang-template
     - .clang7-template
+  cache: {}
   stage: source-check
   when: always
   needs:
@@ -70,11 +70,11 @@ run-clang-format:
 run-copyright-check:
   extends:
     - .binary-build-template
-    - .no-cache-template
     - .variables:default
     - .clang-before-script-template
     - .build-clang-template
     - .clang7-template
+  cache: {}
   stage: source-check
   when: always
   needs:
@@ -104,10 +104,10 @@ run-copyright-check:
 
 run-check-source:
   extends:
-    - .no-cache-template
     - .variables:default
     - .build-docs-binary-template
     - .documentation-before-script-template
+  cache: {}
   stage: source-check
   needs:
     - job: simple-build

diff --git a/admin/gitlab-ci/testing-matrix.gitlab-ci.yml b/admin/gitlab-ci/testing-matrix.gitlab-ci.yml
index 92850e74e4fee69fe3cced38eeec4240be2a8486..c26dc49b18d6a5e46b2b5d70f2a20c02bc5065f4 100644 (file)
--- a/admin/gitlab-ci/testing-matrix.gitlab-ci.yml
+++ b/admin/gitlab-ci/testing-matrix.gitlab-ci.yml
@@ -75,7 +75,7 @@
 simple-build:
   extends:
     - .simple-build-template
-    - .build-cache-template
+    - .use-ccache
     - .variables:default
     - .gcc-before-script-template
     - .build-gcc-template
@@ -237,14 +237,14 @@ simple-build:
 .configure-extends-template:
   extends:
     - .configure-build-template
-    - .no-cache-template
     - .variables:default
+  cache: {}
 
 .configure-release-extends-template:
   extends:
     - .configure-build-release-template
-    - .no-cache-template
     - .variables:default
+  cache: {}
 
 # Templates for configuration stage
 .configure-gcc:
@@ -280,8 +280,8 @@ configure-gcc-7:
 configure-gcc-7-release:
   extends:
     - .configure-gcc-release
-    - .no-cache-template
     - .gcc7-template
+  cache: {}
   variables:
     COMPILER_MAJOR_VERSION: 7
     RELEASE_BUILD_DIR: release-builds-gcc
@@ -328,8 +328,8 @@ configure-gcc-7-double:
 configure-gcc-7-double-release:
   extends:
     - .configure-gcc-release
-    - .no-cache-template
     - .gcc7-template
+  cache: {}
   variables:
     COMPILER_MAJOR_VERSION: 7
     CMAKE_PRECISION_OPTIONS: -DGMX_DOUBLE=ON
@@ -364,8 +364,8 @@ configure-gcc-7-gmxapi-release:
   extends:
     - .configure-gcc-release
     - .configure-gmxapi-template
-    - .no-cache-template
     - .gcc7-template
+  cache: {}
   variables:
     COMPILER_MAJOR_VERSION: 7
     RELEASE_BUILD_DIR: release-builds-gcc
@@ -397,8 +397,8 @@ configure-gcc-8:
 configure-gcc-8-release:
   extends:
     - .configure-gcc-release
-    - .no-cache-template
     - .gcc8-template
+  cache: {}
   variables:
     COMPILER_MAJOR_VERSION: 8
     RELEASE_BUILD_DIR: release-builds-gcc
@@ -470,8 +470,8 @@ configure-clang-7:
 configure-clang-7-release:
   extends:
     - .configure-clang-release
-    - .no-cache-template
     - .clang7-template
+  cache: {}
   variables:
     COMPILER_MAJOR_VERSION: 7
     RELEASE_BUILD_DIR: release-builds-clang
@@ -505,8 +505,8 @@ configure-clang-7-gmxapi-release:
   extends:
     - .configure-clang-release
     - .configure-gmxapi-template
-    - .no-cache-template
     - .clang7-template
+  cache: {}
   variables:
     COMPILER_MAJOR_VERSION: 7
     RELEASE_BUILD_DIR: release-builds-clang
@@ -538,8 +538,8 @@ configure-clang-8:
 configure-clang-8-release:
   extends:
     - .configure-clang-release
-    - .no-cache-template
     - .clang8-template
+  cache: {}
   variables:
     COMPILER_MAJOR_VERSION: 8
     RELEASE_BUILD_DIR: release-builds-clang
@@ -583,7 +583,7 @@ configure-clang-8-release:
 .build-extends-template:
   extends:
     - .binary-build-template
-    - .build-cache-template
+    - .use-ccache
     - .variables:default
 
 .build-gcc:
@@ -899,7 +899,6 @@ build-clang-8-release:
 .test-extends-template:
   extends:
     - .test-base-template
-    - .pull-cache-template
     - .test-script-template
     - .variables:default
 

diff --git a/docs/dev-manual/gitlab.rst b/docs/dev-manual/gitlab.rst
index 3643ad059713cda1594a67e8f4de74876da99a43..3676679481c484a35313643c397e14937bd4c4c3 100644 (file)
--- a/docs/dev-manual/gitlab.rst
+++ b/docs/dev-manual/gitlab.rst
@@ -54,6 +54,14 @@ GitLab CI job parameters, but note the following GROMACS-specific conventions.
         Avoid using *before-script* directly, and be cautious
         about nested *extends* overriding multiple *before_script* definitions.
 
+    cache
+        There is no global default, but jobs that build software will likely
+        set *cache*. To explicitly unset *cache* directives, specify a job
+        parameter of ``cache: {}``.
+        Refer to `GitLab docs <https://docs.gitlab.com/ee/ci/yaml/#cache>`__
+        for details. In particular, note the details of cache identity according
+        to `cache:key <https://docs.gitlab.com/ee/ci/yaml/#cachekey>`__
+
     image
         Part of the tool chain configuration. Instead of setting *image*
         directly, *extend* a *.use_<toolchain>* template from
@@ -64,10 +72,22 @@ GitLab CI job parameters, but note the following GROMACS-specific conventions.
         Refer to `GitLab <https://docs.gitlab.com/ee/ci/yaml/#variables>`__
         for details of the merging behavior. Refer to :ref:`variables` for local usage.
 
+Global templates
+~~~~~~~~~~~~~~~~
+
 In addition to the templates in the main job definition files,
 common "mix-in" functionality and behavioral templates are defined in
 :file:`admin/gitlab-ci/global.gitlab-ci.yml`.
 
+Jobs beginning with ``.use-`` provide mix-in behavior, such as boilerplate for
+jobs using a particular tool chain.
+
+Jobs beginning with a `parameter <https://docs.gitlab.com/ee/ci/yaml>`__
+name allow parameters to be set in a single place for common job characteristics.
+If providing more than a default parameter value, the job name should be suffixed
+by a meaningful descriptor and documented within
+:file:`admin/gitlab-ci/global.gitlab-ci.yml`
+
 .. _variables:
 
 Variables