update docs and scripts

build_mac.sh

@@ -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 &&
 

docs/BUILDING.md

@@ -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

docs/BUILDING_MAC.md

@@ -1,19 +1,12 @@
 # Checking out and building Thorium for Mac
 
-There are instructions for other platforms linked from the
+There are instructions for other platforms here in the Thorium Docs directory.
-[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).)
+*   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
+Build Thorium (the "chrome" target) with Ninja using the command:
-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 -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
+`Thorium wants to use your confidential information stored in "Thorium Safe
-Storage" in your keychain.`, and `Do you want the application "Chromium.app" to
+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
+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):
+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
+$ ./trunk.sh
-$ 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

docs/BUILDING_WIN.md

@@ -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

trunk.sh

@@ -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 &&