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