# Package Manager Functions

All package manager functions are defined in the `Pkg` module. None of the `Pkg` module’s functions are exported; to use them, you’ll need to prefix each function call with an explicit `Pkg.`, e.g. `Pkg.status()` or `Pkg.dir()`.

Functions for package development (e.g. `tag`, `publish`, etc.) have been moved to the PkgDev package. See PkgDev README for the documentation of those functions.

`dir`() → AbstractString

  Returns the absolute path of the package directory. This defaults to `joinpath(homedir(),".julia","v$(VERSION.major).$(VERSION.minor)")` on all platforms (i.e. `~/.julia/v0.5` in UNIX shell syntax). If the `JULIA_PKGDIR` environment variable is set, then that path is used in the returned value as `joinpath(ENV["JULIA_PKGDIR"],"v$(VERSION.major).$(VERSION.minor)")`. If `JULIA_PKGDIR` is a relative path, it is interpreted relative to whatever the current working directory is.

`dir`(names...) → AbstractString

  Equivalent to `normpath(Pkg.dir(),names...)` – i.e. it appends path components to the package directory and normalizes the resulting path. In particular, `Pkg.dir(pkg)` returns the path to the package `pkg`.

`init`(meta::AbstractString=DEFAULT_META, branch::AbstractString=META_BRANCH)

  Initialize `Pkg.dir()` as a package directory. This will be done automatically when the `JULIA_PKGDIR` is not set and `Pkg.dir()` uses its default value. As part of this process, clones a local METADATA git repository from the site and branch specified by its arguments, which are typically not provided. Explicit (non-default) arguments can be used to support a custom METADATA setup.

`resolve`()

  Determines an optimal, consistent set of package versions to install or upgrade to. The optimal set of package versions is based on the contents of `Pkg.dir("REQUIRE")` and the state of installed packages in `Pkg.dir()`, Packages that are no longer required are moved into `Pkg.dir(".trash")`.

`edit`()

  Opens `Pkg.dir("REQUIRE")` in the editor specified by the `VISUAL` or `EDITOR` environment variables; when the editor command returns, it runs `Pkg.resolve()` to determine and install a new optimal set of installed package versions.

`add`(pkg, vers...)

  Add a requirement entry for `pkg` to `Pkg.dir("REQUIRE")` and call `Pkg.resolve()`. If `vers` are given, they must be `VersionNumber` objects and they specify acceptable version intervals for `pkg`.

`rm`(pkg)

  Remove all requirement entries for `pkg` from `Pkg.dir("REQUIRE")` and call `Pkg.resolve()`.

`clone`(url[, pkg])

  Clone a package directly from the git URL `url`. The package does not need to be registered in `Pkg.dir("METADATA")`. The package repo is cloned by the name `pkg` if provided; if not provided, `pkg` is determined automatically from `url`.

`clone`(pkg)

  If `pkg` has a URL registered in `Pkg.dir("METADATA")`, clone it from that URL on the default branch. The package does not need to have any registered versions.

`setprotocol!`(proto)

  Set the protocol used to access GitHub-hosted packages. Defaults to ‘https’, with a blank `proto` delegating the choice to the package developer.

`available`() → Vector{String}

  Returns the names of available packages.

`available`(pkg) → Vector{VersionNumber}

  Returns the version numbers available for package `pkg`.

`installed`() → Dict{String,VersionNumber}

  Returns a dictionary mapping installed package names to the installed version number of each package.

`installed`(pkg) → Void | VersionNumber

  If `pkg` is installed, return the installed version number, otherwise return `nothing`.

`status`()

  Prints out a summary of what packages are installed and what version and state they’re in.

`status`(pkg)

  Prints out a summary of what version and state `pkg`, specifically, is in.

`update`(pkgs...)

  Update the metadata repo – kept in `Pkg.dir("METADATA")` – then update any fixed packages that can safely be pulled from their origin; then call `Pkg.resolve()` to determine a new optimal set of packages versions.

  Without arguments, updates all installed packages. When one or more package names are provided as arguments, only those packages and their dependencies are updated.

`checkout`(pkg, [branch="master"]; merge=true, pull=true)

  Checkout the `Pkg.dir(pkg)` repo to the branch `branch`. Defaults to checking out the “master” branch. To go back to using the newest compatible released version, use `Pkg.free(pkg)`. Changes are merged (fast-forward only) if the keyword argument `merge == true`, and the latest version is pulled from the upstream repo if `pull == true`.

`pin`(pkg)

  Pin `pkg` at the current version. To go back to using the newest compatible released version, use `Pkg.free(pkg)`

`pin`(pkg, version)

  Pin `pkg` at registered version `version`.

`free`(pkg)

  Free the package `pkg` to be managed by the package manager again. It calls `Pkg.resolve()` to determine optimal package versions after. This is an inverse for both `Pkg.checkout` and `Pkg.pin`.

  You can also supply an iterable collection of package names, e.g., `Pkg.free(("Pkg1", "Pkg2"))` to free multiple packages at once.

`build`()

  Run the build scripts for all installed packages in depth-first recursive order.

`build`(pkgs...)

  Run the build script in `deps/build.jl` for each package in `pkgs` and all of their dependencies in depth-first recursive order. This is called automatically by `Pkg.resolve()` on all installed or updated packages.

`test`(; coverage=false)

  Run the tests for all installed packages ensuring that each package’s test dependencies are installed for the duration of the test. A package is tested by running its `test/runtests.jl` file and test dependencies are specified in `test/REQUIRE`. Coverage statistics for the packages may be generated by passing `coverage=true`. The default behavior is not to run coverage.

`test`(pkgs...; coverage=false)

  Run the tests for each package in `pkgs` ensuring that each package’s test dependencies are installed for the duration of the test. A package is tested by running its `test/runtests.jl` file and test dependencies are specified in `test/REQUIRE`. Coverage statistics for the packages may be generated by passing `coverage=true`. The default behavior is not to run coverage.

`dependents`(packagename)

  List the packages that have `packagename` as a dependency.