Cask API

This document provides a reference of the public Cask API, which you may use in your own projects and extensions to Cask.

Cask bundles

A bundle represents a specific Cask project. Essentially, a bundle is a loaded Cask file.

Creating bundles

The following functions create bundles.

Function cask-setup project-path

Setup cask for project at PROJECT-PATH.

This function return a `cask-bundle' object.

Function cask-initialize &optional project-path

Initialize packages under PROJECT-PATH or `user-emacs-directory'.

This function return a `cask-bundle' object.

Bundle paths

These functions return various paths associated with a bundle:

Function cask-file bundle

Return path to BUNDLE Cask-file.

Function cask-path bundle

Return BUNDLE root path.

Function cask-load-path bundle

Return Emacs `load-path' (including BUNDLE dependencies).

Function cask-exec-path bundle

Return Emacs `exec-path' (including BUNDLE dependencies).

Function cask-elpa-path bundle

Return full path to BUNDLE elpa directory.

Package metadata of bundles

These functions give access to the metadata of the package, represented by the bundle.

Function cask-package-name bundle

Return BUNDLE name.

If BUNDLE is not a package, the error `cask-not-a-package' is signaled.

Function cask-package-version bundle

Return BUNDLE version.

If BUNDLE is not a package, the error `cask-not-a-package' is signaled.

Function cask-package-description bundle

Return BUNDLE description.

If BUNDLE is not a package, the error `cask-not-a-package' is signaled.

Bundle contents

Function cask-files bundle

Return BUNDLE files list.

This is done by expanding the patterns in the BUNDLE path.  Files
in the list are relative to the path.

Bundle dependencies

Function cask-dependencies bundle &optional deep

Return BUNDLE's runtime and development dependencies.

If DEEP is true, return all dependencies, recursively.

Return value is a list of `cask-dependency' objects.

Function cask-runtime-dependencies bundle &optional deep

Return BUNDLE's runtime dependencies.

If DEEP is true, return all dependencies, recursively.

Return value is a list of `cask-dependency' objects.

Function cask-development-dependencies bundle &optional deep

Return BUNDLE's development dependencies.

If DEEP is true, return all dependencies, recursively.

Return value is a list of `cask-dependency' objects.

Function cask-installed-dependencies bundle &optional deep

Return list of BUNDLE's installed dependencies.

If DEEP is t, all dependencies recursively will be returned.

Function cask-add-dependency bundle name &rest args

Add dependency to BUNDLE.

NAME is the name of the dependency.

ARGS is a plist with these optional arguments:

 `:version' Depend on at least this version for this dependency.

 `:scope' Add dependency to a certain scope.  Allowed values are
 'development and 'runtime.

 `:files' Only include files matching this pattern.

 `:ref' Fetcher ref to checkout.

 `:branch' Fetcher branch to checkout.

ARGS can also include any of the items in `cask-fetchers'.  The
plist key is one of the items in the list and the value is the
url to the fetcher source.

Function cask-has-dependency bundle name

Return true if BUNDLE contain link with NAME, false otherwise.

Function cask-find-dependency bundle name

Find dependency in BUNDLE with NAME.

Function cask-dependency-path bundle name

Return path to BUNDLE dependency with NAME.

If no such dependency exist, return nil.

Dependency links

These functions deal with dependency links.

See also

cask link

Function cask-links bundle

Return a list of all links for BUNDLE.

The list is a list of alist's where the key is the name of the
link, as a string and the value is the absolute path to the link.

Function cask-link bundle name source

Add BUNDLE link with NAME to SOURCE.

NAME is the name of the package to link as a string.  SOURCE is
the path to the directory to link to.  SOURCE must have either a
NAME-pkg.el or Cask file for the linking to be possible.

Function cask-link-delete bundle name

Delete BUNDLE link with NAME.

Function cask-linked-p bundle name

Return true if BUNDLE has link with NAME.

Dependency sources and package archives

These functions let you add and remove dependency sources, i.e., package archives where to get dependencies from.

Function cask-add-source bundle name-or-alias &optional url

Add source to BUNDLE.

NAME-OR-ALIAS is either a string with the name of the source or a
symbol, which refers to some of the keys in
`cask-source-mapping'.

Second argument URL is only required unless alias.  If no alias,
URL is the url to the mirror.

Function cask-remove-source bundle name

Remove source from BUNDLE with NAME.

Dependency operations

These functions provide operations on dependencies, such as updating, or installing them:

Function cask-install bundle

Install BUNDLE dependencies.

Install all available dependencies.

If some dependencies are not available, signal a
`cask-missing-dependencies' error, whose data is a list of all
missing dependencies.  All available dependencies are installed
nonetheless.

If a dependency failed to install, signal a
`cask-failed-installation' error, whose data is a (DEPENDENCY
. ERR), where DEPENDENCY is the `cask-dependency' which failed
to install, and ERR is the original error data.

Function cask-update bundle

Update BUNDLE dependencies.

Return list of updated packages.

Function cask-outdated bundle

Return list of `epl-upgrade' objects for outdated BUNDLE dependencies.

Byte compilation

These function let you byte compile all Emacs Lisp files in a bundle:

Function cask-build bundle

Build BUNDLE Elisp files.

Function cask-clean-elc bundle

Remove BUNDLE Elisp byte compiled files.

Packaging

These functions create packages and package descriptors:

Function cask-define-package-string bundle

Return `define-package' string for BUNDLE.

Function cask-define-package-file bundle

Return path to `define-package' file for BUNDLE.

Function cask-package bundle &optional target-dir

Build an ELPA package of BUNDLE.

Put package in TARGET-DIR if specified.  If not specified, put in
a directory specified by `cask-dist-path' in the BUNDLE path.

Miscellaneous functions

Function cask-caskify bundle &optional dev-mode

Create Cask-file for BUNDLE path.

If DEV-MODE is true, the dev template is used, otherwise the
configuration template is used.

Function cask-version

Return Cask's version.