Return of the build script via Preferences

Project.toml

@@ -4,6 +4,7 @@ author = ["Josef Heinen (@jheinen)"]
 version = "0.69.5"
 
 [deps]
+Artifacts = "56f22d72-fd6d-98f1-02f0-08ddc0907c33"
 Base64 = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"
 DelimitedFiles = "8bb1440f-4735-579b-a4ab-409b98df4dab"
 GR_jll = "d2c73de3-f751-5644-a686-071e5b155ba9"
@@ -17,11 +18,15 @@ Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 Serialization = "9e88b42a-f829-5b0c-bbe9-9e923198166b"
 Sockets = "6462fe0b-24de-5631-8697-dd941f90decc"
+TOML = "fa267f1f-6049-4f14-aa54-33bafae1ed76"
+Tar = "a4e569a6-e804-4fa4-b0f3-eef7a1d5b13e"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 UUIDs = "cf7118a7-6976-5b1a-9a39-7adc72f591a4"
+p7zip_jll = "3f19e933-33d8-53b3-aaab-bd5110c3b7a0"
 
 [compat]
-Preferences = "1"
 HTTP = "0.8, 0.9, 1"
 JSON = "0.20, 0.21, 1"
+Preferences = "1"
+GR_jll = "0.69.1"
 julia = "1.6"

README.md

@@ -80,3 +80,43 @@ However, if you want to permanently use your own GR run-time, you have to set th
 
 Please note that with the method shown here, `GR_jll` is not imported.
 
+### Switching binaries via GR.GRPreferences
+
+To aid in switching between BinaryBuilder and upstream framework binaries, the `GR.GRPReferences` module implements three methods `use_system_binary()`, `use_upstream_binary()`, and `use_jll_binary()`. These use [Preferences.jl](https://github.com/JuliaPackaging/Preferences.jl) to configure GR.jl
+and GR_jll.jl.
+
+To use an existing GR install, invoke `use_system_binary`.
+
+```julia
+using GR
+GR.GRPreferences.use_system_binary("/path/to/gr"; force = true)
+```
+
+To download and switch to [upstream binaries](https://github.com/sciapp/gr/releases) invoke `use_upstream_binary`.
+
+```julia
+using GR # repeat this if there is an error
+GR.GRPreferences.use_upstream_binary(; force = true)
+```
+
+`use_system_binary` and `use_upstream_binary` accept an `override` keyword. This may be set to one of the following:
+* `:depot` (default) - Use Overrides.toml in the Julia depot. This normally resides in `.julia/artifacts/Overrides.toml`
+* `:project` - Use LocalPreferences.toml. This is usually located near the Project.toml of your active project environment.
+* `(:depot, :project)` - Use both of the override mechanisms above.
+
+To switch back to BinaryBuilder binaries supplied with [GR_jll](https://github.com/JuliaBinaryWrappers/GR_jll.jl), invoke `use_jll_binary`:
+
+```julia
+using GR # repeat this if there is an error
+GR.GRPreferences.use_jll_binary(; force = true)
+```
+
+This will reset both the `:depot` and `:project` override mechanisms above.
+
+If you encounter difficulties switching between binaries, the `diagnostics()` function will provide useful information.
+Please include this information when asking for assistance.
+
+```julia
+using GR
+GR.GRPreferences.diagnostics()
+```