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

There are, unfortunately, circumstances under which Emacs itself resets the EMACS variable in a way which conflicts with cask, in which case you can use the environment variable CASK_EMACS instead. Specifically, this problem effects: Emacs-24, for M-x compile, M-x shell or M-x term, for Emacs-25 and Emacs-26 only for M-x term.

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 environment (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 help

cask [GLOBAL-OPTIONS] help [COMMAND]

Show help about Cask, or a given COMMAND.

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 list

cask [GLOBAL-OPTIONS] list

List all run-time and development dependencies.

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 outdated

cask [GLOBAL-OPTIONS] outdated

Show all outdated dependencies.

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 update

cask [GLOBAL-OPTIONS] update

Update all dependencies installed in the project.

cask upgrade-cask

cask [GLOBAL-OPTIONS] upgrade-cask

Upgrade Cask and all its dependencies.

cask version

cask [GLOBAL-OPTIONS] version

Print version of the current package.

cask files

cask [GLOBAL-OPTIONS] files

Print the list of all package files.

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 clean-elc

cask [GLOBAL-OPTIONS] clean-elc

Remove byte compiled files generated by cask build.

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 the Cask 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 sometimes resets EMACS to other values.