The Makefile is quite stylized. The idea is similar to an
Imakefile or an automake file: the complexity is hidden in
generic rules files, in this case the XEmacs.rules include file
in the top directory of the packages hierarchy.
It is important to note that the XEmacs used to compile packages is the bare minimum: it is called with the ‘-no-autoloads’. This means that anything not dumped into XEmacs by default needs to be specified in the ‘REQUIRES’ variable (for packaged Lisp) or in some cases the ‘PRELOADS’ (autoloads used in libraries mentioned in ‘PRELOADS’).
There isn't much to an XEmacs Packaging System Makefile, basically it just contains a few Makefile variables and that's it. See the example.
Here is a real world example, from the ‘build’ package:
# Makefile for build 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.
# For the time being, remove MULE_ELCS from the all dependencies if
# building without Mule.
VERSION = 1.10
AUTHOR_VERSION = 2.02
MAINTAINER = Adrian Aichner <adrian@xemacs.org>
PACKAGE = build
PKG_TYPE = regular
REQUIRES = xemacs-base pcl-cvs dired w3 prog-modes
CATEGORY = standard
ELCS = build.elc build-report.elc
STANDARD_DOCS = t
include ../../XEmacs.rules
Most packages don't need any more than what you see above. It is usually not necessary to specify any special Makefile rules. Everything is handled from the *.rules files in the toplevel of the package source hierarchy.
Of course, with that said, there are always exceptions to the rule. If you think that your package will need some special Makefile hackery contact the XEmacs developers. We distribute over 100 packages so the chances are good that you won't be the first to need such hackery and it is probably already catered for.
A number of make variables are defined by the XEmacs Packaging System. Some are required, others are optional. Of course your 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 XEmacs Packaging System.
The required variables are described in the table below. The corresponding field names for package-info.in, where relevant, are given in parentheses.
N.B. ‘single-file’ here does not refer to the
number of lisp files in a package. See Package Terminology.
Note that the usual form in package-info.in already has the parentheses, so the make variable should be set to a space-separated list of package names not enclosed in parentheses.
The list is of packages, not libraries, as would
ordinarily be provided to the Lisp require function.
‘REQUIRES’ cannot be correctly computed from the calls to
require in the package's library sources. ‘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
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.
Note there is no sanity-checking done on this variable. If you put ‘.el’ files in here, they will not be compiled and they will be deleted by ‘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 xemacs-patches@xemacs.org.
Optional, but commonly used variables are explained below.
make clean.
ELCS_1_DEST = $(PACKAGE)/extra
Would put the ELCS_1 files for the package, ‘foo’ into
xemacs-packages/lisp/foo/extra/.
PRELOADS=-l ./apackage-macros.el -l ../bpackage/lisp/bpackage-macros.el
Preloads are loaded before package-compile.el, so the
load-path is minimal. Therefore ‘PRELOADS’ must specify a
full path to packaged Lisp. The base load-path does include the
core Lisp directory, so core libraries are found.
N.B. There is no need to use this variable if the .el
files are in the package's toplevel directory. AUTOLOAD_PATH
defaults to ‘.’.
package-suppress here to indicate Lisp libraries
that should only be available to particular versions of XEmacs. For
example:
PACKAGE_SUPPRESS = \
(package-suppress 'xemacs-base \"regexp-opt\" '(emacs-version>= 21 5 11)) \
(package-suppress 'xemacs-base \"easy-mmode\" '(emacs-version>= 21 5 11))
N.B. This feature has not yet been implemented in XEmacs yet.
It will appear in an upcoming version of XEmacs 21.5.
EXPLICIT_DOCS = texi/$(PACKAGE).texi
See DOCS_TXI_EXTENSION and DOCS_TEXINFO_EXTENSION if you
don't use the .texi file extension on your Texinfo sources.
makeinfo
as a dependency.
DATA_DEST = $(PACKAGE)/foo
Would put files into .../etc/$(PACKAGE)/foo/.
The XEmacs Packaging System 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
package-directory-mapcond in package-name-to-directoryThis only needs to be done once, when the package is first added to the XEmacs Packaging System. (Well, when you randomly change the subdirectory layout, too.) Your changes to 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.
This is unfortunate; it works pretty well once set up, but can cause
confusion when first building a package in the XEmacs Packaging System context. In
particular, if the package-directory-map entry for a required
package, including the package itself, is not found, the necessary
requires will not be executed by package-compile.el. If
required functions are executed (under eval-when-compile),
they won't be found and the compile will fail. If required function
is actually a macro, the byte compiler will not recognize that,
compile a function call to the macro. This will cause a run-time
error because the byte-code interpreter does not know how to execute
macros. (Macros can always be expanded at compile-time, and this is
more efficient.)
If your package keeps some or all Lisp code somewhere other than the top
directory, then an entry in package-name-to-directory is also
necessary, or requires will fail, leading to the problems just described.