src/ozone/README.md

   1 # Introduction
   2
   3 Ozone-Wayland is the implementation of Chromium's Ozone for supporting Wayland graphics system. Different projects based on Chromium/Blink like the Chrome browser, ChromeOS, among others can be enabled now using Wayland.
   4
   5 ![Alt text](https://raw.github.com/tiagovignatti/misc/master/chromium-2013-06-07-small.png "Content Shell running on Weston")
   6
   7 ## Contents
   8
   9   - [Design](#design) - the architecture behind
  10   - [Howto](#howto) - set up the system environment, build and run
  11   - [Gardening](#gardening) - updating to the latest Chromium codebase
  12   - [Contributing](#contributing) - help develop and send patches
  13   - [License](#license)
  14
  15
  16 ## Design
  17
  18 Ozone is a set of classes in Chromium for abstracting different window systems on Linux. It provides abstraction for the construction of accelerated surfaces underlying Aura UI framework, input devices assignment and event handling.
  19
  20 http://www.chromium.org/developers/design-documents/ozone
  21
  22 Before when using Aura on Linux, all the native windowing system code (X11) was spread throughout Chromium tree. Now the idea is that Ozone will abstract the native code and because it's a set of class factories, it will switch for whoever is the window system. The biggest advantage of this API is that it allows to implement the needed window system bits externally from the Chromium tree, which is great because it is where the loaded work situates.
  23
  24 Worth to mention also that when Aura is used, there's no need for graphics toolkits, such as GTK+, EFL etc.
  25
  26 ## Howto
  27
  28 We use Ubuntu 12.04 LTS (Precise Pangolin), 32/64-bit but a kernel from Raring though. One can install it pretty easily just
  29 `sudo apt-get install linux-generic-lts-raring`. This version is needed for using Mesa master 9.3.0-devel, a requirement for Weston.
  30
  31 Firstly you'd need to set up the Wayland libraries (version >= 1.2.9), and the Weston reference compositor that you will be running Chromium onto. The information on Wayland's web page should be enough for doing so:
  32
  33 http://wayland.freedesktop.org/building.html
  34
  35 Make sure everything is alright now, setting up the environment variable `$XDG_RUNTIME_DIR` and playing a bit with the Wayland clients, connecting them on Weston.
  36
  37 Then on Chromium's side, we need to setup Chromium's tree together with the
  38 Ozone-Wayland implementation. For that you need to use gclient to clone
  39 Ozone-Wayland; but first you need to download
  40 [depot\_tools](http://dev.chromium.org/developers/how-tos/install-depot-tools)
  41 and configure it. Say your Chromium top-level will be in `~git/chromium`, you will
  42 need:
  43
  44   ```
  45   $ mkdir -p ~git/chromium
  46   $ cd ~git/chromium
  47   $ git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
  48   $ export PATH=`pwd`/depot_tools:"$PATH"
  49   ```
  50
  51 now we can clone Ozone-Wayland and fetch all the dependencies of it, including Chromium itself:
  52
  53   ```
  54   $ gclient config ssh://git@github.com/01org/ozone-wayland.git --name=src/ozone --git-deps
  55   $ GYP_DEFINES='use_ash=0 use_aura=1 chromeos=0 use_ozone=1' gclient sync
  56   ```
  57
  58 It may take a considerable time for downloading the trees. If everything went
  59 fine, now we're able to build.
  60
  61 For now, also apply some patches:
  62
  63   ```
  64   ./src/ozone/patches/patch-chromium.sh
  65   ```
  66
  67 TIP: to speed up debug builds you can disable Blink debugging symbols by setting remove_webcore_debug_symbols=1 in GYP_DEFINES.
  68
  69 Note that in Chromium, gyp uses pkg-config for checking where are Wayland libraries on the system, so double check that you are not mixing some that was already there with latest that you just got and compiled from git.
  70
  71 TIP: if you followed Wayland's web page instructions, then you probably want to set the `PKG_CONFIG_PATH` variable as `$HOME/install` and add it in your .bashrc to be as default.
  72
  73 Now we can conclude compiling a few targets like Content Shell (content_shell) or the Chromium browser:
  74
  75   ```
  76   $ cd src/
  77   $ ninja -C out/Debug -j16 chrome
  78   ```
  79 That's all. At this point you should be able to connect Chromium on Weston using:
  80
  81   ```
  82   $ ~/git/weston/src/weston &
  83   $ ./out/Debug/chrome --no-sandbox
  84   ```
  85
  86 ## Gardening
  87
  88 We pin chromium to a particular revision in order to keep upstream changes from
  89 breaking our build. Updating that revision to a newer one and fixing any
  90 resulting breakage is called gardening. To sync a different version of chromium,
  91 update chromium_rev in .DEPS.git to a newer revision then run the gclient sync
  92 again. Fix any build errors, and commit both changes.
  93
  94 ## Contributing
  95
  96 Instructions can be found here: https://github.com/otcshare/ozone-wayland/wiki
  97
  98 ## License
  99
 100 Ozone-Wayland's code uses the BSD license (check the LICENSE file in the project).