mirror of
https://github.com/Alex313031/thorium.git
synced 2025-01-09 19:37:30 -03:00
more docs updates
This commit is contained in:
parent
df9c03c735
commit
c6f6c416b8
6 changed files with 414 additions and 328 deletions
384
docs/BUILDING_MAC.md
Normal file
384
docs/BUILDING_MAC.md
Normal file
|
@ -0,0 +1,384 @@
|
||||||
|
# Checking out and building Thorium for Mac
|
||||||
|
|
||||||
|
There are instructions for other platforms linked from the
|
||||||
|
[get the code](get_the_code.md) page.
|
||||||
|
|
||||||
|
## Instructions for Google Employees
|
||||||
|
|
||||||
|
Are you a Google employee? See
|
||||||
|
[go/building-chrome](https://goto.google.com/building-chrome) instead.
|
||||||
|
|
||||||
|
[TOC]
|
||||||
|
|
||||||
|
## System requirements
|
||||||
|
|
||||||
|
* A Mac, Intel or Arm.
|
||||||
|
([More details about Arm Macs](https://chromium.googlesource.com/chromium/src.git/+/main/docs/mac_arm64.md).)
|
||||||
|
* [Xcode](https://developer.apple.com/xcode/). Xcode comes with...
|
||||||
|
* The macOS SDK. Run
|
||||||
|
|
||||||
|
```shell
|
||||||
|
$ ls `xcode-select -p`/Platforms/MacOSX.platform/Developer/SDKs
|
||||||
|
```
|
||||||
|
|
||||||
|
to check whether you have it, and what version you have.
|
||||||
|
`mac_sdk_official_version` in [mac_sdk.gni](../build/config/mac/mac_sdk.gni)
|
||||||
|
is the SDK version used on all the bots and for
|
||||||
|
[official builds](https://source.chromium.org/search?q=MAC_BINARIES_LABEL&ss=chromium),
|
||||||
|
so that version is guaranteed to work. Building with a newer SDK usually
|
||||||
|
works too (please fix or file a bug if it doesn't).
|
||||||
|
|
||||||
|
Building with an older SDK might also work, but if it doesn't then we won't
|
||||||
|
accept changes for making it work.
|
||||||
|
|
||||||
|
The easiest way to get the newest SDK is to use the newest version of Xcode,
|
||||||
|
which often requires using the newest version of macOS. We don't use Xcode
|
||||||
|
itself much, so if you're know what you're doing, you can likely get the
|
||||||
|
build working with an older version of macOS as long as you get a new
|
||||||
|
version of the macOS SDK on it.
|
||||||
|
* An APFS-formatted volume (this is the default format for macOS volumes).
|
||||||
|
|
||||||
|
## Install `depot_tools`
|
||||||
|
|
||||||
|
Clone the `depot_tools` repository:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
$ git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
|
||||||
|
```
|
||||||
|
|
||||||
|
Add `depot_tools` to the end of your PATH (you will probably want to put this in
|
||||||
|
your `~/.bash_profile` or `~/.zshrc`). Assuming you cloned `depot_tools` to
|
||||||
|
`/path/to/depot_tools` (note: you **must** use the absolute path or Python will
|
||||||
|
not be able to find infra tools):
|
||||||
|
|
||||||
|
```shell
|
||||||
|
$ export PATH="$PATH:/path/to/depot_tools"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Get the code
|
||||||
|
|
||||||
|
Create a `chromium` directory for the checkout and change to it (you can call
|
||||||
|
this whatever you like and put it wherever you like, as long as the full path
|
||||||
|
has no spaces):
|
||||||
|
|
||||||
|
```shell
|
||||||
|
$ mkdir chromium && cd chromium
|
||||||
|
```
|
||||||
|
|
||||||
|
Run the `fetch` tool from `depot_tools` to check out the code and its
|
||||||
|
dependencies.
|
||||||
|
|
||||||
|
```shell
|
||||||
|
$ caffeinate fetch chromium
|
||||||
|
```
|
||||||
|
|
||||||
|
Running the `fetch` with `caffeinate` is optional, but it will prevent the
|
||||||
|
system from sleeping for the duration of the `fetch` command, which may run for
|
||||||
|
a considerable amount of time.
|
||||||
|
|
||||||
|
If you don't need the full repo history, you can save time by using
|
||||||
|
`fetch --no-history chromium`. You can call `git fetch --unshallow` to retrieve
|
||||||
|
the full history later.
|
||||||
|
|
||||||
|
Expect the command to take 30 minutes on even a fast connection, and many
|
||||||
|
hours on slower ones.
|
||||||
|
|
||||||
|
When `fetch` completes, it will have created a hidden `.gclient` file and a
|
||||||
|
directory called `src` in the working directory. The remaining instructions
|
||||||
|
assume you have switched to the `src` directory:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
$ cd src
|
||||||
|
```
|
||||||
|
|
||||||
|
*Optional*: You can also [install API
|
||||||
|
keys](https://www.chromium.org/developers/how-tos/api-keys) if you want your
|
||||||
|
build to talk to some Google services, but this is not necessary for most
|
||||||
|
development and testing purposes.
|
||||||
|
|
||||||
|
## Setting up the build
|
||||||
|
|
||||||
|
Chromium uses [Ninja](https://ninja-build.org) as its main build tool along with
|
||||||
|
a tool called [GN](https://gn.googlesource.com/gn/+/main/docs/quick_start.md)
|
||||||
|
to generate `.ninja` files. You can create any number of *build directories*
|
||||||
|
with different configurations. To create a build directory:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
$ gn gen out/Default
|
||||||
|
```
|
||||||
|
|
||||||
|
* You only have to run this once for each new build directory, Ninja will
|
||||||
|
update the build files as needed.
|
||||||
|
* You can replace `Default` with another name, but
|
||||||
|
it should be a subdirectory of `out`.
|
||||||
|
* For other build arguments, including release settings, see [GN build
|
||||||
|
configuration](https://www.chromium.org/developers/gn-build-configuration).
|
||||||
|
The default will be a debug component build matching the current host
|
||||||
|
operating system and CPU.
|
||||||
|
* For more info on GN, run `gn help` on the command line or read the
|
||||||
|
[quick start guide](https://gn.googlesource.com/gn/+/main/docs/quick_start.md).
|
||||||
|
* Building Chromium for arm Macs requires [additional setup](mac_arm64.md).
|
||||||
|
|
||||||
|
|
||||||
|
### Faster builds
|
||||||
|
|
||||||
|
Full rebuilds are about the same speed in Debug and Release, but linking is a
|
||||||
|
lot faster in Release builds.
|
||||||
|
|
||||||
|
Put
|
||||||
|
|
||||||
|
```
|
||||||
|
is_debug = false
|
||||||
|
```
|
||||||
|
|
||||||
|
in your `args.gn` to do a release build.
|
||||||
|
|
||||||
|
Put
|
||||||
|
|
||||||
|
```
|
||||||
|
is_component_build = true
|
||||||
|
```
|
||||||
|
|
||||||
|
in your `args.gn` to build many small dylibs instead of a single large
|
||||||
|
executable. This makes incremental builds much faster, at the cost of producing
|
||||||
|
a binary that opens less quickly. Component builds work in both debug and
|
||||||
|
release.
|
||||||
|
|
||||||
|
Put
|
||||||
|
|
||||||
|
```
|
||||||
|
symbol_level = 0
|
||||||
|
```
|
||||||
|
|
||||||
|
in your args.gn to disable debug symbols altogether. This makes both full
|
||||||
|
rebuilds and linking faster (at the cost of not getting symbolized backtraces
|
||||||
|
in gdb).
|
||||||
|
|
||||||
|
#### CCache
|
||||||
|
|
||||||
|
You might also want to [install ccache](ccache_mac.md) to speed up the build.
|
||||||
|
|
||||||
|
## Build Chromium
|
||||||
|
|
||||||
|
Build Chromium (the "chrome" target) with Ninja using the command:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
$ autoninja -C out/Default chrome
|
||||||
|
```
|
||||||
|
|
||||||
|
(`autoninja` is a wrapper that automatically provides optimal values for the
|
||||||
|
arguments passed to `ninja`.)
|
||||||
|
|
||||||
|
You can get a list of all of the other build targets from GN by running `gn ls
|
||||||
|
out/Default` from the command line. To compile one, pass the GN label to Ninja
|
||||||
|
with no preceding "//" (so, for `//chrome/test:unit_tests` use `autoninja -C
|
||||||
|
out/Default chrome/test:unit_tests`).
|
||||||
|
|
||||||
|
## Run Chromium
|
||||||
|
|
||||||
|
Once it is built, you can simply run the browser:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
$ out/Default/Chromium.app/Contents/MacOS/Chromium
|
||||||
|
```
|
||||||
|
|
||||||
|
## Avoiding system permissions dialogs after each build
|
||||||
|
|
||||||
|
Every time you start a new developer build, you may get two system dialogs:
|
||||||
|
`Chromium wants to use your confidential information stored in "Chromium Safe
|
||||||
|
Storage" in your keychain.`, and `Do you want the application "Chromium.app" to
|
||||||
|
accept incoming network connections?`.
|
||||||
|
|
||||||
|
To avoid them, you can run Chromium with these command-line flags (but of
|
||||||
|
course beware that they will change the behavior of certain subsystems):
|
||||||
|
|
||||||
|
```shell
|
||||||
|
--use-mock-keychain --disable-features=DialMediaRouteProvider
|
||||||
|
```
|
||||||
|
|
||||||
|
## Build and run test targets
|
||||||
|
|
||||||
|
Tests are split into multiple test targets based on their type and where they
|
||||||
|
exist in the directory structure. To see what target a given unit test or
|
||||||
|
browser test file corresponds to, the following command can be used:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
$ gn refs out/Default --testonly=true --type=executable --all chrome/browser/ui/browser_list_unittest.cc
|
||||||
|
//chrome/test:unit_tests
|
||||||
|
```
|
||||||
|
|
||||||
|
In the example above, the target is unit_tests. The unit_tests binary can be
|
||||||
|
built by running the following command:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
$ autoninja -C out/Default unit_tests
|
||||||
|
```
|
||||||
|
|
||||||
|
You can run the tests by running the unit_tests binary. You can also limit which
|
||||||
|
tests are run using the `--gtest_filter` arg, e.g.:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
$ out/Default/unit_tests --gtest_filter="BrowserListUnitTest.*"
|
||||||
|
```
|
||||||
|
|
||||||
|
You can find out more about GoogleTest at its
|
||||||
|
[GitHub page](https://github.com/google/googletest).
|
||||||
|
|
||||||
|
## Debugging
|
||||||
|
|
||||||
|
Good debugging tips can be found [here](mac/debugging.md).
|
||||||
|
|
||||||
|
## Update your checkout
|
||||||
|
|
||||||
|
To update an existing checkout, you can run
|
||||||
|
|
||||||
|
```shell
|
||||||
|
$ git rebase-update
|
||||||
|
$ gclient sync
|
||||||
|
```
|
||||||
|
|
||||||
|
The first command updates the primary Chromium source repository and rebases
|
||||||
|
any of your local branches on top of tip-of-tree (aka the Git branch
|
||||||
|
`origin/main`). If you don't want to use this script, you can also just use
|
||||||
|
`git pull` or other common Git commands to update the repo.
|
||||||
|
|
||||||
|
The second command syncs dependencies to the appropriate versions and re-runs
|
||||||
|
hooks as needed.
|
||||||
|
|
||||||
|
## Tips, tricks, and troubleshooting
|
||||||
|
|
||||||
|
### Using Xcode-Ninja Hybrid
|
||||||
|
|
||||||
|
While using Xcode is unsupported, GN supports a hybrid approach of using Ninja
|
||||||
|
for building, but Xcode for editing and driving compilation. Xcode is still
|
||||||
|
slow, but it runs fairly well even **with indexing enabled**. Most people
|
||||||
|
build in the Terminal and write code with a text editor, though.
|
||||||
|
|
||||||
|
With hybrid builds, compilation is still handled by Ninja, and can be run from
|
||||||
|
the command line (e.g. `autoninja -C out/gn chrome`) or by choosing the `chrome`
|
||||||
|
target in the hybrid project and choosing Build.
|
||||||
|
|
||||||
|
To use Xcode-Ninja Hybrid pass `--ide=xcode` to `gn gen`:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
$ gn gen out/gn --ide=xcode
|
||||||
|
```
|
||||||
|
|
||||||
|
Open it:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
$ open out/gn/all.xcodeproj
|
||||||
|
```
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
If you have problems building, join us in `#chromium` on `irc.freenode.net` and
|
||||||
|
ask there. Be sure that the
|
||||||
|
[waterfall](https://build.chromium.org/buildbot/waterfall/) is green and the
|
||||||
|
tree is open before checking out. This will increase your chances of success.
|
||||||
|
|
||||||
|
### Improving performance of `git status`
|
||||||
|
|
||||||
|
#### Increase the vnode cache size
|
||||||
|
|
||||||
|
`git status` is used frequently to determine the status of your checkout. Due
|
||||||
|
to the large number of files in Chromium's checkout, `git status` performance
|
||||||
|
can be quite variable. Increasing the system's vnode cache appears to help. By
|
||||||
|
default, this command:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
$ sysctl -a | egrep 'kern\..*vnodes'
|
||||||
|
```
|
||||||
|
|
||||||
|
Outputs `kern.maxvnodes: 263168` (263168 is 257 * 1024). To increase this
|
||||||
|
setting:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
$ sudo sysctl kern.maxvnodes=$((512*1024))
|
||||||
|
```
|
||||||
|
|
||||||
|
Higher values may be appropriate if you routinely move between different
|
||||||
|
Chromium checkouts. This setting will reset on reboot. To apply it at startup:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
$ sudo tee /Library/LaunchDaemons/kern.maxvnodes.plist > /dev/null <<EOF
|
||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||||
|
<plist version="1.0">
|
||||||
|
<dict>
|
||||||
|
<key>Label</key>
|
||||||
|
<string>kern.maxvnodes</string>
|
||||||
|
<key>ProgramArguments</key>
|
||||||
|
<array>
|
||||||
|
<string>sysctl</string>
|
||||||
|
<string>kern.maxvnodes=524288</string>
|
||||||
|
</array>
|
||||||
|
<key>RunAtLoad</key>
|
||||||
|
<true/>
|
||||||
|
</dict>
|
||||||
|
</plist>
|
||||||
|
EOF
|
||||||
|
```
|
||||||
|
|
||||||
|
Or edit the file directly.
|
||||||
|
|
||||||
|
#### Configure git to use an untracked cache
|
||||||
|
|
||||||
|
Try running
|
||||||
|
|
||||||
|
```shell
|
||||||
|
$ git update-index --test-untracked-cache
|
||||||
|
```
|
||||||
|
|
||||||
|
If the output ends with `OK`, then the following may also improve performance of
|
||||||
|
`git status`:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
$ git config core.untrackedCache true
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Configure git to use fsmonitor
|
||||||
|
|
||||||
|
You can significantly speed up git by using [fsmonitor.](https://github.blog/2022-06-29-improve-git-monorepo-performance-with-a-file-system-monitor/)
|
||||||
|
You should enable fsmonitor in large repos, such as Chromium and v8. Enabling
|
||||||
|
it globally will launch many processes and probably isn't worthwhile. The
|
||||||
|
command to enable fsmonitor in the current repo is:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
$ git config core.fsmonitor true
|
||||||
|
```
|
||||||
|
|
||||||
|
### Xcode license agreement
|
||||||
|
|
||||||
|
If you're getting the error
|
||||||
|
|
||||||
|
> Agreeing to the Xcode/iOS license requires admin privileges, please re-run as
|
||||||
|
> root via sudo.
|
||||||
|
|
||||||
|
the Xcode license hasn't been accepted yet which (contrary to the message) any
|
||||||
|
user can do by running:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
$ xcodebuild -license
|
||||||
|
```
|
||||||
|
|
||||||
|
Only accepting for all users of the machine requires root:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
$ sudo xcodebuild -license
|
||||||
|
```
|
||||||
|
|
||||||
|
### Exclude checkout from Spotlight indexing
|
||||||
|
|
||||||
|
Chromium's checkout contains a lot of files, and building generates many more.
|
||||||
|
Spotlight will try to index all of those files, and uses a lot of CPU time
|
||||||
|
doing so, especially during a build, which can slow things down.
|
||||||
|
|
||||||
|
To prevent the Chromium checkout from being indexed by Spotlight, open System
|
||||||
|
Preferences, go to "Spotlight" -> "Privacy" and add your Chromium checkout
|
||||||
|
directory to the list of excluded locations.
|
|
@ -4,5 +4,6 @@ Simply a place to hold documentation and resources for people building or contri
|
||||||
|
|
||||||
__I've also made some pages on the thorium.rocks website relating to Thorium development.__
|
__I've also made some pages on the thorium.rocks website relating to Thorium development.__
|
||||||
|
|
||||||
- There is a developer page [Here](https://thorium.rocks/misc/dev), with links to different tools on the Thorium Website.
|
- There is a developer page [Here](https://thorium.rocks//dev), with links to different tools on the Thorium Website.
|
||||||
- There is also the [documentation page](https://thorium.rocks/docs/), which has html copies of things in here as well as some things not in here. Recommended.
|
- There is also the [documentation page](https://thorium.rocks/docs/), which has html copies of things in here as well as some things not in here. Recommended.
|
||||||
|
- The .txt instructions are old, use the .md instructions.
|
||||||
|
|
|
@ -1,12 +1,10 @@
|
||||||
# Copy of //chromium/src/chrome/app/theme/chromium/BRANDING
|
COMPANY_FULLNAME=The Thorium Authors
|
||||||
|
COMPANY_SHORTNAME=The Thorium Authors
|
||||||
COMPANY_FULLNAME=The Chromium Authors and Alex313031
|
|
||||||
COMPANY_SHORTNAME=The Chromium Authors and Alex313031
|
|
||||||
PRODUCT_FULLNAME=Thorium
|
PRODUCT_FULLNAME=Thorium
|
||||||
PRODUCT_SHORTNAME=Thorium
|
PRODUCT_SHORTNAME=Thorium
|
||||||
PRODUCT_INSTALLER_FULLNAME=Thorium Installer
|
PRODUCT_INSTALLER_FULLNAME=Thorium Installer
|
||||||
PRODUCT_INSTALLER_SHORTNAME=Thorium Installer
|
PRODUCT_INSTALLER_SHORTNAME=Thorium Installer
|
||||||
COPYRIGHT=Copyright @LASTCHANGE_YEAR@ The Chromium Authors and Alex313031. All rights reserved.
|
COPYRIGHT=Copyright @LASTCHANGE_YEAR@ The Chromium Authors and Alex313031. All rights reserved.
|
||||||
MAC_BUNDLE_ID=org.chromium.Chromium
|
MAC_BUNDLE_ID=org.chromium.Thorium
|
||||||
MAC_CREATOR_CODE=Cr24
|
MAC_CREATOR_CODE=Cr24
|
||||||
MAC_TEAM_ID=
|
MAC_TEAM_ID=
|
||||||
|
|
|
@ -1,322 +0,0 @@
|
||||||
# Checking out and building Thorium on Linux <img src="https://github.com/Alex313031/thorium/blob/main/logos/NEW/build_light.svg#gh-dark-mode-only" width="48"> <img src="https://github.com/Alex313031/thorium/blob/main/logos/NEW/build_dark.svg#gh-light-mode-only" width="48">
|
|
||||||
|
|
||||||
There are instructions for other platforms here in the Thorium Docs directory.
|
|
||||||
You can also read the [old building instructions](https://github.com/Alex313031/thorium/blob/main/infra/BUILDING.md).
|
|
||||||
#### Windows
|
|
||||||
For Windows and Windows [AVX2](https://en.wikipedia.org/wiki/Advanced_Vector_Extensions#Advanced_Vector_Extensions_2), I made new dedicated instructions. If you are building on Windows use [BUILDING_WIN.md](https://github.com/Alex313031/thorium/blob/main/docs/BUILDING_WIN.md) and if you are building for Windows on Linux, use [WIN_CROSS_BUILD_INSTRUCTIONS](https://github.com/Alex313031/thorium/blob/main/docs/WIN_CROSS_BUILD_INSTRUCTIONS.txt)
|
|
||||||
|
|
||||||
## System Requirements
|
|
||||||
|
|
||||||
* A x64 machine with at least 8GB of RAM. 16GB or more is highly
|
|
||||||
recommended.
|
|
||||||
* At least 75GB of free disk space.
|
|
||||||
* You must have Git and Python v3.6+ installed already (and `python3` must point
|
|
||||||
to a Python v3.6+ binary (i.e. in your path or as default python install).
|
|
||||||
|
|
||||||
Most development is done on Ubuntu (currently 22.04, Jammy Jellyfish). Ubuntu 16.04 no longer works. 18.04, 20.04 and Debian 10/11 will work.
|
|
||||||
There are some instructions for other distros below, but they are mostly unsupported.
|
|
||||||
|
|
||||||
__The scripts to build Thorium assume that depot_tools, thorium and chromium are both in $HOME!__
|
|
||||||
|
|
||||||
## Install *depot_tools*
|
|
||||||
|
|
||||||
Clone the `depot_tools` repository:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
$ git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
|
|
||||||
```
|
|
||||||
|
|
||||||
Add *depot_tools* to the end of your *$PATH* (you will probably want to put this
|
|
||||||
in your `~/.bashrc` or `~/.zshrc`). When cloning *depot_tools* to your home directory **do not** use `~` on PATH,
|
|
||||||
otherwise `gclient runhooks` will fail to run. Rather, you should use either
|
|
||||||
`$HOME` or the absolute path. So, assuming you cloned *depot_tools* to *$HOME*:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
$ export PATH="$PATH:${HOME}/depot_tools" or $ export PATH="$PATH:/home/alex/depot_tools"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Get the code
|
|
||||||
|
|
||||||
### Thorium Code
|
|
||||||
|
|
||||||
Clone the Thorium repo into *$HOME*
|
|
||||||
|
|
||||||
```shell
|
|
||||||
$ git clone https://github.com/Alex313031/thorium.git
|
|
||||||
```
|
|
||||||
|
|
||||||
### Chromium Code
|
|
||||||
|
|
||||||
Create a *chromium* directory for the checkout and change to it.
|
|
||||||
|
|
||||||
```shell
|
|
||||||
$ mkdir ~/chromium && cd ~/chromium
|
|
||||||
```
|
|
||||||
|
|
||||||
Run the *fetch* tool from depot_tools to check out the code and its
|
|
||||||
dependencies.
|
|
||||||
|
|
||||||
```shell
|
|
||||||
$ fetch --nohooks chromium
|
|
||||||
```
|
|
||||||
|
|
||||||
The `--nohooks` flag is ommitted on other platforms, we just use it on linux to explicitly run the hooks
|
|
||||||
later, after installing the prerequisites.
|
|
||||||
`fetch` and `repo` are used to download, rebase, and sync all Google repositories, including Chromium, ChromiumOS,
|
|
||||||
Android, Fuchsia, Infra, Monorail, GN, etc.
|
|
||||||
|
|
||||||
If you don't want the full repo history, you can save a lot of time by
|
|
||||||
adding the `--no-history` flag to `fetch`. This is equivalent to a shallow git clone with a depth of 1.
|
|
||||||
|
|
||||||
Expect the command to take 20 minutes on a fast (150mbps+) connection, and many
|
|
||||||
hours on slower ones.
|
|
||||||
|
|
||||||
If you've already installed the build dependencies on the machine (from another
|
|
||||||
checkout, for example), you can omit the `--nohooks` flag and *fetch*
|
|
||||||
will automatically execute `gclient runhooks` at the end.
|
|
||||||
|
|
||||||
When *fetch* completes, it will have created a hidden `.gclient` file and a
|
|
||||||
directory called `src` in the *chromium* directory. The remaining instructions
|
|
||||||
assume you have switched to the `src` directory, so:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
$ cd src
|
|
||||||
```
|
|
||||||
|
|
||||||
### Install additional build dependencies
|
|
||||||
|
|
||||||
Once you have checked out the code, and assuming you're using Ubuntu, run the
|
|
||||||
[*`install-build-deps.sh`*](https://chromium.googlesource.com/chromium/src/+/main/build/install-build-deps.sh) script.
|
|
||||||
|
|
||||||
```shell
|
|
||||||
$ ./build/install-build-deps.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
You can run it with the flag `--help` to see arguments. For example, you would want `--lib32` if building for 32 bit Linux, `--arm` for building
|
|
||||||
a Raspberry Pi release, `--chromeos-fonts` for building Thorium for ThoriumOS, and `--quick-check` just to verify needed libraries are installed.
|
|
||||||
|
|
||||||
You may need to adjust the build dependencies for other distros. There are
|
|
||||||
some [notes](#notes) at the end of this document, but we make no guarantees
|
|
||||||
for their accuracy, as distros get updated over time.
|
|
||||||
|
|
||||||
### 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 like LLVM and a Debian Sysroot.:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
$ gclient runhooks
|
|
||||||
```
|
|
||||||
|
|
||||||
*Optional*: You can also [build with API
|
|
||||||
keys](https://www.chromium.org/developers/how-tos/api-keys) if you want your
|
|
||||||
build to talk to some Google services like Google Sync, Translate, and GeoLocation. <img src="https://github.com/Alex313031/thorium/blob/main/logos/NEW/Key_Light.svg#gh-dark-mode-only" width="26"> <img src="https://github.com/Alex313031/thorium/blob/main/logos/NEW/Key_Dark.svg#gh-light-mode-only" width="26"> Thorium has its own keys in a private repository, if you are a builder or would like access to them, contact me. Otherwise, for personal or development builds,
|
|
||||||
you can create your own keys and add yourself to [google-browser-signin-testaccounts](https://groups.google.com/u/1/a/chromium.org/g/google-browser-signin-testaccounts)
|
|
||||||
to enable Sync.
|
|
||||||
|
|
||||||
## Setting up the build
|
|
||||||
|
|
||||||
First, we need to run `./trunk.sh` (in the root of the Thorium repo.) This will Rebase/Sync the Chromium repo, and revert it to stock Chromium. \
|
|
||||||
It should be used before every seperate build. See the [Updating](#updating) section.
|
|
||||||
|
|
||||||
__IMPORTANT__
|
|
||||||
This will update and sync the sources to the latest revision (tip of tree) and ensure you have all the version tags.
|
|
||||||
|
|
||||||
- Then, to check out the current Chromium revision that Thorium is using, run `./VERSION.sh`. At the end it will download the [PGO profiles](https://chromium.googlesource.com/chromium/src.git/+/refs/heads/main/docs/pgo.md) for Chromium for all platforms. The file will be downloaded to *//chromium/src/chrome/build/pgo_profiles/*.profdata* with the actual file name looking something like 'chrome-linux-main-1632505958-ddbb37bcdfa7dbd7b10cf3a9b6a5bc45e7a958a6.profdata', which should be added to the end of args.gn as per below.
|
|
||||||
- Then, (from where you cloned this repo) run `./setup.sh`. This will copy all the files and patches to the needed locations and drop you to *//chromium/src*.
|
|
||||||
- NOTE: To build for MacOS, use `./setup.sh --mac`. To build for Raspberry Pi, use `./setup.sh --raspi`.
|
|
||||||
|
|
||||||
Chromium and Thorium use [Ninja](https://ninja-build.org) as their main build tool, along with
|
|
||||||
a tool called [GN](https://gn.googlesource.com/gn/+/refs/heads/main/README.md)
|
|
||||||
to generate `.ninja` files in the build output directory. You can create any number of *build directories*
|
|
||||||
with different configurations. To create a build directory:
|
|
||||||
- Run `gn args out/thorium` and the contents of '[args.gn](https://github.com/Alex313031/thorium/blob/main/args.gn)' in the root of this repo should be copy/pasted into the editor. Note that for Windows, Mac, ChromiumOS, or Android there are seperate *_args.gn files for those platforms. *--Include your api keys here at the top or leave blank, and edit the last line to point to the actual path and file name of '*.profdata'*
|
|
||||||
- For more info about args.gn, read the [ABOUT_GN_ARGS.md](https://github.com/Alex313031/thorium/blob/main/infra/DEBUG/ABOUT_GN_ARGS.md) file.
|
|
||||||
- '[infra/args.list](https://github.com/Alex313031/thorium/blob/main/infra/args.list)' contains an alphabetical list with descriptions of all possible build arguments; [gn_args.list](https://github.com/Alex313031/thorium/blob/main/infra/gn_args.list) gives a similar list but with the flags in args.gn added.
|
|
||||||
|
|
||||||
You can list all the possible build arguments and pipe it to a text file by running:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
$ gn args out/thorium --list >> /path/to/ARGS.list
|
|
||||||
```
|
|
||||||
|
|
||||||
* You only have to run this once for each new build directory, Ninja will
|
|
||||||
update the build files as needed.
|
|
||||||
* You can replace *thorium* with another name, but
|
|
||||||
it should be a subdirectory of *out*. Note that if you choose another name, the `trunk.sh` and `build.sh` scripts will not work.
|
|
||||||
* For information on the args.gn that Thorium uses, see [ABOUT_GN_ARGS.md](https://github.com/Alex313031/thorium/blob/main/docs/ABOUT_GN_ARGS.md).
|
|
||||||
* For other build arguments, including release settings, see [GN build
|
|
||||||
configuration](https://www.chromium.org/developers/gn-build-configuration).
|
|
||||||
The default will be a vanilla Chromium debug component build matching the current host
|
|
||||||
operating system and CPU.
|
|
||||||
* For more info on GN, run `gn help` on the command line or read the
|
|
||||||
[quick start guide](https://gn.googlesource.com/gn/+/main/docs/quick_start.md).
|
|
||||||
|
|
||||||
#### ccache
|
|
||||||
|
|
||||||
You can use [ccache](https://ccache.dev) to speed up local builds.
|
|
||||||
|
|
||||||
Increase your ccache hit rate by setting `CCACHE_BASEDIR` to a parent directory
|
|
||||||
that the working directories all have in common (e.g.,
|
|
||||||
`/home/yourusername/development`). Consider using
|
|
||||||
`CCACHE_SLOPPINESS=include_file_mtime` (since if you are using multiple working
|
|
||||||
directories, header times in svn sync'ed portions of your trees will be
|
|
||||||
different - see
|
|
||||||
[the ccache troubleshooting section](https://ccache.dev/manual/latest.html#_troubleshooting)
|
|
||||||
for additional information). If you use symbolic links from your home directory
|
|
||||||
to get to the local physical disk directory where you keep those working
|
|
||||||
development directories, consider putting
|
|
||||||
|
|
||||||
alias cd="cd -P"
|
|
||||||
|
|
||||||
in your `.bashrc` so that `$PWD` or `cwd` always refers to a physical, not
|
|
||||||
logical directory (and make sure `CCACHE_BASEDIR` also refers to a physical
|
|
||||||
parent).
|
|
||||||
|
|
||||||
If you tune ccache correctly, a second working directory that uses a branch
|
|
||||||
tracking trunk and is up to date with trunk and was gclient sync'ed at about the
|
|
||||||
same time should build chrome in about 1/3 the time, and the cache misses as
|
|
||||||
reported by `ccache -s` should barely increase.
|
|
||||||
|
|
||||||
This is especially useful if you use
|
|
||||||
[git-worktree](http://git-scm.com/docs/git-worktree) and keep multiple local
|
|
||||||
working directories going at once.
|
|
||||||
|
|
||||||
## Build Thorium <a name="build"></a>
|
|
||||||
|
|
||||||
Build Thorium (the "chrome" target), as well as [chrome_sandbox](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/linux/sandboxing.md), [chromedriver](https://chromedriver.chromium.org/home), and [thorium_shell](https://github.com/Alex313031/thorium/tree/main/thorium_shell#readme) (based on [content_shell](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/testing/web_tests_in_content_shell.md#as-a-simple-browser) ), using the `build.sh` script in the root of the Thorium repo (where the # is the number of jobs):
|
|
||||||
|
|
||||||
```shell
|
|
||||||
$ ./build.sh 8
|
|
||||||
```
|
|
||||||
|
|
||||||
You could also manually issue the command (where -j is the number of jobs):
|
|
||||||
|
|
||||||
```shell
|
|
||||||
$ autoninja -C ~/chromium/src/out/thorium chrome chrome_sandbox chromedriver thorium_shell -j8
|
|
||||||
```
|
|
||||||
|
|
||||||
`autoninja` is a wrapper that automatically provides optimal values for the
|
|
||||||
arguments passed to `ninja`. `build.sh` uses a [custom autoninja](https://github.com/Alex313031/thorium/blob/main/depot_tools/autoninja) in the *depot_tools* directory in Thorium.
|
|
||||||
|
|
||||||
You can get a list of all of the other build targets from GN by running `gn ls
|
|
||||||
out/thorium` from the command line. To compile one, pass the GN label to Ninja
|
|
||||||
with no preceding "//" (so, for `//chrome/test:unit_tests` use `autoninja -C
|
|
||||||
out/thorium chrome/test:unit_tests`).
|
|
||||||
|
|
||||||
## Run Thorium
|
|
||||||
|
|
||||||
Once it is built, you can simply run the browser:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
$ out/thorium/thorium
|
|
||||||
```
|
|
||||||
**RECOMMENDED** *- Copy and run [clean.sh](https://github.com/Alex313031/thorium/blob/main/clean.sh) within this dir to clean up build artifacts.*
|
|
||||||
|
|
||||||
## Installing Thorium
|
|
||||||
|
|
||||||
Of course, you will probably want to make installation packages. To make a .deb and .rpm run `package.sh` (where the # is the number of jobs) in the root of the repo:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
$ ./package.sh 8
|
|
||||||
```
|
|
||||||
To make an appimage, copy the .deb to `//thorium/infra/APPIMAGE/`
|
|
||||||
and follow the [Instructions](https://github.com/Alex313031/thorium/blob/main/infra/APPIMAGE/README.md#instructions) therein.
|
|
||||||
|
|
||||||
### Tests
|
|
||||||
|
|
||||||
See the [Debugging](#debugging) section below, as well as
|
|
||||||
[Thorium UI Debug Shell](https://github.com/Alex313031/thorium/blob/main/infra/DEBUG/DEBUG_SHELL_README.md).
|
|
||||||
|
|
||||||
Learn about [how to use Chromedriver](https://chromedriver.chromium.org/getting-started) and Google Test at its
|
|
||||||
[GitHub page](https://github.com/google/googletest).
|
|
||||||
|
|
||||||
## Update your checkout and revert to latest vanilla tip-o-tree Chromium. <a name="updating"></a>
|
|
||||||
|
|
||||||
Simply run `trunk.sh` in the root of the Thorium repo or execute the commands inside.
|
|
||||||
|
|
||||||
```shell
|
|
||||||
$ ./trunk.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
## Tips, tricks, and troubleshooting
|
|
||||||
|
|
||||||
### More links
|
|
||||||
|
|
||||||
* Information about [building with Clang](https://chromium.googlesource.com/chromium/src.git/+/refs/heads/main/docs/clang.md).
|
|
||||||
* You may want to [use a chroot](https://chromium.googlesource.com/chromium/src.git/+/refs/heads/main/docs/linux/using_a_chroot.md) to
|
|
||||||
isolate yourself from versioning or packaging conflicts.
|
|
||||||
* Cross-compiling for ARM? (Raspberry Pi) See the [Thorium ARM](https://github.com/Alex313031/thorium/tree/main/arm#readme) dir and [chromium_arm.md](https://chromium.googlesource.com/chromium/src.git/+/refs/heads/main/docs/linux/chromium_arm.md).
|
|
||||||
* [Atom](https://atom.io/) and [Geany](https://www.geany.org/) are reccomended IDEs for working on Thorium.
|
|
||||||
|
|
||||||
### Debugging <a name="debugging"></a>
|
|
||||||
* See the [Thorium DEBUG](https://github.com/Alex313031/thorium/tree/main/infra/DEBUG#readme) dir, including the [More Info](https://github.com/Alex313031/thorium/blob/main/infra/DEBUG/README.md#more-info-) section, and [DEBUGGING.md](https://github.com/Alex313031/thorium/blob/main/infra/DEBUG/DEBUGGING.md).
|
|
||||||
|
|
||||||
## Notes for other distros <a name="notes"></a>
|
|
||||||
|
|
||||||
### Arch Linux
|
|
||||||
|
|
||||||
Instead of running `install-build-deps.sh` to install build dependencies, run:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
$ sudo pacman -S --needed automake autoconf base-devel curl xz squashfs-tools p7zip \
|
|
||||||
git tk python python-pkgconfig python-virtualenv python-oauth2client python-oauthlib \
|
|
||||||
perl gcc gcc-libs bison flex gperf pkgconfig dbus icoutils \
|
|
||||||
nss alsa-lib glib2 gtk3 nspr freetype2 cairo libgnome-keyring \
|
|
||||||
xorg-server-xvfb xorg-xdpyinfo
|
|
||||||
```
|
|
||||||
|
|
||||||
For the optional packages on Arch Linux:
|
|
||||||
|
|
||||||
* `php-cgi` is provided with `pacman`
|
|
||||||
* `wdiff` is not in the main repository but `dwdiff` is. You can get `wdiff`
|
|
||||||
in AUR/`yaourt`
|
|
||||||
|
|
||||||
### Crostini on ChromiumOS/ThoriumOS (Debian based)
|
|
||||||
|
|
||||||
First install the `file` and `lsb-release` commands for the script to run properly:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
$ sudo apt-get install file lsb-release
|
|
||||||
```
|
|
||||||
|
|
||||||
Then invoke install-build-deps.sh with the `--no-arm` argument,
|
|
||||||
because the ARM toolchain doesn't exist for this configuration:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
$ sudo build/install-build-deps.sh --no-arm
|
|
||||||
```
|
|
||||||
|
|
||||||
### Fedora
|
|
||||||
|
|
||||||
Instead of running `build/install-build-deps.sh`, run:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
su -c 'yum install git python bzip2 tar pkgconfig atk-devel alsa-lib-devel \
|
|
||||||
bison binutils brlapi-devel bluez-libs-devel bzip2-devel cairo-devel \
|
|
||||||
cups-devel dbus-devel dbus-glib-devel expat-devel fontconfig-devel \
|
|
||||||
freetype-devel gcc-c++ glib2-devel glibc.i686 gperf glib2-devel \
|
|
||||||
gtk3-devel java-1.*.0-openjdk-devel libatomic libcap-devel libffi-devel \
|
|
||||||
libgcc.i686 libgnome-keyring-devel libjpeg-devel libstdc++.i686 libX11-devel \
|
|
||||||
libXScrnSaver-devel libXtst-devel libxkbcommon-x11-devel ncurses-compat-libs \
|
|
||||||
nspr-devel nss-devel pam-devel pango-devel pciutils-devel \
|
|
||||||
pulseaudio-libs-devel zlib.i686 httpd mod_ssl php php-cli python-psutil wdiff \
|
|
||||||
xorg-x11-server-Xvfb'
|
|
||||||
```
|
|
||||||
|
|
||||||
The fonts needed by Blink's web tests can be obtained by following [these
|
|
||||||
instructions](https://gist.github.com/pwnall/32a3b11c2b10f6ae5c6a6de66c1e12ae).
|
|
||||||
For the optional packages:
|
|
||||||
|
|
||||||
* `php-cgi` is provided by the `php-cli` package.
|
|
||||||
* `sun-java6-fonts` is covered by the instructions linked above.
|
|
||||||
|
|
||||||
### Gentoo
|
|
||||||
|
|
||||||
You can install the deps by doing a dry run of `emerge www-client/chromium`.
|
|
||||||
|
|
||||||
---------------------------------
|
|
||||||
*Happy Thorium Building!*
|
|
||||||
|
|
||||||
<img src="https://github.com/Alex313031/thorium/blob/main/logos/STAGING/Thorium90_504.jpg" width="200">
|
|
25
infra/BUILDING_OLD.md
Normal file
25
infra/BUILDING_OLD.md
Normal file
|
@ -0,0 +1,25 @@
|
||||||
|
> __*NOTE: This document is out of date, and kept for historical purposes only. You should follow the docs located [HERE](https://github.com/Alex313031/thorium/tree/main/docs#readme)*__
|
||||||
|
|
||||||
|
## Building <img src="https://github.com/Alex313031/Thorium/blob/main/logos/NEW/build_light.svg#gh-dark-mode-only"> <img src="https://github.com/Alex313031/Thorium/blob/main/logos/NEW/build_dark.svg#gh-light-mode-only">
|
||||||
|
|
||||||
|
_**The scripts assume the Chromium source is at $HOME/chromiums/src/ and Thorium is at $HOME/thorium/. You may have to 'sudo chmod +x' the scripts to make them executable.**_
|
||||||
|
- __UPDATE:__ For Windows and Windows [AVX2](https://en.wikipedia.org/wiki/Advanced_Vector_Extensions#Advanced_Vector_Extensions_2), I made new dedicated instructions. If you are building on Windows use > [WIN_INSTRUCTIONS.txt](https://github.com/Alex313031/Thorium/blob/main/misc/WIN_INSTRUCTIONS.txt) and if you are building for Windows on Linux, use > [WIN_CROSS_BUILD_INSTRUCTIONS.txt](https://github.com/Alex313031/Thorium/blob/main/misc/WIN_CROSS_BUILD_INSTRUCTIONS.txt)
|
||||||
|
- In general we follow build instructions at https://chromium.googlesource.com/chromium/src/+/refs/heads/main/docs/linux/build_instructions.md and API Keys (if desired) at https://www.chromium.org/developers/how-tos/api-keys <img src="https://github.com/Alex313031/Thorium/blob/main/logos/NEW/Key_Light.svg#gh-dark-mode-only" width="28"> <img src="https://github.com/Alex313031/Thorium/blob/main/logos/NEW/Key_Dark.svg#gh-light-mode-only" width="28">
|
||||||
|
- Make sure dependencies are installed by running ./chromium/src/build/install-build-deps.sh.
|
||||||
|
- After initial download of Chromium source code, run (from where you cloned this repo) `./trunk.sh`. This will update and sync the sources and at the end it will download the PGO profile for Chromium for all platforms. The file will be downloaded to *//chromium/src/chrome/build/pgo_profiles/*.profdata* with the actual file name looking something like 'chrome-linux-main-1632505958-ddbb37bcdfa7dbd7b10cf3a9b6a5bc45e7a958a6.profdata', which should be added to the end of args.gn as per below.
|
||||||
|
- Then, (from where you cloned this repo) run `./setup.sh`. This will copy all the files and patches to the needed locations and drop you to *//chromium/src*.
|
||||||
|
- Run `gn args out/thorium` and the contents of '[args.gn](https://github.com/Alex313031/Thorium/blob/main/args.gn)' in the root of this repo should be copy/pasted into the editor. Note that for Windows, Mac, ChromiumOS, or Android there are seperate *_args.gn files for those platforms. *--Include your api keys here at the top or leave blank, and edit the last line to point to the actual path and file name of '*.profdata'*
|
||||||
|
- For more info about args.gn, read the [ABOUT_GN_ARGS.md](https://github.com/Alex313031/Thorium/blob/main/infra/DEBUG/ABOUT_GN_ARGS.md) file.
|
||||||
|
- '[infra/args.list](https://github.com/Alex313031/Thorium/blob/main/infra/args.list)' contains an alphabetical list with descriptions of all possible build arguments; [gn_args.list](https://github.com/Alex313031/Thorium/blob/main/infra/gn_args.list) gives a similar list but with the flags in args.gn added.
|
||||||
|
- To build, run `./build.sh` (--help for help). For Windows, use `build_win.sh` or `autoninja -C out\thorium chrome chromedriver thorium_shell setup mini_installer -j8` *The -j# can be changed to limit or increase the number of jobs (generally should be the number of CPU cores on your machine)*
|
||||||
|
- To install, copy/paste the contents of your *out/thorium* dir to a good location, i.e. *$HOME/bin/thorium*. **RECOMMENDED** *- Copy and run [clean.sh](https://github.com/Alex313031/Thorium/blob/main/clean.sh) within this dir to clean up build artifacts.* Then you can just run the browser with `~/bin/thorium/chrome`, the content_shell with `~/bin/thorium/thorium_shell`, or chromedriver with `~/bin/thorium/chromedriver`.
|
||||||
|
- **Proper Install:** To install with a .deb, dont copy the contents of *out/thorium*; instead run <br/> `./thordeb.sh` (--help for help). A nice .deb file will now be in *out/thorium* and you can install it with `sudo dpkg -i *.deb` It will be called 'thorium-browser-stable_$VERSIONNUMBER_amd64.deb', and will be installed to */opt/chromium.org/thorium/*. For Windows, just run the mini_installer.exe. \
|
||||||
|
- **Appimage:** You can also make an [Appimage](https://appimage.org/) of Thorium after making the .deb. See > [Appimage README.md](https://github.com/Alex313031/Thorium/tree/main/infra/APPIMAGE#readme)
|
||||||
|
|
||||||
|
__NOTE:__ To get back to "Trunk", i.e. to revert all changes in order to build vanilla Chromium or to update your checkout, just run `./trunk.sh` again. \
|
||||||
|
__NOTE:__ To compile without AVX, simply go to *//chromium/src/build/config/compiler/BUILD.gn*, search for *avx*, and replace *avx* with *sse3* or *sse4*. \
|
||||||
|
__UPDATE:__ Thorium now has API Keys baked in but the instructions below are the same if you are building it yourself as I will not include the keys here. | args.gn exclude API Keys (you can get them yourself) and the PGO profile path is different for each Chromium version (only needed when building). (See above.)
|
||||||
|
|
||||||
|
*Happy Thorium Building!*
|
||||||
|
|
||||||
|
<img src="https://github.com/Alex313031/Thorium/blob/main/logos/STAGING/Thorium90_504.jpg" width="200">
|
Loading…
Reference in a new issue