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 * `android/` All Android-related code, including Java-code, that are for |
| 42 the code living directly in `//blimp/client/core`. |
| 43 * `compositor/` Code related to the Chrome Compositor. |
| 44 * `contents/` Code related to the contents of a web page. |
| 45 * `contents/android/` JNI bridges and Java-code for `contents`. |
| 46 * `session/` Code related to the session with the engine. |
| 47 |
| 48 Most code in `core` do not need any Java counterparts unless the embedder is |
| 49 written for Android and it is typically only needed for things that relate to |
| 50 the embedder UI. |
| 51 |
| 52 #### Actual and dummy implementations of core |
| 53 |
| 54 The `core` directory has two implementations of the public API, a dummy one |
| 55 and a real one. The default is to use the dummy API, but an embedder can choose |
| 56 to enable full blimp support by setting the GN arguments `enable_blimp_client` |
| 57 to `true`. |
| 58 |
| 59 Basically only the implementation of BlimpClientContext has been split out into |
| 60 two parts (both in C++ and Java), and the choice of which backing implementation |
| 61 to be used is selected by the `enable_blimp_client` flag. |
| 62 |
| 63 ### The public directory |
| 64 |
| 65 The `public` directory represents the public API of the blimp client, to be |
| 66 used by the embedders. |
| 67 |
| 68 Embedders should be able to depend on `//blimp/client/public` for C++ code, |
| 69 and for Java they should depend on `//blimp/client/public:public_java`. This |
| 70 automatically pulls in the dependencies on the code in `core`. |
| 71 |
| 72 * `//blimp/client/public/` |
| 73 * `android/` All Android-related code, including Java-code. This includes |
| 74 also code from all the sub-directories such as `contents`. |
| 75 * `contents/` Code from `//blimp/client/core/contents/` that needs to be |
| 76 exposed to embedders. |
| 77 * `session/` Code from `//blimp/client/core/session/` that needs to be |
| 78 exposed to embedders. |
| 79 |
| 80 ### Other directories |
| 81 |
| 82 #### The app directory |
| 83 |
| 84 The `app` directory represents the directory that contains embedder code for |
| 85 a Blimp application on its own. Under a transition period, this directory |
| 86 also contains code that depends directly on `core`, until everything can be |
| 87 updated to depend only on `public`. |
| 88 |
| 89 #### The feature directory |
| 90 |
| 91 The `feature` directory is from the old directory organization, and all the |
| 92 content of this will move over to the `core` directory. The feature-specific |
| 93 code will move together with the usage of the feature itself, such as |
| 94 `core/contents`. |
| 95 |
| 96 #### The session directory |
| 97 |
| 98 The `session` directory is from the old directory organization, and all the |
| 99 content of this will move over to the `core/session` directory. |
| 100 |
| 101 #### The test directory |
| 102 |
| 103 The `test` directory contains tools helpful for testing client code. |
| 104 |
| 105 ### Adding Java files {#adding-java-files} |
| 106 |
| 107 Most of Blimp is written in C++, but some parts have to be written in Java for |
| 108 the Android platform. For those parts of the code, it is required to add an |
| 109 `android` sub-directory, and put JNI-bridges and Java files within there. |
| 110 |
| 111 This will mostly happen in a sub-directory of `core`, so the following section |
| 112 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++ |
| 113 class `Foo`, that lives in `//blimp/client/core/foo/foo.[cc|h]`. |
| 114 |
| 115 * The file Foo.java should be added at: |
| 116 `//blimp/client/core/foo/android/java/src/org/chromium/blimp/core/foo/Foo.ja
va` |
| 117 |
| 118 * The JNI-bridge should live in: |
| 119 `//blimp/client/core/foo/android/foo_android.[cc|h]` |
| 120 |
| 121 * Add the JNI-bridge JNI registration to: |
| 122 `//blimp/client/core/android/blimp_jni_registrar.cc` |
| 123 |
| 124 * Add this to the top of `//blimp/client/core/foo/BUILD.gn`: |
| 125 |
| 126 ```python |
| 127 if (is_android) { |
| 128 import("//build/config/android/config.gni") |
| 129 import("//build/config/android/rules.gni") |
| 130 } |
| 131 ``` |
| 132 |
| 133 * Add the following targets to `//blimp/client/core/foo/BUILD.gn`: |
| 134 |
| 135 ```python |
| 136 android_library("foo_java") { |
| 137 visibility = [ "//blimp/client/*" ] |
| 138 |
| 139 java_files = [ |
| 140 "android/java/src/org/chromium/blimp/core/foo/Foo.java", |
| 141 ] |
| 142 |
| 143 deps = [ |
| 144 ... |
| 145 ] |
| 146 } |
| 147 |
| 148 generate_jni("jni_headers") { |
| 149 visibility = [ ":*" ] |
| 150 |
| 151 sources = [ |
| 152 "android/java/src/org/chromium/blimp/core/foo/Foo.java", |
| 153 ] |
| 154 |
| 155 jni_package = "blimp/client/core/contents" |
| 156 } |
| 157 ``` |
| 158 |
| 159 * Edit the target `//blimp/client/core/foo:foo` to add this Android-part: |
| 160 |
| 161 ```python |
| 162 source_set("foo") { |
| 163 |
| 164 ... |
| 165 |
| 166 if (is_android) { |
| 167 sources += [ |
| 168 "android/foo.cc", |
| 169 "android/foo.h", |
| 170 ] |
| 171 |
| 172 deps += [ ":jni_headers" ] |
| 173 } |
| 174 } |
| 175 ``` |
OLD | NEW |