|[ < ]||[ > ]||[ << ]||[ Up ]||[ >> ]||[Top]||[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 3 of the License, 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. If not, see <http://www.gnu.org/licenses/>. # 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 <email@example.com> 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 section Libraries and Packages.
(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
‘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 firstname.lastname@example.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
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
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.
defaults to ‘.’.
Place calls to
package-suppress here to indicate Lisp libraries
that should only be available to particular versions of XEmacs. For
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
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
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
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.
|[ < ]||[ > ]||[ << ]||[ Up ]||[ >> ]||[Top]||[Contents]||[Index]||[ ? ]|
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
This 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.
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 ‘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
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
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.
Some random notes on documenting your package.
Do write a Texinfo file. It’s not that hard to do basically, and even using the more advanced features of Texinfo soon become natural. For a start, just grab the template ‘Samples/package.texi’ from the XEmacs Packaging System source tree, and drop your current README into the Top node. At least this way your documentation will be accessible from the standard Info readers. Next, try to add lots of cross-referencing and logical markup, and then node structure.
Address both end users and developer issues. You may not be the maintainer forever.
If you are maintaining a package that is part of the GNU Emacs
distribution, you’ll likely find that you occasionally synchronize your
package with the GNU Emacs sources. When you synch a file,
conventionally you should place a comment just above the standard
;;; Code comment that looks like this:
;; Synched with: ;; GNU Emacs 21.1, 2002-02-08, Stephen Turnbull <email@example.com>
This comment is a status flag; the ChangeLog doesn’t really give the same information.
Do maintain a detailed ChangeLog.
|[ << ]||[ >> ]||[Top]||[Contents]||[Index]||[ ? ]|
This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.