Mercurial > hg > xemacs-beta
annotate man/lispref/packaging.texi @ 5903:5afddd952c46
Return ratios in canonical form too, #'string-to-number
src/ChangeLog addition:
2015-05-08 Aidan Kehoe <kehoea@parhasard.net>
* data.c (Fstring_to_number):
Canonicalise ratios in this function, as we do bignums.
| author | Aidan Kehoe <kehoea@parhasard.net> |
|---|---|
| date | Fri, 08 May 2015 13:58:22 +0100 |
| parents | 9c17f7be0b92 |
| children |
| rev | line source |
|---|---|
| 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 |
|
5744
9c17f7be0b92
Require makeinfo 4.12 or later to build the info files. See xemacs-beta
Jerry James <james@xemacs.org>
parents:
5741
diff
changeset
|
527 (4.12 from texinfo-4.12) |
| 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 | |
|
5741
d11efddf3617
Fix texinfo constructs that are rejected by texinfo 5.x. See xemacs-patches
Jerry James <james@xemacs.org>
parents:
5402
diff
changeset
|
603 @section The targets that most people would be interested in would be: |
| 1648 | 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. | |
|
5402
308d34e9f07d
Changed bulk of GPLv2 or later files identified by script
Mats Lidell <matsl@xemacs.org>
parents:
3179
diff
changeset
|
996 # |
|
308d34e9f07d
Changed bulk of GPLv2 or later files identified by script
Mats Lidell <matsl@xemacs.org>
parents:
3179
diff
changeset
|
997 # XEmacs is free software: you can redistribute it and/or modify it |
| 693 | 998 # under the terms of the GNU General Public License as published by the |
|
5402
308d34e9f07d
Changed bulk of GPLv2 or later files identified by script
Mats Lidell <matsl@xemacs.org>
parents:
3179
diff
changeset
|
999 # Free Software Foundation, either version 3 of the License, or (at your |
|
308d34e9f07d
Changed bulk of GPLv2 or later files identified by script
Mats Lidell <matsl@xemacs.org>
parents:
3179
diff
changeset
|
1000 # option) any later version. |
|
308d34e9f07d
Changed bulk of GPLv2 or later files identified by script
Mats Lidell <matsl@xemacs.org>
parents:
3179
diff
changeset
|
1001 # |
| 693 | 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. | |
|
5402
308d34e9f07d
Changed bulk of GPLv2 or later files identified by script
Mats Lidell <matsl@xemacs.org>
parents:
3179
diff
changeset
|
1006 # |
| 693 | 1007 # You should have received a copy of the GNU General Public License |
|
5402
308d34e9f07d
Changed bulk of GPLv2 or later files identified by script
Mats Lidell <matsl@xemacs.org>
parents:
3179
diff
changeset
|
1008 # along with XEmacs. If not, see <http://www.gnu.org/licenses/>. |
| 693 | 1009 |
| 1648 | 1010 # For the time being, remove MULE_ELCS from the all dependencies if |
| 1011 # building without Mule. | |
| 1012 | |
| 1013 VERSION = 1.10 | |
| 1014 AUTHOR_VERSION = 2.02 | |
| 1015 MAINTAINER = Adrian Aichner <adrian@@xemacs.org> | |
| 1016 PACKAGE = build | |
| 693 | 1017 PKG_TYPE = regular |
| 1648 | 1018 REQUIRES = xemacs-base pcl-cvs dired w3 prog-modes |
| 693 | 1019 CATEGORY = standard |
| 1020 | |
| 1648 | 1021 ELCS = build.elc build-report.elc |
| 1022 | |
| 1023 STANDARD_DOCS = t | |
| 693 | 1024 |
| 1025 include ../../XEmacs.rules | |
| 1648 | 1026 @end example |
| 693 | 1027 |
| 1648 | 1028 Most packages don't need any more than what you see above. It is |
| 1029 usually @emph{not} necessary to specify any special @file{Makefile} | |
| 1030 rules. Everything is handled from the @file{*.rules} files in the | |
| 1031 toplevel of the package source hierarchy. | |
| 1032 | |
| 1033 Of course, with that said, there are always exceptions to the rule. If | |
| 1034 you think that your package will need some special @file{Makefile} | |
| 1035 hackery contact the @email{xemacs-beta@@xemacs.org, XEmacs developers}. | |
| 1036 We distribute over 100 packages so the chances are good that you won't | |
| 1037 be the first to need such hackery and it is probably already catered | |
| 1038 for. | |
| 1039 | |
| 1040 @subheading @file{Makefile} Variables Explained: | |
| 2955 | 1041 A number of @file{make} variables are defined by the @value{xpms}. Some are |
| 1648 | 1042 required, others are optional. Of course your @file{Makefile} may |
| 1043 define other variables for private use, but you should be careful not to | |
| 1044 choose names that conflict with variables defined and used by the | |
| 2955 | 1045 @value{xpms}. |
| 1648 | 1046 |
| 1047 The required variables are described in the table below. | |
| 1048 The corresponding field names for @file{package-info.in}, where | |
| 1049 relevant, are given in parentheses. | |
| 1050 | |
| 1051 @c This is the canonical place for this information. If there is | |
| 1052 @c unnecessary duplication with package-info.in documentation, shorten | |
| 1053 @c that and leave this full-length. | |
| 1054 @table @samp | |
| 1055 @item VERSION | |
| 1056 (version) | |
| 1057 The version of the XEmacs package, a numeric literal (a decimal | |
| 1058 fixed-point number with two-places of precision). The only person who | |
| 1059 ever needs to touch this is the XEmacs Packages Release Engineer. | |
| 1060 | |
| 1061 @item AUTHOR_VERSION | |
| 1062 (author-version) | |
| 1063 The upstream author's version, an uninterpreted literal. | |
| 1064 | |
| 1065 @item MAINTAINER | |
| 1066 (maintainer) | |
| 1067 A literal containing the XEmacs package's maintainer and his/her email | |
| 1068 address. | |
| 1069 | |
| 1070 @item PACKAGE | |
| 1071 The name of the package, a literal | |
| 1072 | |
| 1073 @item PKG_TYPE | |
| 1074 The type of package, a literal containing either @samp{regular} for | |
| 1075 regular packages, or @samp{single-file} for single-file packages. This | |
| 1076 should feed the @samp{type} field in @file{package-info.in}, but | |
| 1077 currently it doesn't. | |
| 1078 | |
| 1079 @strong{N.B.} @samp{single-file} here does @emph{not} refer to the | |
| 1080 number of lisp files in a package. @xref{Package Terminology}. | |
| 693 | 1081 |
| 1648 | 1082 @item CATEGORY |
| 1083 (category) | |
| 1084 A literal, either @samp{standard} or @samp{mule}. The non-Mule packages | |
| 1085 are @samp{standard} and the Mule packages are, you guessed it, | |
| 1086 @samp{mule}. This field is used at package installation time as part of | |
| 1087 the process of determining where a package should be installed to. | |
| 1088 | |
| 1089 @item REQUIRES | |
| 1090 (requires) | |
| 1091 A list of packages required to correctly build this package. | |
| 1092 | |
| 1093 Note that the usual form in @file{package-info.in} already has the | |
| 1094 parentheses, so the @file{make} variable should be set to a | |
| 1095 space-separated list of package names @emph{not} enclosed in | |
| 1096 parentheses. | |
| 1097 | |
| 1098 The list is of @emph{packages}, not @emph{libraries}, as would | |
| 1099 ordinarily be provided to the Lisp @code{require} function. | |
| 1100 | |
| 1101 @samp{REQUIRES} cannot be correctly computed from the calls to | |
| 1102 @code{require} in the package's library sources. @samp{REQUIRES} is | |
| 1103 used to ensure that all macro and defstruct definitions used by the | |
| 1104 package are available at build time. This is not merely a matter of | |
| 1105 efficiency, to get the expansions inlined. In fact, it is | |
| 1106 @emph{impossible} to call a macro by name in byte-compiled Emacs Lisp | |
| 1107 code. Thus, if the macro expansion is not inlined, the call will result | |
| 1108 in an error at run-time! Thus, packages providing libraries that would | |
| 1109 be loaded because of autoload definitions must also be included. | |
| 693 | 1110 |
| 1648 | 1111 @item ELCS |
| 1112 The list of the byte-compiled Lisp files used by the package. These | |
| 1113 files and their @file{.el} versions will be included in the binary | |
| 1114 package. This variable determines which libraries will be | |
| 1115 byte-compiled. These libraries are also deleted by @samp{make clean}. | |
| 1116 | |
| 1117 Note there is no sanity-checking done on this variable. If you put | |
| 1118 @samp{.el} files in here, they will not be compiled and they @emph{will} | |
| 1119 be deleted by @samp{make clean}. You would surely be very distressed if | |
| 1120 that happened, so be very careful. If this variable is left empty, none | |
| 1121 of your Lisp code will be compiled or packaged. This would be a less | |
| 1122 than amusing surprise, too. | |
| 1123 | |
| 1124 We don't consider this a feature, of course. Please do submit code to | |
| 1125 do sanity checking to @email{xemacs-patches@@xemacs.org}. | |
| 1126 @end table | |
| 1127 | |
| 1128 Optional, but commonly used variables are explained below. | |
| 1129 | |
| 1130 @table @samp | |
| 1131 @item ELCS_1 | |
| 1132 A list of extra byte-compiled Lisp files used by the package to be | |
| 1133 installed in a subdirectory of the package's lisp directory. The same | |
| 1738 | 1134 care should be taken with this as with @code{ELCS} in regard to |
| 1648 | 1135 @code{make clean}. |
| 1136 | |
| 1137 @item ELCS_1_DEST | |
| 1738 | 1138 The name of the subdirectory for the @code{ELCS_1} files to be installed |
| 1648 | 1139 to. Be sure to include @samp{$(PACKAGE)/} as part of the name. |
| 1140 | |
| 1141 @example | |
| 1142 ELCS_1_DEST = $(PACKAGE)/extra | |
| 693 | 1143 @end example |
| 1144 | |
| 1738 | 1145 Would put the @code{ELCS_1} files for the package, @samp{foo} into |
| 1146 @file{xemacs-packages/lisp/foo/extra/}. | |
| 1648 | 1147 |
| 1148 @item EARLY_GENERATED_LISP | |
| 1149 For additional @file{.el} files that will be generated before any | |
| 1150 byte-compiling happens. Use this for @samp{autoload-type} files. You | |
| 1151 must write @file{Makefile} rules to build these files. | |
| 1152 | |
| 1153 @item GENERATED_LISP | |
| 1154 For additional @file{.el} files that will be generated at | |
| 1155 byte-compilation time. You must write @file{Makefile} rules to build | |
| 1156 these files. | |
| 1157 | |
| 1158 @item PRELOADS | |
| 1159 This is used if you need to pass extra command line arguments to | |
| 1160 XEmacs to build the package. For instance, a specification for | |
| 1161 loading libraries containing macros before compiling the Lisp in the | |
| 1162 package. This is spliced directly into the invocation of XEmacs for | |
| 1163 byte-compilation, so it must contain the @samp{-l} flag for XEmacs: | |
| 1164 | |
| 1165 @example | |
| 1166 PRELOADS=-l ./apackage-macros.el -l ../bpackage/lisp/bpackage-macros.el | |
| 1167 @end example | |
| 1168 | |
| 1169 Preloads are loaded before @file{package-compile.el}, so the | |
| 1738 | 1170 @code{load-path} is minimal. Therefore @samp{PRELOADS} must specify a |
| 1171 full path to packaged Lisp. The base @code{load-path} does include the | |
| 1648 | 1172 core Lisp directory, so core libraries are found. |
| 1173 | |
| 1174 @item AUTOLOAD_PATH | |
| 1175 The subdirectory in the package's source tree where the @file{.el} files | |
| 1176 reside. This is where the @file{auto-autoloads.el} file will be placed. | |
| 1177 | |
| 1178 @strong{N.B.} There is no need to use this variable if the @file{.el} | |
| 1738 | 1179 files are in the package's toplevel directory. @code{AUTOLOAD_PATH} |
| 1648 | 1180 defaults to @samp{.}. |
| 1181 | |
| 1182 @item PACKAGE_SUPPRESS | |
| 1183 Place calls to @code{package-suppress} here to indicate Lisp libraries | |
| 1184 that should only be available to particular versions of XEmacs. For | |
| 1185 example: | |
| 1186 | |
| 1187 @example | |
| 1188 PACKAGE_SUPPRESS = \ | |
| 1189 (package-suppress 'xemacs-base \"regexp-opt\" '(emacs-version>= 21 5 11)) \ | |
| 1190 (package-suppress 'xemacs-base \"easy-mmode\" '(emacs-version>= 21 5 11)) | |
| 1191 @end example | |
| 1192 | |
| 1193 @c Change this when Ben has committed the WS that implements | |
| 1194 @c `package-suppress' --SY. | |
| 1195 @strong{N.B.} This feature has not yet been implemented in XEmacs yet. | |
| 1196 It will appear in an upcoming version of XEmacs 21.5. | |
| 1197 | |
| 1198 @item STANDARD_DOCS | |
| 1199 Set this to @samp{t} if your package's Texinfo source file is located in | |
| 1200 the package's toplevel directory @emph{and} is named | |
| 1201 @file{$(PACKAGE).texi}. | |
| 1202 | |
| 1203 @item EXPLICIT_DOCS | |
| 1204 Use this to explicitly list Texinfo sources that @emph{aren't} in the | |
| 1205 package's toplevel directory. For example: | |
| 1206 | |
| 1207 @example | |
| 1208 EXPLICIT_DOCS = texi/$(PACKAGE).texi | |
| 1209 @end example | |
| 693 | 1210 |
| 1738 | 1211 See @code{DOCS_TXI_EXTENSION} and @code{DOCS_TEXINFO_EXTENSION} if you |
| 1648 | 1212 don't use the @file{.texi} file extension on your Texinfo sources. |
| 693 | 1213 |
| 1648 | 1214 @item EXTRA_TEXI_FILES |
| 1215 List here extra Texinfo source files needed to build your | |
| 1216 documentation. Whatever is listed here is passed on to @code{makeinfo} | |
| 1217 as a dependency. | |
| 1218 | |
| 1219 @item EXTRA_HTML_FILES | |
| 1220 Use this to specify extra @file{.html} files to output. | |
| 1221 | |
| 1222 @item DOCS_TEXINFO_EXTENSION | |
| 1223 Set this to @samp{t} if your Texinfo source files have a @samp{.texinfo} | |
| 1224 extension. | |
| 1225 | |
| 1226 @item DOCS_TXI_EXTENSION | |
| 1227 Set this to @samp{t} if your Texinfo source files have a @samp{.txi} | |
| 1228 extension. | |
| 1229 | |
| 1230 @item EXTRA_DOC_FILES | |
| 1231 Files listed here will be installed to @file{.../man/$(PACKAGE)/}. For | |
| 1232 example, you might want to list @TeX{} files or @file{.eps} files here. | |
| 1233 | |
| 1234 @item EXTRA_SOURCES | |
| 1235 Other files (such as extra Lisp sources or an upstream @file{Makefile}) | |
| 1236 that are normally placed in the installed Lisp directory, but not | |
| 1237 byte-compiled. These files are @emph{preserved} by the @samp{clean} | |
| 1238 targets. | |
| 1239 | |
| 1240 @item LIBSRC_FILES | |
| 1241 For files that need to be installed to @file{lib-src/$(PACKAGE)/}. If | |
| 1242 the files listed here need to be built you will have to write | |
| 1243 @file{Makefile} rules to do so. | |
| 693 | 1244 |
| 1648 | 1245 @item DATA_FILES |
| 1246 Any data files, such as pixmaps, READMEs, and ChangeLogs. These must be | |
| 1247 paths relative to the root of the package's source tree. These files | |
| 1248 will be copied to @samp{$(DATA_DEST)} for installation. Any directory | |
| 1249 component of the path for a file will be stripped, so that the | |
| 1250 file ends up in @samp{$(DATA_DEST)}, not in a subdiredtory. | |
| 1251 | |
| 1252 @item DATA_DEST | |
| 1738 | 1253 The directory where the files in @code{DATA_FILES} are installed to. It |
| 1648 | 1254 is a subdirectory of the installed @file{etc/} directory. Be sure to |
| 1255 prefix this value with @samp{$(PACKAGE)}, for example: | |
| 1256 | |
| 1257 @example | |
| 1258 DATA_DEST = $(PACKAGE)/foo | |
| 1259 @end example | |
| 1260 | |
| 1261 Would put files into @file{.../etc/$(PACKAGE)/foo/}. | |
| 1262 | |
| 1263 @item DATA_1_FILES ... DATA_35_FILES | |
| 1264 For data files that need to go into a different directory from | |
| 1738 | 1265 @code{DATA_DEST}. |
| 1648 | 1266 |
| 1267 @item DATA_1_DEST ... DATA_35_DEST | |
| 1738 | 1268 The name of the subdirectory for files specified in |
| 1269 @code{DATA_@var{n}_FILES}. And like @code{DATA_DEST}, be sure to prefix | |
| 1270 @samp{$(PACKAGE)} to the value of these variables. | |
| 1648 | 1271 |
| 1272 @item EXTRA_DEPENDENCIES | |
| 1273 For additional files to build that aren't appropriate to place in any | |
| 1274 other @file{Makefile} variable. You will need to write @file{Makefile} | |
| 1275 rules to build these files. | |
| 1276 @end table | |
| 1277 | |
| 1278 @section @file{package-compile.el} | |
| 1279 @cindex package-compile.el | |
| 1280 @cindex compiling packages | |
| 2955 | 1281 The @value{xpms} does not automatically become aware of your package simply |
| 693 | 1282 because there is a new subtree. If any package, including your own, |
| 1283 requires any of your files, it must be explicitly added to the compile | |
| 1284 environment or loads/requires that search load-path will fail. The | |
| 1285 changes that need to be made are | |
| 1286 | |
| 1287 @table @strong | |
| 694 | 1288 @item an entry in @code{package-directory-map} |
| 2955 | 1289 This tells the @value{xpms} which distribution (currently |
| 693 | 1290 @samp{xemacs-packages} or @samp{mule-packages}) your package is found |
| 1291 in. It then looks in the distribution subdirectory whose name is the | |
| 1292 same as the package's. | |
| 1293 | |
| 1294 @item an entry in the @code{cond} in @code{package-name-to-directory} | |
| 1295 This is optional; it is necessary only if you keep your Lisp code | |
| 1296 somewhere other than the top-level directory of the package's source | |
| 1738 | 1297 tree, eg, in @file{packages/xemacs-packages/$(PACKAGE)/lisp}. |
| 693 | 1298 @end table |
| 1299 | |
| 1300 This only needs to be done once, when the package is first added to the | |
| 2955 | 1301 @value{xpms}. (Well, when you randomly change the subdirectory layout, too.) |
| 693 | 1302 Your changes to @file{package-compile.el} must be cleared and checked in |
| 1303 by the XEmacs Package Release Engineer before your package will build | |
| 1304 correctly from a fresh checkout. | |
| 1305 | |
| 694 | 1306 This is unfortunate; it works pretty well once set up, but can cause |
| 2955 | 1307 confusion when first building a package in the @value{xpms} context. In |
| 694 | 1308 particular, if the @code{package-directory-map} entry for a required |
| 1648 | 1309 package, including the package itself, is not found, the necessary |
| 1310 requires will not be executed by @file{package-compile.el}. If | |
| 1311 required functions are executed (under @code{eval-when-compile}), | |
| 1312 they won't be found and the compile will fail. If required function | |
| 1313 is actually a macro, the byte compiler will not recognize that, | |
| 1314 compile a function call to the macro. This will cause a run-time | |
| 1315 error because the byte-code interpreter does not know how to execute | |
| 1316 macros. (Macros can always be expanded at compile-time, and this is | |
| 1317 more efficient.) | |
| 694 | 1318 |
| 1319 If your package keeps some or all Lisp code somewhere other than the top | |
| 1320 directory, then an entry in @code{package-name-to-directory} is also | |
| 1321 necessary, or requires will fail, leading to the problems just described. | |
| 693 | 1322 |
| 752 | 1323 @node Documenting Packages, Issues, Creating Packages, Packaging |
| 1324 @comment node-name, next, previous, up | |
| 1325 @cindex documenting packages | |
| 1326 @heading Documenting Packages: | |
| 1327 | |
| 1328 @c #### Add a documentation section to Internals, and xref here. | |
| 1329 Some random notes on documenting your package. | |
| 1330 | |
| 1331 Do write a Texinfo file. It's not that hard to do basically, and even | |
| 1332 using the more advanced features of Texinfo soon become natural. For a | |
| 1333 start, just grab the template @file{Samples/package.texi} from the | |
| 2955 | 1334 @value{xpms} source tree, and drop your current README into the Top node. At |
| 752 | 1335 least this way your documentation will be accessible from the standard |
| 1336 Info readers. Next, try to add lots of cross-referencing and logical | |
| 1337 markup, and then node structure. | |
| 1338 | |
| 1339 Address both end users and developer issues. You may not be the | |
| 1340 maintainer forever. | |
| 1341 | |
| 1342 If you are maintaining a package that is part of the GNU Emacs | |
| 1343 distribution, you'll likely find that you occasionally synchronize your | |
| 1344 package with the GNU Emacs sources. When you synch a file, | |
| 1345 conventionally you should place a comment just above the standard | |
| 1346 @code{;;; Code} comment that looks like this: | |
| 1347 | |
| 1348 @example | |
| 1349 ;; Synched with: | |
| 1350 ;; GNU Emacs 21.1, 2002-02-08, Stephen Turnbull <stephen@@xemacs.org> | |
| 1351 @end example | |
| 1352 | |
| 1353 This comment is a status flag; the ChangeLog doesn't really give the | |
| 1354 same information. | |
| 1355 | |
| 1356 Do maintain a detailed ChangeLog. | |
| 1357 | |
| 1358 @node Issues, , Documenting Packages, Packaging | |
| 693 | 1359 @section Issues |
| 1360 | |
| 694 | 1361 To be completed. |
| 693 | 1362 |