Document "exported" preferences

[timholy]

This gives examples showing how to use "exported"
(I prefer "package-wide") preferences. It also reorganizes
the README around the major decision-points of
project- vs package-specific, and runtime vs compiletime.

[codecov]

Codecov Report

Merging #48 (508e951) into master (09402bc) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master      #48   +/-   ##
=======================================
  Coverage   85.93%   85.93%           
=======================================
  Files           2        2           
  Lines         128      128           
=======================================
  Hits          110      110           
  Misses         18       18           

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

[staticfloat]

This isn't exactly true; a preference can still be loaded from within a function and used at compile time if that function is invoked during precompilation time.

[timholy]

"and that function doesn't get executed at top-level"? But obviously it's not clear.

[staticfloat]

Hmm, yeah. I'm honestly not sure it matters much to draw a distinction between compile-time and non-compile-time preferences; perhaps we should just have a note that says "if you use a preference at compile time, you will have to restart Julia before the changes will be seen" and leave it at that?

[staticfloat]

Alternatively, perhaps we could instead have set_preferences() spit out a @warn() when it notices a compile-time preference has been changed?

[timholy]

I like that idea!

We still might need to discuss this issue somewhere, otherwise people might be mystified about why it sometimes requires a restart and why it sometimes doesn't. (Might feel like a bug when it doesn't warn.)

[staticfloat]

Do you think it would be better to figure out how to pass kwargs to a macro, so we can have @set_preferences!("foo" => "bar"; export=true), or something like that?

[timholy]

I think that would make sense. A related issue: currently you have to read the docstring for set_preferences! in order to understand the force comment in the docstring for @set_preferences!. What do you want to do about that?

[timholy]

Also, I don't understand active_project_only well enough myself to even try describing it in the README (I could read the code, but...)

[timholy]

Hmm, actually "package-wide" preferences don't work. Create a dummy package, WithPreferences, with these contents:

Project.toml:

name = "WithPreferences"
uuid = "dcf8c38c-589d-4550-bcab-b56e5c9171f3"
authors = ["Tim Holy <tim.holy@gmail.com>"]
version = "0.1.0"

[deps]
Preferences = "21216c6a-2e73-6563-6e65-726566657250"

[preferences.WithPreferences]
awesome_languages = ["Julia"]

src/WithPreferences.jl:

module WithPreferences

using Preferences

const awesome_languages = String[]

function loadprefs()
    prefs = @load_preference("awesome_languages")
    if prefs !== nothing
        append!(awesome_languages, prefs)
    end
end

end

Works if you're using the package's Project.toml as your environment:

tim@diva:/tmp/pkgdemo/dev/WithPreferences$ JULIA_DEPOT_PATH=/tmp/pkgdemo juliabin-1.8 --project -q
julia> using WithPreferences

julia> WithPreferences.loadprefs()
1-element Vector{String}:
 "Julia"

julia> WithPreferences.awesome_languages
1-element Vector{String}:
 "Julia"

Does not if you use your default environment:

tim@diva:/tmp/pkgdemo/dev/WithPreferences$ JULIA_DEPOT_PATH=/tmp/pkgdemo juliabin-1.8 -q
julia> using WithPreferences

julia> WithPreferences.loadprefs()

julia> WithPreferences.awesome_languages
String[]

I'm assuming it's supposed to work in the second case, but if not then I'd love to know your thoughts on whether it would be useful & worthwhile to support "package-wide" preferences and if so how to design it.

[timholy]

Also, with the current design, won't package-specific preferences need to be reconfigured each time you update to a new version? I see why that might be necessary, but it also seems likely to be frustrating for packages with complex configuration. Or even just "why is it back to using the xyz backend, I thought I just configured that!"