BUILDING THE SPECTRANET ROMs/MODULES
------------------------------------

Pre-requisites:
A Unix-like build environment (Linux, BSD, Mac OSX, 
Windows with Cygwin, Windows with MinGW etc)

GNU binutils for Z80 (assembler, linker, ar, ranlib etc)
Perl for some build scripts (my intention is to remove this requirement)

To build:
In the top level directory, type "make"

To install:
A firmware programmer is generated in the directory 'installer'. This
must be run on a ZX Spectrum with a Spectranet. Two versions exist - a
version that programs just the base ROM set (first four pages), and
a version that programs the base ROM set and standard modules (basext,
streams, msgrom, config and snapman).

Run 'bin2tzx' to convert the install.bin / base.bin files to TZX files
to load via the Spectrum's tape port. Alternatively, to update a Spectranet
that is already programmed, load via ethernet using the 'ethup' utility:

  On the Spectrum:
  CLEAR 26999
  (press NMI button or short the NMI pins on the bare board)
  (Select 'Load arbitrary data...')

  On the build machine:
  ethup <IP-of-spectrum> install.bin 27000

  Then on the Spectrum, exit the NMI menu and:
  RANDOMIZE USR 27000

Or if you have the computer with the build mounted via TNFS or some other
filesystem, on the Spectrum:

  CLEAR 26999
  %aload "install.bin" CODE 27000
  RANDOMIZE USR 27000

Building z88dk libraries:

  make z88dk

You'll of course need the z88dk installed somewhere in your path to do
this. The build results live in the "z88dk" directory.

DEVELOPING
----------
The source tree is organized as follows:

rom:		The base 4 pages of the Spectranet flash, in other words
		the absolute minimum required to make it work. This
		includes the software interface to the ethernet hardware,
		socket library, TNFS client, NMI handler, BASIC extension
		handler  etc.
syslib:		Libraries of code that's used in more than one place.
		Includes basic user interface functions (42 column print
		routine, input routines), paging functions, flash writer
		etc. Most of these are used by the rom, and various utilities
		also use them (eg. the installer).
modules:	The core set of modules distributed with the Spectranet.
installer:	An installer program. Two versions are generated: one that
		only updates the base ROM (the bottom 4 pages of flash) and
		a version that installs the base ROM and core set of modules.
z88dk:		Libraries for developers using the z88dk: a socket library,
		a general 'Spectranet functions' library, and an HTTP lib.
include:	Assembler include files, including spectranet.inc (equs
		for calling functions in ROM), sockdefs.inc, sysvars.inc
		etc. (Note: the files here should be compatible with most
		assemblers).
buildtools:	Tools that are required to build some parts of the system.
		These will get built by running the top level makefile.
devtools:	Useful tools for development, for example "ethup", a program
		that sends data to be loaded directly into the Spectrum's
		RAM.
utils:		General utilities that are not specific to the Spectranet,
		for example bin2tzx (bin2tzx will be used by the build to
		make a TZX version of the installer).
examples:	Various bits of example code, code for the tutorials etc.

Note that the installer directory's Makefile has all the various binary
objects the installer uses listed as dependencies, and the rules necessary
to have them built, so as a convenience typing "make" in the installer 
directory is almost the equivalent to typing "make" at the top level.

Generated files
---------------
There are a number of files that look "sourcey" that are actually 
automatically generated, so don't edit them :-) (If they aren't actually
a versioned resource within svn, this is a good hint). Generally they
follow the pattern of "something.xinc". Usually they are symbols that can
only be resolved after something has been linked, but there's also
ver.xinc and date.xinc which allows a version/date built string to be
put into the build output so someone can see what build they have running
on the actual hardware.

More on syslib
--------------
If it turns out that something is going to get used in more than one place,
for example, in a module and inside some standalone utility, the code
ought to live in syslib so it's available to be linked by anything.
Currently, the following libraries are available:

libflashwrite.a		: Functions to write to the flash memory
libpager.a		: Paging functions. Used by the ROM and various
			  standalone utilities.
libromui.a		: 42 column print routine, routines to read the
			  keyboard. Used by the ROM and various standalone
			  utilities.

Note that if you're developing a module, it's unlikely you need to link
to either libpager or libromui - just include "spectranet.inc" and use
the functions there since they are already present in the ROM. However,
they are useful for standalone utilities. (Note that there's a little bit
of a complication at present with the 42 column print routine: it has
a lookup table that must not span two 256-byte pages; I hope to eliminate
this eventually, but until then see the .ld file for the installer on how
to make sure this lookup table gets put in the right place in your binary).