doc/lispref/package.texi

   1 @c -*-texinfo-*-
   2 @c This is part of the GNU Emacs Lisp Reference Manual.
   3 @c Copyright (C) 2010, 2011
   4 @c   Free Software Foundation, Inc.
   5 @c See the file elisp.texi for copying conditions.
   6 @setfilename ../../info/package
   7 @node Packaging, Antinews, System Interface, Top
   8 @chapter Preparing Lisp code for distribution
   9 @cindex packaging
  10
  11   Emacs provides a standard way for Emacs Lisp code to be distributed
  12 to users.  This approach lets users easily download, install,
  13 uninstall, and upgrade Lisp code that they might want to use.
  14
  15   A @dfn{package} is simply one or more files, formatted and bundled
  16 in a particular way.  Typically a package includes primarily Emacs
  17 Lisp code, but it is possible to create other kinds of packages as
  18 well.
  19
  20 @menu
  21 * Packaging Basics::        The basic concepts of Emacs Lisp packages.
  22 * Simple Packages::         How to package a single .el file.
  23 * Multi-file Packages::     How to package multiple files.
  24 @end menu
  25
  26 @node Packaging Basics
  27 @section Packaging Basics
  28 @cindex packaging basics
  29
  30   A package has a few attributes:
  31 @cindex package attributes
  32
  33 @table @asis
  34 @item Name
  35 A string, the name of the package.  This attribute is mandatory.  If
  36 it does not exist, the package cannot be installed by the package
  37 manager.
  38
  39 @item Version
  40 A version number, which is anything that can be parsed by
  41 @code{version-to-list}.  This attribute is mandatory.  If it does not
  42 exist, the package cannot be installed by the package manager.
  43
  44 @item Brief description
  45 This is shown to the user in the package menu buffer.  It is just a
  46 single line.  On a terminal with 80 characters per line, there are
  47 only 36 characters available in the package menu mode for showing the
  48 brief description, so it is best to keep it very brief.  If no brief
  49 name is given, an empty string is used.
  50
  51 @item Long description
  52 This can be a @file{README} file or the like.  This is available to
  53 the user before the package is installed, via the package menu.  It
  54 should more fully describe the package and its capabilities, so a user
  55 can read it to decide whether he wants to install the package.  This
  56 attribute is optional.
  57
  58 @item Dependencies
  59 This is a list of other packages and their minimal acceptable
  60 versions.  This is used both at download time (to make sure all the
  61 needed code is available) and at activation time (to ensure a package
  62 is only activated if all its dependencies have been successfully
  63 activated).  This attribute is optional.
  64
  65 @item Manual
  66 A package can optionally include an Info manual.
  67 @end table
  68
  69   Conceptually, a package goes through several state transitions (in
  70 reality some of these transitions are grouped together):
  71
  72 @table @asis
  73 @item Download
  74 Fetch the package from somewhere.
  75
  76 @item Install
  77 Unpack the package, or write a @file{.el} file into the appropriate
  78 install directory.  This step also includes extracting autoloads and
  79 byte-compiling the Emacs Lisp code.
  80
  81 @item Activate
  82 Update @code{load-path} and @code{Info-directory-list} and evaluate
  83 the autoloads, so that the package is ready for the user to use.
  84 @end table
  85
  86   It is best for users if packages do not do too much work at
  87 activation time.  The best approach is to have activation consist of
  88 some autoloads and little more.
  89
  90 @node Simple Packages
  91 @section Simple Packages
  92 @cindex single file packages
  93
  94   The simplest package consists of a single Emacs Lisp source file.
  95 In this case, all the attributes of the package (@pxref{Packaging
  96 Basics}) are taken from this file.
  97
  98   The package system expects this @file{.el} file to conform to the
  99 Emacs Lisp library header conventions.  @xref{Library Headers}.
 100
 101   The name of the package is the same as the base name of the
 102 @file{.el} file, as written in the first comment line.  For example,
 103 given the header line:
 104
 105 @smallexample
 106 ;;; superfrobnicator.el --- frobnicate and bifurcate flanges
 107 @end smallexample
 108
 109 the package name will be @samp{superfrobnicator}.
 110
 111   The short description of the package is also taken from the first
 112 line of the file.
 113
 114   If the file has a ``Commentary'' header, then it is used as the long
 115 description.
 116
 117   The version of the package comes either from the ``Package-Version''
 118 header, if it exists, or from the ``Version'' header.  A package is
 119 required to have a version number.  Each release of a package must be
 120 accompanied by an increase in the version number.
 121
 122   If the file has a ``Package-Requires'' header, then that is used as
 123 the package dependencies.  Otherwise, the package is assumed not to
 124 have any dependencies.
 125
 126   A single-file package cannot have an Info manual.
 127
 128   The file will be scanned for autoload cookies at install time.
 129 @xref{Autoload}.
 130
 131 @node Multi-file Packages
 132 @section Multi-file Packages
 133 @cindex multi-file packages
 134
 135   A multi-file package is just a @file{.tar} file.  While less
 136 convenient to create than a single-file package, a multi-file package
 137 also offers more features: it can include an Info manual, multiple
 138 Emacs Lisp files, and also other data files needed by a package.
 139
 140   The contents of the @file{.tar} file must all appear beneath a
 141 single directory, named after the package and version.  Files can
 142 appear in subdirectories of this top-most directory, but Emacs Lisp
 143 code will only be found (and thus byte-compiled) at the top-most
 144 level.  Also, the @file{.tar} file is typically also given this same
 145 name.  For example, if you are distributing version 1.3 of the
 146 superfrobnicator, the package file would be named
 147 ``superfrobnicator-1.3.tar'' and the contents would all appear in the
 148 directory @file{superfrobnicator-1.3} in that @file{.tar}.
 149
 150   The package must include a @file{-pkg.el} file, named after the
 151 package.  In our example above, this file would be called
 152 @file{superfrobnicator-pkg.el}.  This file must have a single form in
 153 it, a call to @code{define-package}.  The package dependencies and
 154 brief description are taken from this form.
 155
 156 @defun define-package name version &optional docstring requirements
 157 Define a package.  @var{name} is the name of the package, a string.
 158 @var{version} is the package's version, a string.  It must be in a
 159 form that can be understood by @code{version-to-list}.
 160 @var{docstring} is the short description of the package.
 161 @var{requirements} is a list of required packages and their versions.
 162 @end defun
 163
 164   If a @file{README} file exists in the content directory, then it is
 165 used as the long description.
 166
 167   If the package has an Info manual, you should distribute the needed
 168 info files, plus a @file{dir} file made with @command{install-info}.
 169 @xref{Invoking install-info, Invoking install-info, Invoking
 170 install-info, texinfo, Texinfo}.
 171
 172   Do not include any @file{.elc} files in the package.  Those will be
 173 created at install time.  Note that there is no way to control the
 174 order in which files are byte-compiled; your package must be robust
 175 here.
 176
 177   The installation process will scan all the @file{.el} files in the
 178 package for autoload cookies.  @xref{Autoload}.  They are extracted
 179 into a @file{-autoloads.el} file (e.g.,
 180 @file{superfrobnicator-autoloads.el}), so do not include a file of
 181 that name in your package.
 182
 183   Any other files in the @file{.tar} file are simply unpacked when the
 184 package is installed.  This can be useful if your package needs
 185 auxiliary data files --- e.g., icons or sounds.
 186
 187   Emacs Lisp code installed via the package manager must take special
 188 care to be location-independent.  One easy way to do this is to make
 189 references to auxiliary data files relative to @var{load-file-name}.
 190 For example:
 191
 192 @smallexample
 193 (defconst superfrobnicator-base (file-name-directory load-file-name))
 194
 195 (defun superfrobnicator-fetch-image (file)
 196   (expand-file-name file superfrobnicator-base))
 197 @end smallexample