-
Notifications
You must be signed in to change notification settings - Fork 8.2k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Browse files
Browse the repository at this point in the history
* [Build Chromium] Document steps for local build, improve checkout commit e817796d107d554504870cdb8e6dd10db1079a1e Merge: 19e6b300260 61b4e05 Author: Timothy Sullivan <[email protected]> Date: Thu Nov 12 13:25:09 2020 -0700 Merge branch 'chore/build_chromium/improvements' of github.com:tsullivan/kibana into chore/build_chromium/improvements commit 19e6b300260822418cea4dc594bdfdf621a331e0 Author: Timothy Sullivan <[email protected]> Date: Thu Nov 12 13:23:01 2020 -0700 fixes commit 9de24ec298792a46e88207f41c9f6aff1997dbf1 Author: Timothy Sullivan <[email protected]> Date: Thu Nov 12 13:22:52 2020 -0700 add instructions to build local commit 872c0f68e0077ad50c541b605a87253befd1a891 Author: Timothy Sullivan <[email protected]> Date: Thu Nov 12 11:58:25 2020 -0700 simplify commit 8dae9484efcdc483ad20ceab32cae4e97735ab1c Author: Timothy Sullivan <[email protected]> Date: Thu Nov 12 10:28:18 2020 -0700 fixes commit 492f5cfe25e2c7ccffce55a8733383a30aae1cb6 Author: Timothy Sullivan <[email protected]> Date: Wed Nov 11 20:15:43 2020 -0700 --wip-- [skip ci] commit acba359b121f7be8e6c353f90e938bc5d88658a1 Author: Timothy Sullivan <[email protected]> Date: Wed Nov 11 15:47:50 2020 -0700 [Build Chromium] Improve git checkout commit 61b4e05 Author: Timothy Sullivan <[email protected]> Date: Wed Nov 11 20:15:43 2020 -0700 --wip-- [skip ci] commit 58300c9 Author: Timothy Sullivan <[email protected]> Date: Wed Nov 11 15:47:50 2020 -0700 [Build Chromium] Improve git checkout * Apply suggestions from code review Co-authored-by: Joel Griffith <[email protected]> Co-authored-by: Joel Griffith <[email protected]> Co-authored-by: Kibana Machine <[email protected]> Co-authored-by: Joel Griffith <[email protected]> Co-authored-by: Kibana Machine <[email protected]>
- Loading branch information
3 people
authored
Dec 29, 2020
1 parent
804450c
commit ec0bfdc
Showing
4 changed files
with
200 additions
and
92 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,35 +1,105 @@ | ||
| # Chromium build | ||
|
|
||
| We ship our own headless build of Chromium which is significantly smaller than the standard binaries shipped by Google. The scripts in this folder can be used to initialize the build environments and run the build on Mac, Windows, and Linux. | ||
| We ship our own headless build of Chromium which is significantly smaller than | ||
| the standard binaries shipped by Google. The scripts in this folder can be used | ||
| to accept a commit hash from the Chromium repository, and initialize the build | ||
| environments and run the build on Mac, Windows, and Linux. | ||
|
|
||
| The official Chromium build process is poorly documented, and seems to have breaking changes fairly regularly. The build pre-requisites, and the build flags change over time, so it is likely that the scripts in this directory will be out of date by the time we have to do another Chromium build. | ||
|
|
||
| This document is an attempt to note all of the gotchas we've come across while building, so that the next time we have to tinker here, we'll have a good starting point. | ||
|
|
||
| # Before you begin | ||
| You'll need access to our GCP account, which is where we have two machines provisioned for the Linux and Windows builds. Mac builds can be achieved locally, and are a great place to start to gain familiarity. | ||
| ## Before you begin | ||
| If you wish to use a remote VM to build, you'll need access to our GCP account, | ||
| which is where we have two machines provisioned for the Linux and Windows | ||
| builds. Mac builds can be achieved locally, and are a great place to start to | ||
| gain familiarity. | ||
|
|
||
| 1. Login to our GCP instance [here using your okta credentials](https://console.cloud.google.com/). | ||
| 2. Click the "Compute Engine" tab. | ||
| 3. Ensure that `chromium-build-linux` and `chromium-build-windows-12-beefy` are there. | ||
| 4. If #3 fails, you'll have to spin up new instances. Generally, these need `n1-standard-8` types or 8 vCPUs/30 GB memory. | ||
| 5. Ensure that there's enough room left on the disk. `ncdu` is a good linux util to verify what's claming space. | ||
|
|
||
| ## Usage | ||
|
|
||
| ``` | ||
| # Create a dedicated working directory for this directory of Python scripts. | ||
| mkdir ~/chromium && cd ~/chromium | ||
| # Copy the scripts from the Kibana repo to use them conveniently in the working directory | ||
| cp -r ~/path/to/kibana/x-pack/build_chromium . | ||
| # Install the OS packages, configure the environment, download the chromium source | ||
| python ./build_chromium/init.sh [arch_name] | ||
| # Run the build script with the path to the chromium src directory, the git commit id | ||
| python ./build_chromium/build.py <commit_id> | ||
| # You can add an architecture flag for ARM | ||
| python ./build_chromium/build.py <commit_id> arm64 | ||
| ``` | ||
|
|
||
| ## Getting the Commit ID | ||
| Getting `<commit_id>` can be tricky. The best technique seems to be: | ||
| 1. Create a temporary working directory and intialize yarn | ||
| 2. `yarn add puppeteer # install latest puppeter` | ||
| 3. Look through puppeteer's node module files to find the "chromium revision" (a custom versioning convention for Chromium). | ||
| 4. Use `https://crrev.com` and look up the revision and find the git commit info. | ||
|
|
||
| The official Chromium build process is poorly documented, and seems to have | ||
| breaking changes fairly regularly. The build pre-requisites, and the build | ||
| flags change over time, so it is likely that the scripts in this directory will | ||
| be out of date by the time we have to do another Chromium build. | ||
|
|
||
| This document is an attempt to note all of the gotchas we've come across while | ||
| building, so that the next time we have to tinker here, we'll have a good | ||
| starting point. | ||
|
|
||
| ## Build args | ||
|
|
||
| Chromium is built via a build tool called "ninja". The build can be configured by specifying build flags either in an "args.gn" file or via commandline args. We have an "args.gn" file per platform: | ||
| A good how-to on building Chromium from source is | ||
| [here](https://chromium.googlesource.com/chromium/src/+/master/docs/get_the_code.md). | ||
|
|
||
| There are documents for each OS that will explain how to customize arguments | ||
| for the build using the `gn` tool. Those instructions do not apply for the | ||
| Kibana Chromium build. Our `build.py` script ensure the correct `args.gn` | ||
| file gets used for build arguments. | ||
|
|
||
| - mac: darwin/args.gn | ||
| - linux 64bit: linux-x64/args.gn | ||
| We have an `args.gn` file per platform: | ||
|
|
||
| - mac: `darwin/args.gn` | ||
| - linux 64bit: `linux-x64/args.gn` | ||
| - windows: `windows/args.gn` | ||
| - ARM 64bit: linux-aarch64/args.gn | ||
| - windows: windows/args.gn | ||
|
|
||
| The various build flags are not well documented. Some are documented [here](https://www.chromium.org/developers/gn-build-configuration). Some, such as `enable_basic_printing = false`, I only found by poking through 3rd party build scripts. | ||
| To get a list of the build arguments that are enabled, install `depot_tools` and run | ||
| `gn args out/headless --list`. It prints out all of the flags and their | ||
| settings, including the defaults. | ||
|
|
||
| The various build flags are not well documented. Some are documented | ||
| [here](https://www.chromium.org/developers/gn-build-configuration). | ||
|
|
||
| As of this writing, there is an officially supported headless Chromium build args file for Linux: `build/args/headless.gn`. This does not work on Windows or Mac, so we have taken that as our starting point, and modified it until the Windows / Mac builds succeeded. | ||
| As of this writing, there is an officially supported headless Chromium build | ||
| args file for Linux: `build/args/headless.gn`. This does not work on Windows or | ||
| Mac, so we have taken that as our starting point, and modified it until the | ||
| Windows / Mac builds succeeded. | ||
|
|
||
| **NOTE:** Please, make sure you consult @elastic/kibana-security before you change, remove or add any of the build flags. | ||
|
|
||
| ## Building locally | ||
|
|
||
| You can skip the step of running `<os_name>/init.sh` for your OS if you already | ||
| have your environment set up, and the chromium source cloned. | ||
|
|
||
| To get the Chromium code, refer to the [documentation](https://chromium.googlesource.com/chromium/src/+/master/docs/get_the_code.md). | ||
| Install `depot_tools` as suggested, since it comes with useful scripts. Use the | ||
| `fetch` command to clone the chromium repository. To set up and run the build, | ||
| use the Kibana `build.py` script (in this directory). | ||
|
|
||
| It's recommended that you create a working directory for the chromium source | ||
| code and all the build tools, and run the commands from there: | ||
| ``` | ||
| mkdir ~/chromium && cd ~/chromium | ||
| cp -r ~/path/to/kibana/x-pack/build_chromium . | ||
| python ./build_chromium/init.sh [arch_name] | ||
| python ./build_chromium/build.py <commit_id> | ||
| ``` | ||
|
|
||
| ## VMs | ||
|
|
||
| I ran Linux and Windows VMs in GCP with the following specs: | ||
|
|
@@ -57,7 +127,8 @@ The more cores the better, as the build makes effective use of each. For Linux, | |
|
|
||
| ## Initializing each VM / environment | ||
|
|
||
| You only need to initialize each environment once. NOTE: on Mac OS you'll need to install XCode and accept the license agreement. | ||
| In a VM, you'll want to use the init scripts to to initialize each environment. | ||
| On Mac OS you'll need to install XCode and accept the license agreement. | ||
|
|
||
| Create the build folder: | ||
|
|
||
|
|
@@ -86,16 +157,6 @@ In windows, at least, you will need to do a number of extra steps: | |
|
|
||
| ## Building | ||
|
|
||
| Find the sha of the Chromium commit you wish to build. Most likely, you want to build the Chromium revision that is tied to the version of puppeteer that we're using. | ||
|
|
||
| Find the Chromium revision (run in kibana's working directory): | ||
|
|
||
| - `cat node_modules/puppeteer-core/package.json | grep chromium_revision` | ||
| - Take the revision number from that, and tack it to the end of this URL: https://crrev.com | ||
| - (For example, [email protected] has rev (674921): https://crrev.com/674921) | ||
| - Grab the SHA from there | ||
| - (For example, rev 674921 has sha 312d84c8ce62810976feda0d3457108a6dfff9e6) | ||
|
|
||
| Note: In Linux, you should run the build command in tmux so that if your ssh session disconnects, the build can keep going. To do this, just type `tmux` into your terminal to hop into a tmux session. If you get disconnected, you can hop back in like so: | ||
|
|
||
| - SSH into the server | ||
|
|
||
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 |
|---|---|---|
| @@ -1,33 +1,45 @@ | ||
| import os, hashlib | ||
| import os, hashlib, platform, sys | ||
|
|
||
| # This file contains various utility functions used by the init and build scripts | ||
|
|
||
| # Compute the root build and script directory as relative to this file | ||
| script_dir = os.path.realpath(os.path.join(__file__, '..')) | ||
| root_dir = os.path.realpath(os.path.join(script_dir, '..')) | ||
| def runcmdsilent(cmd): | ||
| """Executes a string command in the shell""" | ||
| print(' > ' + cmd) | ||
| return os.system(cmd) | ||
|
|
||
| def runcmd(cmd): | ||
| """Executes a string command in the shell""" | ||
| print(cmd) | ||
| print(' > ' + cmd) | ||
| result = os.system(cmd) | ||
| if result != 0: | ||
| raise Exception(cmd + ' returned ' + str(result)) | ||
|
|
||
| def mkdir(dir): | ||
| print(' > mkdir -p ' + dir) | ||
| """Makes a directory if it doesn't exist""" | ||
| if not os.path.exists(dir): | ||
| print('mkdir -p ' + dir) | ||
| return os.makedirs(dir) | ||
|
|
||
| def md5_file(filename): | ||
| """Builds a hex md5 hash of the given file""" | ||
| md5 = hashlib.md5() | ||
| with open(filename, 'rb') as f: | ||
| for chunk in iter(lambda: f.read(128 * md5.block_size), b''): | ||
| with open(filename, 'rb') as f: | ||
| for chunk in iter(lambda: f.read(128 * md5.block_size), b''): | ||
| md5.update(chunk) | ||
| return md5.hexdigest() | ||
|
|
||
| def configure_environment(): | ||
| """Configures temporary environment variables required by Chromium's build""" | ||
| depot_tools_path = os.path.join(root_dir, 'depot_tools') | ||
| os.environ['PATH'] = depot_tools_path + os.pathsep + os.environ['PATH'] | ||
| def configure_environment(arch_name, build_path, src_path): | ||
| """Runs install scripts for deps, and configures temporary environment variables required by Chromium's build""" | ||
|
|
||
| if platform.system() == 'Linux': | ||
| if arch_name: | ||
| print('Running sysroot install script...') | ||
| sysroot_cmd = src_path + '/build/linux/sysroot_scripts/install-sysroot.py --arch=' + arch_name | ||
| runcmd(sysroot_cmd) | ||
| print('Running install-build-deps...') | ||
| runcmd(src_path + '/build/install-build-deps.sh') | ||
|
|
||
| depot_tools_path = os.path.join(build_path, 'depot_tools') | ||
| full_path = depot_tools_path + os.pathsep + os.environ['PATH'] | ||
| print('Updating PATH for depot_tools: ' + full_path) | ||
| os.environ['PATH'] = full_path |
Oops, something went wrong.