Commit | Line | Data |
---|---|---|
fdc76236 TT |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Emacs Lisp Reference Manual. | |
acaf905b | 3 | @c Copyright (C) 2010-2012 Free Software Foundation, Inc. |
fdc76236 TT |
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 | |
0b3ceceb CY |
8 | @cindex package |
9 | @cindex Lisp package | |
fdc76236 | 10 | |
120d9389 CY |
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. | |
fdc76236 | 15 | |
120d9389 CY |
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. | |
fdc76236 TT |
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. | |
120d9389 | 23 | * Package Archives:: Maintaining package archives. |
fdc76236 TT |
24 | @end menu |
25 | ||
26 | @node Packaging Basics | |
27 | @section Packaging Basics | |
fdc76236 | 28 | @cindex package attributes |
0b3ceceb CY |
29 | @cindex package name |
30 | @cindex package version | |
31 | @cindex dependencies | |
32 | @cindex package dependencies | |
fdc76236 | 33 | |
120d9389 CY |
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 | ||
fdc76236 TT |
48 | @table @asis |
49 | @item Name | |
120d9389 CY |
50 | A short word (e.g. @samp{auctex}). This is usually also the symbol |
51 | prefix used in the program (@pxref{Coding Conventions}). | |
fdc76236 TT |
52 | |
53 | @item Version | |
120d9389 CY |
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. | |
fdc76236 TT |
57 | |
58 | @item Brief description | |
120d9389 CY |
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. | |
fdc76236 TT |
61 | |
62 | @item Long description | |
120d9389 CY |
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 | |
50b063c3 CY |
66 | fully describe the package's capabilities and how to begin using it |
67 | once it is installed. | |
fdc76236 TT |
68 | |
69 | @item Dependencies | |
120d9389 CY |
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. | |
fdc76236 TT |
75 | @end table |
76 | ||
0b3ceceb | 77 | @cindex content directory, package |
120d9389 CY |
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 | ||
0b3ceceb | 87 | @cindex package autoloads |
120d9389 CY |
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. | |
fdc76236 | 105 | |
120d9389 CY |
106 | @node Simple Packages |
107 | @section Simple Packages | |
0b3ceceb CY |
108 | @cindex single file package |
109 | @cindex simple package | |
fdc76236 | 110 | |
120d9389 CY |
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: | |
fdc76236 | 115 | |
120d9389 CY |
116 | @example |
117 | @group | |
118 | ;;; superfrobnicator.el --- Frobnicate and bifurcate flanges | |
fdc76236 | 119 | |
120d9389 CY |
120 | ;; Copyright (C) 2011 Free Software Foundation, Inc. |
121 | @end group | |
fdc76236 | 122 | |
120d9389 CY |
123 | ;; Author: J. R. Hacker <jrh@@example.com> |
124 | ;; Version: 1.3 | |
125 | ;; Package-Requires: ((flange "1.0")) | |
126 | ;; Keywords: frobnicate | |
fdc76236 | 127 | |
120d9389 | 128 | @dots{} |
fdc76236 | 129 | |
120d9389 | 130 | ;;; Commentary: |
fdc76236 | 131 | |
120d9389 CY |
132 | ;; This package provides a minor mode to frobnicate and/or |
133 | ;; bifurcate any flanges you desire. To activate it, just type | |
134 | @dots{} | |
fdc76236 | 135 | |
120d9389 CY |
136 | ;;;###autoload |
137 | (define-minor-mode superfrobnicator-mode | |
138 | @dots{} | |
139 | @end example | |
fdc76236 | 140 | |
120d9389 CY |
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}. | |
fdc76236 | 143 | |
120d9389 CY |
144 | The brief description is also taken from the first line. Here, it |
145 | is @samp{Frobnicate and bifurcate flanges}. | |
fdc76236 | 146 | |
120d9389 CY |
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. | |
fdc76236 | 150 | |
120d9389 CY |
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.) | |
fdc76236 | 155 | |
120d9389 CY |
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. | |
fdc76236 | 161 | |
120d9389 CY |
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}. | |
fdc76236 | 165 | |
120d9389 CY |
166 | @xref{Package Archives}, for a explanation of how to add a |
167 | single-file package to a package archive. | |
fdc76236 TT |
168 | |
169 | @node Multi-file Packages | |
170 | @section Multi-file Packages | |
0b3ceceb | 171 | @cindex multi-file package |
fdc76236 | 172 | |
120d9389 CY |
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}. | |
fdc76236 TT |
197 | |
198 | @defun define-package name version &optional docstring requirements | |
120d9389 CY |
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 | ||
fdc76236 | 204 | @var{requirements} is a list of required packages and their versions. |
120d9389 CY |
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). | |
fdc76236 TT |
209 | @end defun |
210 | ||
120d9389 CY |
211 | If the content directory contains a file named @file{README}, this |
212 | file is used as the long description. | |
fdc76236 | 213 | |
120d9389 CY |
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}. | |
fdc76236 | 216 | @xref{Invoking install-info, Invoking install-info, Invoking |
0b3ceceb CY |
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. | |
fdc76236 | 221 | |
120d9389 CY |
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. | |
fdc76236 | 225 | |
120d9389 CY |
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. | |
fdc76236 | 231 | |
120d9389 CY |
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: | |
fdc76236 TT |
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 | |
120d9389 CY |
242 | |
243 | @node Package Archives | |
244 | @section Creating and Maintaining Package Archives | |
0b3ceceb CY |
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}. |