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