From 1a70d0c93ba16335dd77d947c2e9c6fd080977c4 Mon Sep 17 00:00:00 2001
From: dpranke <dpranke@chromium.org>
Date: Wed, 30 Nov 2016 18:42:29 -0800
Subject: [PATCH] More fixes to the build instructions.

This picks up various fixes noted by scottmg@chromium.org,
thakis@chromium.org, and Twitter user @florpelier, as well as a few
more things I wanted to clean up.

R=scottmg@chromium.org, thakis@chromium.org, sdy@chromium.org
BUG=

Review-Url: https://codereview.chromium.org/2543503004
Cr-Commit-Position: refs/heads/master@{#435533}
---
 docs/android_build_instructions.md | 11 ++++--
 docs/get_the_code.md               |  4 +--
 docs/ios_build_instructions.md     | 11 ++++--
 docs/linux_build_instructions.md   | 12 +++++--
 docs/mac_build_instructions.md     | 29 +++++++++++++---
 docs/windows_build_instructions.md | 56 +++++++++++++++++++-----------
 6 files changed, 89 insertions(+), 34 deletions(-)

diff --git a/docs/android_build_instructions.md b/docs/android_build_instructions.md
index 5f577ee0b2326..2e8d7de67ef52 100644
--- a/docs/android_build_instructions.md
+++ b/docs/android_build_instructions.md
@@ -1,7 +1,14 @@
-# Android Build Instructions
+# Checking out and building Chromium for Android
+
+There are instructions for other platforms linked from the 
+[get the code](get_the_code.md) page.
 
 **See also [the old version of this page](old_android_build_instructions.md).**
 
+## Instructions for Google Employees
+
+Are you a Google employee? See
+[go/building-chrome](https://goto.google.com/building-chrome) instead.
 Google employee? See [go/building-chrome](https://goto.google.com/building-chrome) instead.
 
 [TOC]
@@ -121,7 +128,7 @@ $ sudo update-alternatives --config jar
 $ sudo update-alternatives --config jarsigner
 ```
 
-## Setting up the Build
+## Setting up the build
 
 Chromium uses [Ninja](https://ninja-build.org) as its main build tool along
 with a tool called [GN](../tools/gn/docs/quick_start.md) to generate `.ninja`
diff --git a/docs/get_the_code.md b/docs/get_the_code.md
index 1ab8ce54e1efb..0308a2dad4a97 100644
--- a/docs/get_the_code.md
+++ b/docs/get_the_code.md
@@ -10,8 +10,8 @@ all over the place, we have a self-contained page for each configuration
 you might want to build:
 
 * [Android](android_build_instructions.md)
-* [Cast](cast_build_instructions.md)
-* [ChromeOS](chromeos_build_instructions.md)
+* [Cast](old_cast_build_instructions.md)
+* [ChromeOS](old_chromeos_build_instructions.md)
 * [iOS](ios_build_instructions.md)
 * [Linux](linux_build_instructions.md)
 * [Mac](mac_build_instructions.md)
diff --git a/docs/ios_build_instructions.md b/docs/ios_build_instructions.md
index 7b4541d3f2503..685971cdeabfe 100644
--- a/docs/ios_build_instructions.md
+++ b/docs/ios_build_instructions.md
@@ -1,7 +1,14 @@
-# iOS Build Instructions
+# Checking out and building Chromium for iOS
+
+There are instructions for other platforms linked from the 
+[get the code](get_the_code.md) page.
 
 **See also [the old version of this page](old_ios_build_instructions.md).**
 
+## Instructions for Google Employees
+
+Are you a Google employee? See
+[go/building-chrome](https://goto.google.com/building-chrome) instead.
 Google employee? See [go/building-chrome](https://goto.google.com/building-chrome) instead.
 
 [TOC]
@@ -101,7 +108,7 @@ You can also follow the manual instructions on the
 [Mac page](mac_build_instructions.md), but make sure you set the
 GN arg `target_os="ios"`.
 
-## Running
+## Running `ios_web_shell`
 
 Any target that is built and runs on the bots (see [below](#Troubleshooting))
 should run successfully in a local build. As of the time of writing, this is
diff --git a/docs/linux_build_instructions.md b/docs/linux_build_instructions.md
index 88c4dcef9a0bd..fdfa120de6376 100644
--- a/docs/linux_build_instructions.md
+++ b/docs/linux_build_instructions.md
@@ -1,8 +1,14 @@
 # Checking out and building Chromium on Linux
 
+There are instructions for other platforms linked from the 
+[get the code](get_the_code.md) page.
+
 **See also [the old version of this page](old_linux_build_instructions.md).**
 
-Google employee? See [go/building-chrome](https://goto.google.com/building-chrome) instead.
+## Instructions for Google Employees
+
+Are you a Google employee? See
+[go/building-chrome](https://goto.google.com/building-chrome) instead.
 
 [TOC]
 
@@ -97,7 +103,7 @@ 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
+## Setting up the build
 
 Chromium uses [Ninja](https://ninja-build.org) as its main build tool along
 with a tool called [GN](../tools/gn/docs/quick_start.md) to generate `.ninja`
@@ -151,7 +157,7 @@ You can run the tests in the same way. You can also limit which tests are
 run using the `--gtest_filter` arg, e.g.:
 
 ```shell
-$ ninja -C out/Default unit_tests --gtest_filter="PushClientTest.*"
+$ out/Default/unit_tests --gtest_filter="PushClientTest.*"
 ```
 
 You can find out more about GoogleTest at its
diff --git a/docs/mac_build_instructions.md b/docs/mac_build_instructions.md
index a6521c9979ae9..ea1c26022533b 100644
--- a/docs/mac_build_instructions.md
+++ b/docs/mac_build_instructions.md
@@ -1,6 +1,14 @@
-# Mac Build Instructions
+# Checking out and building Chromium for Mac
 
-Google employee? See [go/building-chrome](https://goto.google.com/building-chrome) instead.
+There are instructions for other platforms linked from the 
+[get the code](get_the_code.md) page.
+
+**See also [the old version of this page](old_mac_build_instructions.md).**
+
+## Instructions for Google Employees
+
+Are you a Google employee? See
+[go/building-chrome](https://goto.google.com/building-chrome) instead.
 
 [TOC]
 
@@ -69,7 +77,7 @@ 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.
 
-## Building
+## Setting up the build
 
 Chromium uses [Ninja](https://ninja-build.org) as its main build tool along
 with a tool called [GN](../tools/gn/docs/quick_start.md) to generate `.ninja`
@@ -128,6 +136,19 @@ in gdb).
 
 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
+$ ninja -C out/Default chrome
+```
+
+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 `ninja -C
+out/Default chrome/test:unit_tests`).
+
 ## Run Chromium
 
 Once it is built, you can simply run the browser:
@@ -142,7 +163,7 @@ You can run the tests in the same way. You can also limit which tests are
 run using the `--gtest_filter` arg, e.g.:
 
 ```
-$ ninja -C out/Default unit_tests --gtest_filter="PushClientTest.*"
+$ out/Default/unit_tests --gtest_filter="PushClientTest.*"
 ```
 
 You can find out more about GoogleTest at its
diff --git a/docs/windows_build_instructions.md b/docs/windows_build_instructions.md
index acf167517d7a1..45cb30602160a 100644
--- a/docs/windows_build_instructions.md
+++ b/docs/windows_build_instructions.md
@@ -1,8 +1,14 @@
-# Checking out and building Chromium on Windows
+# Checking out and Building Chromium for Windows
+
+There are instructions for other platforms linked from the 
+[get the code](get_the_code.md) page.
 
 **See also [the old version of this page](old_linux_build_instructions.md).**
 
-Google employee? See [go/building-chrome](https://goto.google.com/building-chrome) instead.
+## Instructions for Google Employees
+
+Are you a Google employee? See
+[go/building-chrome](https://goto.google.com/building-chrome) instead.
 
 [TOC]
 
@@ -16,12 +22,6 @@ Google employee? See [go/building-chrome](https://goto.google.com/building-chrom
 
 ## Setting up Windows
 
-### System locale
-
-You must set your Windows system locale to English, or else you may get
-build errors about "The file contains a character that cannot be
-represented in the current code page."
-
 ### Visual Studio
 
 As of March 11, 2016 Chromium requires Visual Studio 2015 to build.
@@ -37,12 +37,12 @@ and select:
 You must have the 10586 SDK installed or else you will hit compile errors such
 as redefined macros.
 
-Install Windows Driver Kit (WDK) 10, or use some other method to get the
-Debugging Tools for Windows.
+Install the Windows SDK 10, and choose Debugging Tools For Windows when you
+install this in order to get windbg.
 
 ## Install `depot_tools`
 
-Download the (depot_tools bundle)[https://storage.googleapis.com/chrome-infra/depot_tools.zip]
+Download the [depot_tools bundle](https://storage.googleapis.com/chrome-infra/depot_tools.zip)
 and extract it somewhere.
 
 *** note
@@ -65,7 +65,8 @@ Without Administrator access:
 
 Control Panel → User Accounts → User Accounts → Change my environment variables
 
-Add a PATH user variable: C:\src\depot_tools;%PATH%.
+Add a PATH user variable (or modify the existing one to include):
+`C:\src\depot_tools`.
 
 Also, add a DEPOT_TOOLS_WIN_TOOLCHAIN system variable in the same way, and set
 it to 0. This tells depot_tools to use your locally installed version of Visual
@@ -122,7 +123,7 @@ 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.
 
-## Building
+## Setting up the build
 
 Chromium uses [Ninja](https://ninja-build.org) as its main build tool along
 with a tool called [GN](../tools/gn/docs/quick_start.md) to generate `.ninja`
@@ -151,8 +152,9 @@ argument to `gn gen` when you generate your output directory (as described on
 the [get the code](http://dev.chromium.org/developers/how-tos/get-the-code)
 page):
 
-```gn gen --ide=vs out\Default
-devenv out\Default\all.sln
+```shell
+$ gn gen --ide=vs out\Default
+$ devenv out\Default\all.sln
 ```
 
 GN will produce a file `all.sln` in your build directory. It will internally
@@ -167,7 +169,9 @@ for only the code you're interested in, although this will also limit what
 files appear in the project explorer. A minimal solution that will let you
 compile and run Chrome in the IDE but will not show any source files is:
 
-```gn gen --ide=vs --filters=//chrome out\Default```
+```
+$ gn gen --ide=vs --filters=//chrome out\Default
+```
 
 There are other options for controlling how the solution is generated, run `gn
 help gen` for the current documentation.
@@ -185,7 +189,9 @@ be recompiled.
 
 Build Chromium (the "chrome" target) with Ninja using the command:
 
-    $ ninja -C out\Default chrome
+```shell
+$ ninja -C out\Default chrome
+```
 
 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
@@ -196,14 +202,20 @@ use ninja -C out/Default chrome/test:unit_tests`).
 
 Once it is built, you can simply run the browser:
 
-    $ out\Default\chrome.exe
+```shell
+$ out\Default\chrome.exe
+```
+
+(The ".exe" suffix in the command is actually optional).
 
 ## Running test targets
 
 You can run the tests in the same way. You can also limit which tests are
 run using the `--gtest_filter` arg, e.g.:
 
-    $ ninja -C out\Default unit_tests --gtest_filter="PushClientTest.*"
+```shell
+$ out\Default\unit_tests.exe --gtest_filter="PushClientTest.*"
+```
 
 You can find out more about GoogleTest at its
 [GitHub page](https://github.com/google/googletest).
@@ -212,8 +224,10 @@ You can find out more about GoogleTest at its
 
 To update an existing checkout, you can run
 
-    $ git rebase-update
-    $ gclient sync
+```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/master`).
-- 
GitLab