This directory contains a collection of tools and RPM-related files used to
build Crosswalk RPMs for Tizen.

BUILD INSTRUCTIONS
------------------

In the simplest case, a call to `gbs build' from the xwalk/ directory suffices.
It should create a Tizen chroot and launch a build from there, requiring no
further interaction and producing a few RPMs at the end of the process.

For more information on which other parameters one is normally expected to pass
to `gbs build' (including "-A" to specify the Tizen architecture) and also on
gbs' configuration file, please consult gbs' documentation.

A very important thing to notice is that, due to the way the integration with
gbs is implemented, _anything_ currently present in your source tree will be
built, regardless of whether "--include-all" is passed to `gbs build' or not.

INCREMENTAL BUILDS
------------------

By default, Crosswalk is built inside src/out/Release inside the Chromium's
directory. Also by default, each call to `gbs build' will erase the RPM build
root in the Tizen chroot, which means your previous build will be lost.

To avoid that, you need to specify a different build directory, one located
outside the build root. The new directory should be passed as a macro called
BUILDDIR_NAME:

  $ cd /path/to/src/xwalk
  $ gbs build -A i586 --define 'BUILDDIR_NAME /var/tmp/xwalk-build'

  (Note `/var/tmp/xwalk-build` is still a directory inside the chroot, so to
  the host system this is actually something like
  `/home/user/GBSROOT/local/BUILD-ROOTS/scratch.i586.0/var/tmp/xwalk-build`).

In case the build gets broken somehow, one can then just remove whatever is
faulty in the build directory (or the whole directory).

It is important to note that depending on what the .spec file looks like, an
incremental build may still rebuild some files even if nothing has changed: for
example, if patches are applied as part of the %prep stage and they modify some
source files, these ones will always be rebuilt.

This method is not completely fail-proof, though, and a full rebuild may end up
being triggered if:

- Some problem happens in the `gbs build' call and the whole chroot (not only
  the RPM build root) ends up being erased.

- You use `gbs chroot' to call `make' yourself, as a simple change in the
  original CFLAGS or CXXFLAGS triggers a rebuild of all files.

- You change your source directory name for some reason. This is why
  the generated source tarball does not contain a version number, for
  example.

FURTHER DETAILS
---------------

gbs, the tool used to generate RPM packages for Tizen, expects a single git
tree with all the necessary sources available so that it can run `git archive',
produce a tarball, extract it into a chroot and build from there.

Crosswalk, on the other hand, is made of many independent git and Subversion
repositories put together in a single directory structure. Additionally,
Crosswalk is checked out as a subdirectory of Chromium itself. This all is
unusual and does not work with gbs by default.

The whole problem is worked around by having using git-buildpackage's hooks
mechanism: the original tarball generated by git-buildpackage's call to `git
archive' is replaced by a new one generated with the gbp-flat-tree.sh script
located in packaging/. This new tarball contains everything in src/, except for
a few files we exclude by default (version control files and directories, for
example).

The gbp-flat-tree.sh script also helps us with incremental builds: since the
new tarball is generated with `tar' itself, all the files in the archive have
their correct mtimes (which is not the case with `git archive'). This, together
with an external build directory, allows one to avoid rebuilding all files
every time, since the source files with the right modification times _and_ the
build directory are preserved across builds.