src/ozone/README.md

   1 # Introduction
   2
   3 Ozone-Wayland is the implementation of Chromium's Ozone for supporting [Wayland](http://wayland.freedesktop.org/) graphics system. Different projects based on Chromium/Blink like the Chrome Browser, Chrome OS, [Crosswalk](https://crosswalk-project.org/), 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 ## Design
  16
  17 Ozone-Wayland [architecture](https://docs.google.com/document/d/118Cmq_dedHOr4jfyVeE4jBhV7hXzhnaVCqegNMGano0/) can be found here.
  18
  19 ## Howto
  20
  21 We use Ubuntu 12.04 LTS (Precise Pangolin), 32/64-bit but a kernel from Raring though. One can install it pretty easily just
  22 `sudo apt-get install linux-generic-lts-raring`. This version is needed for using Mesa master 9.3.0-devel, a requirement for Weston. Besides, make sure you have **at least** 25 GB of disk space to store all the sources and a few targets to be compiled (with debugging symbols).
  23
  24 Firstly you'd need to set up the Wayland libraries (version >= 1.4.0), 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:
  25
  26 http://wayland.freedesktop.org/building.html
  27
  28 _Please note that at the moment support for Wayland's XDG Shell protocol only works with the 1.5 series._
  29
  30 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.
  31
  32 Then you'd need some distribution tools and development packages :
  33
  34   ```
  35   $ sudo apt-get install gperf libnss3-dev libpulse-dev libdbus-1-dev libexif-dev libpci-dev libpango1.0-dev libelf-dev libcap-dev libasound2-dev libssl-dev libcups2-dev libgconf2-dev libgnome-keyring-dev
  36   ```
  37
  38 If you are running a 64-bit Ubuntu distribution, you'd additionally need :
  39
  40   ```
  41   $ sudo apt-get install ia32-libs
  42   ```
  43
  44 Then on Chromium's side, we need to setup Chromium's tree together with the
  45 Ozone-Wayland implementation. For that you need to use gclient to clone
  46 Ozone-Wayland; but first you need to download
  47 [depot\_tools](http://dev.chromium.org/developers/how-tos/install-depot-tools)
  48 and configure it. Say your Chromium top-level will be in `~git/chromium`, you will
  49 need:
  50
  51   ```
  52   $ mkdir -p ~git/chromium
  53   $ cd ~git/chromium
  54   $ git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
  55   $ export PATH=`pwd`/depot_tools:"$PATH"
  56   ```
  57
  58 We support HWA Video Decoding using Libva and VAAPI. To enable the support one needs to build
  59 and install these packages. Note: This is still work in progress. You can skip these dependencies if
  60 you don’t need this support.
  61
  62 One needs to set the installation prefix $WLD(Below)  to be same as the one used for setting up Wayland environment.
  63   ```
  64   $ git clone git://anongit.freedesktop.org/libva
  65   $ cd libva/
  66   $ git checkout libva-1.2.1
  67   $ ./autogen.sh --prefix=$WLD
  68   $ make -j4 && make install
  69   ```
  70   ```
  71   $ git clone git://anongit.freedesktop.org/vaapi/intel-driver
  72   $ cd intel-driver/
  73   $ git checkout 1.2.1
  74   $ ./autogen.sh --prefix=$WLD
  75   $ make -j4 && make install
  76   ```
  77 now we can clone Ozone-Wayland and fetch all the dependencies of it, including Chromium itself:
  78
  79   ```
  80   $ gclient config ssh://git@github.com/01org/ozone-wayland.git --name=src/ozone --deps-file ".DEPS.git"
  81   $ export GYP_DEFINES='use_ash=1 use_aura=1 chromeos=0 use_ozone=1'
  82   ```
  83   If you want to enable HWA Video Decoding, you need to have the following GYP_DEFINES:
  84   ```
  85    $ export GYP_DEFINES='use_ash=1 use_aura=1 chromeos=0 use_ozone=1 proprietary_codecs=1 ffmpeg_branding=Chrome'
  86    ```
  87   ```
  88    $ gclient sync
  89    ```
  90 It may take a considerable time for downloading the trees. If everything went
  91 fine, now we're able to build.
  92
  93 For now, also apply some patches:
  94
  95   ```
  96   ./src/ozone/patches/patch-chromium.sh
  97   ```
  98
  99 TIP: to speed up debug builds you can disable Blink debugging symbols by setting remove_webcore_debug_symbols=1 in GYP_DEFINES.
 100
 101 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.
 102
 103 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.
 104
 105 Now we can conclude compiling a few targets like Content Shell (content_shell) or the Chromium browser:
 106
 107   ```
 108   $ cd src/
 109   $ ./build/gyp_chromium
 110   $ ninja -C out/Debug -j16 chrome
 111   ```
 112 (if you get any build errors, please execute "git log" and verify that the first "commit" line matches the "chromium_rev" one found in `src/ozone/.DEPS.git`. If it doesn't, run "git checkout $ID", apply the patches and compile again)
 113
 114 That's all. At this point you should be able to connect Chromium on Weston using:
 115
 116   ```
 117   $ ~/git/weston/src/weston &
 118   $ ./out/Debug/chrome --no-sandbox
 119   ```
 120 ###Sandboxing
 121 If you want to enable Sandboxing provided by Chromium, please follow the instructions from here:
 122 https://code.google.com/p/chromium/wiki/LinuxSUIDSandbox
 123
 124 ###Working with Ozone-Wayland Release branch:
 125
 126 Instructions can be found here: https://github.com/01org/ozone-wayland/wiki/Releasing#wiki-releasebranch
 127
 128 ## Gardening
 129
 130 We pin chromium to a particular revision in order to keep upstream changes from
 131 breaking our build. Updating that revision to a newer one and fixing any
 132 resulting breakage is called gardening. To sync a different version of chromium,
 133 update chromium_rev in .DEPS.git to a newer revision then run the gclient sync
 134 again. Fix any build errors, and commit both changes.
 135
 136 ## Contributing
 137
 138 Instructions can be found here: https://github.com/otcshare/ozone-wayland/wiki
 139
 140 ## License
 141
 142 Ozone-Wayland's code uses the BSD license (check the LICENSE file in the project).