PrecompileTools

Overview

PrecompileTools is designed to help reduce delay on first usage of Julia code. It can forceprecompilation of specific workloads; particularly with Julia 1.9 and higher, the precompiled code is automatically saved to disk, so that it doesn't need to be compiled freshly in each Julia session. You can usePrecompileTools as a package developer, to reduce the latency experienced by users of your package for "typical" workloads; you can also usePrecompileTools as a user, creating custom "Startup" package(s) that precompile workloads important for your work.

The main tool inPrecompileTools is a macro,@compile_workload, which precompiles all the code needed to execute the workload. It also includes a second macro,@setup_workload, which can be used to "mark" a block of code as being relevant only for precompilation but which does not itself force compilation of@setup_workload code. (@setup_workload is typically used to generate test data using functions that you don't need to precompile in your package.) Finally,PrecompileTools includes@recompile_invalidations to mitigate the undesirable consequences ofinvalidations. These different tools are demonstrated below.

Tutorial: forcing precompilation with workloads

No matter whether you're a package developer or a user looking to make your own workloads start faster, the basic workflow ofPrecompileTools is the same. Here's an illustration of how you might use@compile_workload and@setup_workload:

module MyPackageusing PrecompileTools: @setup_workload, @compile_workload    # this is a small dependencystruct MyType    x::Intendstruct OtherType    str::Stringend@setup_workload begin    # Putting some things in `@setup_workload` instead of `@compile_workload` can reduce the size of the    # precompile file and potentially make loading faster.    list = [OtherType("hello"), OtherType("world!")]    @compile_workload begin        # all calls in this block will be precompiled, regardless of whether        # they belong to your package or not (on Julia 1.8 and higher)        d = Dict(MyType(1) => list)        x = get(d, MyType(2), nothing)        last(d[MyType(1)])    endendend

When you buildMyPackage, it will precompile the following,including all their callees:

• Pair(::MyPackage.MyType, ::Vector{MyPackage.OtherType})
• Dict(::Pair{MyPackage.MyType, Vector{MyPackage.OtherType}})
• get(::Dict{MyPackage.MyType, Vector{MyPackage.OtherType}}, ::MyPackage.MyType, ::Nothing)
• getindex(::Dict{MyPackage.MyType, Vector{MyPackage.OtherType}}, ::MyPackage.MyType)
• last(::Vector{MyPackage.OtherType})

In this case, the "top level" calls were fully inferrable, so there are no entries on this list that were called by runtime dispatch. Thus, here you could have gotten the same result with manualprecompile directives. The key advantage of@compile_workload is that it works even if the functions you're calling have runtime dispatch.

Once you set up a block usingPrecompileTools, try your package and see if it reduces the time to first execution, using the same workload you put inside the@compile_workload block.

If you're happy with the results, you're done! If you want deeper verification of whether it worked as expected, or if you suspect problems, theSnoopCompile package provides diagnostic tools. Potential sources of trouble include invalidation (diagnosed withSnoopCompileCore.@snoop_invalidations and related tools) and omission of intended calls from inside the@compile_workload block (diagnosed withSnoopCompileCore.@snoop_inference and related tools).

Tutorial: local "Startup" packages

Users who want to precompile workloads that have not been precompiled by the packages they use can follow the recipe above, creating custom "Startup" packages for each project. Imagine that you have three different kinds of analyses you do: you could have a folder

MyData/  Project1/  Project2/  Project3/

From each one of thoseProject folders you could do the following:

(@v1.9) pkg> activate .  Activating new project at `/tmp/Project1`(Project1) pkg> generate Startup  Generating  project Startup:    Startup/Project.toml    Startup/src/Startup.jl(Project1) pkg> dev ./Startup   Resolving package versions...    Updating `/tmp/Project1/Project.toml`  [e9c42744] + Startup v0.1.0 `Startup`    Updating `/tmp/Project1/Manifest.toml`  [e9c42744] + Startup v0.1.0 `Startup`(Project1) pkg> activate Startup/  Activating project at `/tmp/Project1/Startup`(Startup) pkg> add PrecompileTools LotsOfPackages...

In the last step, you addPrecompileTools and all the package you'll need for your work onProject1 as dependencies ofStartup. Then edit theStartup/src/Startup.jl file to look similar to the tutorial previous section, e.g.,

module Startupusing LotsOfPackages...using PrecompileTools@compile_workload begin    # inside here, put a "toy example" of everything you want to be fastendend

Then when you're ready to start work, from theProject1 environment just sayusing Startup. All the packages will be loaded, together with their precompiled code.

Tutorial: "healing" invalidations

Julia sometimesinvalidates previously compiled code (seeWhy does Julia invalidate code?). PrecompileTools provides a mechanism to recompile the invalidated code so that you get the full benefits of precompilation. This capability can be used in "Startup" packages (like the one described above), as well as by package developers.

The basic usage is simple: wrap expressions that might invalidate with@recompile_invalidations. Invalidation can be triggered by defining new methods of external functions, including during package loading. Using the "Startup" package above, you might wrap theusing statements:

module Startupusing PrecompileTools@recompile_invalidations begin    using LotsOfPackages...end# Maybe a @compile_workload here?end

Note that recompiling invalidations can be useful even if you don't add any additional workloads.

Alternatively, if you're a package developer worried about "collateral damage" you may cause by extending functions owned by Base or other package (i.e., those that requireimport or module-scoping when defining the method), you can wrap those method definitions:

module MyContainersusing AnotherPackageusing PrecompileToolsstruct Container    list::Vector{Any}end# This is a function created by this package, so it doesn't need to be wrappedmake_container() = Container([])@recompile_invalidations begin    # Only those methods extending Base or other packages need to go here    Base.push!(obj::Container, x) = ...    function AnotherPackage.foo(obj::Container)        ⋮    endendend

You can have more than one@recompile_invalidations block in a module. For example, you might use one to wrap yourusings, and a second to wrap your method extensions.

When you can't run a workload

There are cases where you might want to precompile code but cannot safelyexecute that code: for example, you may need to connect to a database, or perhaps this is a plotting package but you may be currently on a headless server lacking a display, etc. In that case, your best option is to fall back on Julia's ownprecompile function. However, as explained inHow PrecompileTools works, there are some differences betweenprecompile and@compile_workload; most likely, you may need multipleprecompile directives. Analysis withSnoopCompile may be required to obtain the results you want; in particular, combining@snoop_inference andparcel will allow you to generate a set ofprecompile directives that can beincluded in your module definition.

Be aware thatprecompile directives are more specific to the Julia version, CPU (integer width), and OS than running a workload.

Troubleshooting

Ensure your workload "works" (runs without error) when copy/pasted into the REPL. If it produces an error only when placed inside@precompile_workload, check whether your workload runs when wrapped in a

let    # workload goes hereend

block.

Package developers: reducing the cost of precompilation during development

If you're frequently modifying one or more packages, you may not want to spend the extra time precompiling the full set of workloads that you've chosen to make fast for your "shipped" releases. One canlocally reduce the cost of precompilation for selected packages using thePreferences.jl-based mechanism and the"precompile_workload" key: from within your development environment, use

using MyPackage, Preferencesset_preferences!(MyPackage, "precompile_workload" => false; force=true)

This will write the following to LocalPreferences.toml alongside your active environment Project.toml

[MyPackage]precompile_workload = false

After restarting julia, the@compile_workload and@setup_workload workloads will be disabled (locally) forMyPackage. You can also specify additional packages (e.g., dependencies ofMyPackage) if you're co-developing a suite of packages. Simply runset_preferences! for the additional packages, or edit LocalPreferences.toml directly.

Finally, it is possible to fully disable PrecompileTools.jl for all packages with

using PrecompileTools, Preferencesset_preferences!(PrecompileTools, "precompile_workloads" => false; force=true)

This can be helpful to reduce the system image size generated when using PackageCompiler.jl by only compiling calls made in a precompilation script.

Seeing what got precompiled

If you want to see the list of calls that will be precompiled, navigate to theMyPackage folder and use

julia> using PrecompileToolsjulia> PrecompileTools.verbose[] = true   # runs the block even if you're not precompiling, and print precompiled callsjulia> include("src/MyPackage.jl");

This will only show the direct- or runtime-dispatched method instances that got precompiled (omitting their inferrable callees). For a more comprehensive list of all items stored in the compile_workload file, seePkgCacheInspector.