tree: e3217e640b98bcf1e2afd3d6faacb566191af340 [path history] [tgz]
  1. BUILD.gn
  2. DEPS
  3. README.md
  4. app/
  5. core/
  6. public/
  7. support/
  8. test/
blimp/client/README.md

Blimp Client

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.

Code Organization

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

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.

Actual and dummy implementations of core

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

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.

Other directories

The app directory

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

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

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

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

The test directory contains tools helpful for testing client code.

Adding Java files

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.