"Fossies" - the Fresh Open Source Software Archive

Member "julia-1.1.1/share/julia/stdlib/v1.1/Pkg/src/Pkg.jl" (16 May 2019, 13594 Bytes) of package /linux/misc/julia-1.1.1-linux-i686.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) Julia source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 # This file is a part of Julia. License is MIT: https://julialang.org/license
    2 
    3 module Pkg
    4 
    5 import Random
    6 import REPL
    7 
    8 export @pkg_str
    9 export PackageSpec
   10 export PackageMode, PKGMODE_MANIFEST, PKGMODE_PROJECT
   11 export UpgradeLevel, UPLEVEL_MAJOR, UPLEVEL_MAJOR, UPLEVEL_MINOR, UPLEVEL_PATCH
   12 export Registry, RegistrySpec
   13 
   14 depots() = Base.DEPOT_PATH
   15 function depots1()
   16     d = depots()
   17     isempty(d) && Pkg.Types.pkgerror("no depots found in DEPOT_PATH")
   18     return d[1]
   19 end
   20 
   21 logdir() = joinpath(depots1(), "logs")
   22 devdir() = get(ENV, "JULIA_PKG_DEVDIR", joinpath(depots1(), "dev"))
   23 envdir(depot = depots1()) = joinpath(depot, "environments")
   24 const UPDATED_REGISTRY_THIS_SESSION = Ref(false)
   25 
   26 # load snapshotted dependencies
   27 include("../ext/TOML/src/TOML.jl")
   28 
   29 include("GitTools.jl")
   30 include("PlatformEngines.jl")
   31 include("Types.jl")
   32 include("Compress.jl")
   33 include("Display.jl")
   34 include("Pkg2/Pkg2.jl")
   35 include("GraphType.jl")
   36 include("Resolve.jl")
   37 include("Operations.jl")
   38 include("API.jl")
   39 include("Registry.jl")
   40 include("REPLMode.jl")
   41 
   42 import .REPLMode: @pkg_str
   43 import .Types: UPLEVEL_MAJOR, UPLEVEL_MINOR, UPLEVEL_PATCH, UPLEVEL_FIXED
   44 import .Types: PKGMODE_MANIFEST, PKGMODE_PROJECT
   45 # legacy CI script support
   46 import .API: clone, dir
   47 
   48 
   49 """
   50     PackageMode
   51 
   52 An enum with the instances
   53 
   54   * `PKGMODE_MANIFEST`
   55   * `PKGMODE_PROJECT`
   56 
   57 Determines if operations should be made on a project or manifest level.
   58 Used as an argument to  [`PackageSpec`](@ref) or as an argument to [`Pkg.rm`](@ref).
   59 """
   60 const PackageMode = Types.PackageMode
   61 
   62 
   63 """
   64     UpgradeLevel
   65 
   66 An enum with the instances
   67 
   68   * `UPLEVEL_FIXED`
   69   * `UPLEVEL_PATCH`
   70   * `UPLEVEL_MINOR`
   71   * `UPLEVEL_MAJOR`
   72 
   73 Determines how much a package is allowed to be updated.
   74 Used as an argument to  [`PackageSpec`](@ref) or as an argument to [`Pkg.update`](@ref).
   75 """
   76 const UpgradeLevel = Types.UpgradeLevel
   77 
   78 # Define new variables so tab comleting Pkg. works.
   79 """
   80     Pkg.add(pkg::Union{String, Vector{String}})
   81     Pkg.add(pkg::Union{PackageSpec, Vector{PackageSpec}})
   82 
   83 Add a package to the current project. This package will be available using the
   84 `import` and `using` keywords in the Julia REPL and if the current project is
   85 a package, also inside that package.
   86 
   87 # Examples
   88 ```julia
   89 Pkg.add("Example") # Add a package from registry
   90 Pkg.add(PackageSpec(name="Example", version="0.3")) # Specify version
   91 Pkg.add(PackageSpec(url="https://github.com/JuliaLang/Example.jl", rev="master")) # From url to remote gitrepo
   92 Pkg.add(PackageSpec(url="/remote/mycompany/juliapackages/OurPackage"))` # From path to local gitrepo
   93 ```
   94 
   95 See also [`PackageSpec`](@ref).
   96 """
   97 const add = API.add
   98 
   99 """
  100     Pkg.rm(pkg::Union{String, Vector{String}})
  101     Pkg.rm(pkg::Union{PackageSpec, Vector{PackageSpec}})
  102 
  103 Remove a package from the current project. If the `mode` of `pkg` is
  104 `PKGMODE_MANIFEST` also remove it from the manifest including all
  105 recursive dependencies of `pkg`.
  106 
  107 See also [`PackageSpec`](@ref), [`PackageMode`](@ref).
  108 """
  109 const rm = API.rm
  110 
  111 """
  112     Pkg.update(; level::UpgradeLevel=UPLEVEL_MAJOR, mode::PackageMode = PKGMODE_PROJECT)
  113     Pkg.update(pkg::Union{String, Vector{String}})
  114     Pkg.update(pkg::Union{PackageSpec, Vector{PackageSpec}})
  115 
  116 Update a package `pkg`. If no posistional argument is given, update all packages in the manifest if `mode` is `PKGMODE_MANIFEST` and packages in both manifest and project if `mode` is `PKGMODE_PROJECT`.
  117 If no positional argument is given `level` can be used to control what how much packages are allowed to be upgraded (major, minor, patch, fixed).
  118 
  119 See also [`PackageSpec`](@ref), [`PackageMode`](@ref), [`UpgradeLevel`](@ref).
  120 """
  121 const update = API.up
  122 
  123 
  124 """
  125     Pkg.test(; coverage::Bool=false)
  126     Pkg.test(pkg::Union{String, Vector{String}; coverage::Bool=false)
  127     Pkg.test(pkgs::Union{PackageSpec, Vector{PackageSpec}}; coverage::Bool=false)
  128 
  129 Run the tests for package `pkg` or if no positional argument is given to `test`,
  130 the current project is tested (which thus needs to be a package).
  131 A package is tested by running its `test/runtests.jl` file.
  132 
  133 The tests are run by generating a temporary environment with only `pkg` and its (recursive) dependencies
  134 (recursively) in it. If a manifest exist, the versions in that manifest is used, otherwise
  135 a feasible set of package are resolved and installed.
  136 
  137 During the test, test-specific dependencies are active, which are
  138 given in the project file as e.g.
  139 
  140 ```
  141 [extras]
  142 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
  143 
  144 [targets]
  145 test = ["Test"]
  146 ```
  147 
  148 Coverage statistics for the packages may be generated by
  149 passing `coverage=true`. The default behavior is not to run coverage.
  150 
  151 The tests are executed in a new process with `check-bounds=yes` and by default `startup-file=no`.
  152 If using the startup file (`~/.julia/config/startup.jl`) is desired, start julia with `--startup-file=yes`.
  153 Inlining of functions during testing can be disabled (for better coverage accuracy)
  154 by starting julia with `--inline=no`.
  155 """
  156 const test = API.test
  157 
  158 """
  159     Pkg.gc()
  160 
  161 Garbage collect packages that are no longer reachable from any project.
  162 Only packages that are tracked by version are deleted, so no packages
  163 that might contain local changes are touched.
  164 """
  165 const gc = API.gc
  166 
  167 
  168 """
  169     Pkg.build(; verbose = false)
  170     Pkg.build(pkg::Union{String, Vector{String}}; verbose = false)
  171     Pkg.build(pkgs::Union{PackageSpec, Vector{PackageSpec}}; verbose = false)
  172 
  173 Run the build script in `deps/build.jl` for `pkg` and all of the dependencies in
  174 depth-first recursive order.
  175 If no argument is given to `build`, the current project is built, which thus needs
  176 to be a package.
  177 This function is called automatically one any package that gets installed
  178 for the first time.
  179 `verbose = true` prints the build output to `stdout`/`stderr` instead of
  180 redirecting to the `build.log` file.
  181 """
  182 const build = API.build
  183 
  184 # TODO: decide what to do with this
  185 const installed = API.installed
  186 
  187 """
  188     Pkg.pin(pkg::Union{String, Vector{String}})
  189     Pkg.pin(pkgs::Union{Packagespec, Vector{Packagespec}})
  190 
  191 Pin a package to the current version (or the one given in the `packagespec` or a certain
  192 git revision. A pinned package is never updated.
  193 """
  194 const pin = API.pin
  195 
  196 """
  197     Pkg.free(pkg::Union{String, Vector{String}})
  198     Pkg.free(pkgs::Union{Packagespec, Vector{Packagespec}})
  199 
  200 Free a package which removes a `pin` if it exists, or if the package is tracking a path,
  201 e.g. after [`Pkg.develop`](@ref), go back to tracking registered versions.
  202 
  203 # Examples
  204 ```julia
  205 Pkg.free("Package")
  206 Pkg.free(PackageSpec("Package"))
  207 ```
  208 """
  209 const free = API.free
  210 
  211 
  212 """
  213     Pkg.develop(pkg::Union{String, Vector{String}})
  214     Pkg.develop(pkgs::Union{Packagespec, Vector{Packagespec}})
  215 
  216 Make a package available for development by tracking it by path.
  217 If `pkg` is given with only a name or by a URL the packages will be downloaded
  218 to the location by the environment variable `JULIA_PKG_DEVDIR` with
  219 `.julia/dev` as the default.
  220 
  221 If `pkg` is given as a local path, the package at that path will be tracked.
  222 
  223 # Examples
  224 ```julia
  225 # By name
  226 Pkg.develop("Example")
  227 
  228 # By url
  229 Pkg.develop(PackageSpec(url="https://github.com/JuliaLang/Compat.jl"))
  230 
  231 # By path
  232 Pkg.develop(PackageSpec(path="MyJuliaPackages/Package.jl"))
  233 ```
  234 
  235 See also [`PackageSpec`](@ref)
  236 
  237 """
  238 const develop = API.develop
  239 
  240 #TODO: Will probably be deprecated for something in PkgDev
  241 const generate = API.generate
  242 
  243 """
  244     Pkg.instantiate()
  245 
  246 If a `Manifest.toml` file exist in the current project, download all
  247 the packages declared in that manifest.
  248 Else, resolve a set of feasible packages from the `Project.toml` files
  249 and install them.
  250 """
  251 const instantiate = API.instantiate
  252 
  253 """
  254     Pkg.resolve()
  255 
  256 Update the current manifest with eventual changes to the dependency graph
  257 from packages that are tracking a path.
  258 """
  259 const resolve = API.resolve
  260 
  261 """
  262     Pkg.status([pkgs...]; mode::PackageMode=PKGMODE_PROJECT)
  263 
  264 Print out the status of the project/manifest.
  265 If `mode` is `PKGMODE_PROJECT` prints out status about only those packages
  266 that are in the project (explicitly added). If `mode` is `PKGMODE_MANIFEST`
  267 also print for those in the manifest (recursive dependencies). If there are
  268 any packages listed as arguments the output will be limited to those packages.
  269 
  270 !!! compat "Julia 1.1"
  271     `Pkg.status` with package arguments requires at least Julia 1.1.
  272 """
  273 const status = API.status
  274 
  275 
  276 """
  277     Pkg.activate([s::String]; shared::Bool=false)
  278 
  279 Activate the environment at `s`. The active environment is the environment
  280 that is modified by executing package commands.
  281 The logic for what path is activated is as follows:
  282 
  283   * If `shared` is `true`, the first existing environment named `s` from the depots
  284     in the depot stack will be activated. If no such environment exists,
  285     create and activate that environment in the first depot.
  286   * If `s` is an existing path, then activate the environment at that path.
  287   * If `s` is a package in the current project and `s` is tracking a path, then
  288     activate the environment at the tracked path.
  289   * Else, `s` is interpreted as a non-existing path, activate that path.
  290 
  291 If no argument is given to `activate`, then activate the home project.
  292 The home project is specified by either the `--project` command line option to
  293 the julia executable, or the `JULIA_PROJECT` environment variable.
  294 
  295 # Examples
  296 ```
  297 Pkg.activate()
  298 Pkg.activate("local/path")
  299 Pkg.activate("MyDependency")
  300 ```
  301 """
  302 const activate = API.activate
  303 
  304 
  305 """
  306     PackageSpec(name::String, [uuid::UUID, version::VersionNumber])
  307     PackageSpec(; name, url, path, rev, version, mode, level)
  308 
  309 A `PackageSpec` is a representation of a package with various metadata.
  310 This includes:
  311 
  312   * The `name` of the package.
  313   * The package unique `uuid`.
  314   * A `version` (for example when adding a package. When upgrading, can also be an instance of
  315    the enum [`UpgradeLevel`](@ref)
  316   * A `url` and an optional git `rev`ision. `rev` could be a branch name or a git commit SHA.
  317   * A local path `path`. This is equivalent to using the `url` argument but can be more descriptive.
  318   * A `mode`, which is an instance of the enum [`PackageMode`](@ref) which can be either `PKGMODE_PROJECT` or
  319    `PKGMODE_MANIFEST`, defaults to `PKGMODE_PROJECT`. Used in e.g. [`Pkg.rm`](@ref).
  320 
  321 Most functions in Pkg take a `Vector` of `PackageSpec` and do the operation on all the packages
  322 in the vector.
  323 
  324 Below is a comparison between the REPL version and the `PackageSpec` version:
  325 
  326 | `REPL`               | `API`                                                 |
  327 |:---------------------|:------------------------------------------------------|
  328 | `Package`            | `PackageSpec("Package")`                              |
  329 | `Package@0.2`        | `PackageSpec(name="Package", version="0.2")`          |
  330 | `Package=a67d...`    | `PackageSpec(name="Package", uuid="a67d...")`         |
  331 | `Package#master`     | `PackageSpec(name="Package", rev="master")`           |
  332 | `local/path#feature` | `PackageSpec(path="local/path"; rev="feature")`       |
  333 | `www.mypkg.com`      | `PackageSpec(url="www.mypkg.com")`                    |
  334 | `--manifest Package` | `PackageSpec(name="Package", mode=PKGSPEC_MANIFEST)`  |
  335 | `--major Package`    | `PackageSpec(name="Package", version=PKGLEVEL_MAJOR)` |
  336 """
  337 const PackageSpec = API.Package
  338 
  339 """
  340     Pkg.setprotocol!(proto::Union{Nothing, AbstractString}=nothing)
  341 
  342 Set the protocol used to access GitHub-hosted packages when `add`ing a url or `develop`ing a package.
  343 Defaults to delegating the choice to the package developer (`proto == nothing`).
  344 Other choices for `proto` are `"https"` or `"git"`.
  345 """
  346 const setprotocol! = API.setprotocol!
  347 
  348 """
  349     RegistrySpec(name::String)
  350     RegistrySpec(; name, url, path)
  351 
  352 A `RegistrySpec` is a representation of a registry with various metadata, much like
  353 [`PackageSpec`](@ref).
  354 
  355 Most registry functions in Pkg take a `Vector` of `RegistrySpec` and do the operation
  356 on all the registries in the vector.
  357 
  358 !!! compat "Julia 1.1"
  359     Pkg's registry handling requires at least Julia 1.1.
  360 
  361 # Examples
  362 
  363 Below is a comparison between the REPL version and the `RegistrySpec` version:
  364 
  365 | `REPL`               | `API`                                           |
  366 |:---------------------|:------------------------------------------------|
  367 | `Registry`           | `RegistrySpec("Registry")`                      |
  368 | `Registry=a67d...`   | `RegistrySpec(name="Registry", uuid="a67d...")` |
  369 | `local/path`         | `RegistrySpec(path="local/path")`               |
  370 | `www.myregistry.com` | `RegistrySpec(url="www.myregistry.com")`        |
  371 """
  372 const RegistrySpec = Types.RegistrySpec
  373 
  374 
  375 function __init__()
  376     if isdefined(Base, :active_repl)
  377         REPLMode.repl_init(Base.active_repl)
  378     else
  379         atreplinit() do repl
  380             if isinteractive() && repl isa REPL.LineEditREPL
  381                 isdefined(repl, :interface) || (repl.interface = REPL.setup_interface(repl))
  382                 REPLMode.repl_init(repl)
  383             end
  384         end
  385     end
  386 end
  387 
  388 METADATA_compatible_uuid(pkg::String) = Types.uuid5(Types.uuid_package, pkg)
  389 
  390 ##################
  391 # Precompilation #
  392 ##################
  393 
  394 const CTRL_C = '\x03'
  395 const precompile_script = """
  396     import Pkg
  397     tmp = mktempdir()
  398     cd(tmp)
  399     empty!(DEPOT_PATH)
  400     pushfirst!(DEPOT_PATH, tmp)
  401     # Prevent cloning registry
  402     mkdir("registries")
  403     touch("registries/blocker") # prevents default registry from cloning
  404     touch("Project.toml")
  405     ] activate .
  406     $CTRL_C
  407     Pkg.add("Test") # adding an stdlib doesn't require internet access
  408     ] add Te\t\t$CTRL_C
  409     ] st
  410     $CTRL_C
  411     rm(tmp; recursive=true)"""
  412 
  413 end # module