Add files via upload
This commit is contained in:
Alexander David Frick
GitHub
parent
aa3a731da6
commit
c39cff9800
1 changed files with 254 additions and 0 deletions
254
docs/BUILDING_WIN.md
Normal file
254
docs/BUILDING_WIN.md
Normal file
|
|
@ -0,0 +1,254 @@
|
|||
# Checking out and Building Thorium for Windows
|
||||
|
||||
## System requirements
|
||||
|
||||
* A 64-bit machine with at least 8GB of RAM. More than 16GB is highly
|
||||
recommended.
|
||||
* At least 75GB of free disk space on an NTFS-formatted hard drive. FAT32
|
||||
will not work, as some of the Git packfiles are larger than 4GB.
|
||||
* An appropriate version of Visual Studio, as described below.
|
||||
* Windows 10 1709 or newer.
|
||||
|
||||
## Setting up Windows
|
||||
|
||||
### Visual Studio
|
||||
|
||||
Chromium requires [Visual Studio 2019](https://visualstudio.microsoft.com/vs/older-downloads/) (>=16.0.0)
|
||||
to build, but [Visual Studio 2022](https://visualstudio.microsoft.com/vs/) (>=17.0.0)
|
||||
is preferred. Visual Studio can also be used to debug Chromium, and version 2022 is
|
||||
preferred for this as it handles Chromium's large debug information much better.
|
||||
The clang-cl compiler is used but Visual Studio's header files, libraries, and
|
||||
some tools are required. Visual Studio Community Edition should work if its
|
||||
license is appropriate for you. You must install the "Desktop development with
|
||||
C++" component and the "MFC/ATL support" sub-components. This can be done from
|
||||
the command line by passing these arguments to the Visual Studio installer (see
|
||||
below for ARM64 instructions):
|
||||
```shell
|
||||
$ VisualStudioSetup.exe --add Microsoft.VisualStudio.Workload.NativeDesktop --add Microsoft.VisualStudio.Component.VC.ATLMFC --includeRecommended
|
||||
```
|
||||
|
||||
If you want to build for Windows on ARM64 then some extra arguments are needed. The
|
||||
full set for that case is:
|
||||
```shell
|
||||
$ VisualStudioSetup.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.1.20348.0 [Windows 10 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 19043 version by default, uncheck this and check the 20348 version).
|
||||
There is also experimental support for the Windows 11 10.1.22000.0 version.
|
||||
|
||||
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.
|
||||
|
||||
## Install `depot_tools`
|
||||
|
||||
Download the [depot_tools bundle](https://storage.googleapis.com/chrome-infra/depot_tools.zip)
|
||||
and extract it somewhere (eg: C:\src\depot_tools).
|
||||
|
||||
*** note
|
||||
**Warning:** **DO NOT** use drag-n-drop or copy-n-paste extract from Explorer,
|
||||
this will not extract the hidden “.git” folder which is necessary for
|
||||
depot_tools to autoupdate itself. You can use “Extract all…” from the
|
||||
context menu though.
|
||||
***
|
||||
|
||||
Add depot_tools to the start of your PATH (must be ahead of any installs of
|
||||
Python. Note that environment variable names are case insensitive).
|
||||
|
||||
Assuming you unzipped the bundle to *C:\src\depot_tools*, open:
|
||||
|
||||
Control Panel → System and Security → System → Advanced system settings
|
||||
|
||||
If you have Administrator access, Modify the PATH system variable and
|
||||
put `C:\src\depot_tools` at the front (or at least in front of any directory
|
||||
that might already have a copy of Python or Git).
|
||||
|
||||
If you don't have Administrator access, you can add a user-level PATH
|
||||
environment variable by opening:
|
||||
|
||||
Control Panel → System and Security → System → Search for "Edit environment variables for your account"
|
||||
|
||||
Add `C:\src\depot_tools` at the front. Note: If your system PATH has a Python in it, you will be out of luck.
|
||||
|
||||
Also, add a `DEPOT_TOOLS_WIN_TOOLCHAIN` environment variable in the same way, and set
|
||||
it to __0__. This tells depot_tools to use your locally installed version of Visual
|
||||
Studio (by default, depot_tools will try to use a google-internal version).
|
||||
|
||||
You should also set the variable `vs2019_install` or
|
||||
`vs2022_install` to your installation path of Visual Studio 19 or 22, like
|
||||
`vs2019_install` = __C:\Program Files (x86)\Microsoft Visual Studio\2019\Community__
|
||||
for Visual Studio 2019, or
|
||||
`vs2022_install` = __C:\Program Files\Microsoft Visual Studio\2022\Community__
|
||||
for Visual Studio 2022.
|
||||
|
||||
Once all of this is done, we will download some infra archives using `gclient`
|
||||
From a cmd.exe shell, run:
|
||||
|
||||
```shell
|
||||
$ gclient
|
||||
```
|
||||
|
||||
On first run, gclient will install all the Windows-specific bits needed to work
|
||||
with the code, including msysgit and Python.
|
||||
|
||||
* If you run gclient from a non-cmd shell (e.g., cygwin, PowerShell),
|
||||
it may appear to run properly, but msysgit, python, and other tools
|
||||
may not get installed correctly.
|
||||
* If you see strange errors with the file system on the first run of gclient,
|
||||
you may want to [disable Windows Indexing](https://tortoisesvn.net/faq.html#cantmove2).
|
||||
|
||||
## Check Python install
|
||||
|
||||
After running gclient open a command prompt and type `where python` and
|
||||
confirm that the depot_tools `python.bat` comes ahead of any copies of
|
||||
python.exe. Failing to ensure this can lead to overbuilding when
|
||||
using gn - see [crbug.com/611087](https://crbug.com/611087).
|
||||
|
||||
[App Execution Aliases](https://docs.microsoft.com/en-us/windows/apps/desktop/modernize/desktop-to-uwp-extensions#alias) in Windows 10/11
|
||||
can conflict with other installations of python on the system so disable
|
||||
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'.
|
||||
|
||||
## Download the Chromium code
|
||||
|
||||
First, configure Git:
|
||||
|
||||
```shell
|
||||
$ 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
|
||||
```
|
||||
|
||||
Create a `chromium` directory in *C:\src* for the checkout and change to it.
|
||||
|
||||
```shell
|
||||
$ cd / && cd src && mkdir chromium && cd chromium
|
||||
```
|
||||
|
||||
Run the `fetch` tool from `depot_tools` to check out the code and its
|
||||
dependencies.
|
||||
|
||||
```shell
|
||||
$ 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`.
|
||||
|
||||
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 this directory (i.e. *C:\src\chromium\src*):
|
||||
|
||||
```shell
|
||||
$ cd src
|
||||
```
|
||||
|
||||
*Optional*: You can also build with [API
|
||||
keys](https://www.chromium.org/developers/how-tos/api-keys) if you want features like Google Sync, Translate, Gelocation API, etc.
|
||||
Thorium release builds use a private API Keys repo, if you would like access, contact me. Otherwise you can follow the above link to learn how to make your own private developer keys.
|
||||
|
||||
## Downloading the Thorium code
|
||||
|
||||
You can either use git clone, or download a .zip from the repo. It should be placed side by side with the Chromium directory in *C:\src*
|
||||
Using Git:
|
||||
|
||||
```shell
|
||||
$ git clone https://github.com/Alex313031/Thorium.git
|
||||
```
|
||||
Or download the .zip (Make sure to rename the extracted dir to just Thorium, not Thorium-main).
|
||||
[https://github.com/Alex313031/Thorium/archive/refs/heads/main.zip](https://github.com/Alex313031/Thorium/archive/refs/heads/main.zip)
|
||||
|
||||
## Setting up the build
|
||||
|
||||
First, we need to copy the Thorium source files over the Chromium tree.
|
||||
Run the `setup.bat` script in *Thorium\win_scripts* to automate this.
|
||||
|
||||
```shell
|
||||
$ cd C:\src\Thorium\win_scripts && setup.bat
|
||||
```
|
||||
It will drop you back to *C:\src\chromium\src*, which is where the rest of the commands will be carried out.
|
||||
|
||||
Next, we will download the PGO profile for Thorium, which changes with every revision. Run:
|
||||
|
||||
```shell
|
||||
$ python3 tools\update_pgo_profiles.py --target=win64 update --gs-url-base=chromium-optimization-profiles/pgo_profiles
|
||||
```
|
||||
This will download a *.profdata file, looking something like `chrome-win64-main-1659409120-058034bd778fed227d12a29fd0edd0942810dbf8.profdata`
|
||||
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. Create the build directory by running:
|
||||
|
||||
```shell
|
||||
$ 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/infra/win_args.gn) file from *C:\src\Thorium\infra\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.
|
||||
__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:
|
||||
|
||||
`pgo_data_path = "C:\src\chromium\src\chrome\build\pgo_profiles\chrome-win64-main-1659409120-058034bd778fed227d12a29fd0edd0942810dbf8.profdata"`
|
||||
|
||||
* For other build arguments, and what the ones that Thorium uses do, see [ABOUT_GN_ARGS.md](https://github.com/Alex313031/Thorium/blob/main/infra/DEBUG/ABOUT_GN_ARGS.md) & [win_args.list](https://github.com/Alex313031/Thorium/blob/main/infra/win_args.list)
|
||||
* 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).
|
||||
|
||||
## Build Thorium
|
||||
|
||||
Build Thorium, and the other things like chromedriver and thorium_shell with Ninja using the command:
|
||||
|
||||
```shell
|
||||
$ autoninja -C out\thorium chrome chromedriver thorium_shell setup mini_installer -j8
|
||||
```
|
||||
(Where -j# can be any number, and should generally be set to the number of cores on your CPU)
|
||||
|
||||
`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 to Ninja
|
||||
the GN label with no preceding "//" (so for `//chrome/test:unit_tests`
|
||||
use autoninja -C out/Default chrome/test:unit_tests).
|
||||
|
||||
## Install/Run Thorium
|
||||
|
||||
Once it is built, you can simply install the browser.
|
||||
|
||||
```shell
|
||||
$ out\thorium\mini_installer.exe
|
||||
```
|
||||
|
||||
## Update your checkout
|
||||
|
||||
To update an existing Chromium checkout, you should run the `trunk.bat` script in win_scripts:
|
||||
|
||||
```shell
|
||||
$ cd C:\src\Thorium\win_scripts && trunk.bat
|
||||
```
|
||||
(This script will also download the latest PGO profile data file at the end.)
|
||||
|
||||
This syncs the subrepositories to the appropriate versions,
|
||||
deleting those that are no longer needed, and re-runs the hooks as needed.
|
||||
|
||||
To update an existing Thorium checkout, just download the latest .zip, or do a git pull:
|
||||
|
||||
```shell
|
||||
$ cd C:\src\Thorium\win_scripts && trunk.bat
|
||||
```
|
||||
|
||||
*Happy Thorium Building!*
|
||||
Loading…
Reference in a new issue