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[bot]]

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           

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

[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 <[email protected]>"]
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!"