NetSurf Toolchain builds

Pre-requisites for Debian systems
---------------------------------

	$ apt-get install build-essential autoconf automake autogen flex bison
	$ apt-get install libtool texinfo help2man subversion cvs git
	$ apt-get install lhasa unzip autoconf2.64 automake1.11
	$ apt-get install pristine-tar

 If you've not got automake 1.15 by default, you'll need:

        $ apt-get install automake-1.15

 Depending on your platform you may also need libfl-dev

 On multiarch-aware systems:

	$ dpkg --add-architecture i386
	$ apt-get update
	$ apt-get install gcc-multilib

Building
--------

It is important that the output prefix (/opt/netsurf by default) is writable.

There are two steps to a build:

  1. building the toolchain (compiler, linkers, etc) for the build system
  2. building the runtime libraries for the host system using the toolchain

The general pattern is as follows:

	$ make -C {ARCH}
	$ GCCSDK_INSTALL_CROSSBIN=/opt/netsurf/{ARCH}/cross/bin \
	  GCCSDK_INSTALL_ENV=/opt/netsurf/{ARCH}/env \
	  make -C sdk

where {ARCH} is one of the supported host triplets (e.g. arm-unknown-riscos)


Sources
-------

The original source tarballs are ingested into git using the "import-orig"
script found in the tools directory.  This uses pristine-tar to ensure a
bit-exact copy of the original source tarball is recreated.  Tags are created
for each upstream version.

The tarballs are recreated dynamically as part of the build using the
relevant sources from the appropriate "upstream/<package>" branch and a
delta file from the "pristine-tar" branch.  Neither branch need be checked
out locally but must be known to git in some way or other (i.e. via the
"origin" remote) -- thus shallow clones and bare branches will not work.

Note that, while source package name and version are usually computed
without incident from the name of the original source tarball, it may
be necessary to tell "import-orig" the answer explicitly -- it has
command line arguments that enable this.  Of particular note are packages
whose tarball name is ambiguous (i.e. where the package name and/or version
contain the likely separator characters: underscore and hyphen).

Note also that it is only possible to use "import-orig" to import a
single source artefact for a given version.  Multiple source archives
for a package are not supported.

Where the original sources are not provided in (compressed) tar format
by the original source, it is necessary to repack them before import.
This may be achieved using the "repack" script found in the tools directory.
This determines the package name and version from the basename of the
output path.

As a general rule, "repack" will encapsulate the contents of the source
archive in a directory with a name in the form of {package}-{version} and
then create the tarball from that.  In the case where a single top-level
directory is found in the source archive it will be renamed to
{package}-{version} and then tarred.

As for "import-orig", "repack" can be confused by ambiguous names so take
care to ensure that the resulting repacked sources look sane before use.


Updates
-------

Each of the Makefiles has a "source-archives" target which fetches the
original sources from wherever they live upstream and, where appropriate,
repack them into a tarball.  Thus, updating components will generally
involve the following steps:

  0. Ensure all upstream/* and pristine-tar branches are checked out locally
     and have no changes
  1. Bump the version numbers of the components in the Makefile
  2. Run "make source-archives" to download them all (noting that bitrot
     is inevitable as URLs are not stable, so fixes to the download rules
     may also be required)
  3. Manually verify the authenticity of the archives (i.e. check against
     published checksums, or validate GPG signatures)
  4. Manually verify that repacked source archives are sane
  5. Use "import-orig" to import each of the updated components to git
  6. Update any local patches/additions (c.f. recipes/*)
  7. Build the updated sources in the usual way

Steps 6 & 7 likely repeat multiple times until done.

Step 3 might be possible to (semi-)automate if checksum/signature files
are published in a deterministic manner by the original source.  However,
this is very much not the case for many sources.

Once complete, ensure all local changes are committed to git and that
everything (i.e. tags, upstream/* branches, pristine-tar branch, and
the working branch containing this document) is pushed -- failure to
do so makes it impossible to reproduce builds later.