ShareAdd.jl

@showenv
@showenv item

Open (shared) environment folder in your desktop GUI. The utility of this macro is that it makes it easy to access these folders in your OS, which might otherwise require some jumping through hoops, as these are located in the hidden folder ~/.julia/

This macro is exported.

Examples

julia> @showenv # called without arguments, opens the "environments" folder which contains all shared environments
julia> @showenv Revise # open the environment folder(s) which contain the Revise package
julia> @showenv "Revise" # both quoted and unquoted forms of the argument are OK
julia> @showenv Math # opens the folder of the shared env @Math

@usingany pkg
@usingany pkg1, pkg2, ... 
@usingany pkg: fn
@usingany pkg: fn, @mcr, ... 
@usingany kwarg = true [pkg...]

Makes package(s) available, if they are not already, and loads them with using keyword.

• If a package is available in an environment in LOAD_PATH, that's OK.
• If a package is available in a shared environment, this environment will be pushed into LOAD_PATH.
• Otherwise if package(s) can be installed, you will be prompted to select an environment to install each package.
• If the package is not listed in any registry, an error will be thrown.

The macro can be called with keyword arguments:

• update_pkg::Bool: if set to true, first updates the package(s) to be imported by the macro
• update_env::Bool: first update the shared environments currently in the LOAD_PATH
• update_all::Bool: first update ALL shared environments as well as the current project

If Julia version supports versioned manifests, on any updates a versioned manifest will be created in each updated env. See also make_current_mnf and update.

If update_all or update_env kwarg is set, @usingany can be called without specifying any package(s) for import. If update_pkg kwarg is set, package(s) to import must be specified.

This macro is exported.

Examples

julia> @usingany Foo, Bar
julia> @usingany Baz: quux
julia> @usingany update_all = true
julia> @usingany update_pkg = true Qux

@usingtmp 
@usingtmp pkg
@usingtmp pkg1, pkg2, ... 
@usingtmp pkg: fn
@usingtmp pkg: fn, @mcr, ...

Activates a temporary environment, optionally installs packages into it and loads them with using keyword.

• If current environment is a temporary one, environment is not changed.
• If current env was a project (not package!), a temporary env will be activated.
• If current env was a package (under development), e.g. MyPkg, a temporary env will be activated, AND MyPkg will be dev-ed in that temporary env.

Afterwards, if @usingtmp was called with arguments, the corresponding packages will be installed into that temporary env, and imported with using keyword.

This macro is exported.

current_env(; depot = first(DEPOT_PATH)) -> EnvInfo

Returns information about the current active environment as an EnvInfo object.

This function is public, not exported.

delete(nms::Union{String, Vector{String}}; inall=ASKING, force = ASKING) -> nothing
delete(nm::AbstractString; inall=ASKING, force = ASKING) -> nothing
delete(p::Pair{<:AbstractString, <:AbstractString}; force = ASKING) -> nothing

Deletes shared envs, or packages therein.

If the provided argument is name(s) of shared environment(s), as specified by leading "@" in the names(s): then deletes the shared environment(s) by erasing their directories.

Otherwise, the provided name(s) are considered package names: then for each package pkg deletes it from it's shared environment(s). Afterwards deletes the environment if it left empty after package deletion.

You can also specify both the env and the package in the form "@Foo" => "bar"

Keyword arguments

Both kwargs accept any integer types, including Bool, as well as enum SkipAskForceEnum with integer values [-1=>SKIPPING, 0=>ASKING, 1=>FORCING]. If Bool is used, false is equivalent to ASKING, and true to FORCING

• inall=ASKING: If set to FORCING, would delete package from multiple environments, whereas with SKIPPING, it will skip without asking. Has no effect if provided nms is/are env name(s).
• force=ASKING: If set to FORCING, would delete the env even if the env is currently in LOAD_PATH, and remove a package even if it is loaded.

Examples

julia> ShareAdd.delete("@TrialPackages")
julia> ShareAdd.delete(["UnusedPkg", "UselessPkg"]; inall=true)
julia> ShareAdd.delete("@Foo" => "bar")

This function is public, not exported.

info(nms::Union{Nothing, String, Vector{String}} = nothing; 
    by_env=true, listing=nothing, std_lib=false, upgradable=false, disp_rslt=true, ret_rslt=false)

Prints out and/or returns information about shared environments.

Argument

• nms: Name(s) of package(s) or environment(s) to return the information on. Environment names must start with "@". Package and env names cannot be provided together in one array.

Keyword arguments

• by_env=true: whether to print out results as a Dict of pairs like @env => [pkg1, ...], or pkg => [@env1, ...]. Has no effect on returned (if any) results.
• listing=nothing: this kwarg can be nothing, :envs, or :pkgs. If one of these two Symbols is provided, the result is printed as a vector of envs or pkgs, resp. In this case by_env is ignored. Has no effect on returned (if any) results
• upgradable=false: if true, all other kwargs will be ignored, and only upgradable packages with installed vs. most recent versions will be printed, ordered by environment.
• disp_rslt=true: whether to print out results.
• ret_rslt=false: whether the function returns anything. If set to true, it returns a NamedTuple (; env_dict, pkg_dict, envs, pkgs, absent), where the two first elements are Dicts with keywords correspondingly by env or by pkg; envs and pkgs are vectors of respective elements, and absent are those names provided through the nms argument, which are not contained in the shared envs. Names of envs in the returned data are without leading "@".

This function is public, but not exported, as to avoid possible name conflicts.

Examples

julia> ShareAdd.info(["BenchmarkTools", "Chairmarks"])
The following packages are not in any shared env:
    ["Chairmarks"]

Found pkgs/envs:
  @BenchmarkTools
   => ["BenchmarkTools"]
  @Tools
   => ["BenchmarkTools"]

julia> ShareAdd.info(["DataFrames", "CSV"]; by_env=false)
  CSV
   => ["@DataFrames"]
  DataFrames
   => ["@DataFrames"]

julia> ShareAdd.info("StaticArrays"; upgradable=true)
  @StaticArrays
    StaticArrays: 1.9.8 --> 1.9.10   

make_current_mnf(path_or_name) -> path
make_current_mnf(; current::Bool) -> path
make_current_mnf(env::EnvInfo) -> path

Creates a versioned manifest

If called make_current_mnf(; current=true), the current environment will be processed by this function.

path_or_name can name of a shared environment starting with @, or a path to any environment.

• If currently executed Julia version doesn't support version-specific manifests, do nothing.
• Else, if a versioned manifest for current Julia already exists, do nothing.
• Else, if the environment is the main shared env for the current Julia version (e.g. "@v1.11" for Julia v1.11), do nothing.
• Else, is a (versioned) manifest for an older Julia exists in the given directory, copy it to a file named according to the current Julia version, e.g. Manifest-v1.11.toml.
• Else, create empty one.

Returns path to the created or existing manifest.

This function is public, not exported.

make_importable(pkg::AbstractString)
make_importable(pkgs::AbstractVector{<:AbstractString})
make_importable(pkg1, pkg2, ...)
make_importable(::Nothing) => :success

Checks packages (by name only, UUIDs not supported!), prompts to install packages which are not in any shared environment, and adds relevant shared environments to LOAD_PATH.

make_importable is used internally by @usingany, but it can be used separately e.g. if you e.g. want to import a package via import statement instead of using.

Returns :success if the operation was successful, and nothing if the user selected "Quit. Do Nothing." on any of the prompts.

Throws an error on unavailable packages.

Examples

julia> using ShareAdd
julia> make_importable("Foo")
:success
julia> import Foo 

julia> using ShareAdd
julia> make_importable("Foo")
:success
julia> using Foo: bazaar as baz  # @usingany Foo: bazaar as baz is not a supported syntax

This function is public, not exported.

reset()

Resets the LOAD_PATH to it's default value of ["@", "@v#.#", "@stdlib"], thus removing any manually added paths.

This function is public, not exported.

sh_add(env_name::AbstractString; depot = first(DEPOT_PATH)) -> Vector{String}
sh_add(env_names::AbstractVector{<:AbstractString}; depot = first(DEPOT_PATH)) -> Vector{String}
sh_add(env_name::AbstractString, ARGS...; depot = first(DEPOT_PATH)) -> Vector{String}

Adds shared environment(s) to LOAD_PATH, making the corresponding packages all available in the current session.

Returns the list of all packages in the added environments as a Vector{String}.

Examples

julia> using ShareAdd: sh_add
julia> sh_add("@StatPackages")
3-element Vector{String}:
 "Arrow"
 "CSV"
 "DataFrames"

julia> sh_add(["@StatPackages", "@Makie"])
4-element Vector{String}:
 "Arrow"
 "CSV"
 "DataFrames"
 "Makie"

julia> sh_add("@StatPackages", "@Makie")
4-element Vector{String}:
 "Arrow"
 "CSV"
 "DataFrames"
 "Makie"

This function is public, not exported.

update()
update(nm::AbstractString; warn_if_missing=false)
update(nm::Vector{<:AbstractString}; warn_if_missing=true)
update(env::AbstractString, pkgs::Union{AbstractString, Vector{<:AbstractString}}; warn_if_missing=true) 
update(env::EnvInfo, pkgs::Union{Nothing, S, Vector{S}} = Nothing; warn_if_missing=false) where S <: AbstractString
update(p::Pair{<:AbstractString, <:AbstractString}; warn_if_missing=false)

• Called without arguments, updates all shared environments.
• Called with a single argument nm::String starting with "@", updates the shared environment nm.
• Called with a single argument nm::String not starting with "@", updates the package nm in all shared environments containing the package, as well as all it's downstream dependencies.
• Called with a single argument nm::Vector{String}, updates the packages and/or environments in nm.
• Called with two arguments env and pkgs, updates the package(s) pkgs in the environment env.
• Called with an argument env => pkg, updates the package pkg in the environment env.

kwarg

• warn_if_missing::Bool=true - if env or pkg not found, issues a warning, otherwise would throw an error

If Julia version supports version-specific manifest, then on any updates a versioned manifest will be created in each updated env. See also make_current_mnf.

Returnes nothing.

Examples

julia> ShareAdd.update("@StatPackages")
julia> ShareAdd.update("@Foo" => "bar")

This function is public, not exported.

mutable struct EnvInfo
EnvInfo(name::AbstractString) -> EnvInfo

• name::String - name of the environment
• path::String - path of the environment's folder
• pkgs::Set{String} - list of packages in the environment
• in_path::Bool - whether the environment is in LOAD_PATH
• standard_env::Bool = false - if the env is the standard one (which is in the v1.11 folder for Julia v1.11)
• shared::Bool = true - if shared env
• temporary::Bool = false - if temporary env
• active_project::Bool = false - if active project

Examples

julia> ShareAdd.EnvInfo("@DocumenterTools")
ShareAdd.EnvInfo("DocumenterTools", "/Users/eben60/.julia/environments/DocumenterTools", Set(["DocumenterTools"]), false, false, true, false, false)

This type is public, not exported.

mutable struct PackageInfo

• name::String - name of the package
• envs::Vector{EnvInfo} - list of environments in which the package is present
• in_path::Bool - whether any of the environments is in LOAD_PATH

This type is public, not exported.

SkipAskForceEnum

Options for deletion of environments and packages.

• SKIPPING = -1
• ASKING = 0
• FORCING = 1

As ShareAdd is intended for interactive usage, and therefore the exported bindings are available in the Main module, we use the "-ing" form to reduce the probability of name collisions.

The values of this enum are exported, whereas the enum type is public but not exported.