|
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
|
|
694
|
128 @file{info} directory obeys the usual conventions.
|
|
|
129 @emph{I.e.}, the @file{info} directory is flat
|
|
693
|
130 with a(n) (optional) @file{dir} file and one (set of) info file(s) per
|
|
694
|
131 package. The @file{man} subdirectory typically contains documentation
|
|
|
132 sources, separated by package. (It does not contain @file{man(1)}
|
|
|
133 pages, as Emacs provides very few of them.)
|
|
693
|
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.
|
|
694
|
179 @c Please, Michael, write some specs up!
|
|
693
|
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
|
|
694
|
422 The XEmacs Package Release Engineer is responsible for keeping the
|
|
|
423 system coherent. The changes to @file{packages/package-compile.el} and
|
|
|
424 @file{packages/xemacs-packages/Makefile} required to make the package
|
|
|
425 available to others, and for building SUMO tarballs, @emph{etc}, are
|
|
|
426 done by the Package Release Engineer, not individual library
|
|
|
427 maintainers.
|
|
693
|
428
|
|
694
|
429 The Package Release Engineer also maintains assorted infrastructure for
|
|
|
430 actually making releases. These are generally available for inspection
|
|
|
431 in the @code{xemacs-builds} module in the CVS repository.
|
|
|
432
|
|
|
433 @c #### To be completed.
|
|
693
|
434
|
|
|
435
|
|
|
436 @c #### The following section is lifted verbatim from the XEmacs User's
|
|
|
437 @c Manual, file packages.texi.
|
|
|
438 @node Package Terminology, Building Packages, Package Overview, Packaging
|
|
|
439 @comment node-name, next, previous, up
|
|
|
440 @heading Package Terminology:
|
|
|
441
|
|
|
442 @subsection Libraries and Packages
|
|
|
443 @cindex library
|
|
|
444 @cindex package
|
|
|
445
|
|
|
446 A Lisp @dfn{library} is a single loadable file containing Lisp code. It
|
|
|
447 may be in source or byte-compiled form. A Lisp @dfn{package} is a set
|
|
|
448 of one or more libraries, usually related to each other in some way,
|
|
|
449 bundled with administrative information for convenient distribution.
|
|
|
450
|
|
|
451 @subsection Package Flavors
|
|
|
452
|
|
|
453 There are two main flavors of packages.
|
|
|
454
|
|
|
455 @table @strong
|
|
|
456 @item Regular Packages
|
|
|
457 @cindex regular package
|
|
|
458 A regular package is a set of Lisp libraries design to cooperate with
|
|
|
459 one another. A very complex example is Gnus. One may not in general
|
|
|
460 safely remove any of the component libraries.
|
|
|
461
|
|
|
462 @item Single-File Packages
|
|
|
463 @cindex single-file package
|
|
|
464 A single-file package is an collection of thematically related but
|
|
|
465 otherwise independent Lisp libraries. These libraries are bundled
|
|
|
466 together for convenience of the maintainers. Usually individual
|
|
|
467 libraries may be deleted at will without any loss of functionality of
|
|
|
468 other libraries in the package. However, we would recommend that you
|
|
|
469 follow this rule of thumb: "When in doubt, don't delete". If it's
|
|
|
470 really that big a deal, request that the maintainers split the package
|
|
|
471 into smaller aggregations.
|
|
|
472 @end table
|
|
|
473
|
|
|
474 @subsection Package Distributions
|
|
|
475 @cindex package distributions
|
|
|
476 @cindex binary packages
|
|
|
477 @cindex source packages
|
|
|
478 XEmacs Lisp packages are distributed in two ways. @dfn{Binary packages}
|
|
|
479 are used by system administrators and end users. They are packaged in a
|
|
|
480 form convenient for direct installation into an XEmacs package
|
|
|
481 hierarchy. @dfn{Source packages} are for developers and include all
|
|
|
482 files necessary for rebuilding byte-compiled lisp and creating tarballs
|
|
|
483 for distribution or installation. This is all of the package author's
|
|
|
484 source code plus all of the files necessary to build distribution
|
|
|
485 tarballs (Unix Tar format files, gzipped for space savings).
|
|
|
486 @c #### This next is an Evile Practice and should be discontinued.
|
|
|
487 (Occasionally sources that are not relevant to XEmacs are removed.)
|
|
|
488
|
|
|
489 Currently, source packages are only available via CVS. See
|
|
|
490 @url{http://www.xemacs.org/Develop/cvsaccess.html} for details.
|
|
|
491
|
|
|
492 The package distributions are also split according to major features
|
|
|
493 required in XEmacs to support them. At present there are @dfn{generic}
|
|
|
494 packages, which can be loaded by @emph{any} XEmacs, and @dfn{Mule}
|
|
|
495 packages, which @emph{require} Mule support or they will cause errors
|
|
|
496 when loaded. Note that there is no guarantee that a generic package
|
|
|
497 will have any useful functionality in a minimally configured XEmacs. As
|
|
|
498 long as any XEmacs can successfully load the package's libraries
|
|
|
499 (perhaps given other required Lisp libraries), it will be classified as
|
|
|
500 generic. At the present time only Mule packages need be treated
|
|
|
501 specially, and even those only if they contain multibyte characters.
|
|
|
502
|
|
|
503
|
|
|
504 @c #### The following section is lifted verbatim from the XEmacs User's
|
|
|
505 @c Manual, file packages.texi.
|
|
|
506 @node Building Packages, Local.rules File, Package Terminology, Packaging
|
|
|
507 @comment node-name, next, previous, up
|
|
|
508 @cindex building packages
|
|
|
509 @cindex package building
|
|
|
510 @heading Building Packages:
|
|
|
511 Currently, source packages are only available via anonymous CVS. See
|
|
|
512 @url{http://www.xemacs.org/Develop/cvsaccess.html} for details of
|
|
|
513 checking out the @file{packages} module.
|
|
|
514
|
|
|
515 @subsection Prerequisites for Building Source Packages
|
|
|
516
|
|
|
517 @table @code
|
|
|
518 @item GNU cp
|
|
|
519 @item GNU install
|
|
|
520 (or a BSD compatible install program).
|
|
|
521 @item GNU make
|
|
|
522 (3.75 or later preferred).
|
|
|
523 @item makeinfo
|
|
|
524 (1.68 from texinfo-3.11 or later required, 1.69 from Texinfo 4 preferred).
|
|
|
525 @item GNU tar
|
|
|
526 (or equivalent).
|
|
|
527 @item GNU gzip
|
|
|
528 (or equivalent).
|
|
|
529 @item A properly configured @file{Local.rules} file.
|
|
|
530 @ref{Local.rules File}.
|
|
|
531 @end table
|
|
|
532
|
|
|
533 And of course, XEmacs, 21.0 or higher.
|
|
|
534
|
|
|
535 @subsection What You Can Do With Source Packages
|
|
|
536
|
|
|
537 The packages CVS sources are most useful for creating XEmacs package
|
|
|
538 tarballs for installation into your own XEmacs installations or for
|
|
|
539 distributing to others.
|
|
|
540
|
|
|
541 The supported @file{make} targets are:
|
|
|
542
|
|
|
543 @table @code
|
|
|
544 @item all
|
|
|
545 Bytecompile all files, build and bytecompile byproduct files like
|
|
|
546 @file{auto-autoloads.el} and @file{custom-load.el}. Create info version
|
|
|
547 of TeXinfo documentation if present.
|
|
|
548
|
|
|
549 @c #### Why do we need this _and_ the binkit target?
|
|
|
550 @item bindist
|
|
|
551 Does a @code{make all} as well as create a binary package tarball in the
|
|
|
552 staging directory.
|
|
|
553
|
|
|
554 @item install
|
|
|
555 Bytecompile all files, build and bytecompile byproduct files like
|
|
|
556 @file{auto-autoloads.el} and @file{custom-load.el}. Create info version
|
|
|
557 of TeXinfo documentation if present. And install everything into the
|
|
|
558 staging directory.
|
|
|
559
|
|
|
560 @item srckit
|
|
|
561 Usually simply depends on @code{srckit-std}, with no actions. This does
|
|
|
562 a @code{make distclean} and creates a package source tarball in the
|
|
|
563 staging directory. This is generally only of use for package
|
|
|
564 maintainers.
|
|
|
565
|
|
|
566 @item binkit
|
|
|
567 May depend on @code{binkit-sourceonly}, @code{binkit-sourceinfo},
|
|
|
568 @code{binkit-sourcedata}, or @code{binkit-sourcedatainfo}, with no
|
|
|
569 actions. @code{sourceonly} indicates there is nothing to install in a
|
|
|
570 data directory or info directory. @code{sourceinfo} indicates that
|
|
|
571 source and info files are to be installed. @code{sourcedata} indicates
|
|
|
572 that source and etc (data) files are to be installed.
|
|
|
573 @code{sourcedatainfo} indicates source, etc (data), and info files are
|
|
|
574 to be installed. A few packages have needs beyond the basic templates
|
|
|
575 so this is not yet complete.
|
|
|
576
|
|
|
577 @item dist
|
|
|
578 Runs the rules @code{srckit} followed by @code{binkit}. This is
|
|
|
579 primarily of use by XEmacs maintainers producing files for distribution.
|
|
|
580
|
|
|
581 @item clean
|
|
|
582 Remove all built files except @file{auto-autoloads.el} and
|
|
|
583 @file{custom-load.el}.
|
|
|
584
|
|
|
585 @item distclean
|
|
|
586 Remove all created files.
|
|
|
587 @end table
|
|
|
588
|
|
|
589 @c #### The following section is lifted verbatim from the XEmacs User's
|
|
|
590 @c Manual, file packages.texi.
|
|
|
591 @node Local.rules File, Creating Packages, Building Packages, Packaging
|
|
|
592 @comment node-name, next, previous, up
|
|
|
593 @cindex local.rules
|
|
|
594 @heading The Local.rules File:
|
|
|
595 This file in @file{packages} provides the @xpms{} with information about
|
|
|
596 the local configuration and environment. To create @file{Local.rules},
|
|
|
597 simply copy @file{Local.rules.template} from that directory to
|
|
|
598 @file{Local.rules} and edit it to suit your needs.
|
|
|
599
|
|
|
600 These are the variables in @file{Local.rules} that you will need to
|
|
|
601 provide values for. The following variables control which packages will
|
|
|
602 be built:
|
|
|
603
|
|
|
604 @table @var
|
|
|
605 @item XEMACS_PACKAGES
|
|
|
606 The default is @samp{xemacs-packages}, which results in the set in
|
|
|
607 the @file{xemacs-packages/Makefile} @code{PACKAGES} variable.
|
|
|
608
|
|
|
609 Otherwise, it should be a list of package source directories prefixed by
|
|
|
610 @samp{xemacs-packages}:
|
|
|
611
|
|
|
612 @example
|
|
|
613 XEMACS_PACKAGES = xemacs-packages/xemacs-base xemacs-packages/bbdb
|
|
|
614 @end example
|
|
|
615
|
|
|
616 @item BUILD_WITHOUT_MULE
|
|
|
617 The default is the empty value.
|
|
|
618
|
|
|
619 Building from CVS defaults to building the Mule
|
|
|
620 packages. Set this to 't' if you don't want/have Mule.
|
|
|
621
|
|
|
622 @item MULE_PACKAGES
|
|
|
623 The default is @samp{mule-packages}, which results in the set in
|
|
|
624 the @file{mule-packages/Makefile} @code{PACKAGES} variable.
|
|
|
625
|
|
|
626 Otherwise, it should be a list of package source directories prefixed by
|
|
|
627 @samp{mule-packages}:
|
|
|
628
|
|
|
629 @example
|
|
|
630 MULE_PACKAGES = mule-packages/mule-base mule-packages/skk
|
|
|
631 @end example
|
|
|
632
|
|
|
633 @item PACKAGE_INDEX
|
|
|
634 The default is @file{package-index}.
|
|
|
635
|
|
|
636 If you want the package index file to have a different name, change
|
|
|
637 this. This is probably a bad idea unless you are a packages release
|
|
|
638 engineer, as it will confuse the package administration tools.
|
|
|
639 @end table
|
|
|
640
|
|
|
641 The following variables determine where files are installed and how they
|
|
|
642 are installed. Several of the defaults use the variable
|
|
|
643 @var{XEMACS_PACKAGES_BASE}. Never set this variable in
|
|
|
644 @file{Local.rules}; it is automatically set in @file{XEmacs.rules}.
|
|
|
645
|
|
|
646 @table @asis
|
|
|
647 @item @var{XEMACS_STAGING}
|
|
|
648 The default is @file{$@{XEMACS_PACKAGES_BASE@}/../xemacs-packages}.
|
|
|
649
|
|
|
650 Generic packages will be installed here. This can be the final
|
|
|
651 destination for files or symlinks (if the packages are being installed
|
|
|
652 locally), or a clean staging area for building tarballs.
|
|
|
653
|
|
|
654 @strong{N.B.} @samp{make bindist} ignores this variable. It should be
|
|
|
655 handled by the administration utilities, but currently isn't.
|
|
|
656
|
|
|
657 @item @var{MULE_STAGING}
|
|
|
658
|
|
|
659 The default is @file{$@{XEMACS_PACKAGES_BASE@}/../mule-packages}.
|
|
|
660
|
|
|
661 Packages requiring Mule to load correctly will be installed here. This
|
|
|
662 can be the final destination for files or symlinks (if the packages are
|
|
|
663 being installed locally), or a clean staging area for building tarballs.
|
|
|
664
|
|
|
665 @strong{N.B.} @samp{make bindist} ignores this variable. It should be
|
|
|
666 handled by the administration utilities, but currently isn't.
|
|
|
667
|
|
|
668 @item symlink
|
|
|
669 The default is the empty value.
|
|
|
670
|
|
|
671 Set this to 't' if you want to simulate ``running in place.'' It is
|
|
|
672 currently not possible to ask XEmacs to use any package source tree as
|
|
|
673 an automatically configured member of @code{load-path}, and it is
|
|
|
674 unlikely that complex trees such as that of the Gnus package will ever
|
|
|
675 be able to ``run in place.'' This variable, when set to `t', causes the
|
|
|
676 build process to create a symlink farm otherwise identical to an
|
|
|
677 installed tree of binary packages. Thus it is purely a space
|
|
|
678 optimization.
|
|
|
679
|
|
|
680 Setting this is incompatible with @samp{make bindist}.
|
|
|
681 @end table
|
|
|
682
|
|
|
683 The following variables determine how packages are made.
|
|
|
684
|
|
|
685 @table @var
|
|
|
686 @item XEMACS
|
|
|
687 The default is @samp{xemacs}.
|
|
|
688
|
|
|
689 The path to the XEmacs executable you wish to use to compile the
|
|
|
690 packages and execute Lisp build scripts.
|
|
|
691
|
|
|
692 @item XEMACS_NATIVE_NT
|
|
|
693 The default is the empty value.
|
|
|
694
|
|
|
695 Set this to 't' if you are building on WinNT. It controls hairy shell
|
|
|
696 quoting in the @file{Makefile}s.
|
|
|
697
|
|
|
698 @item INSTALL
|
|
|
699 The default is @samp{install -c}.
|
|
|
700
|
|
|
701 The path to your BSD compatible install program.
|
|
|
702
|
|
|
703 @item TAR
|
|
|
704 The default is @samp{tar}.
|
|
|
705
|
|
|
706 The path to your tar program.
|
|
|
707
|
|
|
708 @item BZIP2
|
|
|
709 The default is the empty value.
|
|
|
710
|
|
|
711 If unset, bzipped tarballs will not be built. If this is set to
|
|
|
712 something that resolves to a @samp{bzip2} executable, bzip2 tarballs
|
|
|
713 will be built @emph{in addition to} @samp{gzip} tarballs.
|
|
|
714
|
|
|
715 @item MAKEINFO
|
|
|
716 The default is @samp{makeinfo}.
|
|
|
717
|
|
|
718 The path to your @file{makeinfo} program
|
|
|
719 @end table
|
|
|
720
|
|
|
721
|
|
|
722 @c #### The following section is lifted verbatim from the XEmacs User's
|
|
|
723 @c Manual, file packages.texi.
|
|
|
724 @node Creating Packages, Issues, Local.rules File, Packaging
|
|
|
725 @comment node-name, next, previous, up
|
|
|
726 @cindex creating packages
|
|
|
727 @heading Creating Packages:
|
|
|
728 Creating a package from an existing Lisp library is not very difficult.
|
|
|
729
|
|
|
730 In addition to the Lisp libraries themselves, you need a
|
|
|
731 @file{package-info.in} file and a simple @file{Makefile}. The rest is
|
|
|
732 done by @file{XEmacs.rules}, part of the packaging system
|
|
|
733 infrastructure.
|
|
|
734
|
|
|
735 @file{package-info.in} contains a single Lisp form like this:
|
|
|
736
|
|
|
737 @example
|
|
|
738 (NAME ; your package's name
|
|
|
739 (standards-version 1.1
|
|
|
740 version VERSION ; Makefile
|
|
|
741 author-version AUTHOR_VERSION ; Makefile
|
|
|
742 date DATE ; Makefile
|
|
|
743 build-date BUILD_DATE ; generated
|
|
|
744 maintainer MAINTAINER ; Makefile
|
|
|
745 distribution DISTRIBUTION ; "mule" if MULE is needed,
|
|
|
746 ; else "xemacs"
|
|
|
747 priority high
|
|
|
748 category CATEGORY ; Makefile
|
|
|
749 dump nil
|
|
|
750 description "description" ; a one-line description string
|
|
|
751 filename FILENAME ; obsolete
|
|
|
752 md5sum MD5SUM ; generated
|
|
|
753 size SIZE ; generated
|
|
|
754 provides (FEATURE ...) ; one for every `provides' form
|
|
|
755 requires (REQUIRES) ; Makefile
|
|
|
756 ; NOT run-time dependencies! These
|
|
|
757 ; are files that provide macros or
|
|
|
758 ; defsubsts that must be inlined.
|
|
|
759 type regular
|
|
|
760 ))
|
|
|
761 @end example
|
|
|
762
|
|
|
763 You should replace NAME, DISTRIBUTION, DESCRIPTION, and FEATURE ... with
|
|
|
764 appropriate values, according to the comments. Fields marked as
|
|
|
765 @samp{obsolete} can be ignored. Fields marked as @samp{generated} are
|
|
|
766 generated by the package construction process, and will be filled in
|
|
|
767 automatically. Fields marked as @samp{Makefile} should be set as
|
|
|
768 variables in the @file{Makefile}.
|
|
|
769
|
|
|
770 The @samp{provides} can be done automatically, but currently aren't. It
|
|
|
771 would probably be a good idea to set them in the @file{Makefile} (they
|
|
|
772 do change, fairly often, but at present they aren't.
|
|
|
773
|
|
|
774 The @file{Makefile} is quite stylized. The idea is similar to an
|
|
|
775 @file{Imakefile} or an @code{automake} file: the complexity is hidden in
|
|
|
776 generic rules files, in this case the @file{XEmacs.rules} include file
|
|
|
777 in the top directory of the packages hierarchy.
|
|
|
778
|
|
|
779 An @xpms{} @file{Makefile} has three components. First, there is a
|
|
|
780 variable definition section. The standard @xpms{} @file{make} variables
|
|
|
781 must be defined here for use by the @file{XEmacs.rules} include file.
|
|
|
782 Second, the file @file{../../XEmacs.rules} is included. Finally, the
|
|
|
783 @file{make} rules are defined, possibly including additional variable
|
|
|
784 definitions for use by the @file{Makefile}. These always include rules
|
|
|
785 for the targets @samp{all}, @samp{binkit}, and @file{srckit}.
|
|
|
786
|
|
|
787 Although a number of facilities are available for complex libraries,
|
|
|
788 most simple packages' @file{Makefile}s contain a copyright notice, the
|
|
|
789 variable definitions mentioned above, and some boilerplate.
|
|
|
790
|
|
|
791 @example
|
|
|
792 # Makefile for apackage's lisp code
|
|
|
793
|
|
|
794 # This file is part of XEmacs.
|
|
|
795
|
|
|
796 # XEmacs is free software; you can redistribute it and/or modify it
|
|
|
797 # under the terms of the GNU General Public License as published by the
|
|
|
798 # Free Software Foundation; either version 2, or (at your option) any
|
|
|
799 # later version.
|
|
|
800
|
|
|
801 # XEmacs is distributed in the hope that it will be useful, but WITHOUT
|
|
|
802 # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
|
|
803 # FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
|
|
|
804 # for more details.
|
|
|
805
|
|
|
806 # You should have received a copy of the GNU General Public License
|
|
|
807 # along with XEmacs; see the file COPYING. If not, write to
|
|
|
808 # the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
|
|
|
809 # Boston, MA 02111-1307, USA.
|
|
|
810
|
|
|
811 VERSION = 0.00
|
|
|
812 AUTHOR_VERSION = 0.00
|
|
|
813 MAINTAINER = A. M. Aintainer <ama@@not.a.doc>
|
|
|
814 PACKAGE = apackage
|
|
|
815 PKG_TYPE = regular
|
|
|
816 REQUIRES = xemacs-base
|
|
|
817 CATEGORY = standard
|
|
|
818
|
|
|
819 # All .els should be compiled and packaged.
|
|
|
820 ELS = $(wildcard *.el)
|
|
|
821 ELCS = $(ELS:.el=.elc)
|
|
|
822
|
|
|
823 include ../../XEmacs.rules
|
|
|
824
|
|
|
825 all:: $(ELCS) auto-autoloads.elc custom-load.elc
|
|
|
826
|
|
|
827 srckit: srckit-std
|
|
|
828
|
|
|
829 binkit: binkit-common
|
|
|
830 @end example
|
|
|
831
|
|
|
832 @menu
|
|
|
833 * package-compile.el::
|
|
|
834 * package-info.in Fields::
|
|
|
835 * Makefile Variables::
|
|
|
836 * Makefile Targets::
|
|
|
837 @end menu
|
|
|
838
|
|
|
839
|
|
|
840 @node package-compile.el, package-info.in Fields, , Creating Packages
|
|
|
841
|
|
|
842 The @xpms{} does not automatically become aware of your package simply
|
|
|
843 because there is a new subtree. If any package, including your own,
|
|
|
844 requires any of your files, it must be explicitly added to the compile
|
|
|
845 environment or loads/requires that search load-path will fail. The
|
|
|
846 changes that need to be made are
|
|
|
847
|
|
|
848 @table @strong
|
|
694
|
849 @item an entry in @code{package-directory-map}
|
|
693
|
850 This tells the @xpms{} which distribution (currently
|
|
|
851 @samp{xemacs-packages} or @samp{mule-packages}) your package is found
|
|
|
852 in. It then looks in the distribution subdirectory whose name is the
|
|
|
853 same as the package's.
|
|
|
854
|
|
|
855 @item an entry in the @code{cond} in @code{package-name-to-directory}
|
|
|
856 This is optional; it is necessary only if you keep your Lisp code
|
|
|
857 somewhere other than the top-level directory of the package's source
|
|
|
858 tree, eg, in @file{packages/xemacs-packages/@var{PACKAGE}/lisp}.
|
|
|
859 @end table
|
|
|
860
|
|
|
861 This only needs to be done once, when the package is first added to the
|
|
|
862 @xpms{}. (Well, when you randomly change the subdirectory layout, too.)
|
|
|
863 Your changes to @file{package-compile.el} must be cleared and checked in
|
|
|
864 by the XEmacs Package Release Engineer before your package will build
|
|
|
865 correctly from a fresh checkout.
|
|
|
866
|
|
694
|
867 This is unfortunate; it works pretty well once set up, but can cause
|
|
|
868 confusion when first building a package in the @xpms{} context. In
|
|
|
869 particular, if the @code{package-directory-map} entry for a required
|
|
|
870 package
|
|
|
871 @c #### including the package itself?
|
|
|
872 is not found, the necessary requires will not be executed by
|
|
|
873 @file{package-compile.el}. If required functions are executed (under
|
|
|
874 @code{eval-when-compile}), they won't be found and the compile will
|
|
|
875 fail. If required function is actually a macro, the byte compiler will
|
|
|
876 not recognize that, compile a function call to the macro. This will
|
|
|
877 cause a run-time error because the byte-code interpreter does not know
|
|
|
878 how to execute macros. (Macros can always be expanded at compile-time,
|
|
|
879 and this is more efficient.)
|
|
|
880
|
|
|
881 If your package keeps some or all Lisp code somewhere other than the top
|
|
|
882 directory, then an entry in @code{package-name-to-directory} is also
|
|
|
883 necessary, or requires will fail, leading to the problems just described.
|
|
693
|
884
|
|
|
885
|
|
|
886 @node package-info.in Fields, Makefile Variables, package-compile.el, Creating Packages
|
|
|
887
|
|
|
888 The @file{package-info.in} structure is simply Lisp data, to be read by
|
|
|
889 a Lisp script, have values substituted for variables, and then written
|
|
|
890 out (appropriately quoted) into a loadable Lisp file, to be consed into
|
|
|
891 the @file{package-index.el} list at the FTP archives. That list is
|
|
|
892 structured as an alist with package names as keys. The package data is
|
|
|
893 a plist. Do not rely on this, as it may change. If you have a good
|
|
|
894 reason for relying on it, let the maintainers know and we may
|
|
|
895 incorporate it in a future revision of the @xpms{} standard.
|
|
|
896
|
|
|
897 There are several kinds of fields, distinguished by how they get their
|
|
|
898 values. There are literals written into @file{package-info.in} by the
|
|
|
899 package maintainer. There are variables substituted in by the build
|
|
|
900 process, some computed, and others written as values of @file{make}
|
|
|
901 variables in the @file{Makefile} by the package maintainer. There are a
|
|
|
902 few implementation constants, some of which are simply the default value
|
|
|
903 for obsolete fields.
|
|
|
904
|
|
|
905 The @file{package-info.in} literals provided by the maintainer generally
|
|
|
906 should not change over the life of the package. (The exception is the
|
|
|
907 @samp{provides} field, which should be generated, but isn't yet.)
|
|
|
908 Values described as ``literal'' below are unquoted literal test. These
|
|
|
909 are normally interpreted as symbols by the package build process. The
|
|
|
910 maintainer literals are
|
|
|
911
|
|
|
912 @table @asis
|
|
|
913 @item @var{package_name}
|
|
|
914 A literal. The only unnamed ``field,'' the name of the package.
|
|
|
915
|
|
|
916 @item distribution
|
|
|
917 A literal, either @samp{xemacs} (for generic packages) or @samp{mule}
|
|
|
918 (for packages requiring Mule). @xref{Package Terminology}.
|
|
|
919
|
|
|
920 @item description
|
|
|
921 A Lisp string containing a one-line text description for use in package
|
|
|
922 listings.
|
|
|
923
|
|
|
924 @item provides
|
|
|
925 A (Lisp) list of features provided by the libraries in the package. All
|
|
|
926 of the features provided by libraries in your package should be elements
|
|
|
927 of this list.
|
|
|
928
|
|
|
929 @item type
|
|
|
930 A literal, either @samp{regular} or @samp{single-file}. For practical
|
|
|
931 purposes, @samp{regular} should be considered an implementation constant.
|
|
|
932 @end table
|
|
|
933
|
|
|
934 @c #### The following should be rewritten to @xref the make variables
|
|
|
935 @c node, and simply associate the field names to the make variables with
|
|
|
936 @c one line of description.
|
|
|
937 Values which are expected to change regularly as the package is enhanced
|
|
|
938 are implemented as @file{make} variables. You should not change them in
|
|
|
939 the @file{package-info.in} file; they are automatically filled in by the
|
|
|
940 build process.
|
|
|
941
|
|
|
942 The corresponding field name is given in parentheses. These include
|
|
|
943
|
|
|
944 @table @code
|
|
|
945 @item VERSION
|
|
|
946 (version)
|
|
|
947 The version of the XEmacs package, a numeric literal (a decimal
|
|
|
948 fixed-point number with two-places of precision).
|
|
|
949
|
|
|
950 @item AUTHOR_VERSION
|
|
|
951 (author-version)
|
|
|
952 The upstream author's version, an unintepreted literal.
|
|
|
953
|
|
|
954 @item DATE
|
|
|
955 (date)
|
|
|
956 Date of release of the upstream version.
|
|
|
957
|
|
|
958 @item MAINTAINER
|
|
|
959 (maintainer)
|
|
|
960 A literal containing the XEmacs package's maintainer and his/her email
|
|
|
961 address.
|
|
|
962
|
|
|
963 @item CATEGORY
|
|
|
964 (category)
|
|
|
965 A literal, either @samp{standard} or @samp{mule}. Probably redundant.
|
|
|
966
|
|
|
967 @item REQUIRES
|
|
|
968 (requires)
|
|
|
969 A list of packages required to correctly build this package.
|
|
|
970
|
|
|
971 Note that the usual form in @file{package-info.in} already has the
|
|
|
972 parentheses, so the @file{make} variable should be set to a
|
|
|
973 space-separated list of package names @emph{not} enclosed in
|
|
|
974 parentheses.
|
|
|
975
|
|
|
976 The list is of @emph{packages}, not @emph{libraries}, as would
|
|
|
977 ordinarily be provided to the Lisp @code{require} function.
|
|
|
978
|
|
|
979 @samp{REQUIRES} cannot be correctly computed from the calls to
|
|
|
980 @code{require} in the package's library sources. @samp{REQUIRES} is
|
|
|
981 used to ensure that all macro and defstruct definitions used by the
|
|
|
982 package are available at build time. This is not merely a matter of
|
|
|
983 efficiency, to get the expansions inlined. In fact, it is
|
|
|
984 @emph{impossible} to call a macro by name in byte-compiled Emacs Lisp
|
|
|
985 code. Thus, if the macro expansion is not inlined, the call will result
|
|
|
986 in an error at run-time! Thus, packages providing libraries that would
|
|
|
987 be loaded because of autoload definitions must also be included.
|
|
|
988
|
|
|
989 On the other hand, if a package provides no macros to this package, it
|
|
|
990 is preferable @emph{not} to include it in @samp{REQUIRES}, because it is
|
|
|
991 not uncommon that if the developer doesn't normally use the required
|
|
|
992 package, he will never use the functionality in the package being built,
|
|
|
993 either. In that case it would be preferable to not require the
|
|
|
994 developer to have source for the dependencies. That said, of course it
|
|
|
995 is safe to put too many packages in @samp{REQUIRES}.
|
|
|
996 @end table
|
|
|
997
|
|
|
998 Values for the following fields are automatically generated by the build
|
|
|
999 process.
|
|
|
1000
|
|
|
1001 @table @asis
|
|
|
1002 @item build-date
|
|
|
1003 The date the package tarball was generated.
|
|
|
1004
|
|
|
1005 @item md5sum
|
|
|
1006 An MD5 checksum for the package tarball, as gzipped.
|
|
|
1007
|
|
|
1008 @item size
|
|
|
1009 The size of the package tarball, as gzipped.
|
|
|
1010 @end table
|
|
|
1011
|
|
|
1012 It is not clear that either md5sum or size works correctly if the
|
|
|
1013 @samp{BZIP2} variable in @file{Local.rules} is set.
|
|
|
1014
|
|
|
1015 The implementation constants are
|
|
|
1016
|
|
|
1017 @table @asis
|
|
|
1018 @item standards-version
|
|
|
1019 Currently 1.1. Defines the format of the @file{package-info.in} file
|
|
|
1020 and the @file{Makefile}. A true implementation constant.
|
|
|
1021
|
|
|
1022 @item priority
|
|
|
1023 An unimplemented and underspecified feature. Suggestions for
|
|
|
1024 specification and implementation welcome.
|
|
|
1025
|
|
|
1026 @item dump
|
|
|
1027 An obsolete feature, superseded by the @file{site-load.el} mechanism.
|
|
|
1028 The value should always be nil.
|
|
|
1029
|
|
|
1030 @item filename
|
|
|
1031 An obsolete feature, completely ignored. Don't even think about doing
|
|
|
1032 anything useful with it.
|
|
|
1033 @end table
|
|
|
1034
|
|
|
1035
|
|
|
1036 @node Makefile Variables, Makefile Targets, package-info.in Fields, Creating Packages
|
|
|
1037
|
|
|
1038 A number of @file{make} variables are defined by the @xpms{}. Some are
|
|
|
1039 required, others are optional. Of course your @file{Makefile} may
|
|
|
1040 define other variables for private use, but you should be careful not to
|
|
|
1041 choose names that conflict with variables defined and used by the
|
|
|
1042 @xpms{}.
|
|
|
1043
|
|
|
1044 The required variables are described in the table below.
|
|
|
1045 The corresponding field names for @file{package-info.in}, where
|
|
|
1046 relevant, are given in parentheses.
|
|
|
1047
|
|
|
1048 @c #### This is the canonical place for this information. If there is
|
|
|
1049 @c unnecessary duplication with package-info.in documentation, shorten
|
|
|
1050 @c that and leave this full-length.
|
|
|
1051 @table @code
|
|
|
1052 @item VERSION
|
|
|
1053 (version)
|
|
|
1054 The version of the XEmacs package, a numeric literal (a decimal
|
|
|
1055 fixed-point number with two-places of precision).
|
|
|
1056
|
|
|
1057 @item AUTHOR_VERSION
|
|
|
1058 (author-version)
|
|
|
1059 The upstream author's version, an unintepreted literal.
|
|
|
1060
|
|
|
1061 @item DATE
|
|
|
1062 (date)
|
|
|
1063 Date of release of the upstream version.
|
|
|
1064
|
|
|
1065 @item MAINTAINER
|
|
|
1066 (maintainer)
|
|
|
1067 A literal containing the XEmacs package's maintainer and his/her email
|
|
|
1068 address.
|
|
|
1069
|
|
|
1070 @item CATEGORY
|
|
|
1071 (category)
|
|
|
1072 A literal, either @samp{standard} or @samp{mule}. Probably redundant.
|
|
|
1073
|
|
|
1074 @item REQUIRES
|
|
|
1075 (requires)
|
|
|
1076 A list of packages required to correctly build this package.
|
|
|
1077
|
|
|
1078 Note that the usual form in @file{package-info.in} already has the
|
|
|
1079 parentheses, so the @file{make} variable should be set to a
|
|
|
1080 space-separated list of package names @emph{not} enclosed in
|
|
|
1081 parentheses.
|
|
|
1082
|
|
|
1083 The list is of @emph{packages}, not @emph{libraries}, as would
|
|
|
1084 ordinarily be provided to the Lisp @code{require} function.
|
|
|
1085
|
|
|
1086 @samp{REQUIRES} cannot be correctly computed from the calls to
|
|
|
1087 @code{require} in the package's library sources. @samp{REQUIRES} is
|
|
|
1088 used to ensure that all macro and defstruct definitions used by the
|
|
|
1089 package are available at build time. This is not merely a matter of
|
|
|
1090 efficiency, to get the expansions inlined. In fact, it is
|
|
|
1091 @emph{impossible} to call a macro by name in byte-compiled Emacs Lisp
|
|
|
1092 code. Thus, if the macro expansion is not inlined, the call will result
|
|
|
1093 in an error at run-time! Thus, packages providing libraries that would
|
|
|
1094 be loaded because of autoload definitions must also be included.
|
|
|
1095
|
|
|
1096 On the other hand, if a package provides no macros to this package, it
|
|
|
1097 is preferable @emph{not} to include it in @samp{REQUIRES}, because it is
|
|
|
1098 not uncommon that if the developer doesn't normally use the required
|
|
|
1099 package, he will never use the functionality in the package being built,
|
|
|
1100 either. In that case it would be preferable to not require the
|
|
|
1101 developer to have source for the dependencies. That said, of course it
|
|
|
1102 is safe to put too many packages in @samp{REQUIRES}.
|
|
|
1103
|
|
|
1104 @item ELCS
|
|
|
1105 The list of the byte-compiled Lisp files used by the package. These
|
|
|
1106 files and their @file{.el} versions will be included in the binary
|
|
|
1107 package. This variable determines which libraries will be
|
|
|
1108 byte-compiled. These libraries are also deleted by @samp{make clean}.
|
|
|
1109
|
|
|
1110 Note there is no sanity-checking done on this variable. If you put
|
|
|
1111 @samp{.el} files in here, they will not be compiled and they @emph{will}
|
|
|
1112 be deleted by @samp{make clean}. You would surely be very distressed if
|
|
|
1113 that happened, so be very careful. If this variable is left empty, none
|
|
|
1114 of your Lisp code will be compiled or packaged. This would be a less
|
|
|
1115 than amusing surprise, too.
|
|
|
1116
|
|
|
1117 We don't consider this a feature, of course. Please do submit code to
|
|
|
1118 do sanity checking to @email{xemacs-patches@@xemacs.org}.
|
|
|
1119 @end table
|
|
|
1120
|
|
|
1121 Optional, but very commonly used variables include:
|
|
|
1122
|
|
|
1123 @table @code
|
|
|
1124 item EXTRA_SOURCES
|
|
|
1125 Other files (such as extra Lisp sources or an upstream @file{Makefile})
|
|
|
1126 that are normally placed in the installed Lisp directory, but not
|
|
|
1127 byte-compiled. These files are @emph{preserved} by the @samp{clean}
|
|
|
1128 targets.
|
|
|
1129
|
|
|
1130 @item EXTRA_OBJS
|
|
|
1131 Other files (such as compiled autoload or concatenated @file{.elc}
|
|
|
1132 libraries) which are normally placed in the installed Lisp directory,
|
|
|
1133 but do @emph{not} have corresponding source files and @emph{should} be
|
|
|
1134 deleted by the @samp{clean} targets. Some of these (such as
|
|
|
1135 package-specific autoload setups) can and probably should be replaced by
|
|
|
1136 @xpms{} solutions such as @file{auto-autoloads.el}, but many cannot.
|
|
|
1137
|
|
|
1138 @item PRELOADS
|
|
|
1139 A specification for loading libraries containing macros before compiling
|
|
|
1140 the Lisp in the package. This is spliced directly into the invocation
|
|
|
1141 of XEmacs for byte-compilation, so it must contain the @samp{-l} flag
|
|
|
1142 for XEmacs:
|
|
|
1143
|
|
|
1144 @example
|
|
|
1145 PRELOADS=-l ./apackage-macros.el -l ../bpackage/lisp/bpackage-macros.el
|
|
|
1146 @end example
|
|
|
1147
|
|
|
1148 @item INFO_FILES
|
|
|
1149 Any Info file(s) generated by the package. These must be paths relative
|
|
|
1150 to the root of the package's source tree.
|
|
|
1151
|
|
|
1152 @item TEXI_FILES
|
|
|
1153 The Texinfo source file(s). These must be paths relative
|
|
|
1154 to the root of the package's source tree.
|
|
|
1155
|
|
|
1156 @item MANUAL
|
|
|
1157 The name to be used for Info files and man pages.
|
|
|
1158
|
|
|
1159 @item DATA_FILES
|
|
|
1160 Any data files, such as pixmaps, READMEs, and ChangeLogs. These must be
|
|
|
1161 paths relative to the root of the package's source tree.
|
|
|
1162
|
|
|
1163 @item DATA_DEST
|
|
|
1164 The installation location for data files, relative to the @file{etc/}
|
|
|
1165 directory of the package hierarchy. The normal value is simply
|
|
|
1166 $(PACKAGE). Leaving it empty (@emph{i.e.}, put it directly under
|
|
|
1167 @file{etc/}) will probably work, but is subject to name conflicts with
|
|
|
1168 other packages.
|
|
|
1169 @end table
|
|
|
1170
|
|
|
1171 Rarely used variables.
|
|
|
1172
|
|
|
1173 @c @table @code
|
|
|
1174 @c @item
|
|
|
1175 @c @end table
|
|
|
1176
|
|
|
1177 @node Makefile Targets, , Makefile Variables, Creating Packages
|
|
|
1178
|
|
|
1179 The standard targets that need to be defined in your @file{Makefile}
|
|
|
1180 follow. These normally should @emph{not} have an action. All of the
|
|
|
1181 work should be done by dependent targets, usually having standard
|
|
|
1182 definitions in the @xpms{}.
|
|
|
1183
|
|
|
1184 @table @samp
|
|
|
1185 @item all
|
|
|
1186 A list of generated files, usually byte-compiled Lisp libraries, to be
|
|
|
1187 bundled in the package. The typical dependencies are
|
|
|
1188
|
|
|
1189 @example
|
|
|
1190 $(ELCS) auto-autoloads.elc custom-load.elc
|
|
|
1191 @end example
|
|
|
1192
|
|
|
1193 Other targets (such as Info files) may need to be added as dependencies
|
|
|
1194 for the @code{all} target.
|
|
|
1195
|
|
|
1196 @item srckit
|
|
|
1197 The target for generating a source package. Not implemented. If it
|
|
|
1198 were, the normal dependency would be @samp{srckit-std}.
|
|
|
1199
|
|
|
1200 @item binkit
|
|
|
1201 The target for creating a ``master'' installation. Binary packages are
|
|
|
1202 actually generated by the @samp{bindist} target. @xref{Building Packages}.
|
|
|
1203 @end table
|
|
|
1204
|
|
|
1205 Standard dependencies for @code{srckit} and @code{binkit} are defined in
|
|
|
1206 @file{XEmacs.rules}. The most useful of these values are given in the
|
|
|
1207 following table.
|
|
|
1208
|
|
|
1209 @table @samp
|
|
|
1210 @item srckit-std
|
|
|
1211 Build a standard source kit. Not fully implemented.
|
|
|
1212
|
|
|
1213 @item binkit-sourceonly
|
|
|
1214 The @samp{binkit} target need only install source and compiled Lisp in
|
|
|
1215 the staging area. There is nothing to install in a data directory or
|
|
|
1216 info directory.
|
|
|
1217
|
|
|
1218 @item binkit-sourceinfo
|
|
|
1219 Both source and info files are to be installed in the staging area.
|
|
|
1220
|
|
|
1221 @item binkit-sourcedata
|
|
|
1222 Both source and etc (data) files are to be installed in the staging
|
|
|
1223 area.
|
|
|
1224
|
|
|
1225 @item binkit-sourcedatainfo
|
|
|
1226 Source, etc (data), and info files all are present and need to be
|
|
|
1227 installed in the staging area.
|
|
|
1228
|
|
|
1229 @item binkit-common
|
|
|
1230 A dependency for all the above. (In fact in the current implementation
|
|
|
1231 @samp{binkit-common} does all the work for all of the @samp{binkit}
|
|
|
1232 targets.)
|
|
|
1233 @end table
|
|
|
1234
|
|
|
1235 Data files include things like pixmaps for a package-specific toolbar,
|
|
|
1236 and are normally installed in @file{etc/@var{PACKAGE_NAME}}. A few
|
|
|
1237 packages have needs beyond the basic templates. See @file{XEmacs.rules}
|
|
|
1238 or a future revision of this manual for details.
|
|
|
1239
|
|
|
1240
|
|
|
1241 @node Issues, , Creating Packages, Packaging
|
|
|
1242 @section Issues
|
|
|
1243
|
|
694
|
1244 To be completed.
|
|
693
|
1245
|
