-
Notifications
You must be signed in to change notification settings - Fork 8.2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Chromium reports via puppeteer #21788
Changes from all commits
af57568
319df86
e962e8d
4f2567b
86d460d
d6bfcb0
564e634
fb47ae3
01b0ed3
a78668f
3a6f58d
e74ff8a
70ddaf2
ade46e9
ae325eb
e8bb074
407a708
3fa402a
0925740
8a30325
c4370d2
105a18e
9de5acb
98b30dd
579d5ab
f7f3483
5ac4f14
71a9064
16ad83b
1f2fe32
94fa33b
aa3446d
78bcba6
14e448a
d20760c
0c1c9f7
c9ba80e
c5d947e
e88a447
71d099d
610a9b6
ba2f7af
4e7c2b0
6679d81
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
*.pyc |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,12 +1,123 @@ | ||
# Building on Linux | ||
The following script will run in the elastic/ubuntu-16.04-x86_64 virtual machine. It should be noted that the harddisk of the Virtual Machine should be resized to at least 40GB. | ||
# Chromium build | ||
|
||
# Building on Windows | ||
Some dependencies must be installed on the build machine to build on Windows, those are specified [here](https://chromium.googlesource.com/chromium/src/+/master/docs/windows_build_instructions.md). You don't have to install the depot_tools, just Visual Studio and the Windows SDK. When building on Windows, using the `--workspace` flag is likely required because of the NTFS max paths. | ||
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. | ||
|
||
# Building on macOS | ||
XCode and the OS X 10.10 SDK are currently required, but the full requirements are specified [here](https://chromium.googlesource.com/chromium/src/+/master/docs/mac_build_instructions.md). Also, you don't have to install the depot_tools. | ||
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. | ||
|
||
## Updating the revision | ||
If you want to build the headless_shell that mirrors a specific version of the Chrome browser, you can take the version number displayed in `Chrome -> About` and plug it into the "Version" input [here](https://omahaproxy.appspot.com/) and it'll give you the Commit that you can feed into the build script using the `--git-sha` argument. It's highly recommended to update the default when you're upgrading the version. | ||
## 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: | ||
|
||
- mac: darwin/args.gn | ||
- linux: linux/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. | ||
|
||
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. | ||
|
||
## VMs | ||
|
||
I ran Linux and Windows VMs in GCP with the following specs: | ||
|
||
- 8 core vCPU | ||
- 30GB RAM | ||
- 128GB hard drive | ||
- Ubuntu 18.04 LTS (not minimal) | ||
- Windows Server 2016 (full, with desktop) | ||
|
||
The more cores the better, as the build makes effective use of each. For Linux, Ubuntu is the only officially supported build target. | ||
|
||
- Linux: | ||
- SSH in using [gcloud](https://cloud.google.com/sdk/) | ||
- Get the ssh command in the [GCP console](https://console.cloud.google.com/) -> VM instances -> your-vm-name -> SSH -> gcloud | ||
- Their in-browser UI is kinda sluggish, so use the commandline tool | ||
|
||
- Windows: | ||
- Install Microsoft's Remote Desktop tools | ||
- Get the RDP file in the [GCP console](https://console.cloud.google.com/) -> VM instances -> your-vm-name -> RDP -> Download the RDP file | ||
- Edit it in Microsoft Remote Desktop: | ||
- Display -> Resolution (1280 x 960 or something reasonable) | ||
- Local Resources -> Folders, then select the folder(s) you want to share, this is at least `build_chromium` folder | ||
- Save | ||
|
||
## Initializing each VM / environment | ||
|
||
You only need to initialize each environment once. | ||
|
||
Create the build folder: | ||
|
||
- Mac / Linux: `mkdir -p ~/chromium` | ||
- Windows: `mkdir c:\chromium` | ||
|
||
Copy the `x-pack/build-chromium` folder to each. Replace `you@your-machine` with the correct username and VM name: | ||
|
||
- Mac: `cp -r ~/dev/elastic/kibana/x-pack/build_chromium ~/chromium/build_chromium` | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I'd get rid of the There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I don't copy the Kibana codebase to the build servers. Just the build_chromium folder. Really, build_chromium should probably be its own repo / project, as it's essentially independent of Kibana. So, it should probably be There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Ah. You're right. ~dev/build_chromium is wrong. |
||
- Linux: `gcloud compute scp --recurse ~/dev/elastic/kibana/x-pack/build_chromium you@your-machine:~/chromium --zone=us-east1-b` | ||
- Windows: Copy the `build_chromium` folder via the RDP GUI into `c:\chromium\build_chromium` | ||
|
||
There is an init script for each platform. This downloads and installs the necessary prerequisites, sets environment variables, etc. | ||
|
||
- Mac: `~/chromium/build_chromium/darwin/init.sh` | ||
- Linux: `~/chromium/build_chromium/linux/init.sh` | ||
- Windows `c:\chromium\build_chromium\windows\init.bat` | ||
|
||
In windows, at least, you will need to do a number of extra steps: | ||
|
||
- Follow the prompts in the Visual Studio installation process, click "Install" and wait a while | ||
- Once it's installed, open Control Panel and turn on Debugging Tools for Windows: | ||
- Control Panel → Programs → Programs and Features → Select the “Windows Software Development Kit” → Change → Change → Check “Debugging Tools For Windows” → Change | ||
- Press enter in the terminal to continue running the init | ||
|
||
## 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 (modify the following command to be wherever you have the kibana source installed): | ||
|
||
- `cat ~/dev/elastic/kibana/x-pack/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: https://crrev.com/575458) | ||
- Grab the SHA from there | ||
- (For example, rev 575458 has sha 4747cc23ae334a57a35ed3c8e6adcdbc8a50d479) | ||
|
||
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 | ||
- Run `tmux list-sessions` | ||
- Run `tmux switch -t {session_id}`, replacing {session_id} with the value from the list-sessions output | ||
|
||
To run the build, replace the sha in the following commands with the sha that you wish to build: | ||
|
||
- Mac: `python ~/chromium/build_chromium/build.py 4747cc23ae334a57a35ed3c8e6adcdbc8a50d479` | ||
- Linux: `python ~/chromium/build_chromium/build.py 4747cc23ae334a57a35ed3c8e6adcdbc8a50d479` | ||
- Windows: `python c:\chromium\build_chromium\build.py 4747cc23ae334a57a35ed3c8e6adcdbc8a50d479` | ||
|
||
## Artifacts | ||
|
||
After the build completes, there will be a .zip file and a .md5 file in `~/chromium/chromium/src/out/headless`. These are named like so: `chromium-{first_7_of_SHA}-{platform}`, for example: `chromium-4747cc2-linux`. | ||
|
||
The zip files need to be deployed to s3. For testing, I drop them into `headless-shell-dev`, but for production, they need to be in `headless-shell`. And the `x-pack/plugins/reporting/server/browsers/chromium/paths.js` file needs to be upated to have the correct `archiveChecksum`, `archiveFilename` and `baseUrl`. | ||
|
||
*If you're building in the cloud, don't forget to turn off your VM after retrieving the build artifacts!* | ||
|
||
## Diagnosing runtime failures | ||
|
||
After getting the build to pass, the resulting binaries often failed to run or would hang. | ||
|
||
You can run the headless browser manually to see what errors it is generating (replace the `c:\dev\data` with the path to a dummy folder you've created on your system): | ||
|
||
`headless_shell.exe --disable-translate --disable-extensions --disable-background-networking --safebrowsing-disable-auto-update --disable-sync --metrics-recording-only --disable-default-apps --mute-audio --no-first-run --user-data-dir=c:\dev\data --disable-gpu --no-sandbox --headless --hide-scrollbars --window-size=400,400 --remote-debugging-port=3333 about:blank` | ||
|
||
## Resources | ||
|
||
The following links provide helpful context about how the Chromium build works, and its prerequisites: | ||
|
||
- https://www.chromium.org/developers/how-tos/get-the-code/working-with-release-branches | ||
- https://chromium.googlesource.com/chromium/src/+/master/docs/windows_build_instructions.md | ||
- https://chromium.googlesource.com/chromium/src/+/master/docs/mac_build_instructions.md | ||
- https://chromium.googlesource.com/chromium/src/+/master/docs/linux_build_instructions.md | ||
- Some build-flag descriptions: https://www.chromium.org/developers/gn-build-configuration | ||
- The serverless Chromium project was indispensable: https://github.com/adieuadieu/serverless-chrome/blob/b29445aa5a96d031be2edd5d1fc8651683bf262c/packages/lambda/builds/chromium/build/build.sh |
This file was deleted.
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,92 @@ | ||
import subprocess, os, sys, platform, zipfile, hashlib, shutil | ||
from build_util import runcmd, mkdir, md5_file, script_dir, root_dir, configure_environment | ||
|
||
# This file builds Chromium headless on Windows, Mac, and Linux. | ||
|
||
# Verify that we have an argument, and if not print instructions | ||
if (len(sys.argv) < 2): | ||
print('Usage:') | ||
print('python build.py {chromium_version}') | ||
print('Example:') | ||
print('python build.py 68.0.3440.106') | ||
print('python build.py 4747cc23ae334a57a35ed3c8e6adcdbc8a50d479') | ||
sys.exit(1) | ||
|
||
# The version of Chromium we wish to build. This can be any valid git | ||
# commit, tag, or branch, so: 68.0.3440.106 or | ||
# 4747cc23ae334a57a35ed3c8e6adcdbc8a50d479 | ||
source_version = sys.argv[1] | ||
|
||
print('Building Chromium ' + source_version) | ||
|
||
# Set the environment variables required by the build tools | ||
print('Configuring the build environment') | ||
configure_environment() | ||
|
||
# Sync the codebase to the correct version, syncing master first | ||
# to ensure that we actually have all the versions we may refer to | ||
print('Syncing source code') | ||
|
||
os.chdir(os.path.join(root_dir, 'chromium/src')) | ||
|
||
runcmd('git checkout master') | ||
runcmd('git fetch origin') | ||
runcmd('gclient sync --with_branch_heads --with_tags --jobs 16') | ||
runcmd('git checkout ' + source_version) | ||
runcmd('gclient sync --with_branch_heads --with_tags --jobs 16') | ||
runcmd('gclient runhooks') | ||
|
||
# Copy build args/{Linux | Darwin | Windows}.gn from the root of our directory to out/headless/args.gn, | ||
platform_build_args = os.path.join(script_dir, platform.system().lower(), 'args.gn') | ||
print('Generating platform-specific args') | ||
print('Copying build args: ' + platform_build_args + ' to out/headless/args.gn') | ||
mkdir('out/headless') | ||
shutil.copyfile(platform_build_args, 'out/headless/args.gn') | ||
runcmd('gn gen out/headless') | ||
|
||
# Build Chromium... this takes *forever* on underpowered VMs | ||
print('Compiling... this will take a while') | ||
runcmd('autoninja -C out/headless headless_shell') | ||
|
||
# Optimize the output on Linux and Mac by stripping inessentials from the binary | ||
if platform.system() != 'Windows': | ||
print('Optimizing headless_shell') | ||
shutil.move('out/headless/headless_shell', 'out/headless/headless_shell_raw') | ||
runcmd('strip -o out/headless/headless_shell out/headless/headless_shell_raw') | ||
|
||
# Create the zip and generate the md5 hash using filenames like: | ||
# chromium-4747cc2-linux.zip | ||
base_filename = 'out/headless/chromium-' + source_version[:7].strip('.') + '-' + platform.system().lower() | ||
zip_filename = base_filename + '.zip' | ||
md5_filename = base_filename + '.md5' | ||
|
||
print('Creating ' + zip_filename) | ||
archive = zipfile.ZipFile(zip_filename, mode='w', compression=zipfile.ZIP_DEFLATED) | ||
|
||
def archive_file(name): | ||
"""A little helper function to write individual files to the zip file""" | ||
from_path = os.path.join('out/headless', name) | ||
to_path = os.path.join('headless_shell-' + platform.system().lower(), name) | ||
archive.write(from_path, to_path) | ||
|
||
# Each platform has slightly different requirements for what dependencies | ||
# must be bundled with the Chromium executable. | ||
if platform.system() == 'Linux': | ||
archive_file('headless_shell') | ||
elif platform.system() == 'Windows': | ||
archive_file('headless_shell.exe') | ||
archive_file('dbghelp.dll') | ||
archive_file('icudtl.dat') | ||
archive_file('natives_blob.bin') | ||
archive_file('snapshot_blob.bin') | ||
elif platform.system() == 'Darwin': | ||
archive_file('headless_shell') | ||
archive_file('natives_blob.bin') | ||
archive_file('snapshot_blob.bin') | ||
archive_file('Helpers/crashpad_handler') | ||
|
||
archive.close() | ||
|
||
print('Creating ' + md5_filename) | ||
with open (md5_filename, 'w') as f: | ||
f.write(md5_file(zip_filename)) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should you add a step to start the vm instance if it is stopped?
Should we specifically call out the vm instance name so it matches whats on there now?
chromium-build-linux
I see (but it's stopped so I can't SSH in)And maybe a step to make sure you turn it off when done building since I guess we get billed for it.