Cask API¶
This document provides a reference of the public Cask API, which you may use in your own projects and extensions to Cask.
Table of Contents
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
-
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.