xemacs-beta: man/lispref/packaging.texi comparison

comparison man/lispref/packaging.texi @ 693:b05e2a249757

[xemacs-hg @ 2001-12-14 07:50:06 by stephent] add lispref/packaging.texi

author	stephent
date	Fri, 14 Dec 2001 07:50:10 +0000
parents
children	561ad704dc70

comparison

equal deleted inserted replaced

-:cd697e94b3d4
+:b05e2a249757
+@c -*-texinfo-*-
+@c This is part of the XEmacs Lisp Reference Manual.
+@c Copyright (C) 2001 Free Software Foundation, Inc.
+@c See the file lispref.texi for copying conditions.
+@setfilename ../../info/packaging.info
+@c Macro to make formatting of the XEmacs pms name consistent.
+@c Maybe @sc looks OK in HTML?  If so, condition on Info.
+@iftex
+@macro xpms
+XE@sc{macs} Packaging System
+@end macro
+@end iftex
+@ifnottex
+@macro xpms
+XEmacs Packaging System
+@end macro
+@end ifnottex
+@node Packaging, Lisp Data Types, Introduction, Top
+@chapter The @xpms{}
+@cindex package
+@cindex packaging
+The XEmacs distribution, starting with version 21, comes only with a
+very basic set of built-in modes and libraries.  Most of the libraries
+that were part of the distribution of earlier versions of XEmacs are now
+available separately.  The user as well as the system administrator can
+choose which packages to install; the actual installation process is
+easy.  This gives an installer the ability to tailor an XEmacs
+installation for local needs with safe removal of unnecessary code.
+This chapter describes how to package Lisp libraries for use with the
+@xpms{}.
+@emph{Please note carefully} that the term @dfn{package} as used in
+XEmacs refers to an aggregation of Lisp code and/or data distributed as
+a unit.  It does not, as it does in many Lisps, refer to a way of
+creating separate name spaces.  XEmacs has no facility for providing
+separate name spaces.  (If we ever do get separate name spaces, we'll
+probably regret overloading the nomenclature in this way, but it's
+become established.)
+@menu
+Introduction:
+* Package Overview::       Lisp Libraries and Packages.
+Packaging Lisp Libraries:
+* Package Terminology::    Basic stuff.
+* Building Packages::      Turn packaged source into a tarball.
+* Local.rules File::       Tell the @xpms{} about your host.
+* Creating Packages::      Tell the @xpms{} about your package.
+@c * History::                     History of the @xpms{}
+@c * Installation::                Installing the @xpms{} with your (X)Emacs.
+@c * Configuration::               Configuring the @xpms{} for use.
+@c * Usage::                       An overview of the operation of the @xpms{}.
+@c * Bug Reports::                 Reporting Bugs and Problems
+@c * Frequently Asked Questions::  Questions and answers from the mailing list.
+Internals and Package Release Engineering:
+* Issues::
+@end menu
+@node Package Overview, Package Terminology, , Packaging
+@chapter An overview of the @xpms{}
+The @xpms{} is a system for administering the installation, upgrade, and
+removal of Lisp libraries.  For the end user, it provides facilities for
+determining availability of packages and which versions at remote
+sites.  It will download and automatically install a package, ensuring
+that any old files from previous versions of the package are removed
+first.  By providing a standard set of hierarchies for installation, it
+makes configuration of XEmacs simpler.  Furthermore, packages normally
+provide ancillary auto-autoloads and custom-loads libraries, which are
+automatically detected and loaded by XEmacs upon startup.  This means
+that once installed, all facilities of package, including autoloading
+the library upon invocation of a command provided by the library and
+convenient configuration and customization, are automatically available
+to the user.  There is no need to add autoloads or keybindings to in the
+init file, and structured configuration of the package is available
+through the Customize system even before the libraries are loaded.
+All of this convenience comes at a cost.  The cost of administration at
+the package level is negligible compared to the benefits, of course.
+However, the requirement that XEmacs find and load auto-autoloads and
+custom-loads libraries comes at a fairly large cost in startup time.  In
+order to reduce this cost, XEmacs imposes fairly strict conditions on
+the structure of an installed package.
+Meeting these requirements, as well as simply providing the
+auto-autoloads and the information about availability and so on does
+impose some costs on the library maintainer.  The @xpms{} also provides
+structure and utilities to the library maintainer to make these tasks
+easier.  This manual documents the requirements and the tools that the
+@xpms{} provides to ensure that a package satisfies them.
+@menu
+* The User's View::
+* The Library Maintainer's View::
+* The Package Release Engineer's View::
+@end menu
+@node The User's View, The Library Maintainer's View, , Package Overview
+@section The User's View
+@strong{N.B.}  Much of the discussion in this section undoubtedly
+belongs elsewhere, @ref{Packages,,,xemacs}.
+From the user's point of view, an XEmacs binary package is simply a
+standard tarball (usually gzipped) containing Lisp sources, compiled
+Lisp, documentation, and possibly data files or supporting executables.
+The tarball is unpacked using standard tools such as GNU tar and gzip.
+The package system does impose certain requirements for automatic
+configuration to work.
+Here the main consideration is that the tarball ``expects'' to be
+unpacked from the top of a package hierarchy.  A @dfn{package hierarchy}
+is basically an image of a classic Emacs ``run-in-place'' tree, with
+@file{lisp}, @file{etc}, @file{info}, @file{man}, @file{lib-src}, and
+@file{pkginfo} subdirectories of the top.  The @file{pkginfo}
+subdirectory is for use by the @xpms{} administration tools, and
+currently contains a @file{MANIFEST.@var{package-name}} file for each
+package to ensure that no cruft remains when a package is removed or
+updated.  The @file{lisp}, @file{etc}, and @file{lib-src} subdirectories
+are further subdivided, with a subdirectory for each package.  The
+@file{info} and @file{man} directories obey the respective documentation
+systems' conventions.  @emph{I.e.}, the @file{info} directory is flat
+with a(n) (optional) @file{dir} file and one (set of) info file(s) per
+package.  The @file{man} subdirectory is divided into sections.  As
+mentioned, this structure is used for historical reasions, and it is
+likely to change in the future.
+There are several standard package hierarchies, and administrators can
+configure others at build time, while users can configure others at run
+time.  The standard system hierarchies are all subdirectories of an
+@c #### This is possibly incorrect usage of "installation root."
+XEmacs installation root, typically @file{/usr/local/lib/xemacs/}.
+These are the @file{xemacs-packages}, @file{mule-packages},
+@file{infodock-packages}, and @file{site-packages} hierarchies.  Each
+has the structure described above, but the purposes differ.  The
+@file{xemacs-packages} is the normal place for installing ``official''
+packages and many third-party libraries.  Unfortunately, it is not yet
+quite possible to read libraries containing international characters
+with a non-Mule XEmacs, so such libraries are sequestered in the
+@file{mule-packages} hierarchy.  Some packages are compatible only with
+the Infodock development environment, and they will be installed in the
+@file{infodock-packages} hierarchy.  The @file{site-packages} hierarchy
+is for packages not distributed by XEmacs.org, typically locally
+developed.
+Packages are in principle supposed to be XEmacs version-independent, but
+if such dependencies are unavoidable, additional standard package
+hierarchies may be installed under version directories, @emph{e.g.}
+@file{/usr/local/lib/xemacs-21.4.6/}.
+Users who do not have sufficient privilege to install packages in the
+system hierarchies may install package hierarchies under
+@file{~/.xemacs}.  At present only the @file{xemacs-packages} and
+@file{mule-packages} hierarchies are supported, but it might make sense
+to extend this to support @file{infodock-packages} and
+@file{site-packages} hierarchies in the future.
+The package hierarchies are not searched directly for libraries to be
+loaded; this would be very costly.  Instead, the hierarchies are ordered
+according to certain rules, and searched for package lisp directories at
+invocation.  These directories are added to the general
+@code{load-path}.  As usual, it is @code{load-path} that is searched at
+run-time.  This approach is somewhat costly at initialization, but
+results in a very ``clean'' @code{load-path}.
+The order of search can be changed at build time by specifying the
+@samp{--package-path} option to @file{configure}, or at run-time by
+specifying the @code{EMACSPACKAGEPATH} environment variable.
+@xref{Packages,,,xemacs}.
+@c #### The following description is quite possibly inaccurate.
+@c Arrgh, Michael!
+The default order of search is hierarchically determined.  First, the
+roots are ordered.  The @dfn{early} roots are the user-specific roots,
+typically @file{~/.xemacs}.  The @dfn{late} roots are the system roots,
+typically @file{/usr/local/lib/xemacs-21.4.6} and
+@file{/usr/local/lib/xemacs}, in that order.  All hierarchies for a
+given root are searched for package Lisp directories, which are appended
+to @code{load-path} in the order found.  Then the search proceeds to the
+next root, whose results will be appended to the @code{load-path}
+generated by previous roots.
+Second, the hierarchies below each root are searched in the order
+@file{site-packages}, @file{infodock-packages}, @file{mule-packages},
+then @file{xemacs-packages}.
+In each hierarchy there should be a @file{lisp} subdirectory, containing
+directories named for the packages.  Each package's Lisp libraries thus
+are contained in a directory of the form
+@var{root}/@var{hierarchy}/lisp/@var{package}/.
+With such a complex search algorithm, the possibility of libraries being
+shadowed by another library with the same name is quite real.  There are
+two considerations here.  First, every XEmacs package contains certain
+libraries with constant names.  These are
+@table @file
+@item _pkg.el
+Lisp code to inform the package administration system about the package
+@item auto-autoloads.el
+Lisp code to set up autoloaded functions and variables that may be
+needed at load time
+@item custom-load.el
+definitions of configuration variables for use with the Customize
+system.
+@end table
+They are special-cased, because the way they are used prevents shadowing
+from being an issue.
+Second, it is possible that multiple copies of some library, or
+different libraries with the same name, are installed in various places
+in the hierarchies.  To detect such shadows, use
+@code{list-load-path-shadows}.
+Finally, note that most basic Emacs functionality, including most of the
+Lisp API, is implemented in Lisp libraries.  Because they use internal
+reserved APIs that are subject to change according the needs of the
+developers, these libraries are distributed with the XEmacs binary, and
+are called @dfn{core Lisp libraries}.  Most core Lisp libraries are
+``preloaded'' into the Emacs binary and in normal usage are never
+explicitly loaded.  However, they can be explicitly loaded, and if so
+they are searched on @code{load-path}.
+@c #### Is this correct?  It is not for C-h f, for example.
+Furthermore, functions such as @code{locate-library} will also search on
+the @code{load-path}.  The searching takes place under somewhat
+different rules from those used for packaged Lisp.  It is probably
+easiest to think of the package hierarchy searching algorithm as
+receiving a @code{load-path} initialized to the core Lisp directories.
+@node The Library Maintainer's View, The Package Release Engineer's View, The User's View, Package Overview
+@section The Library Maintainer's View
+From the library maintainer's viewpoint, the advantages to the @xpms{}
+stem from the convenience to the user of installation and upgrade.
+Since an installed package automatically registers its entry points via
+autoload and its configuration variables with the Customize system,
+configuration FAQs are reduced.  When it's easy to upgrade, users learn
+to try @samp{Tools | Packages | Update Installed Packages} before
+posting a FAQ whose answer is ``long since fixed, please upgrade.''
+This comes at some cost, as the library maintainer needs to arrange that
+the package be installed in a directory structure that satisfies the
+requirements of the @xpms{}.  Autoload cookies and defcustoms must also
+be added to existing libraries.  The @xpms{} provides infrastructure to
+assure that all of these annoyances need only be dealt with once.  The
+autoload cookies and defcustoms are beyond the scope of this chapter, but
+most maintainers of modern packages are already familiar with these
+mechanisms.
+The @xpms{} may be divided into the @dfn{infrastructure} common to all
+packages, and the package-specific @dfn{control files}.  The
+infrastructure supports global builds, installation, and generation of
+the ``sumo'' bundles of packages, as well as generation of individual
+packages.  The package control files describe the structure of the
+package's source tree and provide administrative information.
+@menu
+* Infrastructure::    Global Makefiles and common rules.
+* Control Files::     Package-specific Makefiles and administrative files.
+* Obtaining::         Obtaining the @xpms{} and required utilities.
+@end menu
+@node Infrastructure, Control Files, , The Library Maintainer's View
+@subsection Infrastructure
+In order to get the greatest benefit from the @xpms{}, a library
+maintainer should place the package sources in an appropriate place in
+the XEmacs source package hierarchy, and arrange to have the source
+package imported into the XEmacs CVS repository.
+@c #### the parenthetical remark should go to "issues."
+(We realize that the
+latter requirement can be quite burdensome.  We are working on ways to
+remove this requirement, but for the present it remains necessary.)  The
+library maintainer must also keep sources for any packages his/her
+package requires.  This requirement is somewhat burdensome, but unlikely
+to be relaxed because of the implementation of compilation of macros in
+Emacs Lisp.  Macros cannot be called by compiled Lisp (the macro
+expansion, which is always known at compile time, is inlined), so the
+source of the macro must be loaded before compiling the called function.
+The source package hierarchy may be rooted anywhere.  The CVS module is
+called ``packages,'' so we will refer to the top directory of the source
+package hierarchy as ``the @file{packages} directory.''  The
+@file{packages} directory contains two source subdirectories,
+@file{xemacs-packages} and @file{mule-packages} (for convenience in
+segregating the packages which depend on Mule, as they will cause
+load-time errors in a non-Mule XEmacs).  Each subdirectory contains many
+package source directories, whose internal structure is not specified.
+That structure is left up to the convenience of the library maintainers.
+The requirements on the top directory of an individual package source
+tree are given below, @ref{Control Files}.
+The @file{packages} directory contains some auxiliary Lisp libraries
+used in the compilation and packaging process.  The content of these
+libraries is of interest primarily to the packaging engineers, @ref{The
+Package Release Engineer's View}.
+Finally, the @file{packages}, @file{packages/xemacs-packages}, and
+@file{packages/mule-packages} directories contain @file{Makefile}s and
+include files to control the package creation process.  The
+@file{Makefile}s in @file{packages/xemacs-packages} and
+@file{packages/mule-packages} simply define the default sets of known
+packages and include @file{../iterate.rules}, which implements recursive
+building of all target packages.
+The @samp{make} infrastructure in @file{packages} includes
+@table @file
+@item Makefile
+controls building of individual packages, local installation, and
+bundling of ``sumo'' tarballs
+@item iterate.rules
+controls recursive builds of multiple packages
+@item XEmacs.rules
+provides the rules for building and packaging.  Included by all package
+@file{Makefile}s.
+@item Local.rules
+provides local configuration, such as installation targets and staging
+directories, as well as a number of kludges (many now obsolete) required
+for building packages on the Windows platform.
+@item Local.rules.template
+a template for Local.rules, liberally commented
+@item Local.rules.mk
+consistency checking for @file{Local.rules}, included by both the
+top-level @file{Makefile} and by @file{XEmacs.rules}.
+@c #### Add to "issues"
+@item package-compile.el
+compile environment (@emph{e.g.}, load-path) setup.  It is very bogus
+that this is here, an alternative mechanism is likely to be provided.
+@end table
+Of these, only @file{Local.rules} and @file{package-compile.el} need to
+be modified by the library maintainer.  The changes to Local.rules
+affect only your environment.  This should need to be done only once
+when first preparing the source environment.  The necessary
+modifications to @file{package-compile.el} need to be done for each
+package and are discussed in the next section, @ref{Control Files}.
+@node Control Files, Obtaining, Infrastructure, The Library Maintainer's View
+@subsection Control Files
+Each package source must contain a number of control files in the
+top-level directory.  These files in general can be created and then
+ignored, except for a few variables that need to be updated when new
+versions are released.  In most cases even adding, renaming, and
+removing library source files can be handled by generic rules.
+The package control files include
+@table @file
+@item Makefile
+Must set a few @file{make} variables used by the administrative
+utilities, and defines a couple of package-building targets to depend on
+appropriate targets defined generically in @file{XEmacs.rules}.  It may
+also provide various variables and rules to transform the source tree
+structure into that expected by the run-time system.
+@item package-info.in
+Provides a template for package information to be provided to the
+administrative utilities.  Static variables that are rarely changed
+(such as the package's name) are entered as literals.  Some variables
+are generated by the build process (build dates and MD5 checksums) and
+are automatically filled in.  Finally, some variables that change
+irregularly (dependences and even version numbers) are set as
+@file{make} variables in the @file{Makefile}.
+@item ChangeLog
+Not strictly required, but normally a ChangeLog will be added by the
+XEmacs package maintainer if different from the upstream maintainer.
+@item package-compile.el
+compile environment (@emph{e.g.}, load-path) setup.  It is very bogus
+that this is here, an alternative mechanism is likely to be provided.
+@item _pkg.el
+Generated.  Simply does a @code{package-provide} for the package.
+@item _auto-autoloads.el
+Generated.  Read when XEmacs is initialized, and provides autoloads for
+all defuns and other specially-marked forms in the sources.
+@item custom-loads.el
+Generated.  Read when XEmacs is initialized, and informs the Customize
+subsystem how to find the defcustom forms needed to create Customization
+forms for the usre configuration variables of the package.
+@end table
+@node Obtaining, , Control Files, The Library Maintainer's View
+@subsection Obtaining the @xpms{} and Required Utilities
+Currently both the infrastructure for creating XEmacs packages and the
+package sources themselves are available only by CVS.  See
+@uref{http://www.xemacs.org/Develop/cvsaccess.html} for more
+intformation.
+The @xpms{} currently requires GNU @file{make}, and probably XEmacs, to
+build packages.
+@node The Package Release Engineer's View, , The Library Maintainer's View, Package Overview
+@subsection The Package Release Engineer's View
+Bu-wha-ha-ha-ha-ha!  If you aren't the package release engineer, you
+@emph{don't want to know}.  If you @emph{are} the package release
+engineer, you have my condolences.  Rest (if you can get any rest)
+assured you are in my prayers.
+To be completed.
+@c #### The following section is lifted verbatim from the XEmacs User's
+@c      Manual, file packages.texi.
+@node Package Terminology, Building Packages, Package Overview, Packaging
+@comment  node-name,  next,  previous,  up
+@heading Package Terminology:
+@subsection Libraries and Packages
+@cindex library
+@cindex package
+A Lisp @dfn{library} is a single loadable file containing Lisp code.  It
+may be in source or byte-compiled form.  A Lisp @dfn{package} is a set
+of one or more libraries, usually related to each other in some way,
+bundled with administrative information for convenient distribution.
+@subsection Package Flavors
+There are two main flavors of packages.
+@table @strong
+@item Regular Packages
+@cindex regular package
+A regular package is a set of Lisp libraries design to cooperate with
+one another.  A very complex example is Gnus.  One may not in general
+safely remove any of the component libraries.
+@item Single-File Packages
+@cindex single-file package
+A single-file package is an collection of thematically related but
+otherwise independent Lisp libraries.  These libraries are bundled
+together for convenience of the maintainers.  Usually individual
+libraries may be deleted at will without any loss of functionality of
+other libraries in the package.  However, we would recommend that you
+follow this rule of thumb: "When in doubt, don't delete".  If it's
+really that big a deal, request that the maintainers split the package
+into smaller aggregations.
+@end table
+@subsection Package Distributions
+@cindex package distributions
+@cindex binary packages
+@cindex source packages
+XEmacs Lisp packages are distributed in two ways.  @dfn{Binary packages}
+are used by system administrators and end users.  They are packaged in a
+form convenient for direct installation into an XEmacs package
+hierarchy.  @dfn{Source packages} are for developers and include all
+files necessary for rebuilding byte-compiled lisp and creating tarballs
+for distribution or installation.  This is all of the package author's
+source code plus all of the files necessary to build distribution
+tarballs (Unix Tar format files, gzipped for space savings).
+@c #### This next is an Evile Practice and should be discontinued.
+(Occasionally sources that are not relevant to XEmacs are removed.)
+Currently, source packages are only available via CVS.  See
+@url{http://www.xemacs.org/Develop/cvsaccess.html} for details.
+The package distributions are also split according to major features
+required in XEmacs to support them.  At present there are @dfn{generic}
+packages, which can be loaded by @emph{any} XEmacs, and @dfn{Mule}
+packages, which @emph{require} Mule support or they will cause errors
+when loaded.  Note that there is no guarantee that a generic package
+will have any useful functionality in a minimally configured XEmacs.  As
+long as any XEmacs can successfully load the package's libraries
+(perhaps given other required Lisp libraries), it will be classified as
+generic.  At the present time only Mule packages need be treated
+specially, and even those only if they contain multibyte characters.
+@c #### The following section is lifted verbatim from the XEmacs User's
+@c      Manual, file packages.texi.
+@node Building Packages, Local.rules File, Package Terminology, Packaging
+@comment  node-name,  next,  previous,  up
+@cindex building packages
+@cindex package building
+@heading Building Packages:
+Currently, source packages are only available via anonymous CVS.  See
+@url{http://www.xemacs.org/Develop/cvsaccess.html} for details of
+checking out the @file{packages} module.
+@subsection Prerequisites for Building Source Packages
+@table @code
+@item GNU cp
+@item GNU install
+(or a BSD compatible install program).
+@item GNU make
+(3.75 or later preferred).
+@item makeinfo
+(1.68 from texinfo-3.11 or later required, 1.69 from Texinfo 4 preferred).
+@item GNU tar
+(or equivalent).
+@item GNU gzip
+(or equivalent).
+@item A properly configured @file{Local.rules} file.
+@ref{Local.rules File}.
+@end table
+And of course, XEmacs, 21.0 or higher.
+@subsection What You Can Do With Source Packages
+The packages CVS sources are most useful for creating XEmacs package
+tarballs for installation into your own XEmacs installations or for
+distributing to others.
+The supported @file{make} targets are:
+@table @code
+@item all
+Bytecompile all files, build and bytecompile byproduct files like
+@file{auto-autoloads.el} and @file{custom-load.el}.  Create info version
+of TeXinfo documentation if present.
+@c #### Why do we need this _and_ the binkit target?
+@item bindist
+Does a @code{make all} as well as create a binary package tarball in the
+staging directory.
+@item install
+Bytecompile all files, build and bytecompile byproduct files like
+@file{auto-autoloads.el} and @file{custom-load.el}.  Create info version
+of TeXinfo documentation if present.  And install everything into the
+staging directory.
+@item srckit
+Usually simply depends on @code{srckit-std}, with no actions.  This does
+a @code{make distclean} and creates a package source tarball in the
+staging directory.  This is generally only of use for package
+maintainers.
+@item binkit
+May depend on @code{binkit-sourceonly}, @code{binkit-sourceinfo},
+@code{binkit-sourcedata}, or @code{binkit-sourcedatainfo}, with no
+actions. @code{sourceonly} indicates there is nothing to install in a
+data directory or info directory.  @code{sourceinfo} indicates that
+source and info files are to be installed.  @code{sourcedata} indicates
+that source and etc (data) files are to be installed.
+@code{sourcedatainfo} indicates source, etc (data), and info files are
+to be installed.  A few packages have needs beyond the basic templates
+so this is not yet complete.
+@item dist
+Runs the rules @code{srckit} followed by @code{binkit}.  This is
+primarily of use by XEmacs maintainers producing files for distribution.
+@item clean
+Remove all built files except @file{auto-autoloads.el} and
+@file{custom-load.el}.
+@item distclean
+Remove all created files.
+@end table
+@c #### The following section is lifted verbatim from the XEmacs User's
+@c      Manual, file packages.texi.
+@node Local.rules File, Creating Packages, Building Packages, Packaging
+@comment  node-name,  next,  previous,  up
+@cindex local.rules
+@heading The Local.rules File:
+This file in @file{packages} provides the @xpms{} with information about
+the local configuration and environment.  To create @file{Local.rules},
+simply copy @file{Local.rules.template} from that directory to
+@file{Local.rules} and edit it to suit your needs.
+These are the variables in @file{Local.rules} that you will need to
+provide values for.  The following variables control which packages will
+be built:
+@table @var
+@item XEMACS_PACKAGES
+The default is @samp{xemacs-packages}, which results in the set in
+the @file{xemacs-packages/Makefile} @code{PACKAGES} variable.
+Otherwise, it should be a list of package source directories prefixed by
+@samp{xemacs-packages}:
+@example
+XEMACS_PACKAGES = xemacs-packages/xemacs-base xemacs-packages/bbdb
+@end example
+@item BUILD_WITHOUT_MULE
+The default is the empty value.
+Building from CVS defaults to building the Mule
+packages.  Set this to 't' if you don't want/have Mule.
+@item MULE_PACKAGES
+The default is @samp{mule-packages}, which results in the set in
+the @file{mule-packages/Makefile} @code{PACKAGES} variable.
+Otherwise, it should be a list of package source directories prefixed by
+@samp{mule-packages}:
+@example
+MULE_PACKAGES = mule-packages/mule-base mule-packages/skk
+@end example
+@item PACKAGE_INDEX
+The default is @file{package-index}.
+If you want the package index file to have a different name, change
+this.  This is probably a bad idea unless you are a packages release
+engineer, as it will confuse the package administration tools.
+@end table
+The following variables determine where files are installed and how they
+are installed.  Several of the defaults use the variable
+@var{XEMACS_PACKAGES_BASE}.  Never set this variable in
+@file{Local.rules}; it is automatically set in @file{XEmacs.rules}.
+@table @asis
+@item @var{XEMACS_STAGING}
+The default is @file{$@{XEMACS_PACKAGES_BASE@}/../xemacs-packages}.
+Generic packages will be installed here.  This can be the final
+destination for files or symlinks (if the packages are being installed
+locally), or a clean staging area for building tarballs.
+@strong{N.B.}  @samp{make bindist} ignores this variable.  It should be
+handled by the administration utilities, but currently isn't.
+@item @var{MULE_STAGING}
+The default is @file{$@{XEMACS_PACKAGES_BASE@}/../mule-packages}.
+Packages requiring Mule to load correctly will be installed here.  This
+can be the final destination for files or symlinks (if the packages are
+being installed locally), or a clean staging area for building tarballs.
+@strong{N.B.}  @samp{make bindist} ignores this variable.  It should be
+handled by the administration utilities, but currently isn't.
+@item symlink
+The default is the empty value.
+Set this to 't' if you want to simulate ``running in place.''  It is
+currently not possible to ask XEmacs to use any package source tree as
+an automatically configured member of @code{load-path}, and it is
+unlikely that complex trees such as that of the Gnus package will ever
+be able to ``run in place.''  This variable, when set to `t', causes the
+build process to create a symlink farm otherwise identical to an
+installed tree of binary packages.  Thus it is purely a space
+optimization.
+Setting this is incompatible with @samp{make bindist}.
+@end table
+The following variables determine how packages are made.
+@table @var
+@item XEMACS
+The default is @samp{xemacs}.
+The path to the XEmacs executable you wish to use to compile the
+packages and execute Lisp build scripts.
+@item XEMACS_NATIVE_NT
+The default is the empty value.
+Set this to 't' if you are building on WinNT.  It controls hairy shell
+quoting in the @file{Makefile}s.
+@item INSTALL
+The default is @samp{install -c}.
+The path to your BSD compatible install program.
+@item TAR
+The default is @samp{tar}.
+The path to your tar program.
+@item BZIP2
+The default is the empty value.
+If unset, bzipped tarballs will not be built.  If this is set to
+something that resolves to a @samp{bzip2} executable, bzip2 tarballs
+will be built @emph{in addition to} @samp{gzip} tarballs.
+@item MAKEINFO
+The default is @samp{makeinfo}.
+The path to your @file{makeinfo} program
+@end table
+@c #### The following section is lifted verbatim from the XEmacs User's
+@c      Manual, file packages.texi.
+@node Creating Packages, Issues, Local.rules File, Packaging
+@comment  node-name,  next,  previous,  up
+@cindex creating packages
+@heading Creating Packages:
+Creating a package from an existing Lisp library is not very difficult.
+In addition to the Lisp libraries themselves, you need a
+@file{package-info.in} file and a simple @file{Makefile}.  The rest is
+done by @file{XEmacs.rules}, part of the packaging system
+infrastructure.
+@file{package-info.in} contains a single Lisp form like this:
+@example
+(NAME                               ; your package's name
+(standards-version 1.1
+version VERSION                  ; Makefile
+author-version AUTHOR_VERSION    ; Makefile
+date DATE                        ; Makefile
+build-date BUILD_DATE            ; generated
+maintainer MAINTAINER            ; Makefile
+distribution DISTRIBUTION        ; "mule" if MULE is needed,
+; else "xemacs"
+priority high
+category CATEGORY                ; Makefile
+dump nil
+description "description"        ; a one-line description string
+filename FILENAME                ; obsolete
+md5sum MD5SUM                    ; generated
+size SIZE                        ; generated
+provides (FEATURE ...)           ; one for every `provides' form
+requires (REQUIRES)              ; Makefile
+; NOT run-time dependencies!  These
+; are files that provide macros or
+; defsubsts that must be inlined.
+type regular
+))
+@end example
+You should replace NAME, DISTRIBUTION, DESCRIPTION, and FEATURE ... with
+appropriate values, according to the comments.  Fields marked as
+@samp{obsolete} can be ignored.  Fields marked as @samp{generated} are
+generated by the package construction process, and will be filled in
+automatically.  Fields marked as @samp{Makefile} should be set as
+variables in the @file{Makefile}.
+The @samp{provides} can be done automatically, but currently aren't.  It
+would probably be a good idea to set them in the @file{Makefile} (they
+do change, fairly often, but at present they aren't.
+The @file{Makefile} is quite stylized.  The idea is similar to an
+@file{Imakefile} or an @code{automake} file: the complexity is hidden in
+generic rules files, in this case the @file{XEmacs.rules} include file
+in the top directory of the packages hierarchy.
+An @xpms{} @file{Makefile} has three components.  First, there is a
+variable definition section.  The standard @xpms{} @file{make} variables
+must be defined here for use by the @file{XEmacs.rules} include file.
+Second, the file @file{../../XEmacs.rules} is included.  Finally, the
+@file{make} rules are defined, possibly including additional variable
+definitions for use by the @file{Makefile}.  These always include rules
+for the targets @samp{all}, @samp{binkit}, and @file{srckit}.
+Although a number of facilities are available for complex libraries,
+most simple packages' @file{Makefile}s contain a copyright notice, the
+variable definitions mentioned above, and some boilerplate.
+@example
+# Makefile for apackage's lisp code
+# This file is part of XEmacs.
+# XEmacs is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation; either version 2, or (at your option) any
+# later version.
+# XEmacs is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# for more details.
+# You should have received a copy of the GNU General Public License
+# along with XEmacs; see the file COPYING.  If not, write to
+# the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+# Boston, MA 02111-1307, USA.
+VERSION = 0.00
+AUTHOR_VERSION = 0.00
+MAINTAINER = A. M. Aintainer <ama@@not.a.doc>
+PACKAGE = apackage
+PKG_TYPE = regular
+REQUIRES = xemacs-base
+CATEGORY = standard
+# All .els should be compiled and packaged.
+ELS = $(wildcard *.el)
+ELCS = $(ELS:.el=.elc)
+include ../../XEmacs.rules
+all:: $(ELCS) auto-autoloads.elc custom-load.elc
+srckit: srckit-std
+binkit: binkit-common
+@end example
+@menu
+* package-compile.el::
+* package-info.in Fields::
+* Makefile Variables::
+* Makefile Targets::
+@end menu
+@node package-compile.el, package-info.in Fields, , Creating Packages
+The @xpms{} does not automatically become aware of your package simply
+because there is a new subtree.  If any package, including your own,
+requires any of your files, it must be explicitly added to the compile
+environment or loads/requires that search load-path will fail.  The
+changes that need to be made are
+@table @strong
+@item an entry in package-directory-map
+This tells the @xpms{} which distribution (currently
+@samp{xemacs-packages} or @samp{mule-packages}) your package is found
+in.  It then looks in the distribution subdirectory whose name is the
+same as the package's.
+@item an entry in the @code{cond} in @code{package-name-to-directory}
+This is optional; it is necessary only if you keep your Lisp code
+somewhere other than the top-level directory of the package's source
+tree, eg, in @file{packages/xemacs-packages/@var{PACKAGE}/lisp}.
+@end table
+This only needs to be done once, when the package is first added to the
+@xpms{}.  (Well, when you randomly change the subdirectory layout, too.)
+Your changes to @file{package-compile.el} must be cleared and checked in
+by the XEmacs Package Release Engineer before your package will build
+correctly from a fresh checkout.
+Obviously all of this is really horrible, and would be totally
+inexcusable if I wasn't afraid the XEmacs Package Release Engineer would
+kill me if I complained loud enough for him to hear.  Maybe it will
+change some day....
+@node package-info.in Fields, Makefile Variables, package-compile.el, Creating Packages
+The @file{package-info.in} structure is simply Lisp data, to be read by
+a Lisp script, have values substituted for variables, and then written
+out (appropriately quoted) into a loadable Lisp file, to be consed into
+the @file{package-index.el} list at the FTP archives.  That list is
+structured as an alist with package names as keys.  The package data is
+a plist.  Do not rely on this, as it may change.  If you have a good
+reason for relying on it, let the maintainers know and we may
+incorporate it in a future revision of the @xpms{} standard.
+There are several kinds of fields, distinguished by how they get their
+values.  There are literals written into @file{package-info.in} by the
+package maintainer.  There are variables substituted in by the build
+process, some computed, and others written as values of @file{make}
+variables in the @file{Makefile} by the package maintainer.  There are a
+few implementation constants, some of which are simply the default value
+for obsolete fields.
+The @file{package-info.in} literals provided by the maintainer generally
+should not change over the life of the package.  (The exception is the
+@samp{provides} field, which should be generated, but isn't yet.)
+Values described as ``literal'' below are unquoted literal test.  These
+are normally interpreted as symbols by the package build process.  The
+maintainer literals are
+@table @asis
+@item @var{package_name}
+A literal.  The only unnamed ``field,'' the name of the package.
+@item distribution
+A literal, either @samp{xemacs} (for generic packages) or @samp{mule}
+(for packages requiring Mule).  @xref{Package Terminology}.
+@item description
+A Lisp string containing a one-line text description for use in package
+listings.
+@item provides
+A (Lisp) list of features provided by the libraries in the package.  All
+of the features provided by libraries in your package should be elements
+of this list.
+@item type
+A literal, either @samp{regular} or @samp{single-file}.  For practical
+purposes, @samp{regular} should be considered an implementation constant.
+@end table
+@c #### The following should be rewritten to @xref the make variables
+@c node, and simply associate the field names to the make variables with
+@c one line of description.
+Values which are expected to change regularly as the package is enhanced
+are implemented as @file{make} variables.  You should not change them in
+the @file{package-info.in} file; they are automatically filled in by the
+build process.
+The corresponding field name is given in parentheses.  These include
+@table @code
+@item VERSION
+(version)
+The version of the XEmacs package, a numeric literal (a decimal
+fixed-point number with two-places of precision).
+@item AUTHOR_VERSION
+(author-version)
+The upstream author's version, an unintepreted literal.
+@item DATE
+(date)
+Date of release of the upstream version.
+@item MAINTAINER
+(maintainer)
+A literal containing the XEmacs package's maintainer and his/her email
+address.
+@item CATEGORY
+(category)
+A literal, either @samp{standard} or @samp{mule}.  Probably redundant.
+@item REQUIRES
+(requires)
+A list of packages required to correctly build this package.
+Note that the usual form in @file{package-info.in} already has the
+parentheses, so the @file{make} variable should be set to a
+space-separated list of package names @emph{not} enclosed in
+parentheses.
+The list is of @emph{packages}, not @emph{libraries}, as would
+ordinarily be provided to the Lisp @code{require} function.
+@samp{REQUIRES} cannot be correctly computed from the calls to
+@code{require} in the package's library sources.  @samp{REQUIRES} is
+used to ensure that all macro and defstruct definitions used by the
+package are available at build time.  This is not merely a matter of
+efficiency, to get the expansions inlined.  In fact, it is
+@emph{impossible} to call a macro by name in byte-compiled Emacs Lisp
+code.  Thus, if the macro expansion is not inlined, the call will result
+in an error at run-time!  Thus, packages providing libraries that would
+be loaded because of autoload definitions must also be included.
+On the other hand, if a package provides no macros to this package, it
+is preferable @emph{not} to include it in @samp{REQUIRES}, because it is
+not uncommon that if the developer doesn't normally use the required
+package, he will never use the functionality in the package being built,
+either.  In that case it would be preferable to not require the
+developer to have source for the dependencies.  That said, of course it
+is safe to put too many packages in @samp{REQUIRES}.
+@end table
+Values for the following fields are automatically generated by the build
+process.
+@table @asis
+@item build-date
+The date the package tarball was generated.
+@item md5sum
+An MD5 checksum for the package tarball, as gzipped.
+@item size
+The size of the package tarball, as gzipped.
+@end table
+It is not clear that either md5sum or size works correctly if the
+@samp{BZIP2} variable in @file{Local.rules} is set.
+The implementation constants are
+@table @asis
+@item standards-version
+Currently 1.1.  Defines the format of the @file{package-info.in} file
+and the @file{Makefile}.  A true implementation constant.
+@item priority
+An unimplemented and underspecified feature.  Suggestions for
+specification and implementation welcome.
+@item dump
+An obsolete feature, superseded by the @file{site-load.el} mechanism.
+The value should always be nil.
+@item filename
+An obsolete feature, completely ignored.  Don't even think about doing
+anything useful with it.
+@end table
+@node Makefile Variables, Makefile Targets, package-info.in Fields, Creating Packages
+A number of @file{make} variables are defined by the @xpms{}.  Some are
+required, others are optional.  Of course your @file{Makefile} may
+define other variables for private use, but you should be careful not to
+choose names that conflict with variables defined and used by the
+@xpms{}.
+The required variables are described in the table below.
+The corresponding field names for @file{package-info.in}, where
+relevant, are given in parentheses.
+@c #### This is the canonical place for this information.  If there is
+@c unnecessary duplication with package-info.in documentation, shorten
+@c that and leave this full-length.
+@table @code
+@item VERSION
+(version)
+The version of the XEmacs package, a numeric literal (a decimal
+fixed-point number with two-places of precision).
+@item AUTHOR_VERSION
+(author-version)
+The upstream author's version, an unintepreted literal.
+@item DATE
+(date)
+Date of release of the upstream version.
+@item MAINTAINER
+(maintainer)
+A literal containing the XEmacs package's maintainer and his/her email
+address.
+@item CATEGORY
+(category)
+A literal, either @samp{standard} or @samp{mule}.  Probably redundant.
+@item REQUIRES
+(requires)
+A list of packages required to correctly build this package.
+Note that the usual form in @file{package-info.in} already has the
+parentheses, so the @file{make} variable should be set to a
+space-separated list of package names @emph{not} enclosed in
+parentheses.
+The list is of @emph{packages}, not @emph{libraries}, as would
+ordinarily be provided to the Lisp @code{require} function.
+@samp{REQUIRES} cannot be correctly computed from the calls to
+@code{require} in the package's library sources.  @samp{REQUIRES} is
+used to ensure that all macro and defstruct definitions used by the
+package are available at build time.  This is not merely a matter of
+efficiency, to get the expansions inlined.  In fact, it is
+@emph{impossible} to call a macro by name in byte-compiled Emacs Lisp
+code.  Thus, if the macro expansion is not inlined, the call will result
+in an error at run-time!  Thus, packages providing libraries that would
+be loaded because of autoload definitions must also be included.
+On the other hand, if a package provides no macros to this package, it
+is preferable @emph{not} to include it in @samp{REQUIRES}, because it is
+not uncommon that if the developer doesn't normally use the required
+package, he will never use the functionality in the package being built,
+either.  In that case it would be preferable to not require the
+developer to have source for the dependencies.  That said, of course it
+is safe to put too many packages in @samp{REQUIRES}.
+@item ELCS
+The list of the byte-compiled Lisp files used by the package.  These
+files and their @file{.el} versions will be included in the binary
+package.  This variable determines which libraries will be
+byte-compiled.  These libraries are also deleted by @samp{make clean}.
+Note there is no sanity-checking done on this variable.  If you put
+@samp{.el} files in here, they will not be compiled and they @emph{will}
+be deleted by @samp{make clean}.  You would surely be very distressed if
+that happened, so be very careful.  If this variable is left empty, none
+of your Lisp code will be compiled or packaged.  This would be a less
+than amusing surprise, too.
+We don't consider this a feature, of course.  Please do submit code to
+do sanity checking to @email{xemacs-patches@@xemacs.org}.
+@end table
+Optional, but very commonly used variables include:
+@table @code
+item EXTRA_SOURCES
+Other files (such as extra Lisp sources or an upstream @file{Makefile})
+that are normally placed in the installed Lisp directory, but not
+byte-compiled.  These files are @emph{preserved} by the @samp{clean}
+targets.
+@item EXTRA_OBJS
+Other files (such as compiled autoload or concatenated @file{.elc}
+libraries) which are normally placed in the installed Lisp directory,
+but do @emph{not} have corresponding source files and @emph{should} be
+deleted by the @samp{clean} targets.  Some of these (such as
+package-specific autoload setups) can and probably should be replaced by
+@xpms{} solutions such as @file{auto-autoloads.el}, but many cannot.
+@item PRELOADS
+A specification for loading libraries containing macros before compiling
+the Lisp in the package.  This is spliced directly into the invocation
+of XEmacs for byte-compilation, so it must contain the @samp{-l} flag
+for XEmacs:
+@example
+PRELOADS=-l ./apackage-macros.el -l ../bpackage/lisp/bpackage-macros.el
+@end example
+@item INFO_FILES
+Any Info file(s) generated by the package.  These must be paths relative
+to the root of the package's source tree.
+@item TEXI_FILES
+The Texinfo source file(s).  These must be paths relative
+to the root of the package's source tree.
+@item MANUAL
+The name to be used for Info files and man pages.
+@item DATA_FILES
+Any data files, such as pixmaps, READMEs, and ChangeLogs.  These must be
+paths relative to the root of the package's source tree.
+@item DATA_DEST
+The installation location for data files, relative to the @file{etc/}
+directory of the package hierarchy.  The normal value is simply
+$(PACKAGE).  Leaving it empty (@emph{i.e.}, put it directly under
+@file{etc/}) will probably work, but is subject to name conflicts with
+other packages.
+@end table
+Rarely used variables.
+@c @table @code
+@c @item
+@c @end table
+@node Makefile Targets, , Makefile Variables, Creating Packages
+The standard targets that need to be defined in your @file{Makefile}
+follow.  These normally should @emph{not} have an action.  All of the
+work should be done by dependent targets, usually having standard
+definitions in the @xpms{}.
+@table @samp
+@item all
+A list of generated files, usually byte-compiled Lisp libraries, to be
+bundled in the package.  The typical dependencies are
+@example
+$(ELCS) auto-autoloads.elc custom-load.elc
+@end example
+Other targets (such as Info files) may need to be added as dependencies
+for the @code{all} target.
+@item srckit
+The target for generating a source package.  Not implemented.  If it
+were, the normal dependency would be @samp{srckit-std}.
+@item binkit
+The target for creating a ``master'' installation.  Binary packages are
+actually generated by the @samp{bindist} target.  @xref{Building Packages}.
+@end table
+Standard dependencies for @code{srckit} and @code{binkit} are defined in
+@file{XEmacs.rules}.  The most useful of these values are given in the
+following table.
+@table @samp
+@item srckit-std
+Build a standard source kit.  Not fully implemented.
+@item binkit-sourceonly
+The @samp{binkit} target need only install source and compiled Lisp in
+the staging area.  There is nothing to install in a data directory or
+info directory.
+@item binkit-sourceinfo
+Both source and info files are to be installed in the staging area.
+@item binkit-sourcedata
+Both source and etc (data) files are to be installed in the staging
+area.
+@item binkit-sourcedatainfo
+Source, etc (data), and info files all are present and need to be
+installed in the staging area.
+@item binkit-common
+A dependency for all the above.  (In fact in the current implementation
+@samp{binkit-common} does all the work for all of the @samp{binkit}
+targets.)
+@end table
+Data files include things like pixmaps for a package-specific toolbar,
+and are normally installed in @file{etc/@var{PACKAGE_NAME}}.  A few
+packages have needs beyond the basic templates.  See @file{XEmacs.rules}
+or a future revision of this manual for details.
+@node Issues, , Creating Packages, Packaging
+@section Issues
+``Issues''?  Mu-wha-ha-ha!  Ha-ha-ha!  Honeychile, they ain't nuthin'
+@emph{but} ``issues'' at this point.  @xref{The Package Release
+Engineer's View}.

Mercurial > hg > xemacs-beta

comparison man/lispref/packaging.texi @ 693:b05e2a249757