$Id: single.html,v 1.3 1997/07/15 00:07:44 ksb Exp $

Starting at the single platform

If we limit our view (for the time being) to a single target platform we can build an understanding for what must lay before us. (Yes, I mean that both ways.)

From the `Net

The standard Internet package one might pluck from an FTP archive has:

Of these the "INSTALL" and "README" files are useless to any automation. The "Configure" script falls back to an interactive mode if it has any choices to make (which makes it hard to automate without "expect").

Starting with the "Makefile" (sometimes spelled "makefile") we have some structure that supports automation. We are going to assume some cultural structure is in place (or can be added with minimal cost) to each make(1) description:

This should yield a make(1) description that gives us the invariants that we need:

  1. builds the product without human intervention
  2. fits the existing make(1) culture (macro and target names)
  3. allows the leverage we need to refine it later
  4. supports the culture we are building

After this customization to the Makefile we should not need any "Configure" script to build the product on this (single) platform. We may have found a feature the product needs that the platform doesn't provide (like strstr(3)).

Emulations and Property Attributes

It might be appropriate to include emulation code in a canonical file to be carried with this source.

Header files used to map types to properties

Some emulations are so small that they can even be done in a C header file. We use a "machine.h" file to map emulations needed and facilities supported, on a platform basis, to property based attributes.

This file maps the type that the Makefile passes in as a cpp(1) macro to many property macros thusly:


	#if !defined(HAVE_property)
	#define HAVE_property	(defined(type)||defined(type))
	#endif

There are a few distinct kinds of properties.

C coded emulations

Additional emulations are larger (but still small) so we have to make a C source file to keep those. We use a "machine.c" file to emulate facilities that the platform is missing. This file has emulations which are triggered by code which looks like:


	#if NEED_property
	/* emulation code for the hollow tree routine
	 */
	is_hollow(....)
	{
	}
	#endif /* property emulation */

Production C code (declarations)

By including the "machine.h" file in each C source file plus some standard system includes we provide just enough leverage to decide which facility to choose to gain the functions we need to implement the product at hand.

After we know which facility we are using we may need to declare, define or include parts. This looks like:


	#if NEED_property
	#include 

	SHALLOW *pSHRoot;
	#endif

Since "machine.h" mapped the HOSTTYPE to a property macro we should always use the property here.

Production C code (usage)

At the actual use of the facility we may need some more leverage (preferably we map 2 facilities into a common calling convention, but sometimes we can't). When we can't fold them they look like this:

	#if HAVE_FCHOWN
		if (-1 == fchown(fdThis, 0, -1)) {
			...
		}
	#else
		if (-1 == chown(pcThis, 0, -1)) {
			...
		}
	#endif

Special Libraries

Any libraries which are needed on just this platform (like -lgen) or special library search paths (-L/usr/local/lib) need to be put directly on the load line (not in a macro by CFLAGS).

Documentation, manual pages

The program mkcat has been constructed to install manual pages. It is presently under revision but should be complete by fall 2000.

Source code kept under RCS

No files will be kept on a platform source machine under RCS, unless extreme unction has been granted by the Tech Advisor. In that strange case the RCS cache directory will most likely not reside under /usr/src.

Install the product

A safer version of install is available. Use it.

Distribution to like machine

This is the other job for distrib. Distrib's -c option may be used to transmit files to like peer platforms. Thus we compile on one representative machine for each platform type and distribute the code to all her friends.

The results for a single platform

With this paradigm we have build a clear path to port to other platforms. By mapping the property macros for a new HOSTTYPE we should only have to update "machine.h" and change the libraries and -Dtype in the Makefile.

The remainder of this document builds on that abstraction to automate it.


Next Page