|
693
|
1 @c -*-texinfo-*-
|
|
|
2 @c This is part of the XEmacs Lisp Reference Manual.
|
|
|
3 @c Copyright (C) 2001 Free Software Foundation, Inc.
|
|
|
4 @c See the file lispref.texi for copying conditions.
|
|
|
5
|
|
|
6 @setfilename ../../info/packaging.info
|
|
|
7
|
|
|
8 @c Macro to make formatting of the XEmacs pms name consistent.
|
|
|
9 @c Maybe @sc looks OK in HTML? If so, condition on Info.
|
|
|
10 @iftex
|
|
|
11 @macro xpms
|
|
|
12 XE@sc{macs} Packaging System
|
|
|
13 @end macro
|
|
|
14 @end iftex
|
|
|
15 @ifnottex
|
|
|
16 @macro xpms
|
|
|
17 XEmacs Packaging System
|
|
|
18 @end macro
|
|
|
19 @end ifnottex
|
|
|
20
|
|
|
21 @node Packaging, Lisp Data Types, Introduction, Top
|
|
|
22 @chapter The @xpms{}
|
|
|
23 @cindex package
|
|
|
24 @cindex packaging
|
|
|
25
|
|
|
26 The XEmacs distribution, starting with version 21, comes only with a
|
|
|
27 very basic set of built-in modes and libraries. Most of the libraries
|
|
|
28 that were part of the distribution of earlier versions of XEmacs are now
|
|
|
29 available separately. The user as well as the system administrator can
|
|
|
30 choose which packages to install; the actual installation process is
|
|
|
31 easy. This gives an installer the ability to tailor an XEmacs
|
|
|
32 installation for local needs with safe removal of unnecessary code.
|
|
|
33
|
|
|
34 This chapter describes how to package Lisp libraries for use with the
|
|
|
35 @xpms{}.
|
|
|
36
|
|
|
37 @emph{Please note carefully} that the term @dfn{package} as used in
|
|
|
38 XEmacs refers to an aggregation of Lisp code and/or data distributed as
|
|
|
39 a unit. It does not, as it does in many Lisps, refer to a way of
|
|
|
40 creating separate name spaces. XEmacs has no facility for providing
|
|
|
41 separate name spaces. (If we ever do get separate name spaces, we'll
|
|
|
42 probably regret overloading the nomenclature in this way, but it's
|
|
|
43 become established.)
|
|
|
44
|
|
|
45 @menu
|
|
|
46 Introduction:
|
|
|
47 * Package Overview:: Lisp Libraries and Packages.
|
|
|
48
|
|
|
49 Packaging Lisp Libraries:
|
|
|
50 * Package Terminology:: Basic stuff.
|
|
|
51 * Building Packages:: Turn packaged source into a tarball.
|
|
|
52 * Local.rules File:: Tell the @xpms{} about your host.
|
|
|
53 * Creating Packages:: Tell the @xpms{} about your package.
|
|
752
|
54 * Documenting Packages:: Explain your package to users and hackers.
|
|
693
|
55 @c * History:: History of the @xpms{}
|
|
|
56 @c * Installation:: Installing the @xpms{} with your (X)Emacs.
|
|
|
57 @c * Configuration:: Configuring the @xpms{} for use.
|
|
|
58 @c * Usage:: An overview of the operation of the @xpms{}.
|
|
|
59 @c * Bug Reports:: Reporting Bugs and Problems
|
|
|
60 @c * Frequently Asked Questions:: Questions and answers from the mailing list.
|
|
|
61
|
|
|
62 Internals and Package Release Engineering:
|
|
|
63 * Issues::
|
|
|
64 @end menu
|
|
|
65
|
|
|
66 @node Package Overview, Package Terminology, , Packaging
|
|
|
67 @chapter An overview of the @xpms{}
|
|
|
68
|
|
|
69 The @xpms{} is a system for administering the installation, upgrade, and
|
|
|
70 removal of Lisp libraries. For the end user, it provides facilities for
|
|
|
71 determining availability of packages and which versions at remote
|
|
|
72 sites. It will download and automatically install a package, ensuring
|
|
|
73 that any old files from previous versions of the package are removed
|
|
|
74 first. By providing a standard set of hierarchies for installation, it
|
|
|
75 makes configuration of XEmacs simpler. Furthermore, packages normally
|
|
|
76 provide ancillary auto-autoloads and custom-loads libraries, which are
|
|
|
77 automatically detected and loaded by XEmacs upon startup. This means
|
|
|
78 that once installed, all facilities of package, including autoloading
|
|
|
79 the library upon invocation of a command provided by the library and
|
|
|
80 convenient configuration and customization, are automatically available
|
|
|
81 to the user. There is no need to add autoloads or keybindings to in the
|
|
|
82 init file, and structured configuration of the package is available
|
|
|
83 through the Customize system even before the libraries are loaded.
|
|
|
84
|
|
|
85 All of this convenience comes at a cost. The cost of administration at
|
|
|
86 the package level is negligible compared to the benefits, of course.
|
|
|
87 However, the requirement that XEmacs find and load auto-autoloads and
|
|
|
88 custom-loads libraries comes at a fairly large cost in startup time. In
|
|
|
89 order to reduce this cost, XEmacs imposes fairly strict conditions on
|
|
|
90 the structure of an installed package.
|
|
|
91
|
|
|
92 Meeting these requirements, as well as simply providing the
|
|
|
93 auto-autoloads and the information about availability and so on does
|
|
|
94 impose some costs on the library maintainer. The @xpms{} also provides
|
|
|
95 structure and utilities to the library maintainer to make these tasks
|
|
|
96 easier. This manual documents the requirements and the tools that the
|
|
|
97 @xpms{} provides to ensure that a package satisfies them.
|
|
|
98
|
|
|
99 @menu
|
|
759
|
100 * The User View::
|
|
|
101 * The Library Maintainer View::
|
|
|
102 * The Package Release Engineer View::
|
|
693
|
103 @end menu
|
|
|
104
|
|
|
105
|
|
759
|
106 @node The User View, The Library Maintainer View, , Package Overview
|
|
|
107 @section The User View
|
|
693
|
108
|
|
|
109 @strong{N.B.} Much of the discussion in this section undoubtedly
|
|
|
110 belongs elsewhere, @ref{Packages,,,xemacs}.
|
|
|
111
|
|
|
112 From the user's point of view, an XEmacs binary package is simply a
|
|
|
113 standard tarball (usually gzipped) containing Lisp sources, compiled
|
|
|
114 Lisp, documentation, and possibly data files or supporting executables.
|
|
|
115 The tarball is unpacked using standard tools such as GNU tar and gzip.
|
|
|
116 The package system does impose certain requirements for automatic
|
|
|
117 configuration to work.
|
|
|
118
|
|
|
119 Here the main consideration is that the tarball ``expects'' to be
|
|
|
120 unpacked from the top of a package hierarchy. A @dfn{package hierarchy}
|
|
|
121 is basically an image of a classic Emacs ``run-in-place'' tree, with
|
|
|
122 @file{lisp}, @file{etc}, @file{info}, @file{man}, @file{lib-src}, and
|
|
|
123 @file{pkginfo} subdirectories of the top. The @file{pkginfo}
|
|
|
124 subdirectory is for use by the @xpms{} administration tools, and
|
|
|
125 currently contains a @file{MANIFEST.@var{package-name}} file for each
|
|
|
126 package to ensure that no cruft remains when a package is removed or
|
|
|
127 updated. The @file{lisp}, @file{etc}, and @file{lib-src} subdirectories
|
|
|
128 are further subdivided, with a subdirectory for each package. The
|
|
694
|
129 @file{info} directory obeys the usual conventions.
|
|
|
130 @emph{I.e.}, the @file{info} directory is flat
|
|
693
|
131 with a(n) (optional) @file{dir} file and one (set of) info file(s) per
|
|
694
|
132 package. The @file{man} subdirectory typically contains documentation
|
|
|
133 sources, separated by package. (It does not contain @file{man(1)}
|
|
|
134 pages, as Emacs provides very few of them.)
|
|
693
|
135
|
|
|
136 There are several standard package hierarchies, and administrators can
|
|
|
137 configure others at build time, while users can configure others at run
|
|
|
138 time. The standard system hierarchies are all subdirectories of an
|
|
|
139 @c #### This is possibly incorrect usage of "installation root."
|
|
|
140 XEmacs installation root, typically @file{/usr/local/lib/xemacs/}.
|
|
|
141 These are the @file{xemacs-packages}, @file{mule-packages},
|
|
|
142 @file{infodock-packages}, and @file{site-packages} hierarchies. Each
|
|
|
143 has the structure described above, but the purposes differ. The
|
|
|
144 @file{xemacs-packages} is the normal place for installing ``official''
|
|
|
145 packages and many third-party libraries. Unfortunately, it is not yet
|
|
|
146 quite possible to read libraries containing international characters
|
|
|
147 with a non-Mule XEmacs, so such libraries are sequestered in the
|
|
|
148 @file{mule-packages} hierarchy. Some packages are compatible only with
|
|
|
149 the Infodock development environment, and they will be installed in the
|
|
|
150 @file{infodock-packages} hierarchy. The @file{site-packages} hierarchy
|
|
|
151 is for packages not distributed by XEmacs.org, typically locally
|
|
|
152 developed.
|
|
|
153
|
|
|
154 Packages are in principle supposed to be XEmacs version-independent, but
|
|
|
155 if such dependencies are unavoidable, additional standard package
|
|
|
156 hierarchies may be installed under version directories, @emph{e.g.}
|
|
|
157 @file{/usr/local/lib/xemacs-21.4.6/}.
|
|
|
158
|
|
|
159 Users who do not have sufficient privilege to install packages in the
|
|
|
160 system hierarchies may install package hierarchies under
|
|
|
161 @file{~/.xemacs}. At present only the @file{xemacs-packages} and
|
|
|
162 @file{mule-packages} hierarchies are supported, but it might make sense
|
|
|
163 to extend this to support @file{infodock-packages} and
|
|
|
164 @file{site-packages} hierarchies in the future.
|
|
|
165
|
|
|
166 The package hierarchies are not searched directly for libraries to be
|
|
|
167 loaded; this would be very costly. Instead, the hierarchies are ordered
|
|
|
168 according to certain rules, and searched for package lisp directories at
|
|
|
169 invocation. These directories are added to the general
|
|
|
170 @code{load-path}. As usual, it is @code{load-path} that is searched at
|
|
|
171 run-time. This approach is somewhat costly at initialization, but
|
|
|
172 results in a very ``clean'' @code{load-path}.
|
|
|
173
|
|
|
174 The order of search can be changed at build time by specifying the
|
|
|
175 @samp{--package-path} option to @file{configure}, or at run-time by
|
|
|
176 specifying the @code{EMACSPACKAGEPATH} environment variable.
|
|
|
177 @xref{Packages,,,xemacs}.
|
|
|
178
|
|
|
179 @c #### The following description is quite possibly inaccurate.
|
|
694
|
180 @c Please, Michael, write some specs up!
|
|
693
|
181 The default order of search is hierarchically determined. First, the
|
|
|
182 roots are ordered. The @dfn{early} roots are the user-specific roots,
|
|
|
183 typically @file{~/.xemacs}. The @dfn{late} roots are the system roots,
|
|
|
184 typically @file{/usr/local/lib/xemacs-21.4.6} and
|
|
|
185 @file{/usr/local/lib/xemacs}, in that order. All hierarchies for a
|
|
|
186 given root are searched for package Lisp directories, which are appended
|
|
|
187 to @code{load-path} in the order found. Then the search proceeds to the
|
|
|
188 next root, whose results will be appended to the @code{load-path}
|
|
|
189 generated by previous roots.
|
|
|
190
|
|
|
191 Second, the hierarchies below each root are searched in the order
|
|
|
192 @file{site-packages}, @file{infodock-packages}, @file{mule-packages},
|
|
|
193 then @file{xemacs-packages}.
|
|
|
194
|
|
|
195 In each hierarchy there should be a @file{lisp} subdirectory, containing
|
|
|
196 directories named for the packages. Each package's Lisp libraries thus
|
|
|
197 are contained in a directory of the form
|
|
|
198 @var{root}/@var{hierarchy}/lisp/@var{package}/.
|
|
|
199
|
|
|
200 With such a complex search algorithm, the possibility of libraries being
|
|
|
201 shadowed by another library with the same name is quite real. There are
|
|
|
202 two considerations here. First, every XEmacs package contains certain
|
|
|
203 libraries with constant names. These are
|
|
|
204
|
|
|
205 @table @file
|
|
|
206 @item _pkg.el
|
|
|
207 Lisp code to inform the package administration system about the package
|
|
|
208
|
|
|
209 @item auto-autoloads.el
|
|
|
210 Lisp code to set up autoloaded functions and variables that may be
|
|
|
211 needed at load time
|
|
|
212
|
|
|
213 @item custom-load.el
|
|
|
214 definitions of configuration variables for use with the Customize
|
|
|
215 system.
|
|
|
216 @end table
|
|
|
217
|
|
|
218 They are special-cased, because the way they are used prevents shadowing
|
|
|
219 from being an issue.
|
|
|
220
|
|
|
221 Second, it is possible that multiple copies of some library, or
|
|
|
222 different libraries with the same name, are installed in various places
|
|
|
223 in the hierarchies. To detect such shadows, use
|
|
|
224 @code{list-load-path-shadows}.
|
|
|
225
|
|
|
226 Finally, note that most basic Emacs functionality, including most of the
|
|
|
227 Lisp API, is implemented in Lisp libraries. Because they use internal
|
|
|
228 reserved APIs that are subject to change according the needs of the
|
|
|
229 developers, these libraries are distributed with the XEmacs binary, and
|
|
|
230 are called @dfn{core Lisp libraries}. Most core Lisp libraries are
|
|
|
231 ``preloaded'' into the Emacs binary and in normal usage are never
|
|
|
232 explicitly loaded. However, they can be explicitly loaded, and if so
|
|
|
233 they are searched on @code{load-path}.
|
|
|
234 @c #### Is this correct? It is not for C-h f, for example.
|
|
|
235 Furthermore, functions such as @code{locate-library} will also search on
|
|
|
236 the @code{load-path}. The searching takes place under somewhat
|
|
|
237 different rules from those used for packaged Lisp. It is probably
|
|
|
238 easiest to think of the package hierarchy searching algorithm as
|
|
|
239 receiving a @code{load-path} initialized to the core Lisp directories.
|
|
|
240
|
|
|
241
|
|
759
|
242 @node The Library Maintainer View, The Package Release Engineer View, The User View, Package Overview
|
|
|
243 @section The Library Maintainer View
|
|
693
|
244
|
|
|
245 From the library maintainer's viewpoint, the advantages to the @xpms{}
|
|
|
246 stem from the convenience to the user of installation and upgrade.
|
|
|
247 Since an installed package automatically registers its entry points via
|
|
|
248 autoload and its configuration variables with the Customize system,
|
|
|
249 configuration FAQs are reduced. When it's easy to upgrade, users learn
|
|
|
250 to try @samp{Tools | Packages | Update Installed Packages} before
|
|
|
251 posting a FAQ whose answer is ``long since fixed, please upgrade.''
|
|
|
252
|
|
|
253 This comes at some cost, as the library maintainer needs to arrange that
|
|
|
254 the package be installed in a directory structure that satisfies the
|
|
|
255 requirements of the @xpms{}. Autoload cookies and defcustoms must also
|
|
|
256 be added to existing libraries. The @xpms{} provides infrastructure to
|
|
|
257 assure that all of these annoyances need only be dealt with once. The
|
|
|
258 autoload cookies and defcustoms are beyond the scope of this chapter, but
|
|
|
259 most maintainers of modern packages are already familiar with these
|
|
|
260 mechanisms.
|
|
|
261
|
|
|
262 The @xpms{} may be divided into the @dfn{infrastructure} common to all
|
|
|
263 packages, and the package-specific @dfn{control files}. The
|
|
|
264 infrastructure supports global builds, installation, and generation of
|
|
|
265 the ``sumo'' bundles of packages, as well as generation of individual
|
|
|
266 packages. The package control files describe the structure of the
|
|
|
267 package's source tree and provide administrative information.
|
|
|
268
|
|
|
269 @menu
|
|
|
270 * Infrastructure:: Global Makefiles and common rules.
|
|
|
271 * Control Files:: Package-specific Makefiles and administrative files.
|
|
|
272 * Obtaining:: Obtaining the @xpms{} and required utilities.
|
|
|
273 @end menu
|
|
|
274
|
|
759
|
275 @node Infrastructure, Control Files, , The Library Maintainer View
|
|
693
|
276 @subsection Infrastructure
|
|
|
277
|
|
|
278 In order to get the greatest benefit from the @xpms{}, a library
|
|
|
279 maintainer should place the package sources in an appropriate place in
|
|
|
280 the XEmacs source package hierarchy, and arrange to have the source
|
|
|
281 package imported into the XEmacs CVS repository.
|
|
|
282 @c #### the parenthetical remark should go to "issues."
|
|
|
283 (We realize that the
|
|
|
284 latter requirement can be quite burdensome. We are working on ways to
|
|
|
285 remove this requirement, but for the present it remains necessary.) The
|
|
|
286 library maintainer must also keep sources for any packages his/her
|
|
|
287 package requires. This requirement is somewhat burdensome, but unlikely
|
|
|
288 to be relaxed because of the implementation of compilation of macros in
|
|
|
289 Emacs Lisp. Macros cannot be called by compiled Lisp (the macro
|
|
|
290 expansion, which is always known at compile time, is inlined), so the
|
|
|
291 source of the macro must be loaded before compiling the called function.
|
|
|
292
|
|
|
293 The source package hierarchy may be rooted anywhere. The CVS module is
|
|
|
294 called ``packages,'' so we will refer to the top directory of the source
|
|
|
295 package hierarchy as ``the @file{packages} directory.'' The
|
|
|
296 @file{packages} directory contains two source subdirectories,
|
|
|
297 @file{xemacs-packages} and @file{mule-packages} (for convenience in
|
|
|
298 segregating the packages which depend on Mule, as they will cause
|
|
|
299 load-time errors in a non-Mule XEmacs). Each subdirectory contains many
|
|
|
300 package source directories, whose internal structure is not specified.
|
|
|
301 That structure is left up to the convenience of the library maintainers.
|
|
|
302 The requirements on the top directory of an individual package source
|
|
|
303 tree are given below, @ref{Control Files}.
|
|
|
304
|
|
|
305 The @file{packages} directory contains some auxiliary Lisp libraries
|
|
|
306 used in the compilation and packaging process. The content of these
|
|
761
|
307 libraries is of interest primarily to the packaging engineers, @ref{The
|
|
|
308 Package Release Engineer View}.
|
|
693
|
309
|
|
|
310 Finally, the @file{packages}, @file{packages/xemacs-packages}, and
|
|
|
311 @file{packages/mule-packages} directories contain @file{Makefile}s and
|
|
|
312 include files to control the package creation process. The
|
|
|
313 @file{Makefile}s in @file{packages/xemacs-packages} and
|
|
|
314 @file{packages/mule-packages} simply define the default sets of known
|
|
|
315 packages and include @file{../iterate.rules}, which implements recursive
|
|
|
316 building of all target packages.
|
|
|
317
|
|
|
318 The @samp{make} infrastructure in @file{packages} includes
|
|
|
319
|
|
|
320 @table @file
|
|
|
321 @item Makefile
|
|
|
322 controls building of individual packages, local installation, and
|
|
|
323 bundling of ``sumo'' tarballs
|
|
|
324
|
|
|
325 @item iterate.rules
|
|
|
326 controls recursive builds of multiple packages
|
|
|
327
|
|
|
328 @item XEmacs.rules
|
|
|
329 provides the rules for building and packaging. Included by all package
|
|
|
330 @file{Makefile}s.
|
|
|
331
|
|
|
332 @item Local.rules
|
|
|
333 provides local configuration, such as installation targets and staging
|
|
|
334 directories, as well as a number of kludges (many now obsolete) required
|
|
|
335 for building packages on the Windows platform.
|
|
|
336
|
|
|
337 @item Local.rules.template
|
|
|
338 a template for Local.rules, liberally commented
|
|
|
339
|
|
|
340 @item Local.rules.mk
|
|
|
341 consistency checking for @file{Local.rules}, included by both the
|
|
|
342 top-level @file{Makefile} and by @file{XEmacs.rules}.
|
|
|
343
|
|
|
344 @c #### Add to "issues"
|
|
|
345 @item package-compile.el
|
|
|
346 compile environment (@emph{e.g.}, load-path) setup. It is very bogus
|
|
|
347 that this is here, an alternative mechanism is likely to be provided.
|
|
|
348 @end table
|
|
|
349
|
|
|
350 Of these, only @file{Local.rules} and @file{package-compile.el} need to
|
|
|
351 be modified by the library maintainer. The changes to Local.rules
|
|
|
352 affect only your environment. This should need to be done only once
|
|
|
353 when first preparing the source environment. The necessary
|
|
|
354 modifications to @file{package-compile.el} need to be done for each
|
|
|
355 package and are discussed in the next section, @ref{Control Files}.
|
|
|
356
|
|
|
357
|
|
759
|
358 @node Control Files, Obtaining, Infrastructure, The Library Maintainer View
|
|
693
|
359 @subsection Control Files
|
|
|
360
|
|
|
361 Each package source must contain a number of control files in the
|
|
|
362 top-level directory. These files in general can be created and then
|
|
|
363 ignored, except for a few variables that need to be updated when new
|
|
|
364 versions are released. In most cases even adding, renaming, and
|
|
|
365 removing library source files can be handled by generic rules.
|
|
|
366
|
|
|
367 The package control files include
|
|
|
368
|
|
|
369 @table @file
|
|
|
370 @item Makefile
|
|
|
371 Must set a few @file{make} variables used by the administrative
|
|
|
372 utilities, and defines a couple of package-building targets to depend on
|
|
|
373 appropriate targets defined generically in @file{XEmacs.rules}. It may
|
|
|
374 also provide various variables and rules to transform the source tree
|
|
|
375 structure into that expected by the run-time system.
|
|
|
376
|
|
|
377 @item package-info.in
|
|
|
378 Provides a template for package information to be provided to the
|
|
|
379 administrative utilities. Static variables that are rarely changed
|
|
|
380 (such as the package's name) are entered as literals. Some variables
|
|
|
381 are generated by the build process (build dates and MD5 checksums) and
|
|
|
382 are automatically filled in. Finally, some variables that change
|
|
|
383 irregularly (dependences and even version numbers) are set as
|
|
|
384 @file{make} variables in the @file{Makefile}.
|
|
|
385
|
|
|
386 @item ChangeLog
|
|
|
387 Not strictly required, but normally a ChangeLog will be added by the
|
|
|
388 XEmacs package maintainer if different from the upstream maintainer.
|
|
|
389
|
|
|
390 @item package-compile.el
|
|
|
391 compile environment (@emph{e.g.}, load-path) setup. It is very bogus
|
|
|
392 that this is here, an alternative mechanism is likely to be provided.
|
|
|
393
|
|
|
394 @item _pkg.el
|
|
|
395 Generated. Simply does a @code{package-provide} for the package.
|
|
|
396
|
|
|
397 @item _auto-autoloads.el
|
|
|
398 Generated. Read when XEmacs is initialized, and provides autoloads for
|
|
|
399 all defuns and other specially-marked forms in the sources.
|
|
|
400
|
|
|
401 @item custom-loads.el
|
|
|
402 Generated. Read when XEmacs is initialized, and informs the Customize
|
|
|
403 subsystem how to find the defcustom forms needed to create Customization
|
|
|
404 forms for the usre configuration variables of the package.
|
|
|
405 @end table
|
|
|
406
|
|
|
407
|
|
759
|
408 @node Obtaining, , Control Files, The Library Maintainer View
|
|
693
|
409 @subsection Obtaining the @xpms{} and Required Utilities
|
|
|
410
|
|
|
411 Currently both the infrastructure for creating XEmacs packages and the
|
|
|
412 package sources themselves are available only by CVS. See
|
|
|
413 @uref{http://www.xemacs.org/Develop/cvsaccess.html} for more
|
|
|
414 intformation.
|
|
|
415
|
|
|
416 The @xpms{} currently requires GNU @file{make}, and probably XEmacs, to
|
|
|
417 build packages.
|
|
|
418
|
|
|
419
|
|
759
|
420 @node The Package Release Engineer View, , The Library Maintainer View, Package Overview
|
|
|
421 @subsection The Package Release Engineer View
|
|
693
|
422
|
|
694
|
423 The XEmacs Package Release Engineer is responsible for keeping the
|
|
|
424 system coherent. The changes to @file{packages/package-compile.el} and
|
|
|
425 @file{packages/xemacs-packages/Makefile} required to make the package
|
|
|
426 available to others, and for building SUMO tarballs, @emph{etc}, are
|
|
|
427 done by the Package Release Engineer, not individual library
|
|
|
428 maintainers.
|
|
693
|
429
|
|
694
|
430 The Package Release Engineer also maintains assorted infrastructure for
|
|
|
431 actually making releases. These are generally available for inspection
|
|
|
432 in the @code{xemacs-builds} module in the CVS repository.
|
|
|
433
|
|
|
434 @c #### To be completed.
|
|
693
|
435
|
|
|
436
|
|
|
437 @c #### The following section is lifted verbatim from the XEmacs User's
|
|
|
438 @c Manual, file packages.texi.
|
|
|
439 @node Package Terminology, Building Packages, Package Overview, Packaging
|
|
|
440 @comment node-name, next, previous, up
|
|
|
441 @heading Package Terminology:
|
|
|
442
|
|
|
443 @subsection Libraries and Packages
|
|
|
444 @cindex library
|
|
|
445 @cindex package
|
|
|
446
|
|
|
447 A Lisp @dfn{library} is a single loadable file containing Lisp code. It
|
|
|
448 may be in source or byte-compiled form. A Lisp @dfn{package} is a set
|
|
|
449 of one or more libraries, usually related to each other in some way,
|
|
|
450 bundled with administrative information for convenient distribution.
|
|
|
451
|
|
|
452 @subsection Package Flavors
|
|
|
453
|
|
|
454 There are two main flavors of packages.
|
|
|
455
|
|
|
456 @table @strong
|
|
|
457 @item Regular Packages
|
|
|
458 @cindex regular package
|
|
|
459 A regular package is a set of Lisp libraries design to cooperate with
|
|
|
460 one another. A very complex example is Gnus. One may not in general
|
|
|
461 safely remove any of the component libraries.
|
|
|
462
|
|
|
463 @item Single-File Packages
|
|
|
464 @cindex single-file package
|
|
901
|
465 A single-file package is a collection of thematically related but
|
|
693
|
466 otherwise independent Lisp libraries. These libraries are bundled
|
|
|
467 together for convenience of the maintainers. Usually individual
|
|
|
468 libraries may be deleted at will without any loss of functionality of
|
|
|
469 other libraries in the package. However, we would recommend that you
|
|
|
470 follow this rule of thumb: "When in doubt, don't delete". If it's
|
|
|
471 really that big a deal, request that the maintainers split the package
|
|
|
472 into smaller aggregations.
|
|
|
473 @end table
|
|
|
474
|
|
|
475 @subsection Package Distributions
|
|
|
476 @cindex package distributions
|
|
|
477 @cindex binary packages
|
|
|
478 @cindex source packages
|
|
|
479 XEmacs Lisp packages are distributed in two ways. @dfn{Binary packages}
|
|
|
480 are used by system administrators and end users. They are packaged in a
|
|
|
481 form convenient for direct installation into an XEmacs package
|
|
|
482 hierarchy. @dfn{Source packages} are for developers and include all
|
|
|
483 files necessary for rebuilding byte-compiled lisp and creating tarballs
|
|
|
484 for distribution or installation. This is all of the package author's
|
|
|
485 source code plus all of the files necessary to build distribution
|
|
|
486 tarballs (Unix Tar format files, gzipped for space savings).
|
|
|
487 @c #### This next is an Evile Practice and should be discontinued.
|
|
|
488 (Occasionally sources that are not relevant to XEmacs are removed.)
|
|
|
489
|
|
|
490 Currently, source packages are only available via CVS. See
|
|
|
491 @url{http://www.xemacs.org/Develop/cvsaccess.html} for details.
|
|
|
492
|
|
|
493 The package distributions are also split according to major features
|
|
|
494 required in XEmacs to support them. At present there are @dfn{generic}
|
|
|
495 packages, which can be loaded by @emph{any} XEmacs, and @dfn{Mule}
|
|
|
496 packages, which @emph{require} Mule support or they will cause errors
|
|
|
497 when loaded. Note that there is no guarantee that a generic package
|
|
|
498 will have any useful functionality in a minimally configured XEmacs. As
|
|
|
499 long as any XEmacs can successfully load the package's libraries
|
|
|
500 (perhaps given other required Lisp libraries), it will be classified as
|
|
|
501 generic. At the present time only Mule packages need be treated
|
|
|
502 specially, and even those only if they contain multibyte characters.
|
|
|
503
|
|
|
504
|
|
|
505 @c #### The following section is lifted verbatim from the XEmacs User's
|
|
|
506 @c Manual, file packages.texi.
|
|
|
507 @node Building Packages, Local.rules File, Package Terminology, Packaging
|
|
|
508 @comment node-name, next, previous, up
|
|
|
509 @cindex building packages
|
|
|
510 @cindex package building
|
|
|
511 @heading Building Packages:
|
|
|
512 Currently, source packages are only available via anonymous CVS. See
|
|
|
513 @url{http://www.xemacs.org/Develop/cvsaccess.html} for details of
|
|
|
514 checking out the @file{packages} module.
|
|
|
515
|
|
|
516 @subsection Prerequisites for Building Source Packages
|
|
|
517
|
|
|
518 @table @code
|
|
|
519 @item GNU cp
|
|
|
520 @item GNU install
|
|
|
521 (or a BSD compatible install program).
|
|
|
522 @item GNU make
|
|
|
523 (3.75 or later preferred).
|
|
|
524 @item makeinfo
|
|
|
525 (1.68 from texinfo-3.11 or later required, 1.69 from Texinfo 4 preferred).
|
|
|
526 @item GNU tar
|
|
|
527 (or equivalent).
|
|
|
528 @item GNU gzip
|
|
|
529 (or equivalent).
|
|
|
530 @item A properly configured @file{Local.rules} file.
|
|
|
531 @ref{Local.rules File}.
|
|
|
532 @end table
|
|
|
533
|
|
|
534 And of course, XEmacs, 21.0 or higher.
|
|
|
535
|
|
|
536 @subsection What You Can Do With Source Packages
|
|
|
537
|
|
|
538 The packages CVS sources are most useful for creating XEmacs package
|
|
|
539 tarballs for installation into your own XEmacs installations or for
|
|
|
540 distributing to others.
|
|
|
541
|
|
|
542 The supported @file{make} targets are:
|
|
|
543
|
|
|
544 @table @code
|
|
|
545 @item all
|
|
|
546 Bytecompile all files, build and bytecompile byproduct files like
|
|
|
547 @file{auto-autoloads.el} and @file{custom-load.el}. Create info version
|
|
|
548 of TeXinfo documentation if present.
|
|
|
549
|
|
|
550 @c #### Why do we need this _and_ the binkit target?
|
|
|
551 @item bindist
|
|
|
552 Does a @code{make all} as well as create a binary package tarball in the
|
|
|
553 staging directory.
|
|
|
554
|
|
|
555 @item install
|
|
|
556 Bytecompile all files, build and bytecompile byproduct files like
|
|
|
557 @file{auto-autoloads.el} and @file{custom-load.el}. Create info version
|
|
|
558 of TeXinfo documentation if present. And install everything into the
|
|
|
559 staging directory.
|
|
|
560
|
|
|
561 @item srckit
|
|
|
562 Usually simply depends on @code{srckit-std}, with no actions. This does
|
|
|
563 a @code{make distclean} and creates a package source tarball in the
|
|
|
564 staging directory. This is generally only of use for package
|
|
|
565 maintainers.
|
|
|
566
|
|
|
567 @item binkit
|
|
|
568 May depend on @code{binkit-sourceonly}, @code{binkit-sourceinfo},
|
|
|
569 @code{binkit-sourcedata}, or @code{binkit-sourcedatainfo}, with no
|
|
|
570 actions. @code{sourceonly} indicates there is nothing to install in a
|
|
|
571 data directory or info directory. @code{sourceinfo} indicates that
|
|
|
572 source and info files are to be installed. @code{sourcedata} indicates
|
|
|
573 that source and etc (data) files are to be installed.
|
|
|
574 @code{sourcedatainfo} indicates source, etc (data), and info files are
|
|
|
575 to be installed. A few packages have needs beyond the basic templates
|
|
|
576 so this is not yet complete.
|
|
|
577
|
|
|
578 @item dist
|
|
|
579 Runs the rules @code{srckit} followed by @code{binkit}. This is
|
|
|
580 primarily of use by XEmacs maintainers producing files for distribution.
|
|
|
581
|
|
|
582 @item clean
|
|
|
583 Remove all built files except @file{auto-autoloads.el} and
|
|
|
584 @file{custom-load.el}.
|
|
|
585
|
|
|
586 @item distclean
|
|
|
587 Remove all created files.
|
|
|
588 @end table
|
|
|
589
|
|
|
590 @c #### The following section is lifted verbatim from the XEmacs User's
|
|
|
591 @c Manual, file packages.texi.
|
|
|
592 @node Local.rules File, Creating Packages, Building Packages, Packaging
|
|
|
593 @comment node-name, next, previous, up
|
|
|
594 @cindex local.rules
|
|
|
595 @heading The Local.rules File:
|
|
|
596 This file in @file{packages} provides the @xpms{} with information about
|
|
|
597 the local configuration and environment. To create @file{Local.rules},
|
|
|
598 simply copy @file{Local.rules.template} from that directory to
|
|
|
599 @file{Local.rules} and edit it to suit your needs.
|
|
|
600
|
|
|
601 These are the variables in @file{Local.rules} that you will need to
|
|
|
602 provide values for. The following variables control which packages will
|
|
|
603 be built:
|
|
|
604
|
|
|
605 @table @var
|
|
|
606 @item XEMACS_PACKAGES
|
|
|
607 The default is @samp{xemacs-packages}, which results in the set in
|
|
|
608 the @file{xemacs-packages/Makefile} @code{PACKAGES} variable.
|
|
|
609
|
|
|
610 Otherwise, it should be a list of package source directories prefixed by
|
|
|
611 @samp{xemacs-packages}:
|
|
|
612
|
|
|
613 @example
|
|
|
614 XEMACS_PACKAGES = xemacs-packages/xemacs-base xemacs-packages/bbdb
|
|
|
615 @end example
|
|
|
616
|
|
|
617 @item BUILD_WITHOUT_MULE
|
|
|
618 The default is the empty value.
|
|
|
619
|
|
|
620 Building from CVS defaults to building the Mule
|
|
|
621 packages. Set this to 't' if you don't want/have Mule.
|
|
|
622
|
|
|
623 @item MULE_PACKAGES
|
|
|
624 The default is @samp{mule-packages}, which results in the set in
|
|
|
625 the @file{mule-packages/Makefile} @code{PACKAGES} variable.
|
|
|
626
|
|
|
627 Otherwise, it should be a list of package source directories prefixed by
|
|
|
628 @samp{mule-packages}:
|
|
|
629
|
|
|
630 @example
|
|
|
631 MULE_PACKAGES = mule-packages/mule-base mule-packages/skk
|
|
|
632 @end example
|
|
|
633
|
|
|
634 @item PACKAGE_INDEX
|
|
|
635 The default is @file{package-index}.
|
|
|
636
|
|
|
637 If you want the package index file to have a different name, change
|
|
|
638 this. This is probably a bad idea unless you are a packages release
|
|
|
639 engineer, as it will confuse the package administration tools.
|
|
|
640 @end table
|
|
|
641
|
|
|
642 The following variables determine where files are installed and how they
|
|
|
643 are installed. Several of the defaults use the variable
|
|
|
644 @var{XEMACS_PACKAGES_BASE}. Never set this variable in
|
|
|
645 @file{Local.rules}; it is automatically set in @file{XEmacs.rules}.
|
|
|
646
|
|
|
647 @table @asis
|
|
|
648 @item @var{XEMACS_STAGING}
|
|
|
649 The default is @file{$@{XEMACS_PACKAGES_BASE@}/../xemacs-packages}.
|
|
|
650
|
|
|
651 Generic packages will be installed here. This can be the final
|
|
|
652 destination for files or symlinks (if the packages are being installed
|
|
|
653 locally), or a clean staging area for building tarballs.
|
|
|
654
|
|
|
655 @strong{N.B.} @samp{make bindist} ignores this variable. It should be
|
|
|
656 handled by the administration utilities, but currently isn't.
|
|
|
657
|
|
|
658 @item @var{MULE_STAGING}
|
|
|
659
|
|
|
660 The default is @file{$@{XEMACS_PACKAGES_BASE@}/../mule-packages}.
|
|
|
661
|
|
|
662 Packages requiring Mule to load correctly will be installed here. This
|
|
|
663 can be the final destination for files or symlinks (if the packages are
|
|
|
664 being installed locally), or a clean staging area for building tarballs.
|
|
|
665
|
|
|
666 @strong{N.B.} @samp{make bindist} ignores this variable. It should be
|
|
|
667 handled by the administration utilities, but currently isn't.
|
|
|
668
|
|
|
669 @item symlink
|
|
|
670 The default is the empty value.
|
|
|
671
|
|
|
672 Set this to 't' if you want to simulate ``running in place.'' It is
|
|
|
673 currently not possible to ask XEmacs to use any package source tree as
|
|
|
674 an automatically configured member of @code{load-path}, and it is
|
|
|
675 unlikely that complex trees such as that of the Gnus package will ever
|
|
|
676 be able to ``run in place.'' This variable, when set to `t', causes the
|
|
|
677 build process to create a symlink farm otherwise identical to an
|
|
|
678 installed tree of binary packages. Thus it is purely a space
|
|
|
679 optimization.
|
|
|
680
|
|
|
681 Setting this is incompatible with @samp{make bindist}.
|
|
|
682 @end table
|
|
|
683
|
|
|
684 The following variables determine how packages are made.
|
|
|
685
|
|
|
686 @table @var
|
|
|
687 @item XEMACS
|
|
|
688 The default is @samp{xemacs}.
|
|
|
689
|
|
|
690 The path to the XEmacs executable you wish to use to compile the
|
|
|
691 packages and execute Lisp build scripts.
|
|
|
692
|
|
|
693 @item XEMACS_NATIVE_NT
|
|
|
694 The default is the empty value.
|
|
|
695
|
|
|
696 Set this to 't' if you are building on WinNT. It controls hairy shell
|
|
|
697 quoting in the @file{Makefile}s.
|
|
|
698
|
|
|
699 @item INSTALL
|
|
|
700 The default is @samp{install -c}.
|
|
|
701
|
|
|
702 The path to your BSD compatible install program.
|
|
|
703
|
|
|
704 @item TAR
|
|
|
705 The default is @samp{tar}.
|
|
|
706
|
|
|
707 The path to your tar program.
|
|
|
708
|
|
|
709 @item BZIP2
|
|
|
710 The default is the empty value.
|
|
|
711
|
|
|
712 If unset, bzipped tarballs will not be built. If this is set to
|
|
|
713 something that resolves to a @samp{bzip2} executable, bzip2 tarballs
|
|
|
714 will be built @emph{in addition to} @samp{gzip} tarballs.
|
|
|
715
|
|
|
716 @item MAKEINFO
|
|
|
717 The default is @samp{makeinfo}.
|
|
|
718
|
|
|
719 The path to your @file{makeinfo} program
|
|
|
720 @end table
|
|
|
721
|
|
|
722
|
|
|
723 @c #### The following section is lifted verbatim from the XEmacs User's
|
|
|
724 @c Manual, file packages.texi.
|
|
752
|
725 @node Creating Packages, Documenting Packages, Local.rules File, Packaging
|
|
693
|
726 @comment node-name, next, previous, up
|
|
|
727 @cindex creating packages
|
|
|
728 @heading Creating Packages:
|
|
|
729 Creating a package from an existing Lisp library is not very difficult.
|
|
|
730
|
|
|
731 In addition to the Lisp libraries themselves, you need a
|
|
|
732 @file{package-info.in} file and a simple @file{Makefile}. The rest is
|
|
|
733 done by @file{XEmacs.rules}, part of the packaging system
|
|
|
734 infrastructure.
|
|
|
735
|
|
|
736 @file{package-info.in} contains a single Lisp form like this:
|
|
|
737
|
|
|
738 @example
|
|
|
739 (NAME ; your package's name
|
|
|
740 (standards-version 1.1
|
|
|
741 version VERSION ; Makefile
|
|
|
742 author-version AUTHOR_VERSION ; Makefile
|
|
|
743 date DATE ; Makefile
|
|
|
744 build-date BUILD_DATE ; generated
|
|
|
745 maintainer MAINTAINER ; Makefile
|
|
|
746 distribution DISTRIBUTION ; "mule" if MULE is needed,
|
|
|
747 ; else "xemacs"
|
|
|
748 priority high
|
|
|
749 category CATEGORY ; Makefile
|
|
|
750 dump nil
|
|
1613
|
751 description "DESCRIPTION" ; a one-line period-terminated string
|
|
693
|
752 filename FILENAME ; obsolete
|
|
|
753 md5sum MD5SUM ; generated
|
|
|
754 size SIZE ; generated
|
|
|
755 provides (FEATURE ...) ; one for every `provides' form
|
|
|
756 requires (REQUIRES) ; Makefile
|
|
|
757 ; NOT run-time dependencies! These
|
|
|
758 ; are files that provide macros or
|
|
|
759 ; defsubsts that must be inlined.
|
|
|
760 type regular
|
|
|
761 ))
|
|
|
762 @end example
|
|
|
763
|
|
|
764 You should replace NAME, DISTRIBUTION, DESCRIPTION, and FEATURE ... with
|
|
1613
|
765 appropriate values, according to the comments. As a matter of style,
|
|
|
766 the first letter of the description should be capitalized, and the
|
|
|
767 string should end with a period. It need not be a complete sentence
|
|
|
768 grammatically. Fields marked as @samp{obsolete} can be ignored. Fields
|
|
|
769 marked as @samp{generated} are generated by the package construction
|
|
|
770 process, and will be filled in automatically. Fields marked as
|
|
|
771 @samp{Makefile} should be set as variables in the @file{Makefile}.
|
|
693
|
772
|
|
|
773 The @samp{provides} can be done automatically, but currently aren't. It
|
|
|
774 would probably be a good idea to set them in the @file{Makefile} (they
|
|
|
775 do change, fairly often, but at present they aren't.
|
|
|
776
|
|
749
|
777 @c #### This organization sucks. Should break up by component, with
|
|
|
778 @c theory of operations, example, and reference subsections.
|
|
693
|
779 The @file{Makefile} is quite stylized. The idea is similar to an
|
|
|
780 @file{Imakefile} or an @code{automake} file: the complexity is hidden in
|
|
|
781 generic rules files, in this case the @file{XEmacs.rules} include file
|
|
|
782 in the top directory of the packages hierarchy.
|
|
|
783
|
|
749
|
784 It is important to note that the XEmacs used to compile packages is the
|
|
|
785 bare minimum: it is called with the @samp{-no-user-file -no-site-file
|
|
|
786 -no-autoloads}. This means that anything not dumped into XEmacs by
|
|
|
787 default needs to be specified in the @samp{REQUIRES} variable (for
|
|
|
788 packaged Lisp) or in some cases the @samp{PRELOADS} (autoloads used in
|
|
|
789 libraries mentioned in @samp{PRELOADS}).
|
|
|
790
|
|
693
|
791 An @xpms{} @file{Makefile} has three components. First, there is a
|
|
|
792 variable definition section. The standard @xpms{} @file{make} variables
|
|
|
793 must be defined here for use by the @file{XEmacs.rules} include file.
|
|
|
794 Second, the file @file{../../XEmacs.rules} is included. Finally, the
|
|
|
795 @file{make} rules are defined, possibly including additional variable
|
|
|
796 definitions for use by the @file{Makefile}. These always include rules
|
|
|
797 for the targets @samp{all}, @samp{binkit}, and @file{srckit}.
|
|
|
798
|
|
|
799 Although a number of facilities are available for complex libraries,
|
|
|
800 most simple packages' @file{Makefile}s contain a copyright notice, the
|
|
|
801 variable definitions mentioned above, and some boilerplate.
|
|
|
802
|
|
|
803 @example
|
|
|
804 # Makefile for apackage's lisp code
|
|
|
805
|
|
|
806 # This file is part of XEmacs.
|
|
|
807
|
|
|
808 # XEmacs is free software; you can redistribute it and/or modify it
|
|
|
809 # under the terms of the GNU General Public License as published by the
|
|
|
810 # Free Software Foundation; either version 2, or (at your option) any
|
|
|
811 # later version.
|
|
|
812
|
|
|
813 # XEmacs is distributed in the hope that it will be useful, but WITHOUT
|
|
|
814 # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
|
|
815 # FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
|
|
|
816 # for more details.
|
|
|
817
|
|
|
818 # You should have received a copy of the GNU General Public License
|
|
|
819 # along with XEmacs; see the file COPYING. If not, write to
|
|
|
820 # the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
|
|
|
821 # Boston, MA 02111-1307, USA.
|
|
|
822
|
|
|
823 VERSION = 0.00
|
|
|
824 AUTHOR_VERSION = 0.00
|
|
|
825 MAINTAINER = A. M. Aintainer <ama@@not.a.doc>
|
|
|
826 PACKAGE = apackage
|
|
|
827 PKG_TYPE = regular
|
|
|
828 REQUIRES = xemacs-base
|
|
|
829 CATEGORY = standard
|
|
|
830
|
|
|
831 # All .els should be compiled and packaged.
|
|
|
832 ELS = $(wildcard *.el)
|
|
|
833 ELCS = $(ELS:.el=.elc)
|
|
|
834
|
|
|
835 include ../../XEmacs.rules
|
|
|
836
|
|
|
837 all:: $(ELCS) auto-autoloads.elc custom-load.elc
|
|
|
838
|
|
|
839 srckit: srckit-std
|
|
|
840
|
|
|
841 binkit: binkit-common
|
|
|
842 @end example
|
|
|
843
|
|
|
844 @menu
|
|
|
845 * package-compile.el::
|
|
|
846 * package-info.in Fields::
|
|
|
847 * Makefile Variables::
|
|
|
848 * Makefile Targets::
|
|
|
849 @end menu
|
|
|
850
|
|
|
851
|
|
|
852 @node package-compile.el, package-info.in Fields, , Creating Packages
|
|
|
853
|
|
|
854 The @xpms{} does not automatically become aware of your package simply
|
|
|
855 because there is a new subtree. If any package, including your own,
|
|
|
856 requires any of your files, it must be explicitly added to the compile
|
|
|
857 environment or loads/requires that search load-path will fail. The
|
|
|
858 changes that need to be made are
|
|
|
859
|
|
|
860 @table @strong
|
|
694
|
861 @item an entry in @code{package-directory-map}
|
|
693
|
862 This tells the @xpms{} which distribution (currently
|
|
|
863 @samp{xemacs-packages} or @samp{mule-packages}) your package is found
|
|
|
864 in. It then looks in the distribution subdirectory whose name is the
|
|
|
865 same as the package's.
|
|
|
866
|
|
|
867 @item an entry in the @code{cond} in @code{package-name-to-directory}
|
|
|
868 This is optional; it is necessary only if you keep your Lisp code
|
|
|
869 somewhere other than the top-level directory of the package's source
|
|
|
870 tree, eg, in @file{packages/xemacs-packages/@var{PACKAGE}/lisp}.
|
|
|
871 @end table
|
|
|
872
|
|
|
873 This only needs to be done once, when the package is first added to the
|
|
|
874 @xpms{}. (Well, when you randomly change the subdirectory layout, too.)
|
|
|
875 Your changes to @file{package-compile.el} must be cleared and checked in
|
|
|
876 by the XEmacs Package Release Engineer before your package will build
|
|
|
877 correctly from a fresh checkout.
|
|
|
878
|
|
694
|
879 This is unfortunate; it works pretty well once set up, but can cause
|
|
|
880 confusion when first building a package in the @xpms{} context. In
|
|
|
881 particular, if the @code{package-directory-map} entry for a required
|
|
|
882 package
|
|
|
883 @c #### including the package itself?
|
|
|
884 is not found, the necessary requires will not be executed by
|
|
|
885 @file{package-compile.el}. If required functions are executed (under
|
|
|
886 @code{eval-when-compile}), they won't be found and the compile will
|
|
|
887 fail. If required function is actually a macro, the byte compiler will
|
|
|
888 not recognize that, compile a function call to the macro. This will
|
|
|
889 cause a run-time error because the byte-code interpreter does not know
|
|
|
890 how to execute macros. (Macros can always be expanded at compile-time,
|
|
|
891 and this is more efficient.)
|
|
|
892
|
|
|
893 If your package keeps some or all Lisp code somewhere other than the top
|
|
|
894 directory, then an entry in @code{package-name-to-directory} is also
|
|
|
895 necessary, or requires will fail, leading to the problems just described.
|
|
693
|
896
|
|
|
897
|
|
|
898 @node package-info.in Fields, Makefile Variables, package-compile.el, Creating Packages
|
|
|
899
|
|
|
900 The @file{package-info.in} structure is simply Lisp data, to be read by
|
|
|
901 a Lisp script, have values substituted for variables, and then written
|
|
|
902 out (appropriately quoted) into a loadable Lisp file, to be consed into
|
|
|
903 the @file{package-index.el} list at the FTP archives. That list is
|
|
|
904 structured as an alist with package names as keys. The package data is
|
|
|
905 a plist. Do not rely on this, as it may change. If you have a good
|
|
|
906 reason for relying on it, let the maintainers know and we may
|
|
|
907 incorporate it in a future revision of the @xpms{} standard.
|
|
|
908
|
|
|
909 There are several kinds of fields, distinguished by how they get their
|
|
|
910 values. There are literals written into @file{package-info.in} by the
|
|
|
911 package maintainer. There are variables substituted in by the build
|
|
|
912 process, some computed, and others written as values of @file{make}
|
|
|
913 variables in the @file{Makefile} by the package maintainer. There are a
|
|
|
914 few implementation constants, some of which are simply the default value
|
|
|
915 for obsolete fields.
|
|
|
916
|
|
|
917 The @file{package-info.in} literals provided by the maintainer generally
|
|
|
918 should not change over the life of the package. (The exception is the
|
|
|
919 @samp{provides} field, which should be generated, but isn't yet.)
|
|
861
|
920 Values described as ``literal'' below are unquoted literal text. These
|
|
693
|
921 are normally interpreted as symbols by the package build process. The
|
|
|
922 maintainer literals are
|
|
|
923
|
|
|
924 @table @asis
|
|
|
925 @item @var{package_name}
|
|
|
926 A literal. The only unnamed ``field,'' the name of the package.
|
|
|
927
|
|
|
928 @item distribution
|
|
|
929 A literal, either @samp{xemacs} (for generic packages) or @samp{mule}
|
|
|
930 (for packages requiring Mule). @xref{Package Terminology}.
|
|
|
931
|
|
|
932 @item description
|
|
|
933 A Lisp string containing a one-line text description for use in package
|
|
|
934 listings.
|
|
|
935
|
|
|
936 @item provides
|
|
|
937 A (Lisp) list of features provided by the libraries in the package. All
|
|
|
938 of the features provided by libraries in your package should be elements
|
|
|
939 of this list.
|
|
|
940
|
|
|
941 @item type
|
|
|
942 A literal, either @samp{regular} or @samp{single-file}. For practical
|
|
|
943 purposes, @samp{regular} should be considered an implementation constant.
|
|
|
944 @end table
|
|
|
945
|
|
|
946 @c #### The following should be rewritten to @xref the make variables
|
|
|
947 @c node, and simply associate the field names to the make variables with
|
|
|
948 @c one line of description.
|
|
|
949 Values which are expected to change regularly as the package is enhanced
|
|
|
950 are implemented as @file{make} variables. You should not change them in
|
|
|
951 the @file{package-info.in} file; they are automatically filled in by the
|
|
|
952 build process.
|
|
|
953
|
|
|
954 The corresponding field name is given in parentheses. These include
|
|
|
955
|
|
|
956 @table @code
|
|
|
957 @item VERSION
|
|
|
958 (version)
|
|
|
959 The version of the XEmacs package, a numeric literal (a decimal
|
|
|
960 fixed-point number with two-places of precision).
|
|
|
961
|
|
|
962 @item AUTHOR_VERSION
|
|
|
963 (author-version)
|
|
|
964 The upstream author's version, an unintepreted literal.
|
|
|
965
|
|
|
966 @item DATE
|
|
|
967 (date)
|
|
|
968 Date of release of the upstream version.
|
|
|
969
|
|
|
970 @item MAINTAINER
|
|
|
971 (maintainer)
|
|
|
972 A literal containing the XEmacs package's maintainer and his/her email
|
|
|
973 address.
|
|
|
974
|
|
|
975 @item CATEGORY
|
|
|
976 (category)
|
|
|
977 A literal, either @samp{standard} or @samp{mule}. Probably redundant.
|
|
|
978
|
|
|
979 @item REQUIRES
|
|
|
980 (requires)
|
|
|
981 A list of packages required to correctly build this package.
|
|
|
982
|
|
|
983 Note that the usual form in @file{package-info.in} already has the
|
|
|
984 parentheses, so the @file{make} variable should be set to a
|
|
|
985 space-separated list of package names @emph{not} enclosed in
|
|
|
986 parentheses.
|
|
|
987
|
|
|
988 The list is of @emph{packages}, not @emph{libraries}, as would
|
|
|
989 ordinarily be provided to the Lisp @code{require} function.
|
|
|
990
|
|
|
991 @samp{REQUIRES} cannot be correctly computed from the calls to
|
|
|
992 @code{require} in the package's library sources. @samp{REQUIRES} is
|
|
|
993 used to ensure that all macro and defstruct definitions used by the
|
|
|
994 package are available at build time. This is not merely a matter of
|
|
|
995 efficiency, to get the expansions inlined. In fact, it is
|
|
|
996 @emph{impossible} to call a macro by name in byte-compiled Emacs Lisp
|
|
|
997 code. Thus, if the macro expansion is not inlined, the call will result
|
|
|
998 in an error at run-time! Thus, packages providing libraries that would
|
|
|
999 be loaded because of autoload definitions must also be included.
|
|
|
1000
|
|
|
1001 On the other hand, if a package provides no macros to this package, it
|
|
|
1002 is preferable @emph{not} to include it in @samp{REQUIRES}, because it is
|
|
|
1003 not uncommon that if the developer doesn't normally use the required
|
|
|
1004 package, he will never use the functionality in the package being built,
|
|
|
1005 either. In that case it would be preferable to not require the
|
|
|
1006 developer to have source for the dependencies. That said, of course it
|
|
|
1007 is safe to put too many packages in @samp{REQUIRES}.
|
|
|
1008 @end table
|
|
|
1009
|
|
|
1010 Values for the following fields are automatically generated by the build
|
|
|
1011 process.
|
|
|
1012
|
|
|
1013 @table @asis
|
|
|
1014 @item build-date
|
|
|
1015 The date the package tarball was generated.
|
|
|
1016
|
|
|
1017 @item md5sum
|
|
|
1018 An MD5 checksum for the package tarball, as gzipped.
|
|
|
1019
|
|
|
1020 @item size
|
|
|
1021 The size of the package tarball, as gzipped.
|
|
|
1022 @end table
|
|
|
1023
|
|
|
1024 It is not clear that either md5sum or size works correctly if the
|
|
|
1025 @samp{BZIP2} variable in @file{Local.rules} is set.
|
|
|
1026
|
|
|
1027 The implementation constants are
|
|
|
1028
|
|
|
1029 @table @asis
|
|
|
1030 @item standards-version
|
|
|
1031 Currently 1.1. Defines the format of the @file{package-info.in} file
|
|
|
1032 and the @file{Makefile}. A true implementation constant.
|
|
|
1033
|
|
|
1034 @item priority
|
|
|
1035 An unimplemented and underspecified feature. Suggestions for
|
|
|
1036 specification and implementation welcome.
|
|
|
1037
|
|
|
1038 @item dump
|
|
|
1039 An obsolete feature, superseded by the @file{site-load.el} mechanism.
|
|
|
1040 The value should always be nil.
|
|
|
1041
|
|
|
1042 @item filename
|
|
|
1043 An obsolete feature, completely ignored. Don't even think about doing
|
|
|
1044 anything useful with it.
|
|
|
1045 @end table
|
|
|
1046
|
|
|
1047
|
|
|
1048 @node Makefile Variables, Makefile Targets, package-info.in Fields, Creating Packages
|
|
|
1049
|
|
|
1050 A number of @file{make} variables are defined by the @xpms{}. Some are
|
|
|
1051 required, others are optional. Of course your @file{Makefile} may
|
|
|
1052 define other variables for private use, but you should be careful not to
|
|
|
1053 choose names that conflict with variables defined and used by the
|
|
|
1054 @xpms{}.
|
|
|
1055
|
|
|
1056 The required variables are described in the table below.
|
|
|
1057 The corresponding field names for @file{package-info.in}, where
|
|
|
1058 relevant, are given in parentheses.
|
|
|
1059
|
|
749
|
1060 @c This is the canonical place for this information. If there is
|
|
693
|
1061 @c unnecessary duplication with package-info.in documentation, shorten
|
|
|
1062 @c that and leave this full-length.
|
|
|
1063 @table @code
|
|
|
1064 @item VERSION
|
|
|
1065 (version)
|
|
|
1066 The version of the XEmacs package, a numeric literal (a decimal
|
|
|
1067 fixed-point number with two-places of precision).
|
|
|
1068
|
|
|
1069 @item AUTHOR_VERSION
|
|
|
1070 (author-version)
|
|
|
1071 The upstream author's version, an unintepreted literal.
|
|
|
1072
|
|
|
1073 @item DATE
|
|
|
1074 (date)
|
|
|
1075 Date of release of the upstream version.
|
|
|
1076
|
|
|
1077 @item MAINTAINER
|
|
|
1078 (maintainer)
|
|
|
1079 A literal containing the XEmacs package's maintainer and his/her email
|
|
|
1080 address.
|
|
|
1081
|
|
|
1082 @item CATEGORY
|
|
|
1083 (category)
|
|
|
1084 A literal, either @samp{standard} or @samp{mule}. Probably redundant.
|
|
|
1085
|
|
|
1086 @item REQUIRES
|
|
|
1087 (requires)
|
|
|
1088 A list of packages required to correctly build this package.
|
|
|
1089
|
|
|
1090 Note that the usual form in @file{package-info.in} already has the
|
|
|
1091 parentheses, so the @file{make} variable should be set to a
|
|
|
1092 space-separated list of package names @emph{not} enclosed in
|
|
|
1093 parentheses.
|
|
|
1094
|
|
|
1095 The list is of @emph{packages}, not @emph{libraries}, as would
|
|
|
1096 ordinarily be provided to the Lisp @code{require} function.
|
|
|
1097
|
|
|
1098 @samp{REQUIRES} cannot be correctly computed from the calls to
|
|
|
1099 @code{require} in the package's library sources. @samp{REQUIRES} is
|
|
|
1100 used to ensure that all macro and defstruct definitions used by the
|
|
|
1101 package are available at build time. This is not merely a matter of
|
|
|
1102 efficiency, to get the expansions inlined. In fact, it is
|
|
|
1103 @emph{impossible} to call a macro by name in byte-compiled Emacs Lisp
|
|
|
1104 code. Thus, if the macro expansion is not inlined, the call will result
|
|
|
1105 in an error at run-time! Thus, packages providing libraries that would
|
|
|
1106 be loaded because of autoload definitions must also be included.
|
|
|
1107
|
|
|
1108 On the other hand, if a package provides no macros to this package, it
|
|
|
1109 is preferable @emph{not} to include it in @samp{REQUIRES}, because it is
|
|
|
1110 not uncommon that if the developer doesn't normally use the required
|
|
|
1111 package, he will never use the functionality in the package being built,
|
|
|
1112 either. In that case it would be preferable to not require the
|
|
|
1113 developer to have source for the dependencies. That said, of course it
|
|
|
1114 is safe to put too many packages in @samp{REQUIRES}.
|
|
|
1115
|
|
|
1116 @item ELCS
|
|
|
1117 The list of the byte-compiled Lisp files used by the package. These
|
|
|
1118 files and their @file{.el} versions will be included in the binary
|
|
|
1119 package. This variable determines which libraries will be
|
|
|
1120 byte-compiled. These libraries are also deleted by @samp{make clean}.
|
|
|
1121
|
|
|
1122 Note there is no sanity-checking done on this variable. If you put
|
|
|
1123 @samp{.el} files in here, they will not be compiled and they @emph{will}
|
|
|
1124 be deleted by @samp{make clean}. You would surely be very distressed if
|
|
|
1125 that happened, so be very careful. If this variable is left empty, none
|
|
|
1126 of your Lisp code will be compiled or packaged. This would be a less
|
|
|
1127 than amusing surprise, too.
|
|
|
1128
|
|
|
1129 We don't consider this a feature, of course. Please do submit code to
|
|
|
1130 do sanity checking to @email{xemacs-patches@@xemacs.org}.
|
|
|
1131 @end table
|
|
|
1132
|
|
749
|
1133 Optional, but very commonly used variables are explained below.
|
|
693
|
1134
|
|
|
1135 @table @code
|
|
|
1136 item EXTRA_SOURCES
|
|
|
1137 Other files (such as extra Lisp sources or an upstream @file{Makefile})
|
|
|
1138 that are normally placed in the installed Lisp directory, but not
|
|
|
1139 byte-compiled. These files are @emph{preserved} by the @samp{clean}
|
|
|
1140 targets.
|
|
|
1141
|
|
|
1142 @item EXTRA_OBJS
|
|
|
1143 Other files (such as compiled autoload or concatenated @file{.elc}
|
|
|
1144 libraries) which are normally placed in the installed Lisp directory,
|
|
|
1145 but do @emph{not} have corresponding source files and @emph{should} be
|
|
|
1146 deleted by the @samp{clean} targets. Some of these (such as
|
|
|
1147 package-specific autoload setups) can and probably should be replaced by
|
|
|
1148 @xpms{} solutions such as @file{auto-autoloads.el}, but many cannot.
|
|
|
1149
|
|
|
1150 @item PRELOADS
|
|
|
1151 A specification for loading libraries containing macros before compiling
|
|
|
1152 the Lisp in the package. This is spliced directly into the invocation
|
|
|
1153 of XEmacs for byte-compilation, so it must contain the @samp{-l} flag
|
|
|
1154 for XEmacs:
|
|
|
1155
|
|
|
1156 @example
|
|
|
1157 PRELOADS=-l ./apackage-macros.el -l ../bpackage/lisp/bpackage-macros.el
|
|
|
1158 @end example
|
|
|
1159
|
|
749
|
1160 Preloads are loaded before @file{package-compile.el}, so the
|
|
|
1161 @var{load-path} is minimal. Therefore @samp{PRELOADS} must specify a
|
|
|
1162 full path to packaged Lisp. The base @var{load-path} does include the
|
|
|
1163 core Lisp directory, so core libraries are found.
|
|
|
1164
|
|
693
|
1165 @item INFO_FILES
|
|
|
1166 Any Info file(s) generated by the package. These must be paths relative
|
|
|
1167 to the root of the package's source tree.
|
|
|
1168
|
|
|
1169 @item TEXI_FILES
|
|
|
1170 The Texinfo source file(s). These must be paths relative
|
|
|
1171 to the root of the package's source tree.
|
|
|
1172
|
|
|
1173 @item MANUAL
|
|
|
1174 The name to be used for Info files and man pages.
|
|
|
1175
|
|
|
1176 @item DATA_FILES
|
|
|
1177 Any data files, such as pixmaps, READMEs, and ChangeLogs. These must be
|
|
749
|
1178 paths relative to the root of the package's source tree. These files
|
|
|
1179 will be copied to @samp{$(DATA_DEST)} for installation. Any directory
|
|
752
|
1180 component of the path for a file will be stripped, so that the
|
|
749
|
1181 file ends up in @samp{$(DATA_DEST)}, not in a subdiredtory. If there are
|
|
|
1182 several destination directories, the forms @samp{$(DATA_FILES_@var{n})}
|
|
|
1183 and @samp{$(DATA_DEST_@var{n})} (@var{n} may take values in 1-40) must
|
|
|
1184 be used. The @xpms{} doesn't make provision for copying trees at this
|
|
|
1185 time.
|
|
693
|
1186
|
|
|
1187 @item DATA_DEST
|
|
|
1188 The installation location for data files, relative to the @file{etc/}
|
|
749
|
1189 directory of the package hierarchy. The default is currently empty, but
|
|
|
1190 the normal value is simply $(PACKAGE). Leaving it empty (@emph{i.e.},
|
|
|
1191 put it directly under @file{etc/}) will probably work, but is subject to
|
|
|
1192 name conflicts with other packages. If there are several destination
|
|
|
1193 directories, the form @samp{$(DATA_DEST_@var{n})} must be used. The
|
|
|
1194 @xpms{} doesn't make provision for copying trees at this time.
|
|
|
1195 @end table
|
|
|
1196
|
|
|
1197 The following variables are defaulted by @file{Local.rules} or
|
|
|
1198 @file{XEmacs.rules}. These variables often should be added to using
|
|
|
1199 @samp{+=} rather than set by @samp{=} or @samp{:=}.
|
|
|
1200
|
|
|
1201 @table @code
|
|
|
1202 @item GENERATED
|
|
|
1203 @c #### Is this correct?
|
|
|
1204 A list of @file{.elc} files compiled from @file{.el} files generated by
|
|
|
1205 the package build process. These files and the corresponding @file{.el}
|
|
|
1206 files are copied to the installed @file{lisp} directory. Defaults to
|
|
|
1207 @samp{$@{AUTOLOAD_PATH@}/auto-autoloads.elc}. Typical usage is
|
|
|
1208 @example
|
|
|
1209 GENERATED += $@{AUTOLOAD_PATH@}/custom-load.elc
|
|
|
1210 @end example
|
|
693
|
1211 @end table
|
|
|
1212
|
|
|
1213 Rarely used variables.
|
|
|
1214
|
|
|
1215 @c @table @code
|
|
|
1216 @c @item
|
|
|
1217 @c @end table
|
|
|
1218
|
|
|
1219 @node Makefile Targets, , Makefile Variables, Creating Packages
|
|
|
1220
|
|
|
1221 The standard targets that need to be defined in your @file{Makefile}
|
|
|
1222 follow. These normally should @emph{not} have an action. All of the
|
|
|
1223 work should be done by dependent targets, usually having standard
|
|
|
1224 definitions in the @xpms{}.
|
|
|
1225
|
|
|
1226 @table @samp
|
|
|
1227 @item all
|
|
|
1228 A list of generated files, usually byte-compiled Lisp libraries, to be
|
|
|
1229 bundled in the package. The typical dependencies are
|
|
|
1230
|
|
|
1231 @example
|
|
|
1232 $(ELCS) auto-autoloads.elc custom-load.elc
|
|
|
1233 @end example
|
|
|
1234
|
|
|
1235 Other targets (such as Info files) may need to be added as dependencies
|
|
|
1236 for the @code{all} target.
|
|
|
1237
|
|
|
1238 @item srckit
|
|
|
1239 The target for generating a source package. Not implemented. If it
|
|
|
1240 were, the normal dependency would be @samp{srckit-std}.
|
|
|
1241
|
|
|
1242 @item binkit
|
|
|
1243 The target for creating a ``master'' installation. Binary packages are
|
|
|
1244 actually generated by the @samp{bindist} target. @xref{Building Packages}.
|
|
|
1245 @end table
|
|
|
1246
|
|
|
1247 Standard dependencies for @code{srckit} and @code{binkit} are defined in
|
|
|
1248 @file{XEmacs.rules}. The most useful of these values are given in the
|
|
|
1249 following table.
|
|
|
1250
|
|
|
1251 @table @samp
|
|
|
1252 @item srckit-std
|
|
|
1253 Build a standard source kit. Not fully implemented.
|
|
|
1254
|
|
|
1255 @item binkit-sourceonly
|
|
|
1256 The @samp{binkit} target need only install source and compiled Lisp in
|
|
|
1257 the staging area. There is nothing to install in a data directory or
|
|
|
1258 info directory.
|
|
|
1259
|
|
|
1260 @item binkit-sourceinfo
|
|
|
1261 Both source and info files are to be installed in the staging area.
|
|
|
1262
|
|
|
1263 @item binkit-sourcedata
|
|
|
1264 Both source and etc (data) files are to be installed in the staging
|
|
|
1265 area.
|
|
|
1266
|
|
|
1267 @item binkit-sourcedatainfo
|
|
|
1268 Source, etc (data), and info files all are present and need to be
|
|
|
1269 installed in the staging area.
|
|
|
1270
|
|
|
1271 @item binkit-common
|
|
|
1272 A dependency for all the above. (In fact in the current implementation
|
|
|
1273 @samp{binkit-common} does all the work for all of the @samp{binkit}
|
|
|
1274 targets.)
|
|
|
1275 @end table
|
|
|
1276
|
|
|
1277 Data files include things like pixmaps for a package-specific toolbar,
|
|
|
1278 and are normally installed in @file{etc/@var{PACKAGE_NAME}}. A few
|
|
|
1279 packages have needs beyond the basic templates. See @file{XEmacs.rules}
|
|
|
1280 or a future revision of this manual for details.
|
|
|
1281
|
|
|
1282
|
|
752
|
1283 @node Documenting Packages, Issues, Creating Packages, Packaging
|
|
|
1284 @comment node-name, next, previous, up
|
|
|
1285 @cindex documenting packages
|
|
|
1286 @heading Documenting Packages:
|
|
|
1287
|
|
|
1288 @c #### Add a documentation section to Internals, and xref here.
|
|
|
1289 Some random notes on documenting your package.
|
|
|
1290
|
|
|
1291 Do write a Texinfo file. It's not that hard to do basically, and even
|
|
|
1292 using the more advanced features of Texinfo soon become natural. For a
|
|
|
1293 start, just grab the template @file{Samples/package.texi} from the
|
|
|
1294 @xpms{} source tree, and drop your current README into the Top node. At
|
|
|
1295 least this way your documentation will be accessible from the standard
|
|
|
1296 Info readers. Next, try to add lots of cross-referencing and logical
|
|
|
1297 markup, and then node structure.
|
|
|
1298
|
|
|
1299 Address both end users and developer issues. You may not be the
|
|
|
1300 maintainer forever.
|
|
|
1301
|
|
|
1302 If you are maintaining a package that is part of the GNU Emacs
|
|
|
1303 distribution, you'll likely find that you occasionally synchronize your
|
|
|
1304 package with the GNU Emacs sources. When you synch a file,
|
|
|
1305 conventionally you should place a comment just above the standard
|
|
|
1306 @code{;;; Code} comment that looks like this:
|
|
|
1307
|
|
|
1308 @example
|
|
|
1309 ;; Synched with:
|
|
|
1310 ;; GNU Emacs 21.1, 2002-02-08, Stephen Turnbull <stephen@@xemacs.org>
|
|
|
1311 @end example
|
|
|
1312
|
|
|
1313 This comment is a status flag; the ChangeLog doesn't really give the
|
|
|
1314 same information.
|
|
|
1315
|
|
|
1316 Do maintain a detailed ChangeLog.
|
|
|
1317
|
|
|
1318 @node Issues, , Documenting Packages, Packaging
|
|
693
|
1319 @section Issues
|
|
|
1320
|
|
694
|
1321 To be completed.
|
|
693
|
1322
|
