Usage¶
This document explains how to use Cask, and provides a reference of its commands and options.
Quickstart¶
Start by creating a file named Cask
in the project root. Use
cask init command to create a Cask
-file automatically,
containing boilerplate code:
$ cask init [--dev]
Use cask init --dev
, if the project is for package development!
If you are using Cask for your Emacs configuration, add this to your
~/.emacs.d/init.el
file:
(require 'cask "~/.cask/cask.el")
(cask-initialize)
Or if you installed Cask via Homebrew:
(require 'cask "/usr/local/share/emacs/site-lisp/cask/cask.el")
(cask-initialize)
To install all dependencies, run:
$ cask install
This will create a directory called .cask
and install all dependencies into
it.
Finding Emacs¶
By default, packages are installed for the default Emacs, i.e. the one behind
the emacs
command. To pick a different Emacs, set the environment variable
EMACS
to the command name or executable path of the Emacs to use:
$ EMACS="emacs24.1" cask command
Note that installed dependencies are scoped on the version of Emacs. So when switching between versions you will have to install the dependencies for each:
$ EMACS="emacs24.5" cask install
Exceptionally, if you are launching cask inside Emacs 24 either
from an internal shell or M-x compile
, then Emacs uses EMACS
in a
way which conflicts with cask, in which case you can use the
environment variable CASK_EMACS
instead. With Emacs 25,
EMACS
can be used as normal.
Commands and options¶
The general syntax of the cask program is as follows:
cask [GLOBAL-OPTIONS] [COMMAND] [COMMAND-OPTIONS] [COMMAND-ARGUMENTS]
cask exec¶
cask [GLOBAL-OPTIONS] exec [COMMAND] [ARGUMENTS ...]
Execute the system command with the given arguments, with a
proper $PATH
(see cask path) and $EMACSLOADPATH
(see cask load-path).
cask emacs¶
cask [GLOBAL-OPTIONS] emacs [ARGUMENTS ...]
Execute emacs
with the given arguments, with the appropriate
environmment (see cask exec). The Emacs executable is that which cask
would normally run in (see Finding Emacs).
cask eval¶
cask [GLOBAL-OPTIONS] eval [FORM]
Evaluate FORM
as a lisp form with a proper $PATH
(see cask path)
and $EMACSLOADPATH (see cask load-path). The return value of the form
is not printed directly: FORM
must print to the standard out or error
stream.
cask info¶
cask [GLOBAL-OPTIONS] info
Show information about the project, such as name, description and version.
cask init¶
cask [GLOBAL-OPTIONS] init [--dev]
Create new Cask
-file in the current directory.
If the project is for package development, use the --dev
option:
-
--dev
¶
Add additional code to the
Cask
file, which is specific to Emacs Lisp packages.
cask install¶
cask [GLOBAL-OPTIONS] [install]
Install all dependencies of the project. This is the default command.
cask load-path¶
cask [GLOBAL-OPTIONS] load-path
Print the load path containing the dependencies of the current project, in
proper format for the EMACSLOADPATH
environment variable.
cask exec automatically runs its commands with the proper load-path.
cask pkg-file¶
cask [GLOBAL-OPTIONS] pkg-file
Write a package descriptor file to project-pkg.el
in the project root.
project
is the project name, as declared in the Cask
file. See
Multi-file Packages(elisp) for details.
cask package-directory¶
cask [GLOBAL-OPTIONS] package-directory
Print path to package directory, where all dependencies are installed.
Currently, this is .cask/emacs-version/elpa
), where emacs-version
is the value of the emacs-version
variable in Emacs.
cask path¶
cask [GLOBAL-OPTIONS] path
Print the PATH
environment variable of this project.
The PATH
of a project contains the binary directories of all
dependencies, prepended to the PATH
inherited from the current shell.
The binary directory of a package is the bin/
subdirectory of the package.
cask exec uses the PATH
returned by this command when running
programs.
cask build¶
cask [GLOBAL-OPTIONS] build
Byte compile all Emacs Lisp files in the package. The resulting byte code is
written to the original path, with the extension replaced by .elc
.
cask link¶
cask [GLOBAL-OPTIONS] link PACKAGE SOURCE
cask [GLOBAL-OPTIONS] link list
cask [GLOBAL-OPTIONS] link delete PACKAGE
Link between this package and a dependency on the local filesystem. A linked
dependency avoids the need to download a dependency from a remote archive. The
package linked to must either have a Cask
-file or a -pkg.el
-file.
cask link package source
links the given source directory
into the package directory of this project, under the given package name.
cask link list
lists all links, and cask link delete package
deletes the link for the given package.
cask package¶
cask [GLOBAL-OPTIONS] package [DISTDIR]
Build a package artefact, and put it into the given DISTDIR, defaulting
to dist/
.
For single-file packages, this command merely copies the corresponding file to
DISTDIR
, under the correct filename package-version.el
.
For multi-file packages, this command creates a TAR archive containing the
package, as package-version.tar
. The TAR archive contains an
appropriate package descriptor as generated by cask pkg-file.
If the files
of the package contain .texinfo
files and if
makeinfo is available, these are compiled to Info before inclusion in
the package, to allow for online reading of the manual in Emacs.
Global options¶
The following options are available on all Cask commands:
-
--proxy
<proxy>
¶ Set Emacs proxy for HTTP and HTTPS:
$ cask --proxy "localhost:8888" install
-
--http-proxy
<proxy>
¶ Set Emacs proxy for HTTP only.
-
--https-proxy
<proxy>
¶ Set Emacs proxy for HTTPS only.
-
--no-proxy
<pattern>
¶ Do not use a proxy for any URL matching pattern.
pattern is an Emacs regular expression.
-
--version
¶
Print Cask’s version.
-
--debug
¶
Enable debug information.
-
--path
<directory>
¶ Use
directory/Cask
instead of theCask
file in the current directory.
-
--verbose
¶
Show all output from
package.el
.
Environment variables¶
-
EMACSLOADPATH
¶ The load path for Emacs, see Library Search(elisp).
-
EMACS
¶ The command name or executable path of Emacs. Cask will use this Emacs in its commands, i.e. byte-compile files with this Emacs, install packages for this Emacs, and run commands from packages installed for this Emacs.
If empty, Cask tries to find a reasonable default. On OS X, Cask tries the following Emacsen, in this order:
~/Applications/Emacs.app
/Applications/Emacs.app
/usr/local/bin
emacs
On other Unix variants, e.g. Linux, Cask will simply use
emacs
.
-
CASK_EMACS
¶ As EMACS, but takes precedence over it. This is most useful for launching Cask inside Emacs which often resets EMACS to other values.