Commit | Line | Data |
---|---|---|
fdc76236 TT |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Emacs Lisp Reference Manual. | |
95df8112 | 3 | @c Copyright (C) 2010-2011 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 | |
8 | @cindex packaging | |
9 | ||
10 | Emacs provides a standard way for Emacs Lisp code to be distributed | |
11 | to users. This approach lets users easily download, install, | |
12 | uninstall, and upgrade Lisp code that they might want to use. | |
13 | ||
14 | A @dfn{package} is simply one or more files, formatted and bundled | |
15 | in a particular way. Typically a package includes primarily Emacs | |
16 | Lisp code, but it is possible to create other kinds of packages as | |
17 | well. | |
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 | @end menu | |
24 | ||
25 | @node Packaging Basics | |
26 | @section Packaging Basics | |
27 | @cindex packaging basics | |
28 | ||
29 | A package has a few attributes: | |
30 | @cindex package attributes | |
31 | ||
32 | @table @asis | |
33 | @item Name | |
34 | A string, the name of the package. This attribute is mandatory. If | |
35 | it does not exist, the package cannot be installed by the package | |
36 | manager. | |
37 | ||
38 | @item Version | |
39 | A version number, which is anything that can be parsed by | |
40 | @code{version-to-list}. This attribute is mandatory. If it does not | |
41 | exist, the package cannot be installed by the package manager. | |
42 | ||
43 | @item Brief description | |
44 | This is shown to the user in the package menu buffer. It is just a | |
45 | single line. On a terminal with 80 characters per line, there are | |
46 | only 36 characters available in the package menu mode for showing the | |
47 | brief description, so it is best to keep it very brief. If no brief | |
48 | name is given, an empty string is used. | |
49 | ||
50 | @item Long description | |
51 | This can be a @file{README} file or the like. This is available to | |
52 | the user before the package is installed, via the package menu. It | |
53 | should more fully describe the package and its capabilities, so a user | |
54 | can read it to decide whether he wants to install the package. This | |
55 | attribute is optional. | |
56 | ||
57 | @item Dependencies | |
58 | This is a list of other packages and their minimal acceptable | |
59 | versions. This is used both at download time (to make sure all the | |
60 | needed code is available) and at activation time (to ensure a package | |
61 | is only activated if all its dependencies have been successfully | |
62 | activated). This attribute is optional. | |
63 | ||
64 | @item Manual | |
65 | A package can optionally include an Info manual. | |
66 | @end table | |
67 | ||
68 | Conceptually, a package goes through several state transitions (in | |
69 | reality some of these transitions are grouped together): | |
70 | ||
71 | @table @asis | |
72 | @item Download | |
73 | Fetch the package from somewhere. | |
74 | ||
75 | @item Install | |
76 | Unpack the package, or write a @file{.el} file into the appropriate | |
77 | install directory. This step also includes extracting autoloads and | |
78 | byte-compiling the Emacs Lisp code. | |
79 | ||
80 | @item Activate | |
81 | Update @code{load-path} and @code{Info-directory-list} and evaluate | |
82 | the autoloads, so that the package is ready for the user to use. | |
83 | @end table | |
84 | ||
85 | It is best for users if packages do not do too much work at | |
86 | activation time. The best approach is to have activation consist of | |
87 | some autoloads and little more. | |
88 | ||
89 | @node Simple Packages | |
90 | @section Simple Packages | |
91 | @cindex single file packages | |
92 | ||
93 | The simplest package consists of a single Emacs Lisp source file. | |
94 | In this case, all the attributes of the package (@pxref{Packaging | |
95 | Basics}) are taken from this file. | |
96 | ||
97 | The package system expects this @file{.el} file to conform to the | |
98 | Emacs Lisp library header conventions. @xref{Library Headers}. | |
99 | ||
100 | The name of the package is the same as the base name of the | |
101 | @file{.el} file, as written in the first comment line. For example, | |
102 | given the header line: | |
103 | ||
104 | @smallexample | |
105 | ;;; superfrobnicator.el --- frobnicate and bifurcate flanges | |
106 | @end smallexample | |
107 | ||
108 | the package name will be @samp{superfrobnicator}. | |
109 | ||
110 | The short description of the package is also taken from the first | |
111 | line of the file. | |
112 | ||
113 | If the file has a ``Commentary'' header, then it is used as the long | |
114 | description. | |
115 | ||
116 | The version of the package comes either from the ``Package-Version'' | |
117 | header, if it exists, or from the ``Version'' header. A package is | |
118 | required to have a version number. Each release of a package must be | |
119 | accompanied by an increase in the version number. | |
120 | ||
121 | If the file has a ``Package-Requires'' header, then that is used as | |
122 | the package dependencies. Otherwise, the package is assumed not to | |
123 | have any dependencies. | |
124 | ||
125 | A single-file package cannot have an Info manual. | |
126 | ||
127 | The file will be scanned for autoload cookies at install time. | |
128 | @xref{Autoload}. | |
129 | ||
130 | @node Multi-file Packages | |
131 | @section Multi-file Packages | |
132 | @cindex multi-file packages | |
133 | ||
134 | A multi-file package is just a @file{.tar} file. While less | |
135 | convenient to create than a single-file package, a multi-file package | |
136 | also offers more features: it can include an Info manual, multiple | |
137 | Emacs Lisp files, and also other data files needed by a package. | |
138 | ||
139 | The contents of the @file{.tar} file must all appear beneath a | |
140 | single directory, named after the package and version. Files can | |
141 | appear in subdirectories of this top-most directory, but Emacs Lisp | |
142 | code will only be found (and thus byte-compiled) at the top-most | |
143 | level. Also, the @file{.tar} file is typically also given this same | |
144 | name. For example, if you are distributing version 1.3 of the | |
145 | superfrobnicator, the package file would be named | |
146 | ``superfrobnicator-1.3.tar'' and the contents would all appear in the | |
147 | directory @file{superfrobnicator-1.3} in that @file{.tar}. | |
148 | ||
149 | The package must include a @file{-pkg.el} file, named after the | |
150 | package. In our example above, this file would be called | |
151 | @file{superfrobnicator-pkg.el}. This file must have a single form in | |
152 | it, a call to @code{define-package}. The package dependencies and | |
153 | brief description are taken from this form. | |
154 | ||
155 | @defun define-package name version &optional docstring requirements | |
156 | Define a package. @var{name} is the name of the package, a string. | |
157 | @var{version} is the package's version, a string. It must be in a | |
158 | form that can be understood by @code{version-to-list}. | |
159 | @var{docstring} is the short description of the package. | |
160 | @var{requirements} is a list of required packages and their versions. | |
161 | @end defun | |
162 | ||
163 | If a @file{README} file exists in the content directory, then it is | |
164 | used as the long description. | |
165 | ||
166 | If the package has an Info manual, you should distribute the needed | |
167 | info files, plus a @file{dir} file made with @command{install-info}. | |
168 | @xref{Invoking install-info, Invoking install-info, Invoking | |
169 | install-info, texinfo, Texinfo}. | |
170 | ||
171 | Do not include any @file{.elc} files in the package. Those will be | |
172 | created at install time. Note that there is no way to control the | |
173 | order in which files are byte-compiled; your package must be robust | |
174 | here. | |
175 | ||
176 | The installation process will scan all the @file{.el} files in the | |
177 | package for autoload cookies. @xref{Autoload}. They are extracted | |
178 | into a @file{-autoloads.el} file (e.g., | |
179 | @file{superfrobnicator-autoloads.el}), so do not include a file of | |
180 | that name in your package. | |
181 | ||
182 | Any other files in the @file{.tar} file are simply unpacked when the | |
183 | package is installed. This can be useful if your package needs | |
184 | auxiliary data files --- e.g., icons or sounds. | |
185 | ||
186 | Emacs Lisp code installed via the package manager must take special | |
187 | care to be location-independent. One easy way to do this is to make | |
188 | references to auxiliary data files relative to @var{load-file-name}. | |
189 | For example: | |
190 | ||
191 | @smallexample | |
192 | (defconst superfrobnicator-base (file-name-directory load-file-name)) | |
193 | ||
194 | (defun superfrobnicator-fetch-image (file) | |
195 | (expand-file-name file superfrobnicator-base)) | |
196 | @end smallexample |