                                             -*- Outline -*-
This file explains how to build and install XEmacs packages from a
CVS workspace.

IMPORTANT:
=========
	You MUST create a 'Local.rules' file in the toplevel build
	directory.  (see below for the format of this file)

Notes for FreeBSD users:
========================
	If running FreeBSD there are options for TAR and RCOPY that
	must be used for package building to work.
	You must use gmake instead of make for building.
	gmake can be installed via the devel/gmake port.
	gtar must be used instead of tar.
	Install it via archivers/gtar in the ports tree.

* Building:
-----------
** Getting Started Quickly:

	(1) Create a 'Local.rules' file in the toplevel directory and
	    edit it to suit your needs.  There is a
	    'Local.rules.template' in the top-level directory which you
	    can copy and modify.

	(2) Run `make' (from the top-level directory) to build the
	    packages.

	(3) Run either 'make install' or 'make bindist' (not both).

	    'make install' installs them into the
	    $NONMULE_INSTALLED_PACKAGES_ROOT directory
	    ($MULE_INSTALLED_PACKAGES_ROOT for mule-packages),
	    see Local.rules format below.  It doesn't create package
	    binary tarballs.

	    'make bindist' creates package binary tarballs and a
	    'package-index' file in $NONMULE_INSTALLED_PACKAGES_ROOT
	    (both for mule and non-mule packages).

** Building a Single Package:

	All you need to do is run the make from the package's
	directory.  Say, for example, you want to build the bbdb
	package:
	  	- cd ./xemacs-packages/bbdb
		- make
		- make install or bindist

** Building Sumo Packages:

	Get the script 'BuildSumo' that is in the xemacs-builds module
	at cvs.xemacs.org.

* Installing:
-------------
** Installing after a 'make install'

	Under normal circumstances, the packages should be installed to
	<xemacs-root>/lib/xemacs/xemacs-packages and
	<xemacs-root>/lib/xemacs/mule-packages.  <xemacs-root> is the
	topmost-level directory under which everything is installed --
	normally /usr/local, and set using the `--prefix'
	parameter to `configure'.

	If you installed elsewhere (see Local.rules.template), you will
	need to either (1) copy, move or symlink to those locations, or (2)
	tell XEmacs about your particular package locations at configure
	time.  (1) is useful when you want a properly installed XEmacs that
	you and perhaps others can run (but then why didn't you install
	directly to <xemacs-root>?).  (2) is better, on the other hand, when
	you're doing development work on XEmacs and possibly the packages,
	and you'd rather have your own private copy of everything, including
	the installed packages.

	(1) To copy to the default location:

		- mkdir /usr/local/lib/xemacs/xemacs-packages
		- mkdir /usr/local/lib/xemacs/mule-packages
		- cd /usr/local/lib/xemacs/xemacs-packages
		- cp -a $NONMULE_INSTALLED_PACKAGES_ROOT/* ./
		- cd ../mule-packages
		- cp -a $MULE_INSTALLED_PACKAGES_ROOT/* ./
		- restart XEmacs.

	NOTE: /usr/local is only the default value of <xemacs-root>, as
	described above.

	(2) To specifically set where the package hierarchies are using
            `configure', use the `--package-path' parameter, as follows:

	Assume you're basically following the suggested layout described
	in the top-level README file of recent XEmacs distributions.
	Assume you set XEMACS_INSTALLED_PACKAGES_ROOT to
	${XEMACS_PACKAGES_BASE}/.., as described in to comments in
	Local.rules.template -- generally a good idea if you're trying to
	develop XEmacs, not just install it.  Assume you have a /src/xemacs
	directory, and under it is all your XEmacs build trees, your
	packages, etc.  Specifically, the package source is in
	/src/xemacs/package-src.  By setting XEMACS_INSTALLED_PACKAGES_ROOT
	as indicated, you will get two package hierarchies installed in
	/src/xemacs/xemacs-packages and /src/xemacs/mule-packages.
	Therefore, you'd use a parameter to `configure' like this:

	configure --package-path=~/.xemacs::/src/xemacs/xemacs-packages:/src/xemacs/mule-packages ...
       

** Installing after a 'make bindist'

	M-x pui-add-install-directory
		- enter the value of $NONMULE_INSTALLED_PACKAGES_ROOT
	M-x package-get-update-base
		- enter '$NONMULE_INSTALLED_PACKAGES_ROOT/package-index'
	M-x pui-list-packages
		- select the packages you want to install
		- hit 'x' to install
	Restart XEmacs.

	NOTE: Normally NONMULE_INSTALLED_PACKAGES_ROOT is defined to be
	${XEMACS_INSTALLED_PACKAGES_ROOT}/xemacs-packages, and this is
  	probably the value it has for you, too.

** Installing - running "in place"

	You can't run XEmacs packages from the CVS source tree because
	the hierarchy is not what XEmacs expects. (In particular, the
	source hierarchy logically puts all parts of a package -- `lisp',
	`etc', `man', `info', `lib-src', and `pkginfo' -- together under a
	single directory.  The installation, however, follows a much less
	logical organization by instead combining all `lisp' together into
	a single directory tree, all `man' together, etc.  Under each of
	these is a directory for each package.)

	But you can come close to a "running in place" install -- set
	`symlink = t' in 'Local.rules' and then run 'make install'.  This
	will build the packages and install them via symlinks to
	the normal XEmacs package directories.

* Local.rules format:
---------------------

These are the variables in 'Local.rules' that you will need to
address.

	XEMACS = xemacs
		If your XEmacs isn't in your path, change this.

	BUILD_WITHOUT_MULE =
		Building from CVS defaults to building the Mule
		packages.  Set this to 't' if you don't want/have Mule

	XEMACS_NATIVE_NT =
		Set this to 't' if you are building on WinNT.

	XEMACS_INSTALLED_PACKAGES_ROOT = /usr/local/lib/xemacs
		Directory tree under which the directories xemacs-packages/
		and mule-packages/ are installed.  See Local.rules.template
		for a description of what you might want to set this to, and
		how it varies depending on whether you're installing a release
		version or developing XEmacs. Depending on how you set
                this, you may have to tell configure about it specially.
		See above, "Installing after a 'make install'".

	symlink =
		Set this to 't' if you want to do a "run in place".
		Setting this doesn't work well with 'make bindist'.

These are other variables you might possibly need to change, but probably
won't.

	NONMULE_INSTALLED_PACKAGES_ROOT = ${XEMACS_INSTALLED_PACKAGES_ROOT}/xemacs-packages
		Set this to where you want normal packages to be
		installed to.  Normally you don't set this directly.

	MULE_INSTALLED_PACKAGES_ROOT = ${XEMACS_INSTALLED_PACKAGES_ROOT}/mule-packages
		Set this to where you want Mule packages installed
		to.  Normally you don't set this directly.
                Note: 'make bindist' does not use this variable.

	NONMULE_PACKAGES = xemacs-packages
		This is where you list the the normal (i.e. non-Mule)
		packages that you want to install. eg:
		   NONMULE_PACKAGES = xemacs-packages/xemacs-base \
                                      xemacs-packages/bbdb
                The default value installs all normal packages.

	MULE_PACKAGES = mule-packages
		Same as for 'NONMULE_PACKAGES' except you list the Mule
		packages you want to install here. eg:
		   MULE_PACKAGES = mule-packages/mule-base mule-packages/skk
                The default value installs all Mule packages.

	PACKAGE_INDEX = package-index
		If you want the package-index file to have a different
		name, change this.

	INSTALL = install -c
		The path to your BSD compatible install program.

	TAR = tar
		The path to your tar program

	BZIP2 =
		If you want tarballs compressed usng bzip2 instead of
		gzip, set this to the path to bzip2.

	MAKEINFO = makeinfo
		The path to your makeinfo program

* Notes:
--------
	(1) Be sure to include the line
		update -Pd
	    in your ~/.cvsrc file.  There seems to be CVS server bug
	    that results in incomplete checkouts of the
	    xemacs-packages module from CVS.  In particular, the files
	    `Local.rules.template' and `Local.rules.mk' might not get
	    checked out.  The problem is fixed by doing a `cvs update'
	    with the -Pd flags specified.  See http://cvs.xemacs.org/
	    for more details on using the CVS repository.
