This document contains documentation for the blimp client code organization.
For a quick guide for how to add Java files to an existing directory, see Adding Java files below.
The blimp client has two main directories to be used for code, core
and public
. Embedders should only ever have to deal with the public
directory.
There are sub-directories resembling the ones in core
for parts that needs to be exposed to embedders, such as BlimpContents
.
All Java-code is put in the public/android
directory, with a package organization that resembles the one in core
.
Within //blimp/client
, the visibility
feature of GN is heavily used to ensure that embedders and dependencies are correctly set up. Currently, the app
directory is not fully extracted out as an embedder, so it does sometime depend directly on code in core
, but that should change when the migration to core
is finished.
The core
directory is to be used for all business logic code, and is an internal concept of the client code.
There are sub-directories for logically separate parts, such as contents
for code that relate to the contents of a web page. All Android code is put into their respective directories, so Android and Java-code related to contents
is put in contents/android
.
Each of the sub-directories have their own BUILD.gn
file, which includes targets for both C++ and Java.
//blimp/client/core/
compositor/
Code related to the Chrome Compositor.contents/
Code related to the contents of a web page.contents/android/
JNI bridges and Java-code for contents
.context/
Code related to the context (BlimpClientContext
), which is the core functionality used by all embedders.context/android
JNI bridges and Java-code for context
.session/
Code related to the session with the engine.Most code in core
do not need any Java counterparts unless the embedder is written for Android and it is typically only needed for things that relate to the embedder UI.
The core
directory has two implementations of the public API, a dummy one and a real one. The default is to use the dummy API, but an embedder can choose to enable full blimp support by setting the GN arguments enable_blimp_client
to true
.
Basically only the implementation of BlimpClientContext
has been split out into two parts (both in C++ and Java), and the choice of which backing implementation to be used is selected by the enable_blimp_client
flag. These two implementations live in //blimp/client/context
.
The public
directory represents the public API of the blimp client, to be used by the embedders.
Embedders should be able to depend on //blimp/client/public
for C++ code, and for Java they should depend on //blimp/client/public:public_java
. This automatically pulls in the dependencies on the code in core
.
//blimp/client/public/
android/
All Android-related code, including Java-code. This includes also code from all the sub-directories such as contents
.contents/
Code from //blimp/client/core/contents/
that needs to be exposed to embedders.session/
Code from //blimp/client/core/session/
that needs to be exposed to embedders.The app
directory represents the directory that contains embedder code for a Blimp application on its own. Under a transition period, this directory also contains code that depends directly on core
, until everything can be updated to depend only on public
.
The feature
directory is from the old directory organization, and all the content of this will move over to the core
directory. The feature-specific code will move together with the usage of the feature itself, such as core/contents
.
The session
directory is from the old directory organization, and all the content of this will move over to the core/session
directory.
The support
directory is a directory providing help to embedders. This typically includes a default implementation of an interface from //blimp/client/public
or other helpful tools.
The test
directory contains tools helpful for testing client code.
Most of Blimp is written in C++, but some parts have to be written in Java for the Android platform. For those parts of the code, it is required to add an android
sub-directory, and put JNI-bridges and Java files within there.
This will mostly happen in a sub-directory of core
, so the following section explains how to add a Java file with JNI hooks for the imaginary sub-directory //blimp/client/core/foo
. Conceptually, it's adding a Java-version of the C++ class Foo
, that lives in //blimp/client/core/foo/foo.[cc|h]
.
The file Foo.java should be added at: //blimp/client/core/foo/android/java/src/org/chromium/blimp/core/foo/Foo.java
The JNI-bridge should live in: //blimp/client/core/foo/android/foo_android.[cc|h]
Add the JNI-bridge JNI registration to: //blimp/client/core/context/android/blimp_jni_registrar.cc
Add this to the top of //blimp/client/core/foo/BUILD.gn
:
if (is_android) { import("//build/config/android/config.gni") import("//build/config/android/rules.gni") }
Add the following targets to //blimp/client/core/foo/BUILD.gn
:
android_library("foo_java") { visibility = [ "//blimp/client/*" ] java_files = [ "android/java/src/org/chromium/blimp/core/foo/Foo.java", ] deps = [ ... ] } generate_jni("jni_headers") { visibility = [ ":*" ] sources = [ "android/java/src/org/chromium/blimp/core/foo/Foo.java", ] jni_package = "blimp/client/core/foo" }
Edit the target //blimp/client/core/foo:foo
to add this Android-part:
source_set("foo") { ... if (is_android) { sources += [ "android/foo.cc", "android/foo.h", ] deps += [ ":jni_headers" ] } }
Add //blimp/client/core/foo:foo_java
as a dependency in //blimp/client/core:core_java
.