Table of Content:
Introduction
The Elvish Package Manager (epm
) is a module bundled
with Elvish for managing third-party packages.
In Elvish terminology, a module is a
.elv
file that can be imported with the use
command, while a package 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.
Like the go
command, Elvish does not
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.
To install the package, one simply uses the following:
use epm
epm:install github.com/elves/sample-pkg
epm
knows out-of-the-box how to manage packages hosted
in GitHub, BitBucket and GitLab, and requires the git
command to be available. It can also copy files via git
or
rsync
from arbitrary locations (see Custom package domains for
details).
Once installed, modules in this package can be imported with
use github.com/elves/sample-pkg/...
. This package has a
module named sample-mod
containing a function
sample-fn
, and can be used like this:
~> use github.com/elves/sample-pkg/sample-mod
~> sample-mod:sample-fn
This is a sample function in a sample module in a sample package
The
epm
-managed directory
Elvish searches for modules in multiple directories,
and epm
only manages one of them:
On UNIX,
epm
manages$XDG_DATA_HOME/elvish/lib
, defaulting to~/.local/share/elvish/lib
if$XDG_DATA_HOME
is unset or empty;On Windows,
epm
manages%LocalAppData%\elvish\lib
.
This directory is called the epm
-managed directory, and
its path is available as $epm:managed-dir
.
Custom package domains
Package names in epm
have the following structure:
domain/path
. The domain
is usually the
hostname from where the package is to be fetched, such as
github.com
. The path
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
is identified as github.com/elves/sample-pkg
.
Packages are stored under the epm
-managed directory in a
path identical to their name. For example, the package mentioned above
is stored at
$epm:managed-dir/github.com/elves/sample-pkg
.
Each domain must be configured with the following information:
The method to use to fetch packages from the domain. The two supported methods are
git
andrsync
.The number of directory levels under the domain directory in which the packages are found. For example, for
github.com
the number of levels is 2, since package paths have two levels (e.g.elves/sample-pkg
). All packages from a given domain have the same number of levels.Depending on the method, other attributes are needed:
git
needs aprotocol
attribute, which can behttps
orhttp
, and determines how the URL is constructed.rsync
needs alocation
attribute, which must be a valid source directory recognized by thersync
command.
epm
includes default domain configurations for
github.com
, gitlab.com
and
bitbucket.org
. These three domains share the same
configuration:
{
"method": "git",
"protocol": "https",
"levels": "2"
}
You can define your own domain by creating a file named
epm-domain.cfg
in the appropriate directory under
$epm:managed-dir
. For example, if you want to define an
elvish-dev
domain which installs packages from your local
~/dev/elvish/
directory, you must create the file
$epm:managed-dir/elvish-dev/epm-domain.cfg
with the
following JSON content:
{
"method": "rsync",
"location": "~/dev/elvish",
"levels": "1"
}
You can then install any directory under ~/dev/elvish/
as a package. For example, if you have a directory
~/dev/elvish/utilities/
, the following command will install
it under $epm:managed-dir/elvish-dev/utilities
:
epm:install elvish-dev/utilities
When you make any changes to your source directory,
epm:upgrade
will synchronize those changes to
$epm:managed-dir
.
Variables
$epm:managed-dir
The path of the epm
-managed directory.
Functions
epm:install
epm:install &silent-if-installed=$false $pkg...
Install the named packages. By default, if a package is already
installed, a message will be shown. This can be disabled by passing
&silent-if-installed=$true
, so that already-installed
packages are silently ignored.
epm:installed
epm:installed
Return an array with all installed packages. epm:list
can be used as an alias for epm:installed
.
epm:is-installed
epm:is-installed $pkg
Returns a boolean value indicating whether the given package is installed.
epm:metadata
epm:metadata $pkg
Returns a hash containing the metadata for the given package. Metadata for a package includes the following base attributes:
name
: name of the packageinstalled
: a boolean indicating whether the package is currently installedmethod
: method by which it was installed (git
orrsync
)src
: source URL of the packagedst
: where the package is (or would be) installed. Note that this attribute is returned even ifinstalled
is$false
.
Additionally, packages can define arbitrary metadata attributes in a
file called metadata.json
in their top directory. The
following attributes are recommended:
description
: a human-readable description of the packagemaintainers
: an array containing the package maintainers, inName <email>
format.homepage
: URL of the homepage for the package, if it has one.dependencies
: an array listing dependencies of the current package. Any packages listed will be installed automatically byepm:install
if they are not yet installed.
epm:query
epm:query $pkg
Pretty print the available metadata of the given package.
epm:uninstall
epm:uninstall $pkg...
Uninstall named packages.
epm:upgrade
epm:upgrade $pkg...
Upgrade named packages. If no package name is given, upgrade all installed packages.