$Id: README,v 1.11 2003/02/04 07:32:34 prakity Exp $

This is the readme file for the toolchain.

This file should have come from a large tarball or cdrom which includes
binutils and gcc directories. In addition, there should be the scripts
bld-host, bld-tools, bld-tools-newlib, bld-tools-uclinux, bld-one,
get-host-type and find-src.

You have the option to install -or- build the mips tools. Building the
tools is NOT recommended. Unless you are already quite familiar with
building binutils and GCC, you are likely to be frustrated by a myriad
of things that will waste your time even if you understand them. You
could easily burn enough of your time to pay for a PC and Linux and we
can't support you. You have been warned.

If you are using a different version of Linux on a PC, I recommend trying
the supplied binaries, because they may well just work. The tool binaries
have been built statically-linked, so they will not rely on particular
versions of shared libraries being present. I still recommend RedHat 7.2
or 8.0, because that is what we test on. We can't test on everything.

We do not recommend running Linux under VMWare hosted on any flavor of
Windows to run the tools. Although this can work, it is tempting to share
disk space between the two environments. Although even that can work, in
practice line-ending confusion often results when Windows-based applications
are used on the uClinux tree. No doubt other things can go wrong as well. 
**We won't help you in these unsupported environmments.**

Further, if you are building the tools so you can run them in Cygwin under
Windows, please reconsider. We won't support you if you build your own tools.
With line-ending issues coming up that can be even more intractable, we will
not support such an environment. If you insist and make it work, fine, but
we aren't interested in supporting it at this time. I've used Cygwin under
Windows and like it a lot, but I still won't support it's use for cross-
development with uClinux.

The following instructions are for installing the standalone newlib tools:

Copy the mips tools from the /mnt/cdrom/opt folder to your PC, /opt folder
using the following instructions:

   I)   Be sure you can write into /opt. You do not need to be root,
	but you do need to be able to write in /opt.

   II)  cp -a /mnt/cdrom/opt /opt

   III) When you are finished,
	/opt/BRECIS/i686-linux-x-mipsisa32-brecis-elf/bin
	should exist. You will need to include
	/opt/BRECIS/i686-linux-x-mipsisa32-brecis-elf/bin
	in your search path. In bash, the command would be:
	export PATH=/opt/BRECIS/i686-linux-x-mipsisa32-brecis-elf/bin:$PATH

The uClinux-targetted tools are now included with the uClinux source. They
will automatically be installed when a "make clean" or "make linuxall" is
done. The makefile will even automatically set the PATH for the build.

uClinux includes the directory brecis/tools where a tarball of the i686-Linux
hosted tools resides. Unpacking that tarball into the same directory results
in a directory mipsisa32-brecis-uclinux which contains the tools. Therefore,
if you wish to invoke tools easily from the command line, you can add the
path to them to your path. For instance, if you are in the uClinux directory
using the bash shell the command to do that would be:
	export PATH=`pwd`/brecis/tools/mipsisa32-brecis-uclinux/bin:$PATH

If you really must build your own tools, the instructions follow. There is no
guarantee that these instructions are complete, correct or even usable in
your environment.

Copy the /mnt/cdrom/open-tools directory to your hard disk to build the mips
tools. If you have uClinux, the open-tool directory should be in the same
directory that holds uClinux. The uClinux tool build expects it to be there
for includes and libraries. Although the tools have been built and run on
other platforms, getting the conditions right for success are impossible to
describe in general. You are on your own. Good luck. I hope you find the
process fun...

To build the mips tools from source, please do the following:
   I)  Insure the destination directory (default is /opt/BRECIS for the
	standalone tools and a temporary directory within the uClinux/brecis
	directory tree for the uClinux-targetted tools) is writeable. If
	building the uClinux-targetted tools, be sure that the uClinux tree
	is in the same directory as the open-tools directory. Also be sure
	that the uClinux tree has been previously built successfully before
	building the tools. Of course this is a chicken-and-egg situation
	that can be tricky to resolve. If you can't figure out how, that is
	a clue that you should not be trying to build these tools and should
	use the binaries. The only clue you get is that both the tools and
	uClinux have to be built multiple times.

   II) Be sure that the development X11 files are installed on your system
	and that /usr/include/X11 points to the X11 include files. Also be
	sure that /bin/bash exists. On some system you may need to create a
	symbolic link from /bin/bash to /usr/bin/bash or /usr/local/bin/bash.
	On some systems, you may even need to install bash. You may even need
	to build bash from source. You may need to link /bin/sh to /bin/bash.
	You may need to install gettext. You may need to install new versions
	of bison or sed. Possibilities abound. This is why building the tools
	is not a trivial undertaking.

   III) Please copy the open-tools directory to the same directory
	as the uClinux source directory and execute the following
	commands:
	cp -a /mnt/cdrom/open-tools .
	cd open-tools
	./bld-tools-uclinux # for uClinux tools
	   -OR-
	./bld-tools-newlib  # for stand-alone tools using newlib

	bld-host builds a host toolchain which can then used to build
	the cross toolchain in case your native host tools just can't
	get the cross tools built. I'm giving you more clues for building
	tools than I ever got. Your mileage may vary. Live and learn.

The bld-* scripts will either extract source from tarballs, and apply
any needed patches which are in the patch-* files, or use existing source
directories. Source distributions are made with all of this in one, big
tarball.

The bld-tools-newlib script will create "build-*" and "/opt/BRECIS/..."
directories. The components will be configured and built in the build
directories. The results of the build will be installed into the
/opt/BRECIS/... directory. Thus, the executable objects of the tools
will reside in /opt/BRECIS/<hosttype>-x-<target>/bin upon completion.

The bld-tools-uclinux script will create "build-*" directories. The
components will be configured and built in the build directories. The
results of the build will be left in a tarball named:

mipsisa32-brecis-uclinux.<hosttype>.<date>.tar.gz

in the open-tools directory. This tarball may be then be placed into the
brecis/tools directory within the uClinux tree 2.0 or later to support
development of that tree. The tarball can be unpacked there, or the
uClinux makefile can be relied on to unpack it if the mipsisa32-brecis-uclinux
directory is first removed (the uClinux makefile will not unpack the
tarball if there are already tools present), These tools should not need
to be rebuilt when includes and libraries in the uClinux tree change,
because the tools reference the peer uClinux tree directly. This is why
there should be a tool installation for each tree under development.

Obviously, whoever runs these scripts needs write access to /opt or at
least /opt/BRECIS. Although the scripts attempt to set PATH itself,
depending on how the shell is initialized, this may not be effective in itself
because many people set PATH in their .bashrc files, thereby negating
higher-level PATH changes. I learned not to do that in 1984 - now it is your
turn.

The destination can be overridden by setting the variable "dest" to
some other destination, i.e.: dest=`pwd`/built ./bld-tools.

Lots of *.out files are created by the bld-host and bld-tools scripts.
These output files are created, in addition to having all of the
output go to standard output as well. The saved files provide a
convenient record for easy review. There are separate output files for
each stage (configure, make and install) for each toolchain (host and
cross)

The script creates a symbolic link to mipsisa32-elf-gcc called mips-gcc
so the tools can consistently be referred to as mips-*. For some
reason, gcc does not use the --program-prefix option like the other
components.

Hopefully, this will build for you without too much trouble. Yeah, right.

