3 [[Chromium|https://www.chromium.org/]] is a massive piece of software that includes a number of third-party programs and libraries at a specific version, probably to have a controlled environments for builds and runtime.
5 The following "channels" are supported currently, among which there is no BSD so custom patches are needed. See [[Chromium channels|https://www.chromium.org/getting-involved/dev-channel]]
7 The chromium port is called "www/chromium/" in FreeBSD ports and so it is in DPorts but, as of the time of this writing, the DPorts version is slightly different since we require changes to the FreeBSD Makefile we cannot do in our overlay (Makefile.DragonFly)
9 ## Third-party software
11 ### Compiler, linker and standard C++ library
13 Chromium uses LLVM's clang to build and lld for the linkage phase. It also uses [[libc++|https://libcxx.llvm.org/]] as standard C++ library. They use a very specific version of these tools which can be obtained with their own scripts and utilities.
15 For more information on how to build Chromium from source for other platforms see [[here|https://chromium.googlesource.com/chromium/src/+/lkcr/docs/clang.md]].
17 ### List of third-party software
19 The list of third-party software is a long one, you can check it [[here|https://cs.chromium.org/chromium/src/third_party/]].
21 ## Current update procedure
23 The outline is as follows:
25 1. Import the FreeBSD ports' specific Chromium version to a new empty branch.
26 2. Create a new branch called _'xx-freebsd'_ based on the branch created in step 1.
27 3. Import all patches from FreeBSD port _www/chromium_ to the _'xx-freebsd'_ branch and commit it one commit per file.
28 4. Create a new branch called _'xx-dfly'_ based on the branch _'xx-freebsd'_ after step 3, that is, with all patches included.
29 5. Cherry-pick the commit(s) needed from the previous 'xx-dfly' branch, resolve conflicts.
30 6. Adapt the FreeBSD port www/chromium, starting from the changes in DPorts' port _www/chromium_.
31 7. Make sure your custom _www/chromium_ builds.
32 8. Once ready, copy the files to the right place and send a PR to [[DeltaPorts|https://github.com/DragonFlyBSD/DeltaPorts/pulls]].
34 This is how we are performing the Chromium updates right now, nothing is written in stone, contributions/ideas are very welcome :-)
36 ### Repository location and contributions
38 The "DragonFly Chromium" repository is located in server **crater**, where all the source repositories are located. There is also a clone of them in server **leaf**. You can access the [[dragonfly's gitweb page|https://gitweb.dragonflybsd.org/]] to browse the code without the need of cloning it. The repository is called _chromium-dfly.git_.
40 We recommend cloning from crater just in case the mirroring on leaf fails for some reason:
43 # git clone git://crater.dragonflybsd.org/chromium-dfly.git
44 Cloning into 'chromium-dfly'...
45 remote: Counting objects: 469609, done.
46 remote: Compressing objects: 100% (254827/254827), done.
50 Only DragonFly committers can push to this repository in crater, you can specify a different url for pushing so that the SSH keys is only used for _git-push_, see below an example of _.git/config_:
54 url = git://crater.dragonflybsd.org/chromium-dfly.git
55 pushurl = ssh://crater.dragonflybsd.org/repository/git/chromium-dfly.git
56 fetch = +refs/heads/*:refs/remotes/crater/*
59 Anyone can submit patches, just go to [[our bug tracker and send an issue for the tracker "Submit"|https://bugs.dragonflybsd.org/projects/dragonfly/issues/new]] (category 'chromium').
63 Vanilla Chromium versions are imported from tarballs to branches named like "chromium-[exact-version]", see below the current ones:
66 # git branch -a | fgrep crater/chromium
67 remotes/crater/chromium-60.0.3112.113
68 remotes/crater/chromium-60.0.3112.116
69 remotes/crater/chromium-67.0.3396.87
70 remotes/crater/chromium-68.0.3440.106
72 The FreeBSD branches are named like: _[major chromium version]-freebsd_ . In case there are several Chromium branches with the same major version, then the last part of the version is used, see below the current ones:
75 # git branch -a | grep freebsd |grep crater
76 remotes/crater/60.113-freebsd
77 remotes/crater/67-freebsd
79 In the above the branch _"60.113-freebsd"_ is based on the vanilla chromium branch _"chromium-60.0.3112.113"_ . As for _"chromium-67.0.3396.87"_ there is only one chromium-67 so the FreeBSD branch is called "67-freebsd".
81 The DragonFly branches are named like: _[major chromium version]-dfly_ . In case there are several Chromium branches with the same major version the same as for FreeBSD applies. For DragonFly there might be user-specific branches. See below the current ones:
84 # git branch -a | grep dfly |grep crater
85 remotes/crater/60-dfly
86 remotes/crater/67-dfly
88 ### Importing a new Chromium version
90 Normally we would import the next Chromium version that is in FreeBSD ports. In this example we're going to use version _68.0.3440.106_. The download URL is: [[https://commondatastorage.googleapis.com/chromium-browser-official/chromium-68.0.3440.106.tar.xz|https://commondatastorage.googleapis.com/chromium-browser-official/chromium-68.0.3440.106.tar.xz]].
92 * Create a new branch based on a previous one for the import, remove all its contents and amend the commit message:
95 # git checkout -b chromium-68.0.3440.106 crater/chromium-60.0.3112.113
98 # git commit -a --amend --allow-empty -m 'Initial import chromium-68.0.3440.106'
100 * Import the tarball to your newly created branch:
102 # tar --strip-components 1 -xzf /usr/distfiles/chromium-68.0.3440.106.tar.xz
104 # git commit --amend -m 'Initial import chromium-68.0.3440.106'
106 * Push the new branch to crater (if you are a DragonFly developer) and maybe prune old branches if they are older than 4 releases:
108 # git push crater chromium-68.0.3440.106
110 ### Creating the '-freebsd' branch
112 This requires either a checkout of FreeBSD ports or at least the www/chromium directory from it. **Make sure you are working with the correct Chromium version!**
114 # fgrep PORTVERSION ~/s/freebsd-ports/www/chromium/Makefile
115 PORTVERSION= 68.0.3440.106
117 Now create a branch for FreeBSD:
120 # git checkout -b 68-freebsd crater/chromium-68.0.3440.106
122 Apply all FreeBSD patches to your new branch. Make sure all patches apply cleanly, there should be no .rej files and all .orig files should be removed. If there are any .orig files originally in the Chromium repo you can either decide to remove them or restore them:
124 # git rev-parse --abbrev-ref HEAD
126 # sh -c 'for p in ~/s/freebsd-ports/www/chromium/patch*; do patch -p0 < $p; done'
127 # find . -iname "*.rej"
128 # find . -iname "*.orig" -delete
130 Now all FreeBSD patches should be in, make sure the 'git status' command shows a sane list, that there is no files left behind, etc. Also 'git status --ignored' and 'git ls-files -mo' should have the same amount of iles:
132 # git status --ignored | less
133 # git ls-files -mo |wc -l
135 # git status --ignored --porcelain | wc -l
138 All changes should be committed with one rule: one file per commit, since it makes merges more granular and there are potentially a lot of merges to be done. Please note that the command below will take a while since the repo is quite big:
140 # sh -c 'for f in $(git ls-files -mo); do git add $f ; git commit -m "$f"; done'
143 Once you're sure all patches have been applied correctly and that the commits contain exactly one file (they should if you ran the command above) you can push the freebsd branch to crater:
145 # git push --set-upstream crater 68-freebsd
146 Enumerating objects: 4672, done.
147 Counting objects: 100% (4672/4672), done.
149 * [new branch] 68-freebsd -> 68-freebsd
150 Branch '68-freebsd' set up to track remote branch '68-freebsd' from 'crater'.
152 ### Creating the 'dfly' branch
154 Once the _'-freebsd'_ branch is created with all the FreeBSD patches for the specific Chromium version on it, you can create the _'-dfly'_ branch from it.
157 # git checkout -b 68-dfly 68-freebsd
160 ### Cherry-picking changes from the previous version
162 At this point you'll have a _'-dfly'_ branch which is exactly the same as the _'-freebsd'_ one. Next step is to cherry pick the changes from the latest working Chromium, in our case _'67-dfly'_, commit:
164 commit 317fe2dbcdc3946787ed8de610e66f2829fc4ffb (67-dfly)
165 Author: Antonio Huete Jimenez <tuxillo@quantumachine.net>
166 Date: Mon Aug 20 05:04:23 2018 -0700
168 Changes to be applied on top of 67-freebsd
172 # git cherry-pick 317fe2dbcdc3946787ed8de610e66f2829fc4ffb
174 Most likely there'll be conflicts to resolve. All of them need to be resolved before issuing a 'git cherry-pick --continue'. For now we are keeping all the changes to be applied on top of the '-freebsd' branch in one commit so there shouldn't be more commits to apply.
178 Here it is described how I have personally done the test build, you don't need to do it the same way but there are some things definitely needed.
180 The port definition for the latest Dports' Chromium version is [[here|https://github.com/DragonFlyBSD/DPorts/tree/master/www/chromium]]. The port definition for the latest FreeBDS ports' Chromium version is [[here|https://github.com/freebsd/freebsd-ports/tree/master/www/chromium]]. The preference is to always go with the FreeBSD latest changes since most of the work is done based on FreeBSD's patches but there must be things kept from the Dports port definition because they'll be DragonFly specific.
182 For example, there is a conditional around the compiler selection which allows the FreeBSD port to be build with either base clang or the port clang.
184 For the FreeBSD port it looks like:
186 .if ${OPSYS} == FreeBSD && ${OSVERSION} < 1101513
187 BUILD_DEPENDS+= clang60:devel/llvm60
190 EXTRA_PATCHES+= ${FILESDIR}/extra-patch-llvm-port
192 BUILD_DEPENDS+= ${LOCALBASE}/bin/ar:devel/binutils
193 EXTRA_PATCHES+= ${FILESDIR}/extra-patch-llvm-base
196 Since the DragonFly port is always built with DPort's clang it should look something like:
198 BUILD_DEPENDS+= ${LOCALBASE}/lib/c++/libstdc++.so:devel/libc++
199 BUILD_DEPENDS+= clang60:devel/llvm60
202 EXTRA_PATCHES+= ${FILESDIR}/extra-patch-llvm-port
204 Note that there is an extra dependency from DPorts: _devel/libc++_ , which will be used as the standard C++ library instead of the system base which is libstdc++.
206 As of now there are two important differences from the FreeBSD port:
208 Allow 'tools/gn' to be compiled and linked against libc++:
211 # GN generator bootstrapping and generating ninja files
212 cd ${WRKSRC} && ${SETENV} ${CONFIGURE_ENV} CC=${CC} CXX=${CXX} LD=${CXX} \
213 READELF=${READELF} AR=${AR} NM=${NM} CXXFLAGS="-I${LOCALBASE}/include/c++/v1" \
214 LDFLAGS="-L${LOCALBASE}/lib/c++" ${PYTHON_CMD} \
215 ./tools/gn/bootstrap/bootstrap.py ${GN_BOOTSTRAP_FLAGS}
217 Pass extra_cxxflags and extra_ldflags for Chromium to be compiled/linked against devel/libc++:
219 ## Appendix# TODO bz@ : install libwidevinecdm.so (see third_party/widevine/cdm/BUILD.gn)
221 # Run "./out/${BUILDTYPE}/gn args out/${BUILDTYPE} --list" for all variables.
222 # Some parts don't have use_system_* flag, and can be turned on/off by using
223 # replace_gn_files.py script, some parts just turned on/off for target host
224 # OS "target_os == is_bsd", like libusb, libpci.
225 GN_ARGS+= clang_use_chrome_plugins=false \
227 enable_one_click_signin=true \
228 enable_remoting=false \
229 fieldtrial_testing_like_official_build=true \
232 treat_warnings_as_errors=false \
233 use_allocator="none" \
234 use_allocator_shim=false \
236 use_bundled_fontconfig=false \
237 use_custom_libcxx=false \
238 use_gnome_keyring=false \
242 use_system_freetype=true \
243 use_system_harfbuzz=true \
244 use_system_libjpeg=true \
245 extra_cxxflags="-stdlib=libc++ -cxx-isystem ${LOCALBASE}/include/c++/v1 -I${LOCALBASE}/include" \
246 extra_ldflags="-L${LOCALBASE}/lib/c++ -L${LOCALBASE}/lib -L /usr/lib -L /lib"
249 Once the DPorts port definition, what I usually do is to copy it to: /usr/dports/www/chromiumXX (in this case XX = 68) and build from there.
251 There are two little scripts you can use to make generating the patches easier but make sure you adjust the paths. For running those scripts the current working directory must be the git repository where you are working on.
253 The patch below removes all the patch-* from the port specified and generates a patch-all file which is enough for the build:
259 rm -f /usr/dports/www/chromium68/files/patch-*
260 git diff --no-prefix crater/chromium-68.0.3440.106 . > /usr/dports/www/chromium68/files/patch-all
262 Once you've extracted chromium and kicked off the build, you'll likely find errors very early. To avoid having to extract over and over to test your patches the script below simplifies the task by detecting what files need to be changed in the chromium's OBJDIR and copies them over, so you can restart the build directly:
266 OBJDIR=/usr/obj/dports/www/chromium68/chromium-68.0.3440.106/
268 for f in $(git ls-files -m)
270 if diff -q $f $OBJDIR/$f >/dev/null; then
271 echo $f does not need repatch
277 To kick-off the build, it can be done as for any other port:
279 # cd /usr/dports/www/chromium68
280 # make | tee /tmp/build.out
282 I recommend sending the output to a log file where you can inspect it more easily.
284 Once the build finishes successfully you can check the _chrome_ binary in 'out/Release/' in the OBJDIR and see if it runs properly. If it does, please check point above *"Repository location and contributions"* on how to submit your work. Thanks!
290 The Chromium project offers a cross-reference tool which is extremely useful when working on Chromium source code: [[Chromium Search Code|https://cs.chromium.org/]]
295 You can contact me (tuxillo) and others in our mailing list (users@) or by IRC in EFnet #dragonflybsd for questions.
300 - Getting in touch with the guys behind [[this repo|https://github.com/gliaskos/freebsd-chromium]] and possibly contribute our changes to it. If done correctly we would eventually have no need to patch chromium at all.