109983
|
1 @c -*-texinfo-*-
|
|
2 @c This is part of the GNU Emacs Lisp Reference Manual.
|
|
3 @c Copyright (C) 2010
|
|
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
|