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