Improve the artifact machinery

.buildkite/pipeline.yml

@@ -1,3 +1,10 @@
+# AMDGPU.jl chooses between the ROCm_Runtime artifacts and a local ROCm through
+# ROCm_Runtime's "local" preference. Every GPU step writes that preference and
+# then asserts the provider it actually resolved to, so that a change of default
+# cannot silently swap the ROCm underneath a job. The artifacts are lazy, so
+# Pkg.instantiate/update download nothing; the pin only has to be in place
+# before AMDGPU is first loaded, which also covers the steps where the
+# julia-test plugin instantiates before the command below runs.
 steps:
   - label: "Documentation"
     plugins:
@@ -36,7 +43,7 @@ steps:
   # packages have to be dev'ed manually before instantiating -- which rules out
   # the julia-test plugin, whose pre-command hook instantiates the project
   # before the step's command gets a chance to run.
-  - label: "Julia 1.10"
+  - label: "Julia 1.10 (ROCm artifacts)"
     plugins:
       - JuliaCI/julia#v1:
           version: "1.10"
@@ -47,19 +54,20 @@ steps:
       rocmgpu: "*"
     if: build.message !~ /\[skip tests\]/
     command: |
+      printf '[ROCm_Runtime]\nlocal = false\n' > LocalPreferences.toml
       julia --project -e '
         using Pkg
         Pkg.develop([PackageSpec(path="ROCm_Runtime"), PackageSpec(path="ROCm_Runtime_Discovery")])
-        Pkg.update()
-        Pkg.test(; coverage=true)'
+        Pkg.update()'
+      julia --project -e 'using AMDGPU; AMDGPU.local_rocm && error("this step selected the ROCm artifacts, but AMDGPU resolved to a local ROCm")'
+      julia --project -e 'using Pkg; Pkg.test(; coverage=true)'
     timeout_in_minutes: 90
     env:
       JULIA_NUM_THREADS: 4
       JULIA_AMDGPU_CORE_MUST_LOAD: "1"
       JULIA_AMDGPU_HIP_MUST_LOAD: "1"
-      JULIA_AMDGPU_DISABLE_ARTIFACTS: "1"
 
-  - label: "Julia 1.11"
+  - label: "Julia 1.11 (ROCm artifacts)"
     plugins:
       - JuliaCI/julia#v1:
           version: "1.11"
@@ -70,15 +78,17 @@ steps:
       queue: "rocm"
       rocmgpu: "*"
     if: build.message !~ /\[skip tests\]/
-    command: "julia --project -e 'using Pkg; Pkg.update()'"
+    command: |
+      printf '[ROCm_Runtime]\nlocal = false\n' > LocalPreferences.toml
+      julia --project -e 'using Pkg; Pkg.update()'
+      julia --project -e 'using AMDGPU; AMDGPU.local_rocm && error("this step selected the ROCm artifacts, but AMDGPU resolved to a local ROCm")'
     timeout_in_minutes: 90
     env:
       JULIA_NUM_THREADS: 4
       JULIA_AMDGPU_CORE_MUST_LOAD: "1"
       JULIA_AMDGPU_HIP_MUST_LOAD: "1"
-      JULIA_AMDGPU_DISABLE_ARTIFACTS: "1"
 
-  - label: "Julia 1.12"
+  - label: "Julia 1.12 (ROCm artifacts)"
     plugins:
       - JuliaCI/julia#v1:
           version: "1.12"
@@ -89,15 +99,41 @@ steps:
       queue: "rocm"
       rocmgpu: "*"
     if: build.message !~ /\[skip tests\]/
-    command: "julia --project -e 'using Pkg; Pkg.update()'"
+    command: |
+      printf '[ROCm_Runtime]\nlocal = false\n' > LocalPreferences.toml
+      julia --project -e 'using Pkg; Pkg.update()'
+      julia --project -e 'using AMDGPU; AMDGPU.local_rocm && error("this step selected the ROCm artifacts, but AMDGPU resolved to a local ROCm")'
+    timeout_in_minutes: 90
+    env:
+      JULIA_NUM_THREADS: 4
+      JULIA_AMDGPU_CORE_MUST_LOAD: "1"
+      JULIA_AMDGPU_HIP_MUST_LOAD: "1"
+
+  # Coverage for the local-ROCm provider, also exercised by the CSCS
+  # MI300 pipeline. Does not use the julia-test plugin, so the provider is
+  # pinned before AMDGPU is first loaded and no artifact is fetched.
+  - label: "Julia 1.12 (local ROCm)"
+    plugins:
+      - JuliaCI/julia#v1:
+          version: "1.12"
+      - JuliaCI/julia-coverage#v1:
+          codecov: true
+    agents:
+      queue: "rocm"
+      rocmgpu: "*"
+    if: build.message !~ /\[skip tests\]/
+    command: |
+      printf '[ROCm_Runtime]\nlocal = true\n' > LocalPreferences.toml
+      julia --project -e 'using Pkg; Pkg.update()'
+      julia --project -e 'using AMDGPU; AMDGPU.local_rocm || error("this step selected a local ROCm, but AMDGPU resolved to the ROCm artifacts")'
+      julia --project -e 'using Pkg; Pkg.test(; coverage=true)'
     timeout_in_minutes: 90
     env:
       JULIA_NUM_THREADS: 4
       JULIA_AMDGPU_CORE_MUST_LOAD: "1"
       JULIA_AMDGPU_HIP_MUST_LOAD: "1"
-      JULIA_AMDGPU_DISABLE_ARTIFACTS: "1"
 
-  - label: "Julia 1.13"
+  - label: "Julia 1.13 (ROCm artifacts)"
     plugins:
       - JuliaCI/julia#v1:
           version: "1.13"
@@ -108,16 +144,17 @@ steps:
       queue: "rocm"
       rocmgpu: "*"
     if: build.message !~ /\[skip tests\]/
-    command: "julia --project -e 'using Pkg; Pkg.update()'"
+    command: |
+      printf '[ROCm_Runtime]\nlocal = false\n' > LocalPreferences.toml
+      julia --project -e 'using Pkg; Pkg.update()'
+      julia --project -e 'using AMDGPU; AMDGPU.local_rocm && error("this step selected the ROCm artifacts, but AMDGPU resolved to a local ROCm")'
     timeout_in_minutes: 90
-    soft_fail: true
     env:
       JULIA_NUM_THREADS: 4
       JULIA_AMDGPU_CORE_MUST_LOAD: "1"
       JULIA_AMDGPU_HIP_MUST_LOAD: "1"
-      JULIA_AMDGPU_DISABLE_ARTIFACTS: "1"
 
-  - label: "Julia nightly"
+  - label: "Julia nightly (ROCm artifacts)"
     plugins:
       - JuliaCI/julia#v1:
           version: "nightly"
@@ -128,17 +165,19 @@ steps:
       queue: "rocm"
       rocmgpu: "*"
     if: build.message !~ /\[skip tests\]/
-    command: "julia --project -e 'using Pkg; Pkg.update()'"
+    command: |
+      printf '[ROCm_Runtime]\nlocal = false\n' > LocalPreferences.toml
+      julia --project -e 'using Pkg; Pkg.update()'
+      julia --project -e 'using AMDGPU; AMDGPU.local_rocm && error("this step selected the ROCm artifacts, but AMDGPU resolved to a local ROCm")'
     timeout_in_minutes: 30
     soft_fail: true
     env:
       JULIA_NUM_THREADS: 4
       JULIA_AMDGPU_CORE_MUST_LOAD: "1"
       JULIA_AMDGPU_HIP_MUST_LOAD: "1"
-      JULIA_AMDGPU_DISABLE_ARTIFACTS: "1"
 
-  # see the "Julia 1.10" step for why this doesn't use the julia-test plugin
-  - label: "Julia 1.10 Enzyme"
+  # see the "Julia 1.10 (ROCm artifacts)" step for why this doesn't use the plugin
+  - label: "Julia 1.10 Enzyme (ROCm artifacts)"
     plugins:
       - JuliaCI/julia#v1:
           version: "1.10"
@@ -147,20 +186,21 @@ steps:
       rocmgpu: "*"
     if: build.message !~ /\[skip tests\]/
     command: |
+      printf '[ROCm_Runtime]\nlocal = false\n' > LocalPreferences.toml
       julia --project -e '
         using Pkg
         Pkg.develop([PackageSpec(path="ROCm_Runtime"), PackageSpec(path="ROCm_Runtime_Discovery")])
-        Pkg.update()
-        Pkg.test(; test_args=["enzyme"])'
+        Pkg.update()'
+      julia --project -e 'using AMDGPU; AMDGPU.local_rocm && error("this step selected the ROCm artifacts, but AMDGPU resolved to a local ROCm")'
+      julia --project -e 'using Pkg; Pkg.test(; test_args=["enzyme"])'
     timeout_in_minutes: 45
     soft_fail: true
     env:
       JULIA_NUM_THREADS: 4
       JULIA_AMDGPU_CORE_MUST_LOAD: "1"
       JULIA_AMDGPU_HIP_MUST_LOAD: "1"
-      JULIA_AMDGPU_DISABLE_ARTIFACTS: "1"
 
-  - label: "Julia 1.11 Enzyme"
+  - label: "Julia 1.11 Enzyme (ROCm artifacts)"
     plugins:
       - JuliaCI/julia#v1:
           version: "1.11"
@@ -170,16 +210,18 @@ steps:
       queue: "rocm"
       rocmgpu: "*"
     if: build.message !~ /\[skip tests\]/
-    command: "julia --project -e 'using Pkg; Pkg.update()'"
+    command: |
+      printf '[ROCm_Runtime]\nlocal = false\n' > LocalPreferences.toml
+      julia --project -e 'using Pkg; Pkg.update()'
+      julia --project -e 'using AMDGPU; AMDGPU.local_rocm && error("this step selected the ROCm artifacts, but AMDGPU resolved to a local ROCm")'
     timeout_in_minutes: 45
     soft_fail: true
     env:
       JULIA_NUM_THREADS: 4
       JULIA_AMDGPU_CORE_MUST_LOAD: "1"
       JULIA_AMDGPU_HIP_MUST_LOAD: "1"
-      JULIA_AMDGPU_DISABLE_ARTIFACTS: "1"
 
-  # see the "Julia 1.10" step for why this doesn't use the julia-test plugin
+  # see the "Julia 1.10 (ROCm artifacts)" step for why this doesn't use the plugin
   - label: "GPU-less environment"
     plugins:
       - JuliaCI/julia#v1:
@@ -202,12 +244,14 @@ steps:
       - JuliaCI/julia#v1:
           version: "1.12"
     command: |
+      printf '[ROCm_Runtime]\nlocal = false\n' > perf/LocalPreferences.toml
       julia --project=perf -e '
         println("--- :julia: Instantiating benchmark project")
         using Pkg
         Pkg.develop([PackageSpec(path="."), PackageSpec(path="ROCm_Runtime"), PackageSpec(path="ROCm_Runtime_Discovery")])
-        Pkg.instantiate()
-
+        Pkg.instantiate()'
+      julia --project=perf -e 'using AMDGPU; AMDGPU.local_rocm && error("this step selected the ROCm artifacts, but AMDGPU resolved to a local ROCm")'
+      julia --project=perf -e '
         println("+++ :julia: Running benchmarks")
         include("perf/runbenchmarks.jl")'
     artifact_paths:
@@ -220,9 +264,7 @@ steps:
     env:
       JULIA_AMDGPU_CORE_MUST_LOAD: "1"
       JULIA_AMDGPU_HIP_MUST_LOAD: "1"
-      JULIA_AMDGPU_DISABLE_ARTIFACTS: "1"
 
 env:
-  JULIA_AMDGPU_LOGGING_ENABLED: true
   SECRET_CODECOV_TOKEN: "lVqFGgrywYmQrILXBcP8i6TosP+q/W2oTDVLIdkWFWscd/a61oSVb8Tycq3qvngsrdmKU9EevdQo+1x+w7cu4IuTq63ahQc0RFgi4Q29hC52OgN2wFql984Cqq3T96P3jyV0ZljaRT+a+9AY0oWmmCph55amvvQ4DOMq3tfGDbp7gdueQvJmSYQGVT3/9Sjn4/esYppcKBGltQqQX2E7WrHLpnqRmsmjcSeZ/S/+PgPRb4ZnpBecAUP2d/MlPgKfP0ZUGbDlcbGu+ZDZNksxKIYuAlNrWPhpNAro7hACfEk4T5RRpNiwmJyXJZ8LUD8zNYIUKSmHjUtmqhNXgujWXA==;U2FsdGVkX1/v/P2Y7KZsvC55Au6eET37uDE6M5I6J275maix+SMD0EoJQ19cFp/lae+G8V7dvpPGfrh4hj2nOg=="
   SECRET_DOCUMENTER_KEY: "Z7qQ0/fkPqZNdY/CiipllaxOo9DeuS3PDmeQ+cnnvaNxv7WseZ+xzWZQw8qp9tVmCb5iTpf0Rr6TTUxCb4a6lxCyQxx3Qewmnl/KJOHFIB4OtBAYIm7trCK3IDL28snHdpN3w7+O4tcLPhRr0rSHy7/hKuACR5q2aC2liz6SbJhZzwpHPVdFxZS4xEG9R4tS4UThkwMR9vwBdi5mqrXip6sl0XXJYe1BTqaIKdr+FyGw8Rv9EIzrIb3wETH/7aZlJWRn7mHGKe+ZMp3EtVJvxCE6B8Mk8377H/wK+p+SL+QN01EjisxINemZLCCu3d0Bf0du72paldq9nMJspPAd/w==;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"

docs/src/api/system.md

@@ -27,11 +27,14 @@ Several behaviours are configured through [Preferences.jl](https://github.com/Ju
 | Preference | Set via | Effect |
 |:--|:--|:--|
 | `version` / `local` | `AMDGPU.set_rocm_version!` | Select the ROCm version, and whether to use downloaded artifacts or a local ROCm installation. |
+| `arch` | `AMDGPU.set_rocm_version!` | Override the GPU architectures used to select the ROCm artifact, as a comma-separated list of `gfx` targets. Useful when no GPU is visible at install time. See [Installation Info](@ref). |
 | `nonblocking_synchronize` | preference | Use non-blocking stream synchronization (default `true`); disable for slightly lower latency. See [Streams](@ref). |
 | `eager_gc` | `AMDGPU.eager_gc!(::Bool)` | Trigger GC before allocations under memory pressure. See [Memory Allocation and Intrinsics](@ref). |
 | `hard_memory_limit` | `AMDGPU.hard_memory_limit!("8 GiB")` | Hard cap on GPU memory, checked before every allocation. |
 | `soft_memory_limit` | `AMDGPU.soft_memory_limit!("6 GiB")` | Advisory limit for the memory pool. |
 
+The `version`, `local` and `arch` preferences belong to the `ROCm_Runtime` subpackage rather than to AMDGPU itself, so when editing `LocalPreferences.toml` by hand they go under a `[ROCm_Runtime]` section. They are compile-time preferences: changing one invalidates precompilation and takes effect after restarting Julia.
+
 ## Debugging kernel launches
 
 Set the environment variable `HIP_LAUNCH_BLOCKING=1` (or toggle `AMDGPU.LAUNCH_BLOCKING[] = true` at runtime) to make kernel launches synchronous. This makes errors surface at the offending launch rather than at a later synchronization point, which is invaluable when tracking down a crashing or misbehaving kernel.