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