README.md
1OpenEmbedded/Yocto BSP layer for Chromium Browsers
2==================================================
3
4This layer provides web browser recipes for use with OpenEmbedded
5and/or Yocto.
6
7This layer depends on:
8
9* URI: git://git.openembedded.org/openembedded-core
10 - branch: master
11 - revision: HEAD
12
13* URI: git://git.openembedded.org/meta-openembedded
14 - layers: meta-oe
15 - branch: master
16 - revision: HEAD
17
18* URI: git://github.com/kraj/meta-clang
19 - branch: master
20 - revision: HEAD
21
22Contributing
23------------
24
25The preferred way to contribute to this layer is to send GitHub pull requests or
26report problems in GitHub's issue tracker.
27
28Alternatively there is the classic way of review on the OpenEmbedded dev mailing
29list openembedded-devel@lists.openembedded.org (you have to be subscribed to
30post to the list). Please cc the maintainers if you send your patches.
31
32Maintainers
33-----------
34* Fabio Berton <fabio.berton@ossystems.com.br>
35* Raphael Kubo da Costa <raphael.kubo.da.costa@intel.com>
36* Khem Raj <raj.khem@gmail.com>
37* Otavio Salvador <otavio@ossystems.com.br>
38* Maksim Sisov <msisov@igalia.com>
39
40When sending single patches, please use something like:
41```
42git send-email -1 -s --to openembedded-devel@lists.openembedded.org --subject-prefix='meta-browser][PATCH'
43```
44
45Recipes
46-------
47recipes-browser/chromium:
48Chromium browser.
49
50This recipe provides a package for the Chromium web browser. It strives to
51always follow the latest stable Linux release as listed in
52https://omahaproxy.appspot.com
53
54We refer to the web browser as Chromium, not Chrome, because "Chrome" is
55Google's version of the web browser with proprietary content on top of the
56open-source Chromium browser.
57
58Compared to a usual, smaller recipe, the Chromium recipe has a few
59peculiarities:
60- We manually patch parts of the build system to replace Chromium's bundled
61 copies of some packages (flac, libjpeg and others) with system-wide ones.
62- Parts of the V8 (Chromium's JavaScript engine) build need to run binaries
63 built for the target, for which we use QEMU.
64
65Build requirements
66------------------
67This recipe requires clang, and GCC is not supported. Upstream Chromium has not
68tested or officially supported GCC for years, so it is safer and easier to
69follow their lead and only support one compiler.
70
71As part of its build process, Chromium builds and runs some binaries on the
72host. clang-native from the meta-clang layer is used to build those binaries.
73
74For building most of the code for your target, a C++14-compliant compiler is
75required. At least clang 7.0.0 (and thus the "thud" branch) is required.
76
77Additionally, make sure the machine being used to build Chromium is powerful
78enough: a x86-64 machine with at least 16GB RAM is recommended.
79
80PACKAGECONFIG knobs
81-------------------
82* component-build: (off by default)
83 Enables component build mode. By default, all of Chromium (with the exception
84 of FFmpeg) is linked into one big binary. The linker step requires at least 8
85 GB RAM. Component mode was created to facilitate development and testing,
86 since with it, there is not one big binary; instead, each component is linked
87 to a separate shared object. Use component mode for development, testing, and
88 in case the build machine is not a 64-bit one, or has less than 8 GB RAM.
89
90* cups: (off by default)
91 Enables CUPS support in Chromium, and adds a dependency on the "cups" recipe.
92
93* custom-libcxx (off by default)
94 Enable vendored version of C++ runtime ( libc++ ) instead of using this from
95 meta-clang provided libc++, this could be useful in some cases, where the
96 binary is to be run on foreign systems which are not built using OE/Yocto
97 base
98
99* gtk4: (off by default)
100 Enables GTK4 runtime support in Chromium by adding --gtk-version=4
101 to the command line. Chromium is still built against GTK3.
102
103* kiosk-mode: (off by default)
104 Enable this option if you want your browser to start up full-screen, without
105 any menu bars, without any clutter, and without any initial start-up
106 indicators.
107
108* proprietary-codecs: (off by default)
109 Enable this option if you want to add support for additional proprietary
110 codecs, most notably MPEG standards (h.264, h.265, MP4, MP3, AAC etc). It is
111 your responsibility to make sure you are complying with the codecs' licensing
112 terms.
113
114* use-egl: (on by default)
115 Without this packageconfig, the Chromium build will use GLX for creating an
116 OpenGL context in X11, and regular OpenGL for painting operations. Neither
117 are desirable on embedded platforms. With this packageconfig, EGL and OpenGL
118 ES 2.x are used instead.
119
120* use-vaapi: (off by default)
121 Enables VA-API support with that allows hardware accelerated media playback on
122 GPUs that support VA-API. If h.264 codec is required, proprietary-codecs must
123 also be enabled. Please note that not all the possible hardware configs are
124 tested and supported.
125
126* upower: (on by default)
127 Chromium expects the presence of `org.freedesktop.UPower` via D-Bus to
128 query battery status. If disabled, there will be warning messages seen on
129 stderr and Battery Status Web API will not work.
130
131Google API keys
132---------------
133Some Chromium features use Google APIs, and to access those APIs either an API
134Key or a set of OAuth 2.0 tokens is required. Setting up API keys is optional.
135
136If you don't do it, the specific APIs using Google services won't work in your
137build, but all other features will run normally.
138
139By default, we build Chromium with invalid keys to avoid the "Google API keys
140are missing" error message in the browser's infobar. If you have your own API
141keys, you need to set the GOOGLE_API_KEY, GOOGLE_DEFAULT_CLIENT_ID and
142GOOGLE_DEFAULT_CLIENT_SECRET appropriately in your local.conf.
143
144For more information, see https://dev.chromium.org/developers/how-tos/api-keys.
145