!OSLib.!Readme  20051231

******************************************************************************

Introduction
------------

  This is the OSLib source release. It contains everything you need  to build
(and modify) OSLib, its build tools, and OSLibSupport. It is available by CVS
from http://ro-oslib.sourceforge.net.


*****************************************************************************

  Directory structure
  -------------------

  NOTE: It is essential  that the work directory can handle  long file names;
unpack  the archive  or  checkout the  repository into  an  appropriate RaFS,
LongFiles, or XFiles directory, as appropriate, if you do not have RISC OS 4.

  The top level  directory is called !OSLib (Under CVS  the work directory is
called OSLib, which contains !OSLib). Double-clicking on this causes a number
of  environment variables (all  names are prefixed  with 'OSLib$'), which are
used during  the build  process.  Any environment  variables pointing  to  an
installed OSLib are  overwritten, so that !OSLib  becomes the reference,  and
any builds use the development library contained herein.

  Within !OSLib,  there are a number  of subdirectories:OSLibSupport contains
the sources to the OSLib Support library; Source contains the source to OSLib
itself, together with some test applications;  and Tools contains the sources
to a number of tools required to build OSLib.

  Below these,  OSLibSupport contains  a subdirectory for  each of  the major
components of the library, plus a 'h' directory containing the public headers
(under UNIX, these are .h  files); Source contains subdirectories for each of
the  four  component  areas  of  OSLib  (to avoid  more  than  77  files  per
directory); it  also contains a  Test directory in  which reside a  number of
test files  which  are executed  during  the build  process.  Tools  contains
further subdirectories for each of the specialised tools used to build OSLib.
Of  these, DefMod (now at  version 2) is the  most important, translating the
SWI definitions into  assembler sources. Bison  is required to  interpret the
DefMod  language definition  file, and  is  used to  build DefMod.  ReduceAOF
removes redundant chunk headers form the AOF files before placing them in the
library, thus minimising the  size of the latter. IndexHelp  and BindHelp are
used to process the Help output from DefMod to create the StrongHelp manuals.
Rm is  a small file  deletion utility, with  the ability to  process multiple
arguments,  and  StripDepends is  used  to  clean  a  Make file  of  all  the
(installation-specific) dynamic dependency  information. Since some  of these
tools are themselves dependant upon OSLib, the build order is critical.

  Additional subdirectories are created during the build process.

*****************************************************************************

  Building OSLib under RISC OS
  ----------------------------

  You'll need:

  1.  An (image) filing system  capable of handling long  file names. Many of
the source  files have names  longer than  10 characters,  and problems  will
arise if these are not preserved.

  2.  A Make utility.  OSLib is currently  built using Acorn's  AMU, which is
part  of the Castle's C/C++ 6.0  package. It is essential  that at least that
version is  used, as  the makefile  structure uses  the latest extensions.  A
current WIP is to produce a set of make files to build OSLib using the GCCSDK
package under RISC OS; it is quite possible to do this, but currently  you're
on your own.

  3. An  Assembler.  Currently,  DefMod,  in  its  RISC  OS  incarnation,  is
hard-wired to call Acorn's ObjAsm, again part  of Acorn's C/C++ package. I am
not  aware of  any other  assembler being  successfully used; indeed  this is
unlikely without changes to DefMod.

  4.  A  C compiler.  Currently the  tools and  OSLibSupport are  built using
Norcroft C, but I know of no reason why GNU C should not be used.

  The entire build  process is divided  into a number  of sub-projects,  each
with its  own make file, named AMUmakefile, to  distinguish it from any other
make system.

  To build OSLib "out of the box", under RISC OS, all that is necessary is to
double-click on the 'Make'  TaskObey, which will look after the  entire build
process and place a distributable OSLib in the 'release' sub-directory. There
are  2  versions  provided: "wide",  which  uses a  wide  directory structure
suitable for RISC OS 4, or any file system capable of containing more than 77
files per directory; and "deep", which contains a file structure suitable for
RISC  OS  3.  Directory  "OSLibHelp"  contains  the  StrongHelp  manual,  and
directory  "OSLibSupport"  contains  the  optional  support  library.  On  my
StrongArm Risc PC  the entire process takes just over  two hours to complete;
somewhat longer over a network connection.

  For  more experienced  users, there  are more  targets in  the AMUmakefile,
which may be invoked by typing "make <target>" at  the command line, with the
default directory  set appropriately. Of  these, "Make distclean"  is perhaps
one  of the more  useful; it restores  the directories to  their condition at
chaeckout.  "Make dist" creates a set of zip files for distribution; for this
you require a copy  of infozip in the  run path (I used  to use SparkFS,  but
this has problems compressing such a large archive).

  No doubt I've got some  of it wrong, and will be grateful  for any comments
and amendments.

*****************************************************************************

  Building OSLib under UNIX/Linux
  -------------------------------

  Building under Linux is possible with the support of the GCCSDK, which can
be found at <http://gccsdk.riscos.info/>. You'll need at least GCCSDK
3.4.5 Release 1.

  Otherwise, building under LINUX is very similar to building under RISC OS.
In a terminal, in the appropriate directory, type "make all", and watch it
all happen by magic. It all happens in 10 minutes on my 1.1 GHz Linux box; a
vast improvement over the 2 hours or more under RISC OS. Again "make dist"
and "make distclean" work very much as expected. Dig around inside the
GNUmakefiles for other less-useful targets.

  Thanks are  due to Druck, for supplying the  initial "portable OSLib", upon
which, with enhancements, the tools are built.

*****************************************************************************

  Tony van der Hoff. mailto: <oslib-user@compton.nu>
