Preparing Lisp code for distribution
************************************

Emacs provides a standard way for Emacs Lisp code to be distributed to users.  This approach lets users easily download, install, uninstall, and upgrade Lisp code that they might want to use.

A package is simply one or more files, formatted and bundled in a particular way.  Typically a package includes primarily Emacs Lisp code, but it is possible to create other kinds of packages as well.

Packaging Basics
================

A package has a few attributes:

Name
     A string, the name of the package.  This attribute is mandatory.  If it does not exist, the package cannot be installed by the package manager.

Version
     A version number, which is anything that can be parsed by version-to-list.  This attribute is mandatory.  If it does not exist, the package cannot be installed by the package manager.

Brief description
     This is shown to the user in the package menu buffer.  It is just a single line.  On a terminal with 80 characters per line, there are only 36 characters available in the package menu mode for showing the brief description, so it is best to keep it very brief.  If no brief name is given, an empty string is used.

Long description
     This can be a README file or the like.  This is available to the user before the package is installed, via the package menu.  It should more fully describe the package and its capabilities, so a user can read it to decide whether he wants to install the package.  This attribute is optional.

Dependencies
     This is a list of other packages and their minimal acceptable versions.  This is used both at download time (to make sure all the needed code is available) and at activation time (to ensure a package is only activated if all its dependencies have been successfully activated).  This attribute is optional.

Manual
     A package can optionally include an Info manual.

Conceptually, a package goes through several state transitions (in reality some of these transitions are grouped together):

Download
     Fetch the package from somewhere.

Install
     Unpack the package, or write a .el file into the appropriate install directory.  This step also includes extracting autoloads and byte-compiling the Emacs Lisp code.

Activate
     Update load-path and Info-directory-list and evaluate the autoloads, so that the package is ready for the user to use.

It is best for users if packages do not do too much work at activation time.  The best approach is to have activation consist of some autoloads and little more.

Simple Packages
===============

The simplest package consists of a single Emacs Lisp source file. In this case, all the attributes of the package (see Packaging Basics) are taken from this file.

The package system expects this .el file to conform to the Emacs Lisp library header conventions.  See Library Headers.

The name of the package is the same as the base name of the .el file, as written in the first comment line.  For example, given the header line:

     ;;; superfrobnicator.el --- frobnicate and bifurcate flanges

the package name will be superfrobnicator.

The short description of the package is also taken from the first line of the file.

If the file has a ``Commentary'' header, then it is used as the long description.

The version of the package comes either from the ``Package-Version'' header, if it exists, or from the ``Version'' header.  A package is required to have a version number.  Each release of a package must be accompanied by an increase in the version number.

If the file has a ``Package-Requires'' header, then that is used as the package dependencies.  Otherwise, the package is assumed not to have any dependencies.

A single-file package cannot have an Info manual.

The file will be scanned for autoload cookies at install time. See Autoload.

Multi-file Packages
===================

A multi-file package is just a .tar file.  While less convenient to create than a single-file package, a multi-file package also offers more features: it can include an Info manual, multiple Emacs Lisp files, and also other data files needed by a package.

The contents of the .tar file must all appear beneath a single directory, named after the package and version.  Files can appear in subdirectories of this top-most directory, but Emacs Lisp code will only be found (and thus byte-compiled) at the top-most level.  Also, the .tar file is typically also given this same name.  For example, if you are distributing version 1.3 of the superfrobnicator, the package file would be named ``superfrobnicator-1.3.tar'' and the contents would all appear in the directory superfrobnicator-1.3 in that .tar.

The package must include a -pkg.el file, named after the package.  In our example above, this file would be called superfrobnicator-pkg.el.  This file must have a single form in it, a call to define-package.  The package dependencies and brief description are taken from this form.

 -- Function: define-package name version &optional docstring requirements
     Define a package.  NAME is the name of the package, a string. VERSION is the package's version, a string.  It must be in a form that can be understood by version-to-list. DOCSTRING is the short description of the package. REQUIREMENTS is a list of required packages and their versions.

If a README file exists in the content directory, then it is used as the long description.

If the package has an Info manual, you should distribute the needed info files, plus a dir file made with install-info. See Invoking install-info (Texinfo).

Do not include any .elc files in the package.  Those will be created at install time.  Note that there is no way to control the order in which files are byte-compiled; your package must be robust here.

The installation process will scan all the .el files in the package for autoload cookies.  See Autoload.  They are extracted into a -autoloads.el file (e.g., superfrobnicator-autoloads.el), so do not include a file of that name in your package.

Any other files in the .tar file are simply unpacked when the package is installed.  This can be useful if your package needs auxiliary data files --- e.g., icons or sounds.

Emacs Lisp code installed via the package manager must take special care to be location-independent.  One easy way to do this is to make references to auxiliary data files relative to LOAD-FILE-NAME. For example:

     (defconst superfrobnicator-base (file-name-directory load-file-name))

     (defun superfrobnicator-fetch-image (file)
       (expand-file-name file superfrobnicator-base))