| OLD | NEW |
| (Empty) |
| 1 # Blimp Client | |
| 2 | |
| 3 This document contains documentation for the blimp client code organization. | |
| 4 | |
| 5 For a quick guide for how to add Java files to an existing directory, see | |
| 6 [Adding Java files](#adding-java-files) below. | |
| 7 | |
| 8 [TOC] | |
| 9 | |
| 10 ## Code Organization | |
| 11 | |
| 12 The blimp client has two main directories to be used for code, `core` and | |
| 13 `public`. Embedders should only ever have to deal with the `public` directory. | |
| 14 | |
| 15 There are sub-directories resembling the ones in `core` for parts that needs to | |
| 16 be exposed to embedders, such as `BlimpContents`. | |
| 17 | |
| 18 All Java-code is put in the `public/android` directory, with a package | |
| 19 organization that resembles the one in `core`. | |
| 20 | |
| 21 Within `//blimp/client`, the `visibility` feature of GN is heavily used to | |
| 22 ensure that embedders and dependencies are correctly set up. Currently, the | |
| 23 `app` directory is not fully extracted out as an embedder, so it does sometime | |
| 24 depend directly on code in `core`, but that should change when the migration to | |
| 25 `core` is finished. | |
| 26 | |
| 27 ### The core directory | |
| 28 | |
| 29 The `core` directory is to be used for all business logic code, and is an | |
| 30 internal concept of the client code. | |
| 31 | |
| 32 There are sub-directories for logically separate parts, such as `contents` for | |
| 33 code that relate to the contents of a web page. All Android code is put into | |
| 34 their respective directories, so Android and Java-code related to `contents` | |
| 35 is put in `contents/android`. | |
| 36 | |
| 37 Each of the sub-directories have their own `BUILD.gn` file, which includes | |
| 38 targets for both C++ and Java. | |
| 39 | |
| 40 * `//blimp/client/core/` | |
| 41 * `compositor/` Code related to the Chrome Compositor. | |
| 42 * `contents/` Code related to the contents of a web page. | |
| 43 * `contents/android/` JNI bridges and Java-code for `contents`. | |
| 44 * **`context/` Code related to the context (`BlimpClientContext`), which | |
| 45 is the core functionality used by all embedders.** | |
| 46 * `context/android` JNI bridges and Java-code for `context`. | |
| 47 * `session/` Code related to the session with the engine. | |
| 48 | |
| 49 Most code in `core` do not need any Java counterparts unless the embedder is | |
| 50 written for Android and it is typically only needed for things that relate to | |
| 51 the embedder UI. | |
| 52 | |
| 53 #### Actual and dummy implementations of core | |
| 54 | |
| 55 The `core` directory has two implementations of the public API, a dummy one | |
| 56 and a real one. The default is to use the dummy API, but an embedder can choose | |
| 57 to enable full blimp support by setting the GN arguments `enable_blimp_client` | |
| 58 to `true`. | |
| 59 | |
| 60 Basically only the implementation of `BlimpClientContext` has been split out | |
| 61 into two parts (both in C++ and Java), and the choice of which backing | |
| 62 implementation to be used is selected by the `enable_blimp_client` flag. These | |
| 63 two implementations live in `//blimp/client/context`. | |
| 64 | |
| 65 ### The public directory | |
| 66 | |
| 67 The `public` directory represents the public API of the blimp client, to be | |
| 68 used by the embedders. | |
| 69 | |
| 70 Embedders should be able to depend on `//blimp/client/public` for C++ code, | |
| 71 and for Java they should depend on `//blimp/client/public:public_java`. This | |
| 72 automatically pulls in the dependencies on the code in `core`. | |
| 73 | |
| 74 * `//blimp/client/public/` | |
| 75 * `android/` All Android-related code, including Java-code. This includes | |
| 76 also code from all the sub-directories such as `contents`. | |
| 77 * `contents/` Code from `//blimp/client/core/contents/` that needs to be | |
| 78 exposed to embedders. | |
| 79 * `session/` Code from `//blimp/client/core/session/` that needs to be | |
| 80 exposed to embedders. | |
| 81 | |
| 82 ### Other directories | |
| 83 | |
| 84 #### The app directory | |
| 85 | |
| 86 The `app` directory represents the directory that contains embedder code for | |
| 87 a Blimp application on its own. Under a transition period, this directory | |
| 88 also contains code that depends directly on `core`, until everything can be | |
| 89 updated to depend only on `public`. | |
| 90 | |
| 91 #### The feature directory | |
| 92 | |
| 93 The `feature` directory is from the old directory organization, and all the | |
| 94 content of this will move over to the `core` directory. The feature-specific | |
| 95 code will move together with the usage of the feature itself, such as | |
| 96 `core/contents`. | |
| 97 | |
| 98 #### The session directory | |
| 99 | |
| 100 The `session` directory is from the old directory organization, and all the | |
| 101 content of this will move over to the `core/session` directory. | |
| 102 | |
| 103 #### The support directory | |
| 104 | |
| 105 The `support` directory is a directory providing help to embedders. This | |
| 106 typically includes a default implementation of an interface from | |
| 107 `//blimp/client/public` or other helpful tools. | |
| 108 | |
| 109 #### The test directory | |
| 110 | |
| 111 The `test` directory contains tools helpful for testing client code. | |
| 112 | |
| 113 ### Adding Java files {#adding-java-files} | |
| 114 | |
| 115 Most of Blimp is written in C++, but some parts have to be written in Java for | |
| 116 the Android platform. For those parts of the code, it is required to add an | |
| 117 `android` sub-directory, and put JNI-bridges and Java files within there. | |
| 118 | |
| 119 This will mostly happen in a sub-directory of `core`, so the following section | |
| 120 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++ | |
| 121 class `Foo`, that lives in `//blimp/client/core/foo/foo.[cc|h]`. | |
| 122 | |
| 123 * The file Foo.java should be added at: | |
| 124 `//blimp/client/core/foo/android/java/src/org/chromium/blimp/core/foo/Foo.ja
va` | |
| 125 | |
| 126 * The JNI-bridge should live in: | |
| 127 `//blimp/client/core/foo/android/foo_android.[cc|h]` | |
| 128 | |
| 129 * Add the JNI-bridge JNI registration to: | |
| 130 `//blimp/client/core/context/android/blimp_jni_registrar.cc` | |
| 131 | |
| 132 * Add this to the top of `//blimp/client/core/foo/BUILD.gn`: | |
| 133 | |
| 134 ```python | |
| 135 if (is_android) { | |
| 136 import("//build/config/android/config.gni") | |
| 137 import("//build/config/android/rules.gni") | |
| 138 } | |
| 139 ``` | |
| 140 | |
| 141 * Add the following targets to `//blimp/client/core/foo/BUILD.gn`: | |
| 142 | |
| 143 ```python | |
| 144 android_library("foo_java") { | |
| 145 visibility = [ "//blimp/client/*" ] | |
| 146 | |
| 147 java_files = [ | |
| 148 "android/java/src/org/chromium/blimp/core/foo/Foo.java", | |
| 149 ] | |
| 150 | |
| 151 deps = [ | |
| 152 ... | |
| 153 ] | |
| 154 } | |
| 155 | |
| 156 generate_jni("jni_headers") { | |
| 157 visibility = [ ":*" ] | |
| 158 | |
| 159 sources = [ | |
| 160 "android/java/src/org/chromium/blimp/core/foo/Foo.java", | |
| 161 ] | |
| 162 | |
| 163 jni_package = "blimp/client/core/foo" | |
| 164 } | |
| 165 ``` | |
| 166 | |
| 167 * Edit the target `//blimp/client/core/foo:foo` to add this Android-part: | |
| 168 | |
| 169 ```python | |
| 170 source_set("foo") { | |
| 171 | |
| 172 ... | |
| 173 | |
| 174 if (is_android) { | |
| 175 sources += [ | |
| 176 "android/foo.cc", | |
| 177 "android/foo.h", | |
| 178 ] | |
| 179 | |
| 180 deps += [ ":jni_headers" ] | |
| 181 } | |
| 182 } | |
| 183 ``` | |
| 184 | |
| 185 * Add `//blimp/client/core/foo:foo_java` as a dependency in | |
| 186 `//blimp/client/core:core_java`. | |
| OLD | NEW |