7. `Makefile'

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 <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.

`Makefile' Variables Explained:

The required variables are described in the table below. The corresponding field names for `package-info.in', where relevant, are given in parentheses.

`VERSION'

(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'

(author-version) The upstream author's version, an uninterpreted literal.

`MAINTAINER'

(maintainer) A literal containing the XEmacs package's maintainer and his/her email address.

`PACKAGE'

The name of the package, a literal

`PKG_TYPE'

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 Package Terminology:.

`CATEGORY'

(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'

(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.

`ELCS'

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.

`ELCS_1'

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.

`ELCS_1_DEST'

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/'.

`EARLY_GENERATED_LISP'

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.

`GENERATED_LISP'

For additional `.el' files that will be generated at byte-compilation time. You must write `Makefile' rules to build these files.

`PRELOADS'

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.

`AUTOLOAD_PATH'

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 `.'.

`PACKAGE_SUPPRESS'

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.

`STANDARD_DOCS'

Set this to `t' if your package's Texinfo source file is located in the package's toplevel directory and is named `$(PACKAGE).texi'.

`EXPLICIT_DOCS'

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.

`EXTRA_TEXI_FILES'

List here extra Texinfo source files needed to build your documentation. Whatever is listed here is passed on to makeinfo as a dependency.

`EXTRA_HTML_FILES'

Use this to specify extra `.html' files to output.

`DOCS_TEXINFO_EXTENSION'

Set this to `t' if your Texinfo source files have a `.texinfo' extension.

`DOCS_TXI_EXTENSION'

Set this to `t' if your Texinfo source files have a `.txi' extension.

`EXTRA_DOC_FILES'

Files listed here will be installed to `.../man/$(PACKAGE)/'. For example, you might want to list TeX files or `.eps' files here.

`EXTRA_SOURCES'

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.

`LIBSRC_FILES'

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.

`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. 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.

`DATA_DEST'

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/'.

`DATA_1_FILES ... DATA_35_FILES'

For data files that need to go into a different directory from DATA_DEST.

`DATA_1_DEST ... DATA_35_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.

`EXTRA_DEPENDENCIES'

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.

7.1 `package-compile.el'

an entry in package-directory-map

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.

an entry in the cond in 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 `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.

Documenting Packages:

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 <stephen@xemacs.org>

This comment is a status flag; the ChangeLog doesn't really give the same information.

Do maintain a detailed ChangeLog.

7.2 Issues

To be completed.