docs/howtos/HowToUpdateChromium/index.mdwn

   1 **NOTE: This page is work in progress**
   2
   3 ## Introduction
   4
   5 [[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.
   6
   7 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]]
   8
   9 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)
  10
  11 ## Third-party software
  12
  13 ### Compiler, linker and standard C++ library
  14
  15 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.
  16
  17 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]].
  18
  19 ### List of third-party software
  20
  21 The list of third-party software is a long one, you can check it [[here|https://cs.chromium.org/chromium/src/third_party/]].
  22
  23 ## Current update procedure
  24
  25 The outline is as follows:
  26
  27 1. Import the FreeBSD ports' specific Chromium version to a new empty branch.
  28 2. Create a new branch called _'xx-freebsd'_ based on the branch created in step 1.
  29 3. Import all patches from FreeBSD port _www/chromium_ to the _'xx-freebsd'_ branch and commit it one commit per file.
  30 4. Create a new branch called _'xx-dfly'_ based on the branch _'xx-freebsd'_ after step 3, that is, with all patches included.
  31 5. Cherry-pick the commit(s) needed from the previous 'xx-dfly' branch, resolve conflicts.
  32 6. Adapt the FreeBSD port www/chromium, starting from the changes in DPorts' port _www/chromium_.
  33 7. Make sure your custom _www/chromium_ builds.
  34 8. Once ready, copy the files to the right place and send a PR to [[DeltaPorts|https://github.com/DragonFlyBSD/DeltaPorts/pulls]].
  35
  36 This is how we are performing the Chromium updates right now, nothing is written in stone, contributions/ideas are very welcome :-)
  37
  38 ### Repository location and contributions
  39
  40 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_.
  41
  42 We recommend cloning from crater just in case the mirroring on leaf fails for some reason:
  43
  44
  45     # git clone git://crater.dragonflybsd.org/chromium-dfly.git
  46     Cloning into 'chromium-dfly'...
  47     remote: Counting objects: 469609, done.
  48     remote: Compressing objects: 100% (254827/254827), done.
  49     [....]
  50
  51
  52 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_:
  53
  54
  55     [remote "crater"]
  56             url = git://crater.dragonflybsd.org/chromium-dfly.git
  57             pushurl = ssh://crater.dragonflybsd.org/repository/git/chromium-dfly.git
  58             fetch = +refs/heads/*:refs/remotes/crater/*
  59
  60
  61 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').
  62
  63 ### Repository layout
  64
  65 Vanilla Chromium versions are imported from tarballs to branches named like "chromium-[exact-version]", see below the current ones:
  66
  67
  68     # git branch -a | fgrep crater/chromium
  69       remotes/crater/chromium-60.0.3112.113
  70       remotes/crater/chromium-60.0.3112.116
  71       remotes/crater/chromium-67.0.3396.87
  72       remotes/crater/chromium-68.0.3440.106
  73
  74 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
  76
  77     # git branch -a | grep freebsd |grep crater
  78       remotes/crater/60.113-freebsd
  79       remotes/crater/67-freebsd
  80
  81 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".
  82
  83 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
  85
  86     # git branch -a | grep dfly |grep crater
  87       remotes/crater/60-dfly
  88       remotes/crater/67-dfly
  89
  90 ### Importing a new Chromium version
  91
  92 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]].
  93
  94 * Create a new branch based on a previous one for the import, remove all its contents and amend the commit message:
  95
  96         # cd chromium-dfly
  97         # git checkout -b chromium-68.0.3440.106 crater/chromium-60.0.3112.113
  98         # rm -fr *
  99         # rm .*
 100         # git commit -a --amend --allow-empty -m 'Initial import chromium-68.0.3440.106'
 101
 102 * Import the tarball to your newly created branch:
 103
 104         # tar --strip-components 1 --xzf /usr/distfiles/chromium-68.0.3440.106.tar.xz
 105         # git add -f .
 106         # git commit --amend -m 'Initial import chromium-68.0.3440.106'
 107
 108 * Push the new branch to crater (if you are a DragonFly developer) and maybe prune old branches if they are older than 4 releases:
 109
 110         # git push crater chromium-68.0.3440.106
 111
 112 ### Creating the '-freebsd' branch
 113
 114 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!**
 115
 116     # fgrep PORTVERSION ~/s/freebsd-ports/www/chromium/Makefile
 117     PORTVERSION=    68.0.3440.106
 118
 119 Now create a branch for FreeBSD:
 120
 121     # cd chromium-dfly
 122     # git checkout -b 68-freebsd crater/chromium-68.0.3440.106
 123
 124 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:
 125
 126     # git rev-parse --abbrev-ref HEAD
 127     68-freebsd
 128     # sh -c 'for p in ~/s/freebsd-ports/www/chromium/patch*; do patch -p0 < $p; done'
 129     # find . -iname "*.rej"
 130     # find . -iname "*.orig" -delete
 131
 132 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:
 133
 134     # git status --ignored | less
 135     # git ls-files -mo |wc -l
 136      609
 137     # git status --ignored --porcelain | wc -l
 138      609
 139
 140 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:
 141
 142     # sh -c 'for f in $(git ls-files -mo); do git add $f ; git commit -m "$f"; done'
 143     #
 144
 145 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:
 146
 147     # git push --set-upstream crater 68-freebsd
 148     Enumerating objects: 4672, done.
 149     Counting objects: 100% (4672/4672), done.
 150     [...]
 151      * [new branch]            68-freebsd -> 68-freebsd
 152     Branch '68-freebsd' set up to track remote branch '68-freebsd' from 'crater'.
 153
 154 ### Creating the 'dfly' branch
 155
 156 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
 158
 159     # git checkout -b 68-dfly 68-freebsd
 160
 161
 162 ## Appendix
 163
 164 ### Tools
 165
 166 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/]]