Mercurial > emacs
annotate doc/lispref/package.texi @ 112394:23a54fb18e67
calc/calc-undo.el (calc-undo): Autoload it.
calc/calc-ext.el (calc-init-extensions): Remove keybindings and autoload for `calc-undo'.
calc/calc.el (calc-mode-map): Add keybindings for `calc-undo'.
author | Jay Belanger <jay.p.belanger@gmail.com> |
---|---|
date | Thu, 20 Jan 2011 22:54:37 -0600 |
parents | 6378d1b57038 |
children |
rev | line source |
---|---|
109983 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
112275
6378d1b57038
Add 2011 to remaining FSF/AIST copyright years.
Glenn Morris <rgm@gnu.org>
parents:
109983
diff
changeset
|
3 @c Copyright (C) 2010, 2011 |
109983 | 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 |