	    ===================================================
	    How To Build an Amiga Cross Development Environment
	    ===================================================

		       (Last Updated 11/11/96)

--------------------------------------------
(1) Pick an installation tree root directory
--------------------------------------------

Pick a location for the root of the binary install tree.  This is where all
the executables, libraries, include files, etc will be installed after being
built.  This can be any directory you want, as long as you have sufficient
permissions to create it or write to it.

On many systems, the standard location for this directory is "/usr/local",
and in fact that is the default location.  For these instructions, because I
want to create a totally private toolset, I will be installing in the
directory "/home/fnf/ade".

Make the install directory and a few necessary subdirectories, if they don't
already exist:

	mkdir -p /home/fnf/ade
	mkdir -p /home/fnf/ade/bin
	mkdir -p /home/fnf/ade/lib
	mkdir -p /home/fnf/ade/m68k-amigaos

Strictly speaking it isn't necessary to make anything except /home/fnf/ade,
since the subdirectories will normally be created as needed during the
install procedure.

-------------------------------------
(2) Pick a source tree root directory
-------------------------------------

Pick a location for the root of the source tree.  An example, used in these
directions, is "/home/fnf/ade-src".  This is where you will unpack all the
ADE source archives.

Make the directory if it doesn't already exist:

	mkdir -p /home/fnf/ade-src

------------------------------------
(3) Pick a build tree root directory
------------------------------------

Pick a location for the build tree.  This is a temporary work area in which
you will build all the object files, executables, libraries, etc, that will
be installed in your installation tree.  It is possible to use the source
tree as the build tree (building "in place") but that is not recommended.
For one thing, you may want to remove the build tree once you've built and
installed everything, and it is much easier to do that if you can just
remove an entire directory and all subdirectories.  For another thing, if
you make changes to the source tree, it is easier to find out later what
those changes are if your source tree is not cluttered with all the files
created during the build, by simply diffing your source tree against the
original.

An example, used in these directions, is "/home/fnf/ade-build".  Make the
directory if it doesn't already exist:

	mkdir -p /home/fnf/ade-build

IMPORTANT: In order to successfully use separate source and build trees you
must be using a "make" program that fully supports "VPATH".  Some native
"make" programs do not!  The workaround is to use GNU make, so you may have
to first build and install GNU make if you wish to keep the build and source
trees separate.  If this is not an option for you, then you can just do the
builds in the source tree and forget about having a separate build tree.

----------------------------------------------------
(4) Get and unpack the ixemul includes and libraries
----------------------------------------------------

During the build of the cross tools, you will need the standard ixemul
header files.  These are not used to build the cross tools, but rather used
by the cross compiler when it is compiling some amiga objects, such as the
libgcc.a runtime library that gets linked with the output of the cross
compiler to make an Amiga executable.  You will also need some other runtime
files, such as an Amiga crt0.o and libc.a, from the ixemul library
distribution.  It is best if you get and install these files now, before
starting to build the cross tools.

From the latest ADE distribution, get the AmigaOS specific inline files
(fd2inline-X.X-bin.lha), the AmigaOS specific libraries (libamiga-bin.lha),
the libnix libraries (libnix-X.X-bin.lha) and the ixemul runtime files
(ixemul-X.X-env-bin.lha, ixemul-X.X-inc-bin.lha).

If you expect to do Amiga specific development you will also need the
AT/VISCorp include files, which are not available in the ftp ADE
distributions but are in the ADE CD-ROM distributions (at-inc-bin.lha).
Alternatively you can get these files later from some other source, such as
one of the Native Developer Update Kits (NDUK) or from the AT developers
CD-ROM.  The AT/VISCorp include files are not necessary for building the
cross environment, just for using it to build any AmigaOS specific programs.

Because these files are distributed in lha format in the ADE distribution,
the easiest way to get them to your cross machine is to extract all of these
archives in a temporary directory on an Amiga and then make a "tar" archive
which will be copied to your cross machine and unpacked there:

	(on an Amiga)
	lha -mraxe x fd2inline-X.X-bin.lha
	lha -mraxe x libamiga-bin.lha
	lha -mraxe x libnix-X.X-bin.lha
	lha -mraxe x ixemul-X.X-env-bin.lha
	lha -mraxe x ixemul-X.X-inc-bin.lha

This will create subdirectories "bin", "guide", "include", "lib", and "man".
Delete the bin and guide directories since you won't need their contents.

	delete bin guide all force

Extract the AmigaOS include files from the optional at-inc-bin.lha archive
from the ADE CD-ROM (or skip this step if you don't have the CD-ROM), copy
the files to the include directory, and delete the os-include directory that
is created from the archive extraction:

	lha -mraxe x at-inc-bin.lha
	copy os-include/#? include all
	delete os-include all force

Use the Amiga version of tar to pack the "include", "lib", and "man"
directories into a tar archive, move the archive to the system on which you
are installing the cross environment, and unarchive it in the appropriate
subdirectory in the binary tree:

	(on an Amiga)
	tar -cvf inclibman.tar include lib man
	delete include lib man all

	(on the cross host system)
	cd /home/fnf/ade/m68k-amigaos
	tar -xvf inclibman.tar
	rm inclibman.tar

Note that you can use any other method you like to get these files from your
Amiga to the cross host system.  The important thing is that they end up in
the correct subdirectory in the installation tree, which is where the cross
tools will look for them once the tools are built.

------------------------------------
(5) Build and install the "binutils"
------------------------------------

Get the binutils (assembler, linker, archiver, etc) distribution from the
latest ADE snapshot (ftp.ninemoons.com:pub/ade/961012/binutils-2.7-src.tgz
for example) and extract it in the source directory.  It will create the
subdirectory "fsf/binutils" and populate it with the binutils source files:

	cd /home/fnf/ade-src
	tar -xvzf binutils-2.7-src.tgz

Check the ADE updates directory (ftp.ninemoons.com:pub/ade/updates) for any
patch files that need to be applied to the archive from the latest snapshot
directory, and apply the patch (if necessary):

	gzip -d binutils-961012-961111.diffs.gz   (no such file, example only)
	cd fsf/binutils
	patch -p0 <../../binutils-961012-961111.diffs

Configure and build the binutils in the build tree.  Note that the --prefix
option should be set to the binary tree that you chose and it should be an
absolute path (starts with a '/' character) not a relative path.  Also,
using a common cache file via the --cache-file option makes the configure go
faster:

	cd /home/fnf/ade-build
	mkdir binutils
	cd binutils
	/home/fnf/ade-src/fsf/binutils/configure -v --prefix=/home/fnf/ade --target=m68k-amigaos --cache-file=config.cache
	make

If everything builds OK, then install the binutils into the binary tree:

	make install

-------------------------
(6) Build and install gcc
-------------------------

Get the gcc distribution (ftp.ninemoons.com:pub/ade/961012/gcc-2.7.2.1-src.tgz
for example) from the latest ADE snapshot and extract it in the source
directory.  It will create the subdirectory "fsf/gcc" and populate it with the
gcc source files:

	cd /home/fnf/ade-src
	tar -xvzf gcc-2.7.2.1-src.tgz

Check the ADE updates directory (ftp.ninemoons.com:pub/ade/updates) for any
patch files that need to be applied to the archive from the latest snapshot
directory, and apply the patch (if necessary):

	gzip -d gcc-961012-961111.diffs.gz   (no such file, example only)
	cd fsf/gcc
	patch -p0 <../../gcc-961012-961111.diffs

Configure gcc in the build tree.  Note that the --prefix option should be
set to the binary tree that you chose:

	cd /home/fnf/ade-build
	mkdir gcc
	cd gcc
	/home/fnf/ade-src/fsf/gcc/configure -v --prefix=/home/fnf/ade --target=m68k-amigaos

Because of some unresolved problems building a cross compiler, apply the
following patch to the gcc Makefile after configuring and before building
gcc.

============================================================================
--- Makefile.orig	Mon Nov 11 18:51:20 1996
+++ Makefile	Mon Nov 11 20:07:16 1996
@@ -38,5 +38,5 @@
 # Selection of languages to be made.
 # This is overridden by configure.
-LANGUAGES = c objective-c proto  c++
+LANGUAGES = c c++
 
 ALLOCA =
@@ -194,5 +194,5 @@
 # include files.
 # NOTE: local_prefix *should not* default from prefix.
-local_prefix = /ade/local
+local_prefix = $(prefix)/local
 # Directory in which to put host dependent programs and libraries
 exec_prefix = $(prefix)
@@ -273,5 +273,5 @@
 
 # libgcc1-test target (must also be overridable for a target)
-LIBGCC1_TEST = libgcc1-test
+LIBGCC1_TEST =
 
 # List of extra executables that should be compiled for this target machine
@@ -438,5 +438,5 @@
 
 SYSTEM_HEADER_DIR = /ade/include
-OTHER_FIXINCLUDES_DIRS = /ade/os-include
+OTHER_FIXINCLUDES_DIRS =
 
 # We don't need a libgcc1, it's all in ixemul.library
@@ -2437,5 +2437,5 @@
 # Remake the info files.
 
-doc: info guide
+doc: info # guide
 info: cpp.info gcc.info lang.info
 guide: cpp.guide gcc.guide lang.guide
@@ -2606,5 +2606,5 @@
 # broken is small.
 install-normal: install-common $(INSTALL_HEADERS) $(INSTALL_LIBGCC) \
-    install-libobjc install-man install-info install-guide lang.install-normal install-driver
+    install-libobjc install-man install-info lang.install-normal install-driver # install-guide 
 
 # Do nothing while making gcc with a cross-compiler. The person who
============================================================================

After the patch is applied, build and install gcc: 

	make
	make install

You might want to add the binary directory to your PATH variable:

	PATH=/home/fnf/ade/bin:$PATH ; export PATH

----------------------------
(7) Test the new cross tools
----------------------------

An easy way to test the new cross tools is to configure and build one of
the ADE components in the cross environment, and then copy the executable
back to an Amiga to see if it runs OK.  I would suggest using the "brik"
program:

	cd /home/fnf/ade-src
	tar -xvzf brik-2.0-src.tgz
	cd /home/fnf/ade-build
	mkdir brik
	cd brik
	CC=m68k-amigaos-gcc /home/fnf/ade-src/contrib/brik/configure -v
	make CC=m68k-amigaos-gcc

On a 166 Mhz Pentium system running RedHat linux this build takes only 3
seconds while on an A4000 with 40 Mhz WarpEngine, it takes about 20 seconds.
The executable should be about 12,800 bytes, but the exact size may vary
depending upon a number of factors.  Move the executable back to an Amiga
and test it:

	(on an Amiga)
	brik -Gvb brik

which should print something like:

	# Whole file CRCs generated by Brik v2.0.  Use "brik -C" to verify them.

	# CRC-32        filename
	# ------        --------

	2515614901b     brik

Don't worry if the CRC is not the same as printed here.

If this works, you now have a functioning cross environment (or at least a
cross compiler) that depending upon the model of your Amiga and the machine
you are using as a cross development host, could easily be 20 times faster
than a native compiler.

-Fred Fish
