forked from chromium/chromium
-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
This will replace this page: https://www.chromium.org/developers/how-tos/component-build This patch also removes some out-of-date GYP references from a few other places (but not all of them). Review-Url: https://codereview.chromium.org/2206383002 Cr-Commit-Position: refs/heads/master@{#409607}
- Loading branch information
brettw
authored and
Commit bot
committed
Aug 3, 2016
1 parent
1aca73d
commit dbb91a1
Showing
4 changed files
with
267 additions
and
64 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,249 @@ | ||
| # The Chrome Component Build | ||
|
|
||
| ## Introduction | ||
|
|
||
| Release builds are “static” builds which compile to one executable and | ||
| zero-to-two shared libraries (depending on the platform). This is efficient at | ||
| runtime, but can take a long time to link because so much code goes into a | ||
| single binary. When you set the GN build variable | ||
|
|
||
| ```python | ||
| is_component_build = true | ||
| ``` | ||
|
|
||
| the build will generate many smaller shared libraries. This speeds up link | ||
| times, and means that many changes only require that the local shared library | ||
| be linked rather than the full executable, but at the expense of program | ||
| load-time performance. | ||
|
|
||
| ### How to make a component | ||
|
|
||
| Defining a component just means using the GN “component” template instead | ||
| of a shared library, static library, or source set. The template will | ||
| generate a shared library when `is_component_build` is enabled, and a static | ||
| library otherwise. | ||
|
|
||
| ```python | ||
| component("browser") { | ||
| output_name = "chrome_browser" | ||
| sources = ... | ||
| ... | ||
| } | ||
| ``` | ||
|
|
||
| Shared libraries in GN must have globally unique output names. According to GN | ||
| style, your target should be named something simple and convenient (often | ||
| matching your directory name). If this is non-unique, override it with the | ||
| output_name variable. | ||
|
|
||
| ### Dependencies between targets | ||
|
|
||
| When a component directly or indirectly depends on a static library or source | ||
| set, it will be linked into this component. If other components do the same, | ||
| the static library or source set’s code will be duplicated. | ||
|
|
||
| In a few cases (for defining some constants) this duplication is OK, but in | ||
| general this is a bad idea. Globals and singletons will get duplicated which | ||
| will wreak havoc. Therefore, you should normally ensure that components only | ||
| depend on other components. | ||
|
|
||
| ### Component granularity | ||
|
|
||
| Creating lots of small components isn’t desirable. Some code can easily get | ||
| duplicated, it takes extra time to create the shared libraries themselves, load | ||
| time will get worse, and the build and code can get complicated. On the other | ||
| extreme, very large components negate the benefits of the component build. A | ||
| good rule of thumb is that components should be medium sized, somewhere in the | ||
| range of several dozen to several hundred files. | ||
|
|
||
| ## Exporting and importing symbols | ||
|
|
||
| When a shared library or executable uses a symbol from a shared library, it is | ||
| “imported” by the user of the symbol, and “exported” from the shared library | ||
| that defines the symbol. Don’t confuse exported symbols with the public API of | ||
| a component. For example, unit tests will often require implementation details | ||
| to be exported. Export symbols to make the build link the way you need it, and | ||
| use GN’s public headers and visibility restrictions to define your public API. | ||
|
|
||
| ### Chrome’s pattern for exports | ||
|
|
||
| Write a header with the name <component_name>_export.h. Copy an [existing | ||
| one](https://cs.chromium.org/chromium/src/ipc/ipc_export.h) | ||
| and update the macro names. It will key off of two macros: | ||
|
|
||
| * `COMPONENT_BUILD`: A globally defined preprocessor definition set when the | ||
| component build is on. | ||
| * `<component_name>_IMPLEMENTATION`: A macro you define for code inside your | ||
| component, and leave undefined for code outside of your component. The | ||
| naming should match your `*_export.h` header. | ||
|
|
||
| It will define a macro `<component_name>_EXPORT`. This will use the | ||
| `*_IMPLEMENTATION` macro to know whether code is being compiled inside or outside | ||
| of your component, and the `*_EXPORT` macro will set it to being exported or | ||
| imported, respectively. You should copy an existing file and update the | ||
| `*_EXPORT` macro naming for your component. | ||
|
|
||
| When defining the target for your component, set: | ||
|
|
||
| ```python | ||
| defines = [ "FOO_IMPLEMENTATION" ] | ||
| ``` | ||
|
|
||
| In your BUILD.gn file. If you have source sets that also make up your | ||
| component, set this on them also. A good way to share this is to put the | ||
| definition in a GN config: | ||
|
|
||
| ```python | ||
| config("foo_implementation") { | ||
| defines = [ "FOO_IMPLEMENTATION" ] | ||
| } | ||
| ``` | ||
|
|
||
| and set the config on the targets that use it: | ||
|
|
||
| ```python | ||
| configs += [ ":foo_implementation" ] | ||
| ``` | ||
|
|
||
| The component build is only reason to use the `*_IMPLEMENTATION` macros. If | ||
| your code is not being compiled into a component, don’t define such a macro | ||
| (sometimes people do this by copying other targets without understanding). | ||
|
|
||
| ### Marking symbols for export | ||
|
|
||
| Use the `*_EXPORT` macros on function and class declarations (don’t annotate | ||
| the implementations) as follows: | ||
|
|
||
| ```c++ | ||
| #include "yourcomponent/yourcomponent_export.h" | ||
|
|
||
| class YOURCOMPONENT_EXPORT YourClass { ... }; | ||
|
|
||
| YOURCOMPONENT_EXPORT void SomeFunction(); | ||
| ``` | ||
|
|
||
| Sometimes you have an internal helper class used as the base for an exported | ||
| class. Visual C++ will complain if the base class is not exported: | ||
|
|
||
| warning C4275: non dll-interface class 'YourClass' used as base for dll-interface class 'Base' | ||
|
|
||
| If you don’t use the base class outside of the component, Chrome supplies the NON_EXPORTED_BASE macro in base/compiler_specific.h to disable the warning. For example: | ||
|
|
||
| ```c++ | ||
| class YourClass : public NON_EXPORTED_BASE(Base) { ... }; | ||
| ``` | ||
|
|
||
| ## Creating components from multiple targets | ||
|
|
||
| ### Static library symbol export issues | ||
|
|
||
| Components can be made up of static libraries and GN source sets. A source set | ||
| results in all object files from that compilation being linked into the | ||
| component. But when code is in a static library, only those object files needed | ||
| to define undefined symbols will be pulled in to the link. If an object file is | ||
| not needed to link the component itself, it won’t be pulled into the link, even | ||
| though it might have exported symbols needed by other components. | ||
|
|
||
| Therefore, all code with exported symbols should be either on the component | ||
| target itself or in source sets it depends on. | ||
|
|
||
| ### Splitting targets differently in static and component builds | ||
|
|
||
| Sometimes you might have something consisting of multiple sub-targets. For | ||
| example: a browser, a renderer, and a common directory, each with their own | ||
| target. In the static build, they would all be linked into different places. In | ||
| the component build, you may want to have these be in a single component for | ||
| performance and sanity reasons. Content is such an example. | ||
|
|
||
| The important thing is that the sub-projects not be depended on directly from | ||
| outside of the component in the component build. This will duplicate the code | ||
| and the import/export of symbols will get confused (see “Common mistakes” | ||
| below). | ||
|
|
||
| Generally the way to do this is to create browser and renderer group targets | ||
| that forward to the right place. In static builds these would forward to | ||
| internal targets with the actual code in them. In component builds, these would | ||
| forward to the component. | ||
|
|
||
| In the static build the structure will be: `//external/thing` ➜ `//foo:browser` | ||
| ➜ `//foo:browser_impl` | ||
|
|
||
| In the component build the structure will be: `//external/thing` ➜ | ||
| `//foo:browser` ➜ `//foo:mycomponent` ➜ `//foo:browser_impl` | ||
|
|
||
| Set GN visibility so that the targets with the code can only be depended on by | ||
| targets inside your component. | ||
|
|
||
| ```python | ||
| if (is_component_build) { | ||
| component("mycomponent") { | ||
| public_deps = [ ":browser_impl", ":renderer_impl" ] | ||
| } | ||
| } | ||
|
|
||
| # External targets always depend on this or the equivalent “renderer” target. | ||
| group("browser") { | ||
| if (is_component_build) { | ||
| public_deps = [ ":mycomponent" ] | ||
| } else { | ||
| public_deps = [ ":browser_impl" ] | ||
| } | ||
| } | ||
|
|
||
| source_set("browser_impl") { | ||
| visibility = [ ":*" ] # Prevent accidental dependencies. | ||
| defines = [ "MYCOMPONENT_IMPLEMENTATION" ] | ||
| sources = [ ... ] | ||
| } | ||
| ``` | ||
|
|
||
| ## Common mistakes | ||
|
|
||
| ### Forgetting to mark a symbol with `*_EXPORT` | ||
|
|
||
| If a function is not marked with your `*_EXPORT` annotation, other components | ||
| won’t see the symbol when linking and you’ll get undefined symbols during | ||
| linking: | ||
|
|
||
| some_file.obj : error LNK2001: unresolved external symbol <some definition> | ||
|
|
||
| This will only happen on Windows component builds, which makes the error more | ||
| difficult to debug. However, if you see such an error only for Windows | ||
| component builds, you know it’s this problem. | ||
|
|
||
| ### Not defining `*_IMPLEMENTATION` for code in your component | ||
|
|
||
| When code is compiled that sees a symbol marked with `__declspec(dllimport)`, | ||
| it will expect to find that symbol in another shared library. If that symbol | ||
| ends up in the same shared library, you’ll see the error: | ||
|
|
||
| some_file.obj : warning LNK4217: locally defined symbol | ||
| <horrendous mangled name> imported in function <some definition> | ||
|
|
||
| The solution is to make sure your `*_IMPLEMENTATION` define is set consistently | ||
| for all code in the component. If your component links in source sets or static | ||
| libraries, the `*_IMPLEMENTATION` macro must be set on those as well. | ||
|
|
||
| ### Defining `*_IMPLEMENTATION` for code outside your component | ||
|
|
||
| If your `*_IMPLEMENTATION` macro is set for code compiled outside of the | ||
| component, that code will expect the symbol to be in the current shared | ||
| library, but it won’t be found. It won’t even go looking in other libraries and | ||
| the result will be an undefined symbol: | ||
|
|
||
| some_file.obj : error LNK2001: unresolved external symbol <some definition> | ||
|
|
||
| ### Depending on a source set or static library from both inside and outside a component | ||
|
|
||
| If the source set or static library has any `*_EXPORT` macros and ends up both | ||
| inside and outside of the component boundary, those symbols will fall under the | ||
| cases above where `_IMPLEMENTATION` is inappropriately defined or inappropriately | ||
| undefined. Use GN visibility to make sure callers don’t screw up. | ||
|
|
||
| ### Putting exported symbols in static libraries | ||
|
|
||
| As discussed above, exported symbols should not be in static libraries because | ||
| the object file might not be brought into the link. Even if it is brought in | ||
| today, it might not be brought in due to completely unrelated changes in the | ||
| future. The result will be undefined symbol errors from other components. Use | ||
| source sets if your component is made up of more than one target. |
Oops, something went wrong.