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 |