Source

xemacs-packages / INSTALL

                                             -*- 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:
-----------
** Building Quickstart:

	(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 toplevel directory which you
	    can copy and modify.

	(2) Regardless of the type of build you decide upon, it's
	    probably a good idea to run 'make autoloads' from the
	    toplevel directory.

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

	    'make install' builds the packages and installs them into
	    the $STAGING directory (see Local.rules format below).  It
	    doesn't create package binary tarballs.

	    'make bindist' builds the packages and creates package
	    binary tarballs and a 'package-index' file in $STAGING.

** 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 install or bindist

	You can build a category of packages just as easily.  For
	example, if you want to build all the packages in ./libs:
		- cd ./xemacs-packages
		- 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'

	I know that sounds odd, but if you set $XEMACS_STAGING and
	$MULE_STAGING to anything other than
	<emacs-roots>/lib/xemacs/xemacs-packages and
	<emacs-roots>/lib/xemacs/mule-packages respectively, you will
	need to either copy, move or symlink.

		- mkdir /usr/local/lib/xemacs/xemacs-packages
		- mkdir /usr/local/lib/xemacs/mule-packages
		- cd /usr/local/lib/xemacs/xemacs-packages
		- cp -a /path/to/$XEMACS_STAGING/* ./
		- cd ../mule-packages
		- cp -a /path/to/$MULE_STAGING/* ./
		- restart XEmacs.

** Installing after a 'make bindist'

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

** Installing - running "in place"

	You can't run XEmacs packages from the CVS source tree because
	the hierarchy is not what XEmacs expects.  But you can come
	close to a "running in place" install.

	Set the following in 'Local.rules':

	   - symlink = t
	   - XEMACS_STAGING = /usr/local/lib/xemacs/xemacs-packages
	   - MULE_STAGING = /usr/local/lib/xemacs/mule-packages

	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.

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

	XEMACS_PACKAGES =
		This is where you list the the normal (i.e. non-mule)
		packages that you want to install. eg:
		   XEMACS_PACKAGES = xemacs-packages/xemacs-base xemacs-packages/bbdb

	XEMACS_STAGING = ${XEMACS_PACKAGES_BASE}/../Packages
		Set this to where you want normal packages to be
		installed to.

	PACKAGE_INDEX = package-index
		If you want the package-index file to have a different
		name, 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

	MULE_PACKAGES =
		Same as for 'XEMACS_PACKAGES' except you list the Mule
		packages you want to install here. eg:
		   MULE_PACKAGES = mule-packages/mule-base mule-packages/skk

	MULE_STAGING = ${XEMACS_PACKAGES_BASE}/../Mule-Packages
		Set this to where you want Mule packages installed
		to.  Note:  'make bindist' does not use this variable.

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

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

	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.