f-cpu/COMPILE.txt
created Tue Aug 28 08:26:04 2001 by whygee@f-cpu.org
version sam mar 30 07:34:59 2002
updated Sun Jun 23 03:29:35 2002 : tool's database

Welcome
-------

Thanks for reading this file which explains how to compile the
different parts of this source tree. If you have a "source only"
version of the F-CPU package, you will remark that some steps are
required to obtain a working source tree. You can probably find
already pre-processed source files but their modification will
require the modification of the original (before preprocessing)
files. Be sure to understand this.

A shell (bash) script called "install.sh" will setup the files,
run some sanity checks and perform some basic compilations.
It is currently in its preliminary form but it will run all the
package can do.

Here is what to do if you want/have to do it "the hard way"
(by hand) or if you need to modify something.


Requirements :
--------------

Basically, you need a Linux/POSIXy environment
with the following GNU tools :
 - a good shell (bash is highly recommended)
 - m4 (we can't configure anything without this)
 - a text editor of your choice
 - make (for the Makefile's)
 - gcc (for the C utilities)
 - and a VHDL tool (see the VHDL-HOWTO in the
f-cpu/vhdl directory for more explanations).

Notice that the F-CPU manual is not addressed here.

FYI, this package has been developped mostly on crappy PCs
running stripped-down Linux software without even a GUI,
chances are that it works with you :-)


Structure and setup :
---------------------

There is no global environment variable (at least not yet).
Something like "$FCPU_DIR" would be useful in the future
but it could make working simultaneously with several
versions difficult. We work with relative directory paths,
assuming "f-cpu/" as a base directory in our examples.
This directory should be created when the tarball is extracted.

First, you have to go to f-cpu/configuration/ and run "make" :
this command will create/update a lot of files which depend
on user settings in different langages. This operation was first
performed by a script (f-cpu/configure.sh) but it is now only a
wrapper for the make utility. However this name was chosen on purpose
because "configure" is usually executed before "make" in most GNU packages.

Only after this step is performed, you can start to look around.
Please look at the f-cpu/configuration directory for more information
about the configuration stage. It is also where the "original" files
(suffixed with ".in") are stored.

Then, you can start to compile the tools and the VHDL packages.
A shell script (suffixed with ".bat" for DOS or ".sh" for un*x)
or a Makefile is provided in each subdirectory. Concerning the
VHDL side, read the HOWTO.

A recent useful addition is a tool description "database"
that abstract all low-level VHDL invokations. It is used to reduce
the amount of scripts and keep them independent from the
tool's invocation details. The database is regenerated
automatically.

All tested directory have a file named "test.sh". You can run
them to start the corresponding individual tests. They are called
by f-cpu/install.sh anyway.

The core is compiled with the f-cpu/vhdl/fc0.sh script.


Modifications :
---------------

Beware : all user-modifiable VHDL constants are contained
in f-cpu/configuration/f-cpu_user.m4
You will have to rerun f-cpu/configure.sh or the modifications
will not be taken into account.


Have fun,
YG
