PkgOptions.jl

PkgOptions: package configuration system for Julia

Features

• Project/environment-local per-package configuration options.
• Precompilation is triggered when package options are changed.
• Minimal dependency (PkgOptionsLoader) for a package to support package options.

Installation

pkg> add https://github.com/tkf/PkgOptionsLoader.jl.git

pkg> add https://github.com/tkf/PkgOptions.jl.git

pkg> add https://github.com/tkf/PkgOptionsDemo.jl.git  # a demo

Usage

End-users

Use PkgOptions.set(pkg; ...) to configure package options for package pkg:

julia> using PkgOptions

julia> PkgOptions.set(:PkgOptionsDemo, some_option=true)

julia> using PkgOptionsDemo
       PkgOptionsDemo.pkgoptions
[ Info: Precompiling PkgOptionsDemo [bb3b8621-5970-400b-8acd-051caadabee1]
Dict{String,Any} with 1 entry:
  "some_option" => true

Note that package options are precompile-time options. You need to reload package to re-configure it.

To use the default option, remove the package option by:

julia> PkgOptions.rm(:PkgOptionsDemo)

See more details in the documentation.

Package authors

To support package options, use PkgOptionsLoader.@load to load package options (a Dict{String,Any}). For example, PkgOptionsDemo.jl used above in the demo is defined as

module PkgOptionsDemo
using PkgOptionsLoader
const pkgoptions = PkgOptionsLoader.@load
end

See more details in the PkgOptionsLoader.@load documentation.

How it works

PkgOptions.set, PkgOptionsLoader.@load, etc. read and write the package options in a TOML file at

~/.julia/options/$project_slug/$package_slug/$package_name.toml

where

• $project_slug is a hash determined by the project path (Base.active_project()).
• $package_slug is a hash determined by the UUID of the package whose options are configured.
• $package_name is the name of the package whose options are configured.
• ~/.julia may be different if you configure Base.DEPOT_PATH[1]

Changing the TOML file triggers precompilation using Base.include_dependency mechanism.

PkgOptions.load(pkg::Symbol)

PkgOptions.rm(pkg::Symbol)

Remove package options (use the defaults) of package pkg.

PkgOptions.set(pkg::Symbol, options::Pair...)
PkgOptions.set(pkg::Symbol; options...)

Set and/or add options to package options for package pkg.

PkgOptions.set(pkg::Symbol, options::AbstractDict)

Set package options of package pkg to options, removing the ones not specified by options.

PkgOptionsLoader.@load

Load package options for current module at expansion time. It evaluates to a Dict. It is recommended to load it at the top level of your package module:

const pkgoptions = PkgOptionsLoader.@load

It also is a good idea to verify options and then assign it to a const:

get!(pkgoptions, "FEATURE_FLAG", false)  # default

if !(pkgoptions["FEATURE_FLAG"] isa Bool)
    error("some helpful error message")
end

const FEATURE_FLAG::Bool = pkgoptions["FEATURE_FLAG"]