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)
To install all dependencies, run:
$ cask install
This will create a directory called .cask and install all dependencies into it.
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
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 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 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.