The RISC OS Software Development Kit
====================================

This rather large package is a collection of software that I use regularly
when writing software.  Originally written as many seperate build trees,
I decided to take advantage of recursive makefiles and package everything
together into one large tree.  I was also getting a bit disturbed over
the increasing length of time it takes to build GCC on RISC OS and since
I mainy use Linux-based PCs at home and work, I decided to port the whole
lot to that platform.

What you have here is a complete cross-compiler toolset for targetting
ARM/RISC OS that is easily portable to other Unix-like operating systems.


Prerequisites
-------------

In order to successfully build GCCSDK, you will need to have the following
packages installed on your system, with at *least* these software revisions.

	autoconf 	version 2.13
	bison		version 1.27
	gcc		version 2.91
	gperf		version 2.7.2
	sed		version 2.05

GNU make is required for building the package as the makefiles use
extensions not commonly found in the BSD make utility.

Installation
------------

Make sure you've got about 150Mb spare disk space and a spare couple of
hours.  It is recommended that you install GCCSDK has a non-root user.
The makefiles are still under development.  If something does go wrong
then at least your system directory structure will still be preserved. 

Generate the configure script:
  $ autoconf ; autoheader

Configure it.  The package creates two main installations.  The first,
is a Unix-based cross-compiler for targetting RISC OS which will be
installed under the directory specified with the `--prefix' option. 
The second, is a complete GCC compiler toolset built to run natively on
RISC OS and will be installed under the directory specified with
the `--with-riscos-dist' option.  Finally, `--with-riscos-pkg' points
to a directory where distributable zip files of the RISC OS GCC toolset
will be created.  These should then be suitable for unpacking on a RISC OS
computer to make a working compiler.
  $ ./configure --prefix=/home/riscos/cross \
	--with-riscos-dist=/home/riscos/riscos-dist \
	--with-riscos-pkg=/home/riscos/riscos-pkg \
	--enable-filetype-ff8

Adding the flag --enable-filetype-ff8 to the configure options will add the
",ff8" suffix to any RISC OS executables built under Unix.  This is to allow
filetyping by networking filing systems from RISC OS, such as LanMan98.
We supply a modified version of `zip' which can encode proper filetypes
into zipfiles whenever it sees the ,xxx suffix.  

Create installation directory structure
  $ gmake setup

Build it.  This will take about 1 hour 30 mins on a Pentium II-266MHz.
  $ gmake

Optionally, you can create the RISC OS GCC compiler zip packages using
this command.
  $ gmake riscos-pkg


Using it
--------

Once built, you need only add /home/riscos/cross/bin to your PATH
variable.  Then use it as you would the GCC compiler normally.


RISC OS filename compatibility issues for the cross-compiler
------------------------------------------------------------

Since the cross-compiler is built to execute on a Unix-like file system,
it expects file naming conventions particular to that operating system.
However, since there is going to be a lot of source code out there that
makes use of some RISC OS pathname features, the pre-processor has been
fixed to cope with path variable names in file names.

When the pre-processor attempts to read an include statement like:
  #include <DeskLib:Wimp.h>
it will try to resolve the DeskLib reference against the environment variable
DESKLIB_PATH.  So you could install the DeskLib header files in a place
such as /home/riscos/libs/include/desklib.  To get GCC to search in that
directory for those headers, simply define the variable:
  $ export DESKLIB_PATH=/home/riscos/lib/include/desklib


Bug reporting
-------------

Please use the bug-tracking system at http://bugs.hard-mofo.dsvr.net.


GCCSDK package contents
-----------------------

The cross-compiler contains the following tools:

  Language compilers for C, C++, Fortran 77 and Pascal.

   armemu - a RISC OS emulator.  It consists of a ARM emulator and an
	    implementation of several RISC OS SWIs in order to get a
	    very small number of RISC OS applications running on Unix.

   drlink - Dave Daniels' RISC OS AOF linker.
  libfile - a RISC OS ALF builder.
     gcov - a test coverage program
   libscl - C library headers and stubs for linking with the SharedCLibrary.
  unixlib - A C library with BSD, System V and POSIX library extensions.
  rink, rinkptr, extractsym - components of Ben Summers' run-time linker
      zip - A file archive utility

The RISC OS distribution contains the following tools:

  Language compilers for C, C++, Fortran 77 and Pascal.

   drlink - Dave Daniels' RISC OS AOF linker.
  libfile - a RISC OS ALF builder.
     gcov - a test coverage program
   libscl - C library headers and stubs for linking with the SharedCLibrary.
  unixlib - A C library with BSD, System V and POSIX library extensions.
    bison - A YACC implementation.
     flex - A lexical analyser.
     grep - A patten matcher
    gperf - A perfect hash generator
     gzip - A file compression utility
     make - A make utility
    mkdir - A port of the Unix directory creator.
    patch - A program that can patch files when supplied with the output
            of diff.
      sed - A batch stream editor
    touch - A port of the Unix touch command for changing file timestamps.
  rink, rinkptr, extractsym - components of Ben Summers' run-time linker.


FAQ
---

Q1. How can I build Unixlib with function names?

A1. The default is for GCC to not embed function names in the program,
    so backtraces will show ?() for functions.   The following applies
    equally to most parts of the build process:

    In unixlib/source/Makefile, add "-mpoke-function-name" to the
    CROSS_CFLAGS line.

    Delete previous Unixlib objetcs, e.g.:
       find arm-riscos-aof/unixlib/ -type f | xargs rm

    Rebuild with gmake.

    If you want function names in all libraries and RISC OS binaries
    then edit the top-level Makefile.in and set the following lines thus:

       CROSS_CFLAGS=-O2 $(TARGET_DEFS) -mpoke-function-name
       CROSS_CXXFLAGS=-O2 $(TARGET_DEFS) -mpoke-function-name


-----------------------------------------------------------------------------

Q2. What systems has GCCSDK been built on?

A2. Systems on which it has successfully been built upon include:
        Debian i386/Linux,
        RedHat i386/Linux,
        Debian ARM/Linux,
        FreeBSD,
	OpenBSD,
	NetBSD,
        Cygwin,
        and others.


-----------------------------------------------------------------------------

Q3. Where does the Unixlib library file end up?

A3. It depends on the parameters you pass to configure.  But for the
    RISC OS distribution it could be something like:
      /usr/home/riscos/riscos-dist/bin/arm-riscos-aof/apcs26/unixlib/o/

    For the Unix tree it could be:
      /usr/home/riscos/riscos-cross/bin/arm-riscos-aof/apcs26/unixlib/unixlib.o


-----------------------------------------------------------------------------

Q4. My Unix variant appears to be unsupported.  How do I fix it?

A4. Fortunately this is quite easy and, in most cases, only requires you to
    make changes to a few configuration files.

    a) Change gccsdk/configure.in to correctly detect your CPU and OS type,
       fixing up cpu_type and os_type respectively.

    b) Fix config.h and hconfig.h.  Add a HOST_CPU_OS clause for your machine,
       which should include an appropriate xm-*.h file, which you would have
       previously copied from an original GCC 2.95.x release.

    Big-endian CPUs, such as Sparc and MIPS, are currently unsupported.

-----------------------------------------------------------------------------

Q5. Where do I report bugs or send patches ?

A5. The preferred method for issuing bug reports for any package distributed
    with GCCSDK can be registered at http://bugs.hard-mofo.dsvr.net.  A
    centralised location for bug reports helps the authors keep track of
    problems which can otherwise get lost under large piles of e-mail.

    Patches for any application can also be sent to the site.  Alternatively
    bugs or patches can be e-mailed to gcc@hard-mofo.dsvr.net.
