How to build your own Chromium release for starters

Samplasion -

The other day I downloaded the Avast antivirus and I noticed it installed the Secure browser. When I opened it, it didn't take long until I noticed it's just a Chromium based browser with built-in extensions.

After that, I started thinking, "Is it hard to create a Chromium-based browser?". Today, I can certainly say the answer is no.

But before actually starting with this tutorial, I should say that if you haven't got either a fast connection or much, much time, don't even bother starting this tutorial, because as stated in the official Chromium website, the download of the source code takes a long time on fast connections. I personally haven't got that fast of a connection, but I still managed to download it.

Don't get intimidated by the length of this tutorial; only selected sections of it will apply to you.

So, without further ado, let's start.

Preparation

There are some things that you'll need to build your own Chromium release.

  • At least 100 GB of disk space on a drive formatted with a filesystem capable of handling files greater than 4 GB. Yes, the Chromium codebase is huge.
  • The requirements stated by the Chromium docs. As of the 27th of August 2019, these are stated here.
    • For Windows, the requirements are:
      • A 64-bit Intel machine with at least 8GB of RAM. More than 16GB is highly recommended.
      • An appropriate version of Visual Studio (tl;dr: either 2017 latest or 2019 latest)
      • Windows 7 or newer.
    • For macOS, the requirements are:
      • A 64-bit Mac running 10.12+.
      • Xcode 8+
      • The OS X 10.12 SDK.
    • For Linux, the requirements depend on the target OS:
      • If the target OS is Linux:
        • A 64-bit Intel machine with at least 8GB of RAM. More than 16GB is highly recommended.
        • You must have Git and Python v2 installed already.
      • If the target OS is Chromium OS, the steps are done through emulation, so, additionally to a working linux setup, you'll need:
      Obviously, you can choose to build for Linux but not ChromeOS, or to build for both.

Windows Pre-Setup

Before setting up the Chromium codebase, you'll need to install Visual Studio. Chromium requires Visual Studio 2017 (>=15.7.2) or 2019 (>=16.0.0) to build. Visual Studio can also be used to debug Chromium. To install the required libraries along with the code, run:

$ PATH_TO_INSTALLER.EXE ^
--add Microsoft.VisualStudio.Workload.NativeDesktop ^
--add Microsoft.VisualStudio.Component.VC.ATLMFC ^
--includeRecommended

If you want to build for ARM64 Win32 then some extra arguments are needed. The full set for that case is:

$ PATH_TO_INSTALLER.EXE ^
--add Microsoft.VisualStudio.Workload.NativeDesktop ^
--add Microsoft.VisualStudio.Component.VC.ATLMFC ^
--add Microsoft.VisualStudio.Component.VC.Tools.ARM64 ^
--add Microsoft.VisualStudio.Component.VC.MFC.ARM64 ^
--includeRecommended

You must have the version 10.0.18362 or higher Windows 10 SDK installed. This can be installed separately or by checking the appropriate box in the Visual Studio Installer.

The SDK Debugging Tools must also be installed. If the Windows 10 SDK was installed via the Visual Studio installer, then they can be installed by going to: Control Panel → Programs → Programs and Features → Select the “Windows Software Development Kit” → Change → Change → Check “Debugging Tools For Windows” → Change. Or, you can download the standalone SDK installer and use it to install the Debugging Tools.

Installing depot_tools

The next step is to install the depot_tools, which are crucial to the development routine in which they are the frontend to building the source code.

Now, the installation method is the same on macOS and Linux, but it differs on Windows.

Linux / macOS

Clone the depot_tools repository:

$ git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git

Add depot_tools to the start of your PATH (you will probably want to put this in your ~/.bashrc or ~/.zshrc). Assuming you cloned depot_tools to /path/to/depot_tools:

$ export PATH=/path/to/depot_tools:$PATH

It's highly important that you put the depot_tools before any Python installations. See the second note below for more information.

Windows

Download the depot_tools bundle and extract it somewhere. Make sure to extract the hidden .git directory to allow for the tools to auto update themselves.

Add depot_tools to the start of your PATH (must be ahead of any installs of Python). Again, it's highly important that you put the depot_tools before any Python installations. See the second note below for more information.

Assuming you unzipped the bundle to C:\workspace\depot_tools, edit the path to add the depot_tools. To edit the path, go to Control Panel → System and Security → System → Advanced system settings if you have administrator access, or Control Panel → User Accounts → User Accounts → Change my environment variables if you haven't, then modify the PATH system variable to include C:\workspace\depot_tools at the start.

From a Command Prompt shell, run the command gclient (without arguments). On first run, it will install all the Windows-specific bits needed to work with the code, including msysgit and python.

Notes
  1. If you run gclient from a shell that's not cmd, it may appear to run properly, but msysgit, python, and other tools may not get installed correctly.
  2. After running gclient, open a command prompt and type where python. Confirm that the depot_tools python.bat comes ahead of any copies of python.exe. If it doesn't, gn will build files it doesn't need to build.

Downloading the Source Code

If you are on Windows, execute the following steps before downloading:

$ git config --global user.name "My Name"
$ git config --global user.email "my-name@chromium.org"
$ git config --global core.autocrlf false
$ git config --global core.filemode false
$ git config --global branch.autosetuprebase always

To download the source code, execute the following steps:

# Create a directory to store the files
$ mkdir Chrome
$ cd Chrome

# Start the download
$ fetch chromium

If you don't want the full repo history, you can save a lot of time by adding the --no-history flag to fetch, and if at any time the installation stops before finishing, run  gclient sync.

Expect the command to take 30 minutes on even a fast connection, and many hours on slower ones.

When fetch is done, it'll have created a hidden .git directory and a src directory with the source code. Enter the src directory:

$ cd src

Platform-Specific and General Instructions

Now, the instructions for actually creating the build vary between cases, so here's a complete list.

Basic setup
Note
If you're on Linux, you must first follow this.

Create a build directory by using:

gn gen out/Default
You can replace Default with your own string, as long as it's a subdirectory of out

This will generate all the needed files.

Windows setup with Visual Studio

If you want to use the Visual Studio IDE, pass --ide=vs to gn gen.

$ gn gen --ide=vs out/Default
$ devenv out\Default\all.sln

GN will produce a file all.sln in your build directory. It will internally use Ninja to compile while still allowing most IDE functions to work (there is no native Visual Studio compilation mode). If you manually run gen again you will need to resupply this argument, but normally gn will keep the build and IDE files up to date automatically when you build.

The generated solution will contain several thousand projects and will be very slow to load. Use the --filters argument to restrict generating project files for only the code you're interested in. Although this will also limit what files appear in the project explorer, debugging will still work and you can set breakpoints in files that you open manually. A minimal solution that will let you compile and run Chrome in the IDE but will not show any source files is:

$ gn gen --ide=vs --filters=//chrome --no-deps out\Default

You can selectively add other directories you care about to the filter like so: --filters=//chrome;//third_party/WebKit/*;//gpu/*.

macOS setup with Xcode

If you want to use Xcode, pass --ide=xcode to gn gen:

$ gn gen out/Default --ide=xcode

Open it:

$ open out/Default/ninja/all.xcworkspace
You may run into a problem where http://YES is opened as a new tab every time you launch Chrome. To fix this, open the scheme editor for the Run scheme, choose the Options tab, and uncheck “Allow debugging when using document Versions Browser”. When this option is checked, Xcode adds --NSDocumentRevisionsDebugMode YES to the launch arguments, and the YES gets interpreted as a URL to open.
Linux setup
Install additional build dependencies

Once you have downloaded the code, run build/install-build-deps.sh

$ ./build/install-build-deps.sh

You will need to adjust the build dependencies for other distros. There are some notes in the official guide.

Run the hooks

Once you've run install-build-deps at least once, you can now run the Chromium-specific hooks, which will download additional binaries and other things you might need:

$ gclient runhooks

You can now follow this section.

Build the source code

Once you've edited the source code, you can run:

$ autoninja -C out/Default chrome

where out/Default is the value you provided in Platform-Specific and General Instructions

Run the source code

To run the build, it's enough to open it from Explorer/Finder/File manager. Or, if you want to do it through the Terminal:

# Windows
$ out\Default\chrome.exe

\# macOS
$ out/Default/Chromium.app/Contents/MacOS/Chromium

\# Linux
$ out/Default/chrome

again, where out/Default is the value you provided in Platform-Specific and General Instructions

Update the source code

If you want to update the source code to a newer version/commit of Chromium, run:

# Update the code
$ git pull

\# Sync dependencies to the appropriate versions and re-run hooks as needed.
$ gclient sync

Create a Release build

To create a release build, open out/<dir name> and edit args.gn to include:

is_debug = false

Building again creates a stand-alone executable that can be shared.

Final thoughts

I really hope you'll get around to creating an awesome Chromium release, and I hope you enjoyed this tutorial. If you've got any questions, ask them in the comments. See you soon!