Reference

BotConfig(package_name::AbstractString ; exclusions, os, else_os, version, else_version, package_path, precompiles_rootpath, subst, tmin)

Construct a SnoopCompile bot configuration. package_name is the name of the package. This object is passed to snoop_bot and snoop_bench.

You may supply the following optional keyword arguments:

• exclusions : A vector of of Strings (or RegExp) to exclude some functions from being precompiled

• os: A vector of of Strings (or RegExp) to support with precompile statements.

Example: os = ["windows", "linux"]

• else_os: If you want to use a specific operating system's precompile file as the default, set else_os to the name of that os. Not passing this argument skips precompilation on any operating system other than those explicitly listed in os.

Example: else_os = "linux"

• version: A vector of of Julia versions used to generate precompile signatures.

Example: version = [v"1.1",v"1.5.0", "nightly"]

It is assumed that the generated precompile signatures are valid for patch versions of Julia (e.g. givingv"1.5.0" supports v"1.4.0" to v"1.4.999").

• else_version: the Julia version used to generate the default signatures for other versions.

Not passing this argument skips precompilation on any Julia version other than those explicitly listed in version.

Example: else_version =v"1.5.0"

• yml_path: instead of directly passing os and version to BotConfig, you can pass yml_path which should be the GitHub actions YAML path or file name.

It assumes that the job name is SnoopCompile.

Example: yaml_path = "SnoopCompile.yml"

• package_path: path to the main .jl file of the package (similar to pathof). Default path is pathof_noload(package_name).

• precompiles_rootpath: the path where precompile files are stored. Default path is "dirname(dirname(package_path))/deps/SnoopCompile/precompile".

• subst : A vector of pairs of Strings (or RegExp) to replace a packages precompile statements with another's package like ["ImageTest" => "Images"].

• tmin: Methods that take less time than tmin to be inferred will not be added to the precompile statements. Defaults to 0.01. Set it to 0.0 if you want to include all the sentences.

• check_eval: By default, the bot discards the precompile statements that cannot be evaled.

In rare cases (when snooping is very time consuming), you may want to do this manually by using the printed errors to add the problematic functions to exclusions and then set check_eval=false for the future runs.

Example

botconfig1 = BotConfig(
  "Zygote";                            # package name (the one this configuration lives in)
  os = ["linux", "windows", "macos"],  # operating systems for which to precompile
  version = [v"1.5.0", v"1.3.1"],      # supported Julia versions
  exclusions = ["SqEuclidean"],         # exclude functions (by name) that would be problematic if precompiled
)

botconfig2 = BotConfig(
  "Zygote";                            # package name (the one this configuration lives in)
  yml_path = "SnoopCompile.yml"        # parse `os` and `version` from `SnoopCompile.yml`
  exclusions = ["SqEuclidean"],         # exclude functions (by name) that would be problematic if precompiled
)

# A full example:
BotConfig("MatLang", exclusions = ["badfunction"], os = ["linux", "windows", "macos"], else_os = "linux", version = ["1.5.0", "1.2", "1.0.5"], else_version = "1.5.0" )

# Different examples for other possibilities:
BotConfig("MatLang")

BotConfig("MatLang", exclusions = ["badfunction"])

BotConfig("MatLang", os = ["linux", "windows"])

BotConfig("MatLang", os = ["windows", "linux"], else_os = "linux")

BotConfig("MatLang", version = [v"1.1",v"1.5.0"])

BotConfig("MatLang", version = [v"1.1",v"1.5.0"], else_version =v"1.5.0")

BotConfig("MatLang", os = ["linux", "windows"], version = [v"1.1",v"1.5.0"])

snoop_bot(config::BotConfig, path_to_example_script::String, test_modul=Main; snoop_mode=:auto)

Generate precompile statements using a precompile script. config can be generated by BotConfig. path_to_example_script is preferred to be an absolute path. The example script will be run in the module specified by test_modul. snoop_mode can be :auto, :snoopi (to run SnoopCompileCore.@snoopi), or :snoopc (to run SnoopCompileCore.@snoopc), where :auto chooses :snoopi on supported versions of Julia.

See the online documentation for a more complete overview.

Extended help

Example

In this case, the bot-running script is placed in the same directory as the precompile script, so we can use @__DIR__ to find it:

using CompileBot

snoop_bot(BotConfig("MatLang"), "$(@__DIR__)/example_script.jl")

snoop_bot(config::BotConfig, test_modul::Module = Main; snoop_mode::Symbol = :auto)

Generate precompile statements using the package's runtests.jl file.

During snooping, snoop_bot sets the global variable SnoopCompile_ENV to true. If needed, your runtests.jl can check for the existence and value of this variable to customize test behavior specifically for snooping.

snoop_bot(config::BotConfig, expression::Expr, test_modul::Module = Main; snoop_mode::Symbol = :auto)

Generate precompile statements by evaluating an expression, for example :(using MyPackage). Interpolation and macros are not supported.

snoop_bench(config::BotConfig, path_to_example_script::String, test_modul::Module=Main; snoop_mode=:auto)

Benchmark the impact of precompile statements, by running a script with and without the precompiles. config can be generated by BotConfig. path_to_example_script is preferred to be an absolute path. The example script will be run in the module specified by test_modul. snoop_mode can be :auto, :snoopi (to test with SnoopCompileCore.@snoopi), or :runtime (to measure total script run time with @timev). :auto chooses :snoopi on supported versions of Julia.

See the online documentation for a more complete overview.

Extended help

Example

In this case, the benchmarking script is placed in the same directory as the precompile script, so we can use @__DIR__ to find it:

using CompileBot

snoop_bench(BotConfig("MatLang"), "$(@__DIR__)/example_script.jl")

As an alternative to @__DIR__ (for example, if you store your benchmarking script(s) outside the package itself), you can find the package with pathof_noload.

snoop_bench(config::BotConfig, test_modul::Module = Main; snoop_mode::Symbol = :auto)

Benchmark your precompile files using the package's runtests.jl file.

During snooping, snoop_bench sets the global variable SnoopCompile_ENV to true. If needed, your runtests.jl can check for the existence and value of this variable to customize test behavior specifically for snooping. ```

snoop_bench(config::BotConfig, expression::Expr, test_modul::Module = Main; snoop_mode::Symbol = :auto)

Benchmark your precompile files by evaluating an expression, for example :(using MyPackage). Interpolation and macros are not supported.

Returns a package's path without loading the package in the main Julia process. May launch a separate Julia process to find the package.

Examples

pathof_noload("MatLang")

timesum(snoop::Vector{Tuple{Float64, Core.MethodInstance}}, unit = :s)

Calculates the total time measured by a snoop macro. unit can be :s or :ms.

Examples

using SnoopCompile
data = @snoopi begin
    using MatLang
    MatLang_rootpath = dirname(dirname(pathof("MatLang")))

    include("$MatLang_rootpath/test/runtests.jl")
end
println(timesum(data, :ms))