Previous: package-info.in, Up: Creating Packages [Contents][Index]
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.
(version) The version of the XEmacs package, a numeric literal (a decimal fixed-point number with two-places of precision). The only person who ever needs to touch this is the XEmacs Packages Release Engineer.
(author-version) The upstream author’s version, an uninterpreted literal.
(maintainer) A literal containing the XEmacs package’s maintainer and his/her email address.
The name of the package, a literal
The type of package, a literal containing either ‘regular’ for regular packages, or ‘single-file’ for single-file packages. This should feed the ‘type’ field in package-info.in, but currently it doesn’t.
N.B. ‘single-file’ here does not refer to the number of lisp files in a package. See Package Terminology.
(category) A literal, either ‘standard’ or ‘mule’. The non-Mule packages are ‘standard’ and the Mule packages are, you guessed it, ‘mule’. This field is used at package installation time as part of the process of determining where a package should be installed to.
(requires) A list of packages required to correctly build this package.
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.
The list of the byte-compiled Lisp files used by the package. These files and their .el versions will be included in the binary package. This variable determines which libraries will be byte-compiled. These libraries are also deleted by ‘make clean’.
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.
A list of extra byte-compiled Lisp files used by the package to be
installed in a subdirectory of the package’s lisp directory. The same
care should be taken with this as with ELCS in regard to
make clean.
The name of the subdirectory for the ELCS_1 files to be installed to. Be sure to include ‘$(PACKAGE)/’ as part of the name.
ELCS_1_DEST = $(PACKAGE)/extra
Would put the ELCS_1 files for the package, ‘foo’ into xemacs-packages/lisp/foo/extra/.
For additional .el files that will be generated before any byte-compiling happens. Use this for ‘autoload-type’ files. You must write Makefile rules to build these files.
For additional .el files that will be generated at byte-compilation time. You must write Makefile rules to build these files.
This is used if you need to pass extra command line arguments to XEmacs to build the package. For instance, 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 ‘-l’ flag for XEmacs:
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.
The subdirectory in the package’s source tree where the .el files reside. This is where the auto-autoloads.el file will be placed.
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 ‘.’.
Place calls 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.
Set this to ‘t’ if your package’s Texinfo source file is located in the package’s toplevel directory and is named $(PACKAGE).texi.
Use this to explicitly list Texinfo sources that aren’t in the package’s toplevel directory. For example:
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.
List here extra Texinfo source files needed to build your
documentation. Whatever is listed here is passed on to makeinfo
as a dependency.
Use this to specify extra .html files to output.
Set this to ‘t’ if your Texinfo source files have a ‘.texinfo’ extension.
Set this to ‘t’ if your Texinfo source files have a ‘.txi’ extension.
Files listed here will be installed to .../man/$(PACKAGE)/. For example, you might want to list TeX files or .eps files here.
Other files (such as extra Lisp sources or an upstream Makefile) that are normally placed in the installed Lisp directory, but not byte-compiled. These files are preserved by the ‘clean’ targets.
For files that need to be installed to lib-src/$(PACKAGE)/. If the files listed here need to be built you will have to write Makefile rules to do so.
Any data files, such as pixmaps, READMEs, and ChangeLogs. These must be paths relative to the root of the package’s source tree. These files will be copied to ‘$(DATA_DEST)’ for installation. Any directory component of the path for a file will be stripped, so that the file ends up in ‘$(DATA_DEST)’, not in a subdiredtory.
The directory where the files in DATA_FILES are installed to. It is a subdirectory of the installed etc/ directory. Be sure to prefix this value with ‘$(PACKAGE)’, for example:
DATA_DEST = $(PACKAGE)/foo
Would put files into .../etc/$(PACKAGE)/foo/.
For data files that need to go into a different directory from DATA_DEST.
The name of the subdirectory for files specified in DATA_n_FILES. And like DATA_DEST, be sure to prefix ‘$(PACKAGE)’ to the value of these variables.
For additional files to build that aren’t appropriate to place in any other Makefile variable. You will need to write Makefile rules to build these files.
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-mapThis tells the XEmacs Packaging System which distribution (currently ‘xemacs-packages’ or ‘mule-packages’) your package is found in. It then looks in the distribution subdirectory whose name is the same as the package’s.
cond in package-name-to-directoryThis 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 packages/xemacs-packages/PACKAGE/lisp.
This 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.
Previous: package-info.in, Up: Creating Packages [Contents][Index]