| 1 | @c -*-texinfo-*- |
| 2 | @c This is part of the GNU Emacs Lisp Reference Manual. |
| 3 | @c Copyright (C) 2010-2012 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 package |
| 9 | @cindex Lisp package |
| 10 | |
| 11 | Emacs provides a standard way to distribute Emacs Lisp code to |
| 12 | users. A @dfn{package} is a collection of one or more files, |
| 13 | formatted and bundled in such a way that users can easily download, |
| 14 | install, uninstall, and upgrade it. |
| 15 | |
| 16 | The following sections describe how to create a package, and how to |
| 17 | put it in a @dfn{package archive} for others to download. |
| 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 | * Package Archives:: Maintaining package archives. |
| 24 | @end menu |
| 25 | |
| 26 | @node Packaging Basics |
| 27 | @section Packaging Basics |
| 28 | @cindex package attributes |
| 29 | @cindex package name |
| 30 | @cindex package version |
| 31 | @cindex dependencies |
| 32 | @cindex package dependencies |
| 33 | |
| 34 | A package is either a @dfn{simple package} or a @dfn{multi-file |
| 35 | package}. A simple package is stored in a package archive as a single |
| 36 | Emacs Lisp file, while a multi-file package is stored as a tar file |
| 37 | (containing multiple Lisp files, and possibly non-Lisp files such as a |
| 38 | manual). |
| 39 | |
| 40 | In ordinary usage, the difference between simple packages and |
| 41 | multi-file packages is relatively unimportant; the Package Menu |
| 42 | interface makes no distinction between them. However, the procedure |
| 43 | for creating them differs, as explained in the following sections. |
| 44 | |
| 45 | Each package (whether simple or multi-file) has certain |
| 46 | @dfn{attributes}: |
| 47 | |
| 48 | @table @asis |
| 49 | @item Name |
| 50 | A short word (e.g. @samp{auctex}). This is usually also the symbol |
| 51 | prefix used in the program (@pxref{Coding Conventions}). |
| 52 | |
| 53 | @item Version |
| 54 | A version number, in a form that the function @code{version-to-list} |
| 55 | understands (e.g. @samp{11.86}). Each release of a package should be |
| 56 | accompanied by an increase in the version number. |
| 57 | |
| 58 | @item Brief description |
| 59 | This is shown when the package is listed in the Package Menu. It |
| 60 | should occupy a single line, ideally in 36 characters or less. |
| 61 | |
| 62 | @item Long description |
| 63 | This is shown in the buffer created by @kbd{C-h P} |
| 64 | (@code{describe-package}), following the package's brief description |
| 65 | and installation status. It normally spans multiple lines, and should |
| 66 | fully describe the package's capabilities and how to begin using it |
| 67 | once it is installed. |
| 68 | |
| 69 | @item Dependencies |
| 70 | A list of other packages (possibly including minimal acceptable |
| 71 | version numbers) on which this package depends. The list may be |
| 72 | empty, meaning this package has no dependencies. Otherwise, |
| 73 | installing this package also automatically installs its dependencies; |
| 74 | if any dependency cannot be found, the package cannot be installed. |
| 75 | @end table |
| 76 | |
| 77 | @cindex content directory, package |
| 78 | Installing a package, either via the Package Menu, or via the |
| 79 | command @code{package-install-file}, creates a subdirectory of |
| 80 | @code{package-user-dir} named @file{@var{name}-@var{version}}, where |
| 81 | @var{name} is the package's name and @var{version} its version |
| 82 | (e.g. @file{~/.emacs.d/elpa/auctex-11.86/}). We call this the |
| 83 | package's @dfn{content directory}. It is where Emacs puts the |
| 84 | package's contents (the single Lisp file for a simple package, or the |
| 85 | files extracted from a multi-file package). |
| 86 | |
| 87 | @cindex package autoloads |
| 88 | Emacs then searches every Lisp file in the content directory for |
| 89 | autoload magic comments (@pxref{Autoload}). These autoload |
| 90 | definitions are saved to a file named @file{@var{name}-autoloads.el} |
| 91 | in the content directory. They are typically used to autoload the |
| 92 | principal user commands defined in the package, but they can also |
| 93 | perform other tasks, such as adding an element to |
| 94 | @code{auto-mode-alist} (@pxref{Auto Major Mode}). During this time, |
| 95 | Emacs will also byte-compile the Lisp files. |
| 96 | |
| 97 | After installation, and (by default) each time Emacs is started, the |
| 98 | installed package is @dfn{activated}. During activation, Emacs adds |
| 99 | the package's content directory to @code{load-path}, and evaluates the |
| 100 | autoload definitions in @file{@var{name}-autoloads.el}. |
| 101 | |
| 102 | Note that a package typically does @emph{not} autoload every |
| 103 | function and variable defined within it---only the handful of commands |
| 104 | typically called to begin using the package. |
| 105 | |
| 106 | @node Simple Packages |
| 107 | @section Simple Packages |
| 108 | @cindex single file package |
| 109 | @cindex simple package |
| 110 | |
| 111 | A simple package consists of a single Emacs Lisp source file. The |
| 112 | file must conform to the Emacs Lisp library header conventions |
| 113 | (@pxref{Library Headers}). The package's attributes are taken from |
| 114 | the various headers, as illustrated by the following example: |
| 115 | |
| 116 | @example |
| 117 | @group |
| 118 | ;;; superfrobnicator.el --- Frobnicate and bifurcate flanges |
| 119 | |
| 120 | ;; Copyright (C) 2011 Free Software Foundation, Inc. |
| 121 | @end group |
| 122 | |
| 123 | ;; Author: J. R. Hacker <jrh@@example.com> |
| 124 | ;; Version: 1.3 |
| 125 | ;; Package-Requires: ((flange "1.0")) |
| 126 | ;; Keywords: frobnicate |
| 127 | |
| 128 | @dots{} |
| 129 | |
| 130 | ;;; Commentary: |
| 131 | |
| 132 | ;; This package provides a minor mode to frobnicate and/or |
| 133 | ;; bifurcate any flanges you desire. To activate it, just type |
| 134 | @dots{} |
| 135 | |
| 136 | ;;;###autoload |
| 137 | (define-minor-mode superfrobnicator-mode |
| 138 | @dots{} |
| 139 | @end example |
| 140 | |
| 141 | The name of the package is the same as the base name of the file, as |
| 142 | written on the first line. Here, it is @samp{superfrobnicator}. |
| 143 | |
| 144 | The brief description is also taken from the first line. Here, it |
| 145 | is @samp{Frobnicate and bifurcate flanges}. |
| 146 | |
| 147 | The version number comes from the @samp{Package-Version} header, if |
| 148 | it exists, or from the @samp{Version} header otherwise. One or the |
| 149 | other @emph{must} be present. Here, the version number is 1.3. |
| 150 | |
| 151 | If the file has a @samp{;;; Commentary:} section, this section is |
| 152 | used as the long description. (When displaying the description, Emacs |
| 153 | omits the @samp{;;; Commentary:} line, as well as the leading comment |
| 154 | characters in the commentary itself.) |
| 155 | |
| 156 | If the file has a @samp{Package-Requires} header, that is used as |
| 157 | the package dependencies. In the above example, the package depends |
| 158 | on the @samp{flange} package, version 1.0 or higher. @xref{Library |
| 159 | Headers}, for a description of the @samp{Package-Requires} header. If |
| 160 | the header is omitted, the package has no dependencies. |
| 161 | |
| 162 | The file ought to also contain one or more autoload magic comments, |
| 163 | as explained in @ref{Packaging Basics}. In the above example, a magic |
| 164 | comment autoloads @code{superfrobnicator-mode}. |
| 165 | |
| 166 | @xref{Package Archives}, for a explanation of how to add a |
| 167 | single-file package to a package archive. |
| 168 | |
| 169 | @node Multi-file Packages |
| 170 | @section Multi-file Packages |
| 171 | @cindex multi-file package |
| 172 | |
| 173 | A multi-file package is less convenient to create than a single-file |
| 174 | package, but it offers more features: it can include multiple Emacs |
| 175 | Lisp files, an Info manual, and other file types (such as images). |
| 176 | |
| 177 | Prior to installation, a multi-file package is stored in a package |
| 178 | archive as a tar file. The tar file must be named |
| 179 | @file{@var{name}-@var{version}.tar}, where @var{name} is the package |
| 180 | name and @var{version} is the version number. Its contents, once |
| 181 | extracted, must all appear in a directory named |
| 182 | @file{@var{name}-@var{version}}, the @dfn{content directory} |
| 183 | (@pxref{Packaging Basics}). Files may also extract into |
| 184 | subdirectories of the content directory. |
| 185 | |
| 186 | One of the files in the content directory must be named |
| 187 | @file{@var{name}-pkg.el}. It must contain a single Lisp form, |
| 188 | consisting of a call to the function @code{define-package}, described |
| 189 | below. This defines the package's version, brief description, and |
| 190 | requirements. |
| 191 | |
| 192 | For example, if we distribute version 1.3 of the superfrobnicator as |
| 193 | a multi-file package, the tar file would be |
| 194 | @file{superfrobnicator-1.3.tar}. Its contents would extract into the |
| 195 | directory @file{superfrobnicator-1.3}, and one of these would be the |
| 196 | file @file{superfrobnicator-pkg.el}. |
| 197 | |
| 198 | @defun define-package name version &optional docstring requirements |
| 199 | This function defines a package. @var{name} is the package name, a |
| 200 | string. @var{version} is the version, as a string of a form that can |
| 201 | be understood by the function @code{version-to-list}. @var{docstring} |
| 202 | is the brief description. |
| 203 | |
| 204 | @var{requirements} is a list of required packages and their versions. |
| 205 | Each element in this list should have the form @code{(@var{dep-name} |
| 206 | @var{dep-version})}, where @var{dep-name} is a symbol whose name is |
| 207 | the dependency's package name, and @var{dep-version} is the |
| 208 | dependency's version (a string). |
| 209 | @end defun |
| 210 | |
| 211 | If the content directory contains a file named @file{README}, this |
| 212 | file is used as the long description. |
| 213 | |
| 214 | If the content directory contains a file named @file{dir}, this is |
| 215 | assumed to be an Info directory file made with @command{install-info}. |
| 216 | @xref{Invoking install-info, Invoking install-info, Invoking |
| 217 | install-info, texinfo, Texinfo}. The relevant Info files should also |
| 218 | be present in the content directory. In this case, Emacs will |
| 219 | automatically add the content directory to @code{Info-directory-list} |
| 220 | when the package is activated. |
| 221 | |
| 222 | Do not include any @file{.elc} files in the package. Those are |
| 223 | created when the package is installed. Note that there is no way to |
| 224 | control the order in which files are byte-compiled. |
| 225 | |
| 226 | Do not include any file named @file{@var{name}-autoloads.el}. This |
| 227 | file is reserved for the package's autoload definitions |
| 228 | (@pxref{Packaging Basics}). It is created automatically when the |
| 229 | package is installed, by searching all the Lisp files in the package |
| 230 | for autoload magic comments. |
| 231 | |
| 232 | If the multi-file package contains auxiliary data files (such as |
| 233 | images), the package's Lisp code can refer to these files via the |
| 234 | variable @code{load-file-name} (@pxref{Loading}). Here is an example: |
| 235 | |
| 236 | @smallexample |
| 237 | (defconst superfrobnicator-base (file-name-directory load-file-name)) |
| 238 | |
| 239 | (defun superfrobnicator-fetch-image (file) |
| 240 | (expand-file-name file superfrobnicator-base)) |
| 241 | @end smallexample |
| 242 | |
| 243 | @node Package Archives |
| 244 | @section Creating and Maintaining Package Archives |
| 245 | @cindex package archive |
| 246 | |
| 247 | Via the Package Menu, users may download packages from @dfn{package |
| 248 | archives}. Such archives are specified by the variable |
| 249 | @code{package-archives}, whose default value contains a single entry: |
| 250 | the archive hosted by the GNU project at @url{elpa.gnu.org}. This |
| 251 | section describes how to set up and maintain a package archive. |
| 252 | |
| 253 | @cindex base location, package archive |
| 254 | @defopt package-archives |
| 255 | The value of this variable is an alist of package archives recognized |
| 256 | by the Emacs package manager. |
| 257 | |
| 258 | Each alist element corresponds to one archive, and should have the |
| 259 | form @code{(@var{id} . @var{location})}, where @var{id} is the name of |
| 260 | the archive (a string) and @var{location} is its @dfn{base location} |
| 261 | (a string). |
| 262 | |
| 263 | If the base location starts with @samp{http:}, it is treated as a HTTP |
| 264 | URL, and packages are downloaded from this archive via HTTP (as is the |
| 265 | case for the default GNU archive). |
| 266 | |
| 267 | Otherwise, the base location should be a directory name. In this |
| 268 | case, Emacs retrieves packages from this archive via ordinary file |
| 269 | access. Such ``local'' archives are mainly useful for testing. |
| 270 | @end defopt |
| 271 | |
| 272 | A package archive is simply a directory in which the package files, |
| 273 | and associated files, are stored. If you want the archive to be |
| 274 | reachable via HTTP, this directory must be accessible to a web server. |
| 275 | How to accomplish this is beyond the scope of this manual. |
| 276 | |
| 277 | A convenient way to set up and update a package archive is via the |
| 278 | @code{package-x} library. This is included with Emacs, but not loaded |
| 279 | by default; type @kbd{M-x load-library @kbd{RET} package-x @kbd{RET}} |
| 280 | to load it, or add @code{(require 'package-x)} to your init file. |
| 281 | @xref{Lisp Libraries,, Lisp Libraries, emacs, The GNU Emacs Manual}. |
| 282 | Once loaded, you can make use of the following: |
| 283 | |
| 284 | @defopt package-archive-upload-base |
| 285 | The value of this variable is the base location of a package archive, |
| 286 | as a directory name. The commands in the @code{package-x} library |
| 287 | will use this base location. |
| 288 | |
| 289 | The directory name should be absolute. You may specify a remote name, |
| 290 | such as @file{/ssh:foo@@example.com:/var/www/packages/}, if the |
| 291 | package archive is on a different machine. @xref{Remote Files,, |
| 292 | Remote Files, emacs, The GNU Emacs Manual}. |
| 293 | @end defopt |
| 294 | |
| 295 | @deffn Command package-upload-file filename |
| 296 | This command prompts for @var{filename}, a file name, and uploads that |
| 297 | file to @code{package-archive-upload-base}. The file must be either a |
| 298 | simple package (a @file{.el} file) or a multi-file package (a |
| 299 | @file{.tar} file); otherwise, an error is raised. The package |
| 300 | attributes are automatically extracted, and the archive's contents |
| 301 | list is updated with this information. |
| 302 | |
| 303 | If @code{package-archive-upload-base} does not specify a valid |
| 304 | directory, the function prompts interactively for one. If the |
| 305 | directory does not exist, it is created. The directory need not have |
| 306 | any initial contents (i.e., you can use this command to populate an |
| 307 | initially empty archive). |
| 308 | @end deffn |
| 309 | |
| 310 | @deffn Command package-upload-buffer |
| 311 | This command is similar to @code{package-upload-file}, but instead of |
| 312 | prompting for a package file, it uploads the contents of the current |
| 313 | buffer. The current buffer must be visiting a simple package (a |
| 314 | @file{.el} file) or a multi-file package (a @file{.tar} file); |
| 315 | otherwise, an error is raised. |
| 316 | @end deffn |
| 317 | |
| 318 | @noindent |
| 319 | After you create an archive, remember that it is not accessible in the |
| 320 | Package Menu interface unless it is in @code{package-archives}. |