Hey Emacs, this is yet another file of -*- text -*-.

You should be reading this file if you were directed here by the README
file.  If you are installing Bash on a Sun or Vax, or other popular
machine, you probably need to do no more than type `make'.  If Bash says
that your machine type is "UNKNOWN_MACHINE", or Bash thought it knew
something about your machine, but was wrong, then reading this file
could be of use to you.

Files in the Make Process
*************************

Makefile:	This is responsible for making the actual Makefile that
		will be used to create Bash.  It runs the C preprocessor
		(usually located in /lib/cpp) on the file `cpp-Makefile'
		producing the output file `bash-Makefile'.

cpp-Makefile:	This is a file of C comments and text.  It contains a
		reasonable number of `ifdefs' which control what files
		get compiled and which flags are passed to the various C
		files comprising Bash.  It includes a file called
		`machines.h'.

machines.h:	This file contains the basic compilation parameters for
		all of the machines that Bash has been ported to.  It
		consists of a series of conditional blocks, one per
		machine type.  The blocks are conditionalized based upon
		the unique identifier that `cpp' has predefined for this
		machine.  In some cases, additional information can be
		passed in from `Makefile', such as whether or not a
		particular file is available on this system, etc.

bash-Makefile:	This is the output from the initial stage of `make'.  It
		is a stripped down version of cpp-Makefile which is
		tailor-made for your machine and OS.  All subsequent
		makes use this file.

Porting to a New Machine
************************

You need to create a block in machines.h which is conditional based on a
unique identifier present in your version of the C preprocessor.  If you
don't know what that symbol is, you might try the following simple test:

	echo "main () { }" > foo.c
	cc -v foo.c

and look for -DMACHINE, where MACHINE is an identifier for your machine.
If you are very unlucky, your machine's C preprocessor doesn't have a
unique identifier.  In this case you will have to define the identifier
in Makefile manually.  Let's say you have a machine from Yoyodyne
Industries, called the YoYo.  It runs a version of BSD, so it is
reasonably compatible.  However, the cpp on this YoYo machine doesn't
define any unique identifiers.  You change the Makefile line for
CPPFLAGS to:

	CPPFLAGS = -P -DYoYo

Then, in machines.h, you copy the block for UNKNOWN_MACHINE, and change
the conditional to

	#if defined (YoYo)

Inside of the YoYo block you define M_MACHINE="YoYo", and M_OS=BSD.  You
also modify the existing defines to match your machine's software.

If Bash still won't compile, perhaps because of missing code that is
required for your YoYo machine, you will have to write that code, and
place it within a conditional block based on YoYo.

Most Un*x machines will simply require a few of the default values to be
redefined.  I would appreciate having all fixes and changes mailed back
to me in the form of context diffs:

	diff -c orig-machines.h machines.h >machines.diffs

Please don't hesitate to include which version of the shell that you
have.

Brian Fox
bfox@ai.mit.edu		(Personal e-mail)
bash-maintainers@ai.mit.edu (Context diffs for Bash bug fixes)
bug-bash.ai.mit.edu	(Discussion and questions about Bash)
