netsurf/Docs/BUILDING-RISC_OS

--------------------------------------------------------------------------------
  Build Instructions for RISC OS NetSurf                        10 August 2009
--------------------------------------------------------------------------------

  This document provides instructions for building the RISC OS NetSurf
  natively on a RISC OS computer and provides guidance on obtaining NetSurf's
  build dependencies.

  RISC OS NetSurf should work on RISC OS 4.02 and above.

  | Note: This guide assumes that you have the RISC OS SVN client installed,
  |       and that you have used it to fetch the NetSurf source.  It also
  |       assumes that you have the following requirements installed:
  |
  |           + OSLib 6.80 or later
  |           + Perl 5.8.8 or later
  |           + GCC 3.4.6 release 3 or later
  |           + The latest NSTools
  |
  |       For instructions on how to do all of the above, consult the following
  |       document:
  |
  |           http://www.netsurf-browser.org/documentation/robuild

  If you want to cross-compile NetSurf for RISC OS, use the BUILDING-ROCross
  document.


  Building and executing NetSurf
================================

  | Note: The version of make supplied with some RISC OS GCC 3 is old and has
  |       a bug that prevents NetSurf from building.  Either ensure that
  |       NSTools is seen before GCC, or replace the make inside "!GCC.bin"
  |       with the make from "!NSTools.bin".
  |       The minimal version of make you need is v3.81 and can be checked
  |       with its '--version' command line option.

  | Note: The pre-built libraries currently supplied in NSTools are AOF format,
  |       and will not work with GCC4, which requires them to be in ELF format.
  |       If you want to build NetSurf with GCC4, you will need to build the
  |       libraries yourself.  See "Obtaining NetSurf's dependencies" below for
  |       details.

  You can examine the contents of Makefile.defaults and enable and disable
  features as you see fit by creating a Makefile.config file.  The default
  settings will work fine.

  You should then obtain NetSurf's dependencies, keeping in mind which options
  you have enabled in the configuration file.  See the next section for
  specifics.

  Once done, to build RISC OS NetSurf on a RISC OS system, set the CSD to the
  directory containing the NetSurf sources, set the next slot to at least
  6000K, and in a TaskWindow, simply run:

      *make

  If that produces errors, you probably don't have some of NetSurf's build
  dependencies installed, or your libraries may be out of date.
  
  See "Obtaining NetSurf's dependencies" below.  Or turn off the complaining
  features in a Makefile.config file.  You may need to "make clean" before
  attempting to build after installing the dependencies.

  Once NetSurf is compiled, the !RunImage is put into the !NetSurf
  application directory, so you can simply double click it as normal.

  To confirm that you're running your own development NetSurf build, view the
  Info window from the NetSurf iconbar menu.  The Version string should read

      #.0 (Development)

  where # is the next major release version number.


  Obtaining NetSurf's build dependencies
========================================

  NSTools contains all of the tools needed to build NetSurf, such as make,
  uname and ccres.  It also contains pre-built libraries.

  Currently NSTools contains libraries which are in a format that are in a
  format which is compatible with RISC OS GCC3 but not RISC OS GCC4.  Until
  NSTools is updated with GCC4 compatible libraries, it is recommended that
  you use GCC3 for native builds.

  The NSTools on the web site is not auto-built, so it may not always have
  the latest versions of the NetSurf project's own libraries.  In this case
  you will need to build the libraries yourself and update NSTools.

  Fetching the sources
----------------------

  Use SVN to obtain the latest versions of each of the libraries.  To do this,
  set the CSD to a directory where you want to keep your copies of the library
  sources, and run each of the following commands:

      *svn<76>co<63>svn://svn.netsurf-browser.org/trunk/libparserutils
      *svn<76>co<63>svn://svn.netsurf-browser.org/trunk/libwapcaplet
      *svn<76>co<63>svn://svn.netsurf-browser.org/trunk/hubbub
      *svn<76>co<63>svn://svn.netsurf-browser.org/trunk/libcss
      *svn<76>co<63>svn://svn.netsurf-browser.org/trunk/libnsgif
      *svn<76>co<63>svn://svn.netsurf-browser.org/trunk/libnsbmp

  The above will create a directory for each of the libraries containing their
  sources.

  Updating NSTools' copies of the libraries
-------------------------------------------

  Set the CSD to the directory of the library you want to build, set your next
  slot to at least 6000K and in a TaskWindow, run

      *svn update

  This updates your local copy of the source to the latest version. To build
  the library, run

      *make

  If you are using GCC3, you may get a warning about AR.  This can be ignored.

  To update your NSTools, copy the latest headers from the include directory
  for the library you built into "!NSTools.include" and copy the built library
  from the build-riscos-riscos-release-lib-static.a directory to the
  "!NSTools.lib.a" directory.