packaging/README

   1 This directory contains a collection of tools and RPM-related files used to
   2 build Crosswalk RPMs for Tizen.
   3
   4 BUILD INSTRUCTIONS
   5 ------------------
   6
   7 In the simplest case, a call to `gbs build' from the xwalk/ directory suffices.
   8 It should create a Tizen chroot and launch a build from there, requiring no
   9 further interaction and producing a few RPMs at the end of the process.
  10
  11 For more information on which other parameters one is normally expected to pass
  12 to `gbs build' (including "-A" to specify the Tizen architecture) and also on
  13 gbs' configuration file, please consult gbs' documentation.
  14
  15 A very important thing to notice is that, due to the way the integration with
  16 gbs is implemented, _anything_ currently present in your source tree will be
  17 built, regardless of whether "--include-all" is passed to `gbs build' or not.
  18
  19 INCREMENTAL BUILDS
  20 ------------------
  21
  22 By default, Crosswalk is built inside src/out/Release inside the Chromium's
  23 directory. Also by default, each call to `gbs build' will erase the RPM build
  24 root in the Tizen chroot, which means your previous build will be lost.
  25
  26 To avoid that, you need to specify a different build directory, one located
  27 outside the build root. The new directory should be passed as a macro called
  28 BUILDDIR_NAME:
  29
  30   $ cd /path/to/src/xwalk
  31   $ gbs build -A i586 --define 'BUILDDIR_NAME /var/tmp/xwalk-build'
  32
  33   (Note `/var/tmp/xwalk-build` is still a directory inside the chroot, so to
  34   the host system this is actually something like
  35   `/home/user/GBSROOT/local/BUILD-ROOTS/scratch.i586.0/var/tmp/xwalk-build`).
  36
  37 In case the build gets broken somehow, one can then just remove whatever is
  38 faulty in the build directory (or the whole directory).
  39
  40 It is important to note that depending on what the .spec file looks like, an
  41 incremental build may still rebuild some files even if nothing has changed: for
  42 example, if patches are applied as part of the %prep stage and they modify some
  43 source files, these ones will always be rebuilt.
  44
  45 This method is not completely fail-proof, though, and a full rebuild may end up
  46 being triggered if:
  47
  48 - Some problem happens in the `gbs build' call and the whole chroot (not only
  49   the RPM build root) ends up being erased.
  50
  51 - You use `gbs chroot' to call `make' yourself, as a simple change in the
  52   original CFLAGS or CXXFLAGS triggers a rebuild of all files.
  53
  54 - You change your source directory name for some reason. This is why
  55   the generated source tarball does not contain a version number, for
  56   example.
  57
  58 FURTHER DETAILS
  59 ---------------
  60
  61 gbs, the tool used to generate RPM packages for Tizen, expects a single git
  62 tree with all the necessary sources available so that it can run `git archive',
  63 produce a tarball, extract it into a chroot and build from there.
  64
  65 Crosswalk, on the other hand, is made of many independent git and Subversion
  66 repositories put together in a single directory structure. Additionally,
  67 Crosswalk is checked out as a subdirectory of Chromium itself. This all is
  68 unusual and does not work with gbs by default.
  69
  70 The whole problem is worked around by having using git-buildpackage's hooks
  71 mechanism: the original tarball generated by git-buildpackage's call to `git
  72 archive' is replaced by a new one generated with the gbp-flat-tree.sh script
  73 located in packaging/. This new tarball contains everything in src/, except for
  74 a few files we exclude by default (version control files and directories, for
  75 example).
  76
  77 The gbp-flat-tree.sh script also helps us with incremental builds: since the
  78 new tarball is generated with `tar' itself, all the files in the archive have
  79 their correct mtimes (which is not the case with `git archive'). This, together
  80 with an external build directory, allows one to avoid rebuilding all files
  81 every time, since the source files with the right modification times _and_ the
  82 build directory are preserved across builds.