add news, docs, tests

Author: IanButterworth

CHANGELOG.md

@@ -3,6 +3,8 @@ Pkg v1.13 Release Notes
 
 - Project.toml environments now support a `readonly` field to mark environments as read-only, preventing modifications. ([#4284])
 - Packages are now automatically added to `[sources]` when they are added by url or devved.
+- Added `Pkg.precompile() do` block syntax to delay autoprecompilation until after multiple operations complete, improving efficiency when performing several environment changes. ([#4262])
+- Added `Pkg.autoprecompilation_enabled(state::Bool)` to globally enable or disable automatic precompilation for Pkg operations. ([#4262])
 
 Pkg v1.12 Release Notes
 =======================
@@ -13,7 +15,7 @@ Pkg v1.12 Release Notes
 - Pkg now supports "apps" which are Julia packages that can be run directly from the terminal after installation.
   Apps can be defined in a package's Project.toml and installed via Pkg. ([#3772])
 - `status` now shows when different versions/sources of dependencies are loaded than that which is expected by the manifest ([#4109])
-- When adding or developing a package that exists in the `[weakdeps]` section, it is now automatically removed from 
+- When adding or developing a package that exists in the `[weakdeps]` section, it is now automatically removed from
   weak dependencies and added as a regular dependency. ([#3865])
 - Enhanced fuzzy matching algorithm for package name suggestions.
 

docs/src/api.md

@@ -39,6 +39,7 @@ Pkg.gc
 Pkg.status
 Pkg.compat
 Pkg.precompile
+Pkg.autoprecompilation_enabled
 Pkg.offline
 Pkg.why
 Pkg.dependencies

docs/src/environments.md

@@ -190,16 +190,53 @@ If a given package version errors during auto-precompilation, Pkg will remember
 automatically tries and will skip that package with a brief warning. Manual precompilation can be used to
 force these packages to be retried, as `pkg> precompile` will always retry all packages.
 
-To disable the auto-precompilation, set `ENV["JULIA_PKG_PRECOMPILE_AUTO"]=0`.
-
 The indicators next to the package names displayed during precompilation
-indicate the status of that package's precompilation. 
+indicate the status of that package's precompilation.
 
 - `[◐, ◓, ◑, ◒]` Animated "clock" characters indicate that the package is currently being precompiled.
 - `✓` A green checkmark indicates that the package has been successfully precompiled (after which that package will disappear from the list). If the checkmark is yellow it means that the package is currently loaded so the session will need to be restarted to access the version that was just precompiled.
 - `?` A question mark character indicates that a `PrecompilableError` was thrown, indicating that precompilation was disallowed, i.e. `__precompile__(false)` in that package.
 - `✗` A cross indicates that the package failed to precompile.
 
+#### Controlling Auto-precompilation
+
+Auto-precompilation can be controlled in several ways:
+
+- **Environment variable**: Set `ENV["JULIA_PKG_PRECOMPILE_AUTO"]=0` to disable auto-precompilation globally.
+- **Programmatically**: Use `Pkg.autoprecompilation_enabled(false)` to disable auto-precompilation for the current session, or `Pkg.autoprecompilation_enabled(true)` to re-enable it.
+- **Scoped control**: Use `Pkg.precompile(f, args...; kwargs...)` to execute a function `f` with auto-precompilation temporarily disabled, then automatically trigger precompilation afterward if any packages were modified during the execution.
+
+!!! compat "Julia 1.13"
+    The `Pkg.autoprecompilation_enabled()` function and `Pkg.precompile()` do-block syntax require at least Julia 1.13.
+
+For example, to add multiple packages without triggering precompilation after each one:
+
+```julia-repl
+julia> Pkg.precompile() do
+           Pkg.add("Example")
+           Pkg.dev("JSON")
+           Pkg.update("HTTP")
+       end
+   Resolving package versions...
+   ...
+Precompiling environment...
+  14 dependencies successfully precompiled in 25 seconds
+```
+
+Or to temporarily disable auto-precompilation:
+
+```julia-repl
+julia> Pkg.autoprecompilation_enabled(false)
+false
+
+julia> Pkg.add("Example")  # No precompilation happens
+   Resolving package versions...
+   ...
+
+julia> Pkg.autoprecompilation_enabled(true)
+true
+```
+
 ### Precompiling new versions of loaded packages
 
 If a package that has been updated is already loaded in the session, the precompilation process will go ahead and precompile

src/Pkg.jl

@@ -73,7 +73,7 @@ can_fancyprint(io::IO) = (usable_io(io)) && (get(ENV, "CI", nothing) != "true")
 
 _autoprecompilation_enabled::Bool = true
 _autoprecompilation_enabled_scoped = Base.ScopedValues.ScopedValue{Bool}(true)
-autoprecompilation_enabled(state::Bool) = (autoprecompilation_enabled = state)
+autoprecompilation_enabled(state::Bool) = (global _autoprecompilation_enabled = state)
 function should_autoprecompile()
     if Base.JLOptions().use_compiled_modules == 1 &&
         _autoprecompilation_enabled &&
@@ -251,6 +251,9 @@ end
 !!! compat "Julia 1.9"
     Timing mode requires at least Julia 1.9.
 
+!!! compat "Julia 1.13"
+    The `Pkg.precompile(f, args...; kwargs...)` do-block syntax requires at least Julia 1.13.
+
 # Examples
 ```julia
 Pkg.precompile()
@@ -260,6 +263,39 @@ Pkg.precompile(["Foo", "Bar"])
 """
 const precompile = API.precompile
 
+"""
+    Pkg.autoprecompilation_enabled(state::Bool)
+
+Enable or disable automatic precompilation for Pkg operations.
+
+When `state` is `true` (default), Pkg operations that modify the project environment
+will automatically trigger precompilation of affected packages. When `state` is `false`,
+automatic precompilation is disabled and packages will only be precompiled when
+explicitly requested via [`Pkg.precompile`](@ref).
+
+This setting affects the global state and persists across Pkg operations in the same
+Julia session. It can be used in combination with [`Pkg.precompile`](@ref) do-syntax
+for more fine-grained control over when precompilation occurs.
+
+!!! compat "Julia 1.13"
+    This function requires at least Julia 1.13.
+
+# Examples
+```julia
+# Disable automatic precompilation
+Pkg.autoprecompilation_enabled(false)
+Pkg.add("Example")  # Will not trigger auto-precompilation
+Pkg.precompile()    # Manual precompilation
+
+# Re-enable automatic precompilation
+Pkg.autoprecompilation_enabled(true)
+Pkg.add("AnotherPackage")  # Will trigger auto-precompilation
+```
+
+See also [`Pkg.precompile`](@ref).
+"""
+const autoprecompilation_enabled = autoprecompilation_enabled
+
 """
     Pkg.rm(pkg::Union{String, Vector{String}}; mode::PackageMode = PKGMODE_PROJECT)
     Pkg.rm(pkg::Union{PackageSpec, Vector{PackageSpec}}; mode::PackageMode = PKGMODE_PROJECT)

test/api.jl

@@ -158,6 +158,63 @@ import .FakeTerminals.FakeTerminal
             @test !occursin("Precompiling", String(take!(iob))) # test that the previous precompile was a no-op
         end
 
+        dep8_srcfile = joinpath("packages", "Dep8", "src", "Dep8.jl")
+        @testset "delayed precompilation with do-syntax" begin
+            iob = IOBuffer()
+            Pkg.develop(Pkg.PackageSpec(path="packages/Dep7"))
+
+            # Test that operations inside Pkg.precompile() do block don't trigger auto-precompilation
+            Pkg.precompile(io=iob) do
+                write(dep8_srcfile, read(dep8_srcfile, String) * " ") # Modify the source to ensure it is recompiled
+                Pkg.add(Pkg.PackageSpec(path="packages/Dep8"))
+                Pkg.rm("Dep8")
+                write(dep8_srcfile, read(dep8_srcfile, String) * " ") # Modify the source to ensure it is recompiled
+                Pkg.add(Pkg.PackageSpec(path="packages/Dep8"))
+            end
+
+            # The precompile should happen once at the end
+            str = String(take!(iob))
+            @test occursin("Precompiling", str)
+
+            # Verify it was precompiled by checking a second call is a no-op
+            Pkg.precompile(io=iob)
+            @test !occursin("Precompiling", String(take!(iob)))
+        end
+
+        @testset "autoprecompilation_enabled global control" begin
+            iob = IOBuffer()
+
+            # Test disabling autoprecompilation globally
+            original_state = Pkg._autoprecompilation_enabled
+            try
+                Pkg.autoprecompilation_enabled(false)
+                @test Pkg._autoprecompilation_enabled == false
+
+                # Operations should not trigger autoprecompilation when globally disabled
+                write(dep8_srcfile, read(dep8_srcfile, String) * " ") # Modify the source to ensure it is recompiled
+                Pkg.add(Pkg.PackageSpec(path="packages/Dep8"), io=iob)
+                @test !occursin("Precompiling", String(take!(iob)))
+
+                # Manual precompile should still work
+                Pkg.precompile(io=iob)
+                @test occursin("Precompiling", String(take!(iob)))
+
+                # Re-enable autoprecompilation
+                Pkg.autoprecompilation_enabled(true)
+                @test Pkg._autoprecompilation_enabled == true
+
+                # Operations should now trigger autoprecompilation again
+                Pkg.rm("Dep8", io=iob)
+                write(dep8_srcfile, read(dep8_srcfile, String) * " ") # Modify the source to ensure it is recompiled
+                Pkg.add(Pkg.PackageSpec(path="packages/Dep8"), io=iob)
+                @test occursin("Precompiling", String(take!(iob)))
+
+            finally
+                # Restore original state
+                Pkg.autoprecompilation_enabled(original_state)
+            end
+        end
+
         @testset "instantiate" begin
             iob = IOBuffer()
             Pkg.activate("packages/Dep7")