How PrecompileTools works
Julia itself has a function precompile, to which you can pass specific signatures to force precompilation. For example, precompile(foo, (ArgType1, ArgType2)) will precompile foo(::ArgType1, ::ArgType2) and all of its inferrable callees. Alternatively, you can just execute some code at "top level" within the module, and during precompilation any method or signature "owned" by your package will also be precompiled. Thus, base Julia itself has substantial facilities for precompiling code.
The workload macros
@compile_workload adds one key feature: the non-inferrable callees (i.e., those called via runtime dispatch) that get made inside the @compile_workload block will also be cached, regardless of module ownership. In essence, it's like you're adding an explicit precompile(noninferrable_callee, (OtherArgType1, ...)) for every runtime-dispatched call made inside @compile_workload.
These workload macros add other features as well:
- Statements that occur inside a
@compile_workloadblock are executed only if the package is being actively precompiled; it does not run when the package is loaded, nor if you're running Julia with--compiled-modules=no. - Compared to just running some workload at top-level,
@compile_workloadensures that your code will be compiled (it disables the interpreter inside the block) - PrecompileTools also defines
@setup_workload, which you can use to create data for use inside a@compile_workloadblock. Like@compile_workload, this code only runs when you are precompiling the package, but it does not necessarily result in the@setup_workloadcode being stored in the package precompile file.
@recompile_invalidations
@recompile_invalidations activates logging of invalidations before executing code in the block. It then parses the log to extract the "leaves" of the trees of invalidations, which generally represent the top-level calls (typically made by runtime dispatch). It then triggers their recompilation. Note that the recompiled code may return different results than the original (this possibility is why the code had to be invalidated in the first place).