===============================
 Cask Domain Specific Language
===============================

.. role:: el(code)
   :language: cl

.. default-role:: el

.. default-domain:: el

This document provides a reference on the :abbr:`DSL (Domain Specific
Language)`.

Package metadata
================

.. function:: package name version description

   Declare a package with the given :var:`name`, :var:`version` and
   :var:`description`:

   .. code-block:: cl

      (package "ecukes" "0.2.1" "Cucumber for Emacs.")

   All arguments are strings.  The :var:`version` must be a version understood
   by Emacs' built-in :function:`version-to-list`.

.. function:: package-file file

   Declare a package by taking the package metadata from the given :var:`file`.
   Relative filenames are relative to the directory of the :file:`Cask` file.

   The package name will be the name of the given :var:`file`, sans directory
   and extension.  The description is taken from the very first line of
   :var:`file`.  The version and the runtime dependencies are taken from the
   library headers of :var:`file`.  See :infonode:`(elisp)Library Headers` for
   details about library headers

Package contents
================

.. function:: files &rest patterns

   The files to include in the package built by :ref:`cask package`.  The
   :var:`patterns` have the same format as the `:files` in an `MELPA recipe`_,
   as Cask uses the same library to build packages.

   Each :var:`pattern` in :var:`patterns` is either a simple glob pattern as
   string or an expression :varcode:`({target} {pattern}...)`.  In the former
   case, all files matching the pattern (relative to the directory of the
   :file:`Cask` file) are included at the *top-level* of the package.

   In the latter case, :var:`target` is the *unqualified* target directory
   within the package, each :var:`pattern` describes the contents of the package
   under the :var:`target` directory recursively.

   Hence, the pattern `("*.el" ("resources" ("snippets" "*.snippet")))` would
   include all `.el` files from the project root in the package root, and all
   `.snippet` files from the project root in the directory `resources/snippets`
   under the package root.

   .. _MELPA recipe: https://github.com/milkypostman/melpa#recipe-format

Dependencies
============

.. function:: depends-on package-name &optional minimum-version
              depends-on package-name :fetcher repourl &optional :ref hash :branch name :files patterns

   Specify a dependency of this package.

   :var:`package-name` is the name of a package which is a dependency of this
   package.

   In the first variant, install the package from a package archive (see
   :function:`source`), optionally requiring a :var:`minimum-version`.

   In the second variant, install the package from a VCS repository.
   Replace :var:`fetcher` with any of the following: ``:git``,
   ``:bzr``, ``:hg``, ``:darcs``, ``:svn`` or ``:cvs``.
   :var:`repourl` is the repository URL to install the package from.

   :var:`ref` and :var:`branch` specify the commit hash or branch name
   to install from.  If both are omitted, default to the ``master``
   branch.

   :var:`files` gives the files from the repository to include in the
   package, in the same format as :function:`files`.  If omitted, try to take
   the files from the :file:`Cask` file of the repository.

.. function:: development &rest body

   Scope all :function:`depends-on` expressions in :var:`body` to development.

   Development dependencies are installed with :ref:`cask install`, but are not
   included in package descriptors generated by :ref:`cask pkg-file` and
   :ref:`cask package`.

.. function:: source alias
              source name url

   Add a package archive to install dependencies from.

   In the first variant, add a built-in package archive.  In the second variant,
   add a package archive with the given :var:`name`, and the given :var:`url`.

   Cask includes the following built-in package archives:

   `gnu`
      The standard GNU ELPA archive at https://elpa.gnu.org/.

      .. warning::

         Unlike an interactive Emacs, Cask does **not** enable any archive by
         default.  Hence, you **must** explicitly add the `gnu` archive if you
         need it.

   `melpa-stable`
      An archive of stable versions built automatically from upstream
      repositories, at https://stable.melpa.org/.

   `melpa`
      An archive of VCS snapshots built automatically from upstream
      repositories, at https://melpa.org/.

   `marmalade`
      An archive of packages uploaded by users and maintainers, at
      https://marmalade-repo.org/.

   `SC`
      An archive providing packages for `Sunrise Commander`_, at
      http://joseito.republika.pl/sunrise-commander/.

      .. _Sunrise Commander: http://www.emacswiki.org/emacs/Sunrise_Commander

   `org`
      An archive providing packages for `Org Mode`_, at
      http://orgmode.org/elpa/.

      Note that unlike the `gnu` archive, which also provides an `org` package,
      this archive provides the `org-plus-contrib` package, which installs
      additional extensions for Org Mode maintained by the Org Mode maintainers,
      which are not included in the standard `gnu` packages for copyright
      reasons.

      .. _Org Mode: http://orgmode.org
