1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
|
# How to add a new dependency on Linux
For this example, imagine we want to add a dependency on the DBus client
library. Note that this dependency already exists.
Test locally and do not start committing changes until you finish [testing that
the new dependency
works](#Test-that-you-can-build-and-run-against-the-new-dependency).
## (Debian) Determine which packages are needed
### Which dev package do we need?
The DBus documentation includes examples that include the DBus header like this:
```
#include <dbus/dbus.h>
```
Searching for `dbus/dbus.h` on
[`packages.debian.org`](https://packages.debian.org/) yields only 1 result:
[`libdbus-1-dev`](https://packages.debian.org/buster/libdbus-1-dev). This is the
dev package that we need.
### Which library package do we need?
The page for the dev package shows only two dependencies: `pkg-config` and
[`libdbus-1-3`](https://packages.debian.org/buster/libdbus-1-3). The latter is
the one we want.
Now is a good time to make sure the package is available (and that the minimum
version is available) on all supported distros. The source of truth for
supported Debian-based distros is given in the `SUPPORTED_DEBIAN_RELEASES` and
`SUPPORTED_UBUNTU_RELEASES` variables in
[`//chrome/installer/linux/debian/update_dist_package_versions.py`](https://cs.chromium.org/chromium/src/chrome/installer/linux/debian/update_dist_package_versions.py).
Check on both [`packages.debian.org`](https://packages.debian.org/) and
[`packages.ubuntu.com`](https://packages.ubuntu.com/).
## (RPM) Determine which library is needed
Look at the [list of
files](https://packages.debian.org/buster/amd64/libdbus-1-dev/filelist) provided
by the Debian dev package. There should be at least one file with a `.so`
extension. In our case, this is `libdbus-1.so`: save this for later.
If the packages were available on all supported Debian-based distros, it's
highly likely they will be available on all RPM-based ones too. But if you want
to double-check, [`rpmfind.net`](https://www.rpmfind.net/) is a good resource.
The source of truth for supported RPM-based distros is given in the
`SUPPORTED_FEDORA_RELEASES` and `SUPPORTED_OPENSUSE_LEAP_RELEASES` variables in
[`//chrome/installer/linux/rpm/update_package_provides.py`](https://cs.chromium.org/chromium/src/chrome/installer/linux/rpm/update_package_provides.py).
## Add the dev and library packages to the sysroot
From the earlier section "(Debian) Determine which packages are needed", we know
that we need `libdbus-1-dev` and `libdbus-1-3`. Add these both to the
`DEBIAN_PACKAGES` list in
[`//build/linux/sysroot_scripts/sysroot-creator-sid.sh`](https://cs.chromium.org/chromium/src/build/linux/sysroot_scripts/sysroot-creator-sid.sh).
Building and uploading the sysroot images is detailed in [Linux sysroot
images](https://chromium.googlesource.com/chromium/src.git/+/master/docs/sysroot.md).
You may need to add additional dependent libraries for your new library.
## Whitelist the new dependencies
### Debian
Add the library package to the `PACKAGE_FILTER` variable in
[`//chrome/installer/linux/debian/update_dist_package_versions.py`](https://cs.chromium.org/chromium/src/chrome/installer/linux/debian/update_dist_package_versions.py)
and run the script.
### RPM
Add the library file to the `LIBRARY_FILTER` variable in
[`//chrome/installer/linux/rpm/update_package_provides.py`](https://cs.chromium.org/chromium/src/chrome/installer/linux/rpm/update_package_provides.py)
and run the script.
## Build against the package
### Using `pkg-config`
If the dev package provides a file with a `.pc` extension, it's a good idea to
set up your build config using `pkg-config`, as this will automatically pass
include dirs to the compiler, and library files to the linker.
`libdbus-1-dev` provides `dbus-1.pc`, so we can add this to our `BUILD.gn`:
```
import("//build/config/linux/pkg_config.gni")
# "dbus" is whatever you want to name the config.
pkg_config("dbus") {
# "dbus-1" is the name of the .pc file.
packages = [ "dbus-1" ]
}
component("my_awesome_component") {
deps = [ ":dbus" ]
...
}
```
See
[`//build/config/linux/pkg_config.gni`](https://cs.chromium.org/chromium/src/build/config/linux/pkg_config.gni)
for further details.
### Including the library directly
If the dev package doesn't provide a `.pc` file, you will need to add the build
flags manually:
```
config("dbus") {
# libdbus-1.so is the name of the dev library.
libs = [ "dbus-1" ]
include_dirs = [
"/usr/include/dbus-1.0",
...
]
}
```
## Test that you can build and run against the new dependency
For DBus, you might try:
```
#include <dbus/dbus.h>
void TestIt() {
DBusConnection* bus = dbus_bus_get(DBUS_BUS_SESSION, nullptr);
DCHECK(bus);
}
```
The purpose of the test is to make sure that:
1. The include path is set up properly.
2. The library can be dynamically linked at runtime.
3. The `.deb` and `.rpm` packages can build.
To test 3, make sure your `args.gn` has the following:
```
is_component_build = false # This is required.
use_sysroot = true # This is the default.
# is_*san = false # This is the default.
```
Next, build `chrome/installer/linux`. If there are dependency errors, your
package may not be available on all supported distros.
## Add packages to build deps script
Add the dev package to the `dev_list` variable in
[`//build/install-build-deps.sh`](https://cs.chromium.org/chromium/src/build/install-build-deps.sh?q=install-build-deps.sh),
and add the library package to the `common_lib_list` variable in the same file.
Note that if you are removing a package from this script, be sure to add the
removed packages to the `backwards_compatible_list` variable.
## Install packages on the bots
After adding the packages to `install-build-deps.sh`, new swarming images will
be generated and rolled out to the swarming bots. However, this can take several
days. To expedite the process, the packages can be added to the Puppet config
and rolled out immediately. To do this, add the dev package, the library
package, and the i386 version of the library package to the [Puppet config
file](https://goto.google.com/ynnzy). For DBus, this will look like:
```
# Add packages here temporarily to roll out to the fleet as needed.
all:
- libdbus-1-dev
- libdbus-1-3
- libdbus-1-3:i386
```
## Instrumented libraries
In order for `MSAN` to work, you will likely need to add your library package to
the instrumented libraries. To do this, add the library dev package to
[`third_party/instrumented_libraries/BUILD.gn`](https://cs.chromium.org/chromium/src/third_party/instrumented_libraries/BUILD.gn):
```
# This is the minimum you will need. Check other examples in this file if
# something goes wrong.
instrumented_library("libdbus-1-3") {
build_method = "debian"
}
```
Then add `:libdbus-1-3` to
`//third_party/instrumented_libraries:locally_built`'s `deps`.
See [Linux Instrumented
Libraries](https://chromium.googlesource.com/chromium/src.git/+/master/docs/instrumented_libraries.md)
for instructions on building and uploading the instrumented libraries.
|
