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