Thorium_Archive
/
thorium-mirror
mirror of https://github.com/Alex313031/thorium.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

update docs and scripts

This commit is contained in:
Alexander Frick 2024-02-14 07:45:45 -06:00
parent d16e02a8b8
commit 137dc4bc9e
5 changed files with 94 additions and 142 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
build_mac.sh
View File

@ -1,6 +1,6 @@
#!/bin/bash
# Copyright (c) 2024 Alex313031.
# Copyright (c) 2024 Alex313031 and midzer.
YEL='\033[1;33m' # Yellow
CYA='\033[1;96m' # Cyan
@ -37,7 +37,7 @@ buildShell () {
export NINJA_SUMMARIZE_BUILD=1 &&
cd ${CR_SRC_DIR} &&
autoninja -C out/thorium chrome chromedriver thorium_shell -j$@ &&
autoninja -C out/thorium thorium chromedriver thorium_shell -j$@ &&
cat ~/thorium/logos/thorium_logo_ascii_art.txt &&
@ -66,7 +66,7 @@ export NINJA_SUMMARIZE_BUILD=1 &&
export NINJA_STATUS="[%r processes, %f/%t @ %o/s | %e sec. ] " &&
cd ${CR_SRC_DIR} &&
autoninja -C out/thorium chrome chromedriver -j$@ &&
autoninja -C out/thorium thorium chromedriver -j$@ &&
cat ~/thorium/logos/thorium_logo_ascii_art.txt &&

8
docs/BUILDING.md
View File

@ -2,6 +2,7 @@
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)
@ -120,7 +121,7 @@ to enable Sync.
## Setting up the build <a name="setup"></a>
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. \
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__
@ -128,13 +129,13 @@ This will update and sync the sources to the latest revision (tip of tree) and e
- 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/&#42;.profdata* with the actual file name looking something like 'chrome-linux-6167-1706004111-41f78c57fb3a1fe49a5c549b16f0221465339af9.profdata', which should be added to the end of args.gn as per below.
Take note of this, as we will be using it in the `args.gn` 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*.
- Then, (from where you cloned this repo) run `./setup.sh`. This will copy all the files and patches to the needed locations.
- NOTE: To build for MacOS, use `./setup.sh --mac`. To build for Raspberry Pi, use `./setup.sh --raspi`. Use `./setup.sh --help` to see all options/platforms.
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:
with different configurations. Create the build output directory by running:
- 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 &#42;_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 '&#42;.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.
@ -243,6 +244,7 @@ Simply run `trunk.sh` in the root of the Thorium repo or execute the commands in
```shell
$ ./trunk.sh
```
## Running test targets
Tests are split into multiple test targets based on their type and where they

189
docs/BUILDING_MAC.md
View File

@ -1,19 +1,12 @@
# 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]
There are instructions for other platforms here in the Thorium Docs directory.
## System requirements
* A Mac, Intel or Arm.
([More details about Arm Macs](https://chromium.googlesource.com/chromium/src.git/+/main/docs/mac_arm64.md).)
* MacOS 10.15 or higher.
* [Xcode](https://developer.apple.com/xcode/). Xcode comes with...
* The macOS SDK. Run
@ -38,7 +31,7 @@ Are you a Google employee? See
version of the macOS SDK on it.
* An APFS-formatted volume (this is the default format for macOS volumes).
## Downloading the Thorium code
## Downloading the Thorium code <a name="get-the-code"></a>
Using Git:
```shell
@ -62,7 +55,7 @@ not be able to find infra tools):
$ export PATH="$PATH:/path/to/depot_tools"
```
## Get the code
## Get the Chromium 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
@ -105,104 +98,106 @@ development and testing purposes.
## Setting up the build
First, we need to make sure we have all the tags/branches and are on Tip of Tree.
For this, run (from within the Thorium repo):
```shell
./trunk.sh
```
Secondly, we need to check out the revision that Thorium is currently using.
For this, run:
```shell
./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 for MacOS will be downloaded to */Users/$USERNAME/chromium/src/build/pgo_profiles/&#42;.profdata* with the actual file name looking something like
'chrome-mac-6167-1706032279-25144dc1c87be275c5981becbafed7785e2f39f2.profdata', which should be added to the end of args.gn as per below.
Take note of this, as we will be using it in the `args.gn` below.
Lastly, we need to copy the Thorium source files over the Chromium tree.
For this, run:
```shell
./setup.sh --mac
```
This will copy all the files and patches to the needed locations.
- NOTE: To build for arm64, use `./setup.sh --mac-arm`. Use `./setup.sh --help` to see all options/platforms.
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:
with different configurations. Create the build output directory by running:
```shell
$ gn gen out/Default
$ gn args out/thorium
```
The contents of '[mac_args.gn](https://github.com/Alex313031/thorium/blob/other/Mac/mac_args.gn)' in the root of this repo should be copy/pasted into the editor.
*and edit the last line to point to the actual path and file name of the '&#42;.profdata' it*
Use the '[mac_ARM_args.gn](https://github.com/Alex313031/thorium/blob/other/Mac/mac_ARM_args.gn)' for arm64 builds.
* 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).
* Building Thorium for arm64 Macs requires [additional setup](mac_arm64.md).
### Faster builds
## Build Thorium <a name="build"></a>
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:
Build Thorium (the "chrome" target) with Ninja using the command:
```shell
$ autoninja -C out/Default chrome
$ autoninja -C out/thorium thorium chromedriver
```
(`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
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/Default chrome/test:unit_tests`).
out/thorium chrome/test:unit_tests`).
## Run Chromium
## Run/Install Thorium
Once it is built, you can simply run the browser:
```shell
$ out/Default/Chromium.app/Contents/MacOS/Chromium
$ out/thorium/Thorium.app/Contents/MacOS/Thorium
```
## Avoiding system permissions dialogs after each build
To generate a .dmg installation package, run (from within the Thorium repo):
```shell
$ ./build_dmg.sh
```
## Avoiding repetitive 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
`Thorium wants to use your confidential information stored in "Thorium Safe
Storage" in your keychain.`, and `Do you want the application "Thorium.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):
To avoid them, you can run Thorium with these command-line flags (but of
course beware that they will change the behavior of certain subsystems, like password storage):
```shell
--use-mock-keychain --disable-features=DialMediaRouteProvider
```
## Debugging
Good debugging tips can be found [here](mac/debugging.md).
If you have problems building, join us in the Thorium IRC Channel at
`#thorium` on `irc.libera.chat` and ask there.
## Build and run test targets
Tests are split into multiple test targets based on their type and where they
@ -210,7 +205,7 @@ 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
$ gn refs out/thorium --testonly=true --type=executable --all chrome/browser/ui/browser_list_unittest.cc
//chrome/test:unit_tests
```
@ -218,77 +213,29 @@ 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
$ autoninja -C out/thorium 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.*"
$ out/thorium/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
To update an existing checkout, you can run (from within the Thorium repo):
```shell
$ git rebase-update
$ gclient sync
$ ./trunk.sh
```
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

29
docs/BUILDING_WIN.md
View File

@ -1,5 +1,7 @@
# Checking out and Building Thorium for Windows &nbsp;<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.
## System Requirements
* A 64-bit machine with at least 8GB of RAM. More than 16GB is highly
@ -33,7 +35,7 @@ VisualStudioSetup.exe --add Microsoft.VisualStudio.Workload.NativeDesktop --add
- You must have the version 10.1.22621.2428 [Windows 11 SDK](https://developer.microsoft.com/en-us/windows/downloads/sdk-archive/)
installed. This can be installed separately or by checking the appropriate box
in the Visual Studio Installer __(Note that MSVS 2022 will try to install the 22000 version by default, uncheck this and check the 22621 version)__.
in the Visual Studio Installer. __(Note that MSVS 2022 will try to install the 22000 version by default, uncheck this and check the 22621 version)__.
The 10.1.22621.2428 SDK Debugging Tools must also be installed. This
version of the Debugging tools is needed in order to support reading the
@ -83,7 +85,7 @@ Studio (by default, depot_tools will try to use a google-internal version).
You should also set the variable `vs2022_install` to your installation path of Visual Studio 22, like
`vs2022_install` = __C:\Program Files\Microsoft Visual Studio\2022\Community__
Once all of this is done, we will download some infra archives using `gclient`. \
Once all of this is done, we will download some infra archives using `gclient`.
From a __cmd.exe__ shell, run:
```shell
gclient
@ -111,7 +113,7 @@ these for 'python.exe' and 'python3.exe' by opening 'App execution aliases'
section of Control Panel and unticking the boxes next to both of these
that point to 'App Installer'.
## Downloading the Chromium code
## Downloading the Chromium code <a name="get-the-code"></a>
First, configure Git (you may want to backup your current .gitconfig file if it exists):
@ -160,7 +162,7 @@ to enable Sync.
## Downloading the Thorium code
Using Git:
It should be placed in $HOME, i.e. C:\Users\$USERNAME. \
It should be placed in $HOME, i.e. C:\Users\$USERNAME.
```shell
git clone --recursive https://github.com/Alex313031/thorium.git
@ -172,7 +174,7 @@ To use the build scripts, we need bash on Windows. It is recommended to use Git
All the following script instructions assume that Chromium is in *C:\src\chromium\src* and that you have changed to the thorium repo in bash.
First, we need to make sure we have all the tags/branches and are on Tip of Tree.
For this, run:
For this, run (from within the Thorium repo):
```shell
./trunk.sh
@ -185,19 +187,20 @@ For this, run:
./version.sh
```
Secondly, we need to copy the Thorium source files over the Chromium tree. \
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 for Windows will be downloaded to *C:\src\chromium\src\chrome\build\pgo_profiles\&#42;.profdata* with the actual file name looking something like
'chrome-win64-6167-1706032279-97e63d82a0938b7701d8cdf028299c39d523a3c6.profdata', which should be added to the end of args.gn as per below.
Take note of this, as we will be using it in the `args.gn` below.
Lastly, we need to copy the Thorium source files over the Chromium tree.
For this, run:
```shell
./setup.sh
```
This will copy all the files and patches to the needed locations.
- NOTE: To build for AVX2, use `./setup.sh --avx2`. To build SSE3, use `./setup.sh --sse3`. Use `./setup.sh --help` to see all options/platforms.
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 for Windows will be downloaded to *C:\src\chromium\src\chrome\build\pgo_profiles\&#42;.profdata* with the actual file name looking something like
'chrome-win64-6167-1706032279-97e63d82a0938b7701d8cdf028299c39d523a3c6.profdata', which should be added to the end of args.gn as per below.
Take note of this, as we will be using it in the `args.gn` below.
### Creating the build directory
Chromium & Thorium use [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.
@ -212,7 +215,7 @@ gn args out\thorium
This will open up notepad.exe, and this is where we will specify build arguments ("args") which direct Ninja on how to lay out the build directory tree.
We will be copy/pasting the contents of the [win_args.gn](https://github.com/Alex313031/thorium/blob/main/win_args.gn) file (from *C:\src\Thorium\win_args.gn*) into notepad.
Notice the three lines at the top, related to API Keys. It is fine to leave them blank, or add the ones you have made. \
Notice the three lines at the top, related to API Keys. It is fine to leave them blank, or add the ones you have made.
__At the bottom__, though, notice the line that says *pgo_data_path = ""*. This is where we will put the full path to the PGO profile data file we downloaded earlier.
That line should look something like:
@ -224,7 +227,7 @@ That line should look something like:
## Build Thorium <a name="build"></a>
Build Thorium, and the other things like [chromedriver](https://chromedriver.chromium.org/home) and [thorium_shell](https://github.com/Alex313031/thorium/tree/main/thorium_shell#readme) with Ninja using the command:
Build Thorium (the "chrome" target), and the other things like [chromedriver](https://chromedriver.chromium.org/home) and [thorium_shell](https://github.com/Alex313031/thorium/tree/main/thorium_shell#readme) with Ninja using the command:
```shell
autoninja -C out\thorium thorium chromedriver thorium_shell setup mini_installer -j8

4
trunk.sh
View File

@ -18,7 +18,7 @@ try() { "$@" || die "${RED}Failed $*"; }
# --help
displayHelp () {
printf "\n" &&
printf "${bold}${GRE}Script to Rebase/Sync Chromium repo.${c0}\n" &&
printf "${bold}${GRE}Script to Rebase/Sync the Chromium repo.${c0}\n" &&
# printf "${bold}${YEL}Use the --shallow flag to do a shallow sync, if you have downloaded${c0}\n" &&
# printf "${bold}${YEL}the Chromium repo with the --no-history flag.${c0}\n" &&
printf "\n"
@ -37,7 +37,7 @@ else
fi
printf "\n" &&
printf "${bold}${GRE}Script to Rebase/Sync Chromium repo.${c0}\n" &&
printf "${bold}${GRE}Script to Rebase/Sync the Chromium repo.${c0}\n" &&
printf "\n" &&
printf "${YEL}Rebasing/Syncing and running hooks...\n" &&
tput sgr0 &&