README for imboot
Paul DuBois
12 April 1997

imboot is a bootstrapper for imake; it generates a Makefile from an
Imakefile by passing appropriate arguments to imake.  imboot is similar
in nature to xmkmf, the imake bookstrapper for projects that use the
X11 configuration files.  However, imboot is not tied to any particular
set of configuration files.  Instead, you specify on the imboot command
line which set of files you want to use:

	% imboot -c NAME	(or)
	% imboot -C NAME

imboot looks for a directory with the given name under the
configuration root directory (typically /usr/local/lib/config) and
tells imake to use the configuration files in that directory.

imboot comes in sh or Perl versions.  It runs on UNIX and Windows NT.

Windows NT notes:
- You can use the Perl version of imboot if you have NT Perl installed.
- cp commands below would use copy, and chmod commands may be ignored.

This README has the following sections:

I)   Building and installing imboot by hand
II)  Building and installing imboot using imake
III) Using imboot

-----------------------------------------------------------------------------

Section I. Building and installing imboot by hand

Decide whether to use the sh or Perl version of imboot.  Both are
functionally equivalent.  (Under Windows NT you must use the Perl
version, but to do so you must have NT Perl installed.)

To configure the sh version of imboot:

1) Copy imboot.cpp to imboot:

	% cp imboot.cpp imboot

2) Edit imboot, replacing all instances of XCOMM with # and all
instances of CONFIGROOTDIR with /usr/local/lib/config (or with the full
pathname of whatever directory you use for your configuration root).

3) Make imboot executable:

	% chmod a+x imboot

4) Install imboot in a location appropriate for your system.

To configure the Perl version of imboot:

1) Copy imboot.pl to imboot:

	% cp imboot.pl imboot

2) Edit imboot, replacing $(PERLPATH) with the full patname to your
Perl executable (either Perl 4 or Perl 5), and and $(CONFIGROOTDIR)
with /usr/local/lib/config (or with the full pathname of whatever
directory you use for your configuration root).

3) Make imboot executable:

	% chmod a+x imboot

4) (Windows NT only.)  Convert imboot to a batch file imboot.bat:

	pl2bat imboot

5) Install imboot (or imboot.bat, for Windows NT) in a location appropriate
for your system.

To configure the manual page:

1) Copy imboot.man.cpp to imboot.man:

	% cp imboot.man.cpp imboot.man

2) Edit imboot.man, replacing all instances of XCOMM with #
and all instances of CONFIGROOTDIR with /usr/local/lib/config (or with
the full pathname of whatever directory you use for your configuration
root).

3) Install imboot.man in a location appropriate for your system.

-----------------------------------------------------------------------------

Section II. Building and installing imboot using imake

If you have xmkmf, imake, msub, and the X11 configuration files, you can
use the instructions in this section.

To use the default configuration values, do this:

	% xmkmf			Generate the Makefile
	% make clean		Remove anything extraneous
	% make			Build imboot and the manual page
	% make install		Install imboot
	% make install.man	Install the imboot manual page

This will build the sh version of imboot, configure the configuration
root directory as /usr/local/lib/config, and install imboot and its
manual page in the X11 bin and manpage directories.

To change the defaults, take a look at extras.tmpl and use the instructions
below.

1) Find the line that sets the value of CONFIGROOTDIR:

	CONFIGROOTDIR = /usr/local/lib/config

This is the imboot configuration root; it's the directory that holds the
various sets of configuration files that imboot should know about.  Each
set of files is installed in its own directory under the configuration
root.

If you want to use a directory other than the one that's listed in the
extras.tmpl file, change the value of CONFIGROOTDIR.  (For Windows NT,
you probably should make sure to add the drive letter of the partition
in which you want to locate the directory.)

2) UNIX systems:

If you want to use the sh version of imboot, the "#define UsePerlImboot"
line should be commented out:

	/*#define UsePerlImboot YES*/

If you want to use the Perl version of imboot, the line should be uncommented:

	#define UsePerlImboot YES

Then you should also make sure the value of PERLPATH is correct for
your system.  It can be the full pathname of either Perl 4 or Perl 5.

3) Windows NT systems:

If you have the Windows NT version of Perl, you can use the Perl
version of imboot. Uncomment the "#define WinNTHasPerl" line:

	#define WinNTHasPerl YES

If you don't have Perl, the line should be commented out:

	/*#define WinNTHasPerl YES*/

4) Build the Makefile, then build imboot and the manual page imboot.man:

	% xmkmf
	% make

5) Determine whether the installation directories for imboot and imboot.man
are appropriate for your system:

	% make -n install
	% make -n install.man

These commands show you where the Makefile will install the files.  If
the locations are suitable, install the files:

	% make install
	% make install.man

Otherwise install the files by hand.  imboot can be installed in any
directory in your search path.  Be sure to make the installed copy
executable.

-----------------------------------------------------------------------------

Section III. Using imboot

If the configuration root directory has not been created on your system
already, create it:

	% mkdir /usr/local/lib/config	(or whatever pathname you're using)

To install a set of configuration files for use with imboot, they need
to have a name.  Suppose they're called XYZ.  Create a directory called
XYZ under the configuration root directory for them to live in:

	% mkdir /usr/local/lib/config/XYZ

Then copy the files into that directory.

The next step is to make sure that the self-reference for the files is
correct.  That is, the configuration parameter that tells the files
where they live needs to point to /usr/local/lib/config/XYZ.  The
self-reference is typically specified as the value of ConfigDir in one
of the configuration files.  You can either change the definition in
the file where it's defined, or add a definition to site.def (which is
perhaps preferable):

	#ifndef ConfigDir
	#define ConfigDir /usr/local/lib/config/XYZ
	#endif

If the parameter that specifies the location is something other than
ConfigDir, change the definition of that parameter instead.

For a set of configuration files that is already located elsewhere, you
may be able to hook it into the configuration root directory so that it
can be used with imboot.  For instance, if the X11R6.3 files are
located in /usr/X11R6.3/lib/X11/config, you can make them useable with
imboot like this:

	% ln -s /usr/X11R6.3/lib/X11/config /usr/local/lib/config/X11R6.3

Then these two commands become equivalent:

	% xmkmf
	% imboot -c X11R6.3
