.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "elvish-epm" "7" "Dec 07, 2021" "Elvish 0.17.0~rc4" "Miscellaneous Information Manual"
.hy
.PP
.SH Introduction
.PP
The Elvish Package Manager (\f[C]epm\f[R]) is a module bundled with
Elvish for managing third-party packages.
.PP
In Elvish terminology, a \f[B]module\f[R] is a \f[C].elv\f[R] file that
can be imported with the \f[C]use\f[R] command, while a
\f[B]package\f[R] is a collection of modules that are usually kept in
the same repository as one coherent project and may have
interdependencies.
The Elvish language itself only deals with modules; the concept of
package is a matter of how to organize modules.
.PP
Like the \f[C]go\f[R] command, Elvish does \f[B]not\f[R] have a central
registry of packages.
A package is simply identified by the URL of its code repository, e.g.
github.com/elves/sample-pkg (https://github.com/elves/sample-pkg).
To install the package, one simply uses the following:
.IP
.nf
\f[C]
use epm
epm:install github.com/elves/sample-pkg
\f[R]
.fi
.PP
\f[C]epm\f[R] knows out-of-the-box how to manage packages hosted in
GitHub, BitBucket and GitLab, and requires the \f[C]git\f[R] command to
be available.
It can also copy files via \f[C]git\f[R] or \f[C]rsync\f[R] from
arbitrary locations (see Custom package domains for details).
.PP
Once installed, modules in this package can be imported with
\f[C]use github.com/elves/sample-pkg/...\f[R].
This package has a module named \f[C]sample-mod\f[R] containing a
function \f[C]sample-fn\f[R], and can be used like this:
.IP
.nf
\f[C]
\[ti]> use github.com/elves/sample-pkg/sample-mod
\[ti]> sample-mod:sample-fn
This is a sample function in a sample module in a sample package
\f[R]
.fi
.SH The \f[C]epm\f[R]-managed directory
.PP
Elvish searches for modules in multiple directories, and \f[C]epm\f[R]
only manages one of them:
.IP \[bu] 2
On UNIX, \f[C]epm\f[R] manages \f[C]$XDG_DATA_HOME/elvish/lib\f[R],
defaulting to \f[C]\[ti]/.local/share/elvish/lib\f[R] if
\f[C]$XDG_DATA_HOME\f[R] is unset or empty;
.IP \[bu] 2
On Windows, \f[C]epm\f[R] manages
\f[C]%LocalAppData%\[rs]elvish\[rs]lib\f[R].
.PP
This directory is called the \f[C]epm\f[R]-managed directory, and its
path is available as \f[C]$epm:managed-dir\f[R].
.SH Custom package domains
.PP
Package names in \f[C]epm\f[R] have the following structure:
\f[C]domain/path\f[R].
The \f[C]domain\f[R] is usually the hostname from where the package is
to be fetched, such as \f[C]github.com\f[R].
The \f[C]path\f[R] can have one or more components separated by slashes.
Usually, the full name of the package corresponds with the URL from
where it can be fetched.
For example, the package hosted at
https://github.com/elves/sample-pkg (https://github.com/elves/sample-pkg)
is identified as \f[C]github.com/elves/sample-pkg\f[R].
.PP
Packages are stored under the \f[C]epm\f[R]-managed directory in a path
identical to their name.
For example, the package mentioned above is stored at
\f[C]$epm:managed-dir/github.com/elves/sample-pkg\f[R].
.PP
Each domain must be configured with the following information:
.IP \[bu] 2
The method to use to fetch packages from the domain.
The two supported methods are \f[C]git\f[R] and \f[C]rsync\f[R].
.IP \[bu] 2
The number of directory levels under the domain directory in which the
packages are found.
For example, for \f[C]github.com\f[R] the number of levels is 2, since
package paths have two levels (e.g.
\f[C]elves/sample-pkg\f[R]).
All packages from a given domain have the same number of levels.
.IP \[bu] 2
Depending on the method, other attributes are needed:
.RS 2
.IP \[bu] 2
\f[C]git\f[R] needs a \f[C]protocol\f[R] attribute, which can be
\f[C]https\f[R] or \f[C]http\f[R], and determines how the URL is
constructed.
.IP \[bu] 2
\f[C]rsync\f[R] needs a \f[C]location\f[R] attribute, which must be a
valid source directory recognized by the \f[C]rsync\f[R] command.
.RE
.PP
\f[C]epm\f[R] includes default domain configurations for
\f[C]github.com\f[R], \f[C]gitlab.com\f[R] and \f[C]bitbucket.org\f[R].
These three domains share the same configuration:
.IP
.nf
\f[C]
{
    \[dq]method\[dq]: \[dq]git\[dq],
    \[dq]protocol\[dq]: \[dq]https\[dq],
    \[dq]levels\[dq]: \[dq]2\[dq]
}
\f[R]
.fi
.PP
You can define your own domain by creating a file named
\f[C]epm-domain.cfg\f[R] in the appropriate directory under
\f[C]$epm:managed-dir\f[R].
For example, if you want to define an \f[C]elvish-dev\f[R] domain which
installs packages from your local \f[C]\[ti]/dev/elvish/\f[R] directory,
you must create the file
\f[C]$epm:managed-dir/elvish-dev/epm-domain.cfg\f[R] with the following
JSON content:
.IP
.nf
\f[C]
{
    \[dq]method\[dq]: \[dq]rsync\[dq],
    \[dq]location\[dq]: \[dq]\[ti]/dev/elvish\[dq],
    \[dq]levels\[dq]: \[dq]1\[dq]
}
\f[R]
.fi
.PP
You can then install any directory under \f[C]\[ti]/dev/elvish/\f[R] as
a package.
For example, if you have a directory
\f[C]\[ti]/dev/elvish/utilities/\f[R], the following command will
install it under \f[C]$epm:managed-dir/elvish-dev/utilities\f[R]:
.IP
.nf
\f[C]
epm:install elvish-dev/utilities
\f[R]
.fi
.PP
When you make any changes to your source directory,
\f[C]epm:upgrade\f[R] will synchronize those changes to
\f[C]$epm:managed-dir\f[R].
.SH Variables
.PP
.SS $epm:managed-dir {#epm:managed-dir}
.PP
The path of the \f[C]epm\f[R]-managed directory.
.SH Functions
.PP
.SS epm:install {#epm:install}
.IP
.nf
\f[C]
epm:install &silent-if-installed=$false $pkg...
\f[R]
.fi
.PP
Install the named packages.
By default, if a package is already installed, a message will be shown.
This can be disabled by passing \f[C]&silent-if-installed=$true\f[R], so
that already-installed packages are silently ignored.
.PP
.SS epm:installed {#epm:installed}
.IP
.nf
\f[C]
epm:installed
\f[R]
.fi
.PP
Return an array with all installed packages.
\f[C]epm:list\f[R] can be used as an alias for \f[C]epm:installed\f[R].
.PP
.SS epm:is-installed {#epm:is-installed}
.IP
.nf
\f[C]
epm:is-installed $pkg
\f[R]
.fi
.PP
Returns a boolean value indicating whether the given package is
installed.
.PP
.SS epm:metadata {#epm:metadata}
.IP
.nf
\f[C]
epm:metadata $pkg
\f[R]
.fi
.PP
Returns a hash containing the metadata for the given package.
Metadata for a package includes the following base attributes:
.IP \[bu] 2
\f[C]name\f[R]: name of the package
.IP \[bu] 2
\f[C]installed\f[R]: a boolean indicating whether the package is
currently installed
.IP \[bu] 2
\f[C]method\f[R]: method by which it was installed (\f[C]git\f[R] or
\f[C]rsync\f[R])
.IP \[bu] 2
\f[C]src\f[R]: source URL of the package
.IP \[bu] 2
\f[C]dst\f[R]: where the package is (or would be) installed.
Note that this attribute is returned even if \f[C]installed\f[R] is
\f[C]$false\f[R].
.PP
Additionally, packages can define arbitrary metadata attributes in a
file called \f[C]metadata.json\f[R] in their top directory.
The following attributes are recommended:
.IP \[bu] 2
\f[C]description\f[R]: a human-readable description of the package
.IP \[bu] 2
\f[C]maintainers\f[R]: an array containing the package maintainers, in
\f[C]Name <email>\f[R] format.
.IP \[bu] 2
\f[C]homepage\f[R]: URL of the homepage for the package, if it has one.
.IP \[bu] 2
\f[C]dependencies\f[R]: an array listing dependencies of the current
package.
Any packages listed will be installed automatically by
\f[C]epm:install\f[R] if they are not yet installed.
.PP
.SS epm:query {#epm:query}
.IP
.nf
\f[C]
epm:query $pkg
\f[R]
.fi
.PP
Pretty print the available metadata of the given package.
.PP
.SS epm:uninstall {#epm:uninstall}
.IP
.nf
\f[C]
epm:uninstall $pkg...
\f[R]
.fi
.PP
Uninstall named packages.
.PP
.SS epm:upgrade {#epm:upgrade}
.IP
.nf
\f[C]
epm:upgrade $pkg...
\f[R]
.fi
.PP
Upgrade named packages.
If no package name is given, upgrade all installed packages.