diff options
| author | Allan Sandfeld Jensen <allan.jensen@qt.io> | 2022-02-04 17:20:24 +0100 |
|---|---|---|
| committer | Allan Sandfeld Jensen <allan.jensen@qt.io> | 2022-02-12 08:15:25 +0000 |
| commit | 8fa0776f1f79e91fc9c0b9c1ba11a0a29c05196b (patch) | |
| tree | 788d8d7549712682703a0310ca4a0f0860d4802b /chromium/docs/website/site/developers/how-tos | |
| parent | 606d85f2a5386472314d39923da28c70c60dc8e7 (diff) | |
| download | qtwebengine-chromium-8fa0776f1f79e91fc9c0b9c1ba11a0a29c05196b.tar.gz | |
BASELINE: Update Chromium to 98.0.4758.90
Change-Id: Ib7c41539bf8a8e0376bd639f27d68294de90f3c8
Reviewed-by: Allan Sandfeld Jensen <allan.jensen@qt.io>
Diffstat (limited to 'chromium/docs/website/site/developers/how-tos')
.png.sha1?id=8fa0776f1f79e91fc9c0b9c1ba11a0a29c05196b){kind=link}
196 files changed, 9708 insertions, 0 deletions
diff --git a/chromium/docs/website/site/developers/how-tos/-quickly-building-for-cros-arm-x64/bashrc-tail b/chromium/docs/website/site/developers/how-tos/-quickly-building-for-cros-arm-x64/bashrc-tail new file mode 100644 index 00000000000..2966794ba7f --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/-quickly-building-for-cros-arm-x64/bashrc-tail @@ -0,0 +1,85 @@ +#!/bin/bash +# -*- fill-column: 200 -*- + + +function lumpy() { + export BOARD=lumpy + chrome_build +} + +function daisy() { + export BOARD=daisy + chrome_build +} + + +# Useful site: https://sites.google.com/a/chromium.org/dev/chromium-os/building-chromium-os/building-chromium-separately +function chrome_build() { + # https://sites.google.com/a/chromium.org/dev/chromium-os/how-tos-and-troubleshooting/building-chromium-browser + export CHROME_ORIGIN=LOCAL_SOURCE + + unset GYP_DEFINES GYP_GENERATORS + export BUILD_OUT=out_${BOARD} + export builddir_name=out_${BOARD} + export GYP_GENERATOR_FLAGS="output_dir=out_${BOARD} config=Debug" + export GYP_GENERATORS="ninja" + export GYP_DEFINES="$GYP_DEFINES disable_nacl=1 enable_svg=0 chromeos=1 use_official_google_api_keys=1" + if [ "$BOARD" = "daisy" ]; then + export GYP_DEFINES="$GYP_DEFINES target_arch=arm armv7=1 arm_float_abi=hard v8_use_arm_eabi_hardfloat=true" + export GYP_DEFINES="$GYP_DEFINES use_allocator=none " + export GYP_DEFINES="$GYP_DEFINES arm_neon=1" + # Of interest: http://code.google.com/p/chromium/wiki/LinuxChromiumArm + export XBASE="armv7a-cros-linux-gnueabi" + function crosip() { + echo 10.0.0.1 + } + else + export XBASE="x86_64-cros-linux-gnu" + function crosip() { + echo 10.0.0.2 + } + fi + export GYP_DEFINES="$GYP_DEFINES proprietary_codecs=1 ffmpeg_branding=ChromeOS enable_smooth_scrolling=1" + export GYP_DEFINES="$GYP_DEFINES python_ver=2.6 swig_defines=-DOS_CHROMEOS linux_sandbox_path=/opt/google/chrome/chrome-sandbox" + export GYP_DEFINES="$GYP_DEFINES remove_webcore_debug_symbols=1" + export GYP_DEFINES="$GYP_DEFINES component=shared_library" + export SYSROOT=/build/${BOARD}/ + + export GOLDIFY="-B/usr/x86_64-pc-linux-gnu/${XBASE}/binutils-bin/2.21-gold/" + export SYSROOTFLAG="--sysroot=$SYSROOT" + export BACKTRACE="-funwind-tables -rdynamic" + export GYP_GENERATORS=ninja + export GYP_PARALLEL=1 + export AR="${XBASE}-ar" + export CC="${XBASE}-gcc $SYSROOTFLAG $BACKTRACE" + export CXX="${XBASE}-g++ $SYSROOTFLAG $GOLDIFY $BACKTRACE" + export AR_host="ar" + export CC_host="gcc" + export CXX_host="g++ -B/usr/x86_64-pc-linux-gnu/x86_64-cros-linux-gnu/binutils-bin/2.21-gold/" + +} + +export NINJA_STATUS="[%u/%r/%f] " + +export TESTING_RSA_KEY=~/trunk/src/scripts/mod_for_test_scripts/ssh_keys/testing_rsa + +function crosdevice() { + echo -e "\ek$BOARD\e\\" + ssh -o StrictHostKeyChecking=no -o CheckHostIP=no -i $TESTING_RSA_KEY root@$(crosip) "$@" +} + +function crosdevicecp() { + scp -o StrictHostKeyChecking=no -o CheckHostIP=no -i $TESTING_RSA_KEY \ + "$@" root@$(crosip):/home/chronos/user/chrome/ +} + +function initcrosdevice() { + cd ~/chrome_root/src + crosdevice 'bash -x -c "echo \"core.%p\" > /proc/sys/kernel/core_pattern && \ + mkdir -p ~chronos/chrome && chown chronos ~chronos/chrome && \ + sudo -u chronos /bin/bash -c \"cd ~chronos/chrome && mkdir -p Release Debug\""' && \ + echo "Now log into crosdevice and run:" + echo "ulimit -c unlimited && cd ~chronos/chrome && sudo -u chronos bash" + echo "sshfs <desktop-username>@<desktop-hostname>:/home/<desktop-username>/src/chromium/src/out_$BOARD/Debug Debug" + crosdevice +} diff --git a/chromium/docs/website/site/developers/how-tos/-quickly-building-for-cros-arm-x64/goma-ninja b/chromium/docs/website/site/developers/how-tos/-quickly-building-for-cros-arm-x64/goma-ninja new file mode 100644 index 00000000000..2393346ff1f --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/-quickly-building-for-cros-arm-x64/goma-ninja @@ -0,0 +1,10 @@ +#!/bin/bash + +export PATH="/home/fischman/src/goma:$PATH" +# AMI: per http://go/g-d/msg/goma-users/iqAEq3IBLk8/K0gOhNxLxVoJ +if [ -n "$GOMA_IMPLICIT_INPUT_FILES" ]; then + GOMA_IMPLICIT_INPUT_FILES="$GOMA_IMPLICIT_INPUT_FILES," +fi +export GOMA_IMPLICIT_INPUT_FILES="${GOMA_IMPLICIT_INPUT_FILES}$(dirname $(realpath $0))/src/build/common.gypi" + +{ ~/src/goma/goma_ctl.sh status || ~/src/goma/goma_ctl.sh start; } && $(dirname $0)/ninja -j5000 "$@" diff --git a/chromium/docs/website/site/developers/how-tos/-quickly-building-for-cros-arm-x64/index.md b/chromium/docs/website/site/developers/how-tos/-quickly-building-for-cros-arm-x64/index.md new file mode 100644 index 00000000000..d96955a1e7b --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/-quickly-building-for-cros-arm-x64/index.md @@ -0,0 +1,72 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: -quickly-building-for-cros-arm-x64 +title: (Quickly!) Building for CrOS (ARM & x64) +--- + +Googlers note: you might want go/simplechrome instead of this page. + +Assuming you have a local chromium checkout you've been building natively, and +you want to be able to hack in it and build it for a CrOS device, see +instructions below. + +Following +<http://dev.chromium.org/chromium-os/how-tos-and-troubleshooting/building-chromium-browser>, +a one-time setup step is: +> $ cros_sdk --enter --chrome_root=.../path/to/chrome/dir \[ +> --chroot=../../which_chroot \] + +(where the *chrome/dir* part is the parent of *src/*). + +Subsequent cros_sdk invocations will have the chrome source directory mounted at +*~/chrome_root/src* inside the chroot. + +Make sure you've run *build_packages* and *build_image* at least one +successfully in the repo in question, or it's likely you'll be missing +packages/binaries/includes/libs needed to build chrome! See [CrOS dev +guide](/chromium-os/developer-guide) for details on those commands. + +Inside the parent of the chrome src/ dir, I have two scripts: "ninja" and +"goma-ninja" (attached to this page): + +* ninja: wraps regular ninja assuming a 32-core machine (z620) and + emitting build output depending on $GYP_GENERATOR_FLAGS so that + different builds (e.g.: native, lumpy, and daisy) can coexist +* (**google-internal only)** goma-ninja: wraps the above ninja wrapper + to compile on [goma](http://go/ma) with a parallelism of -j5000. + +Having these scripts in the parent of the src/ dir means they're available both +inside the chroot and outside it, so regardless of where I am, I can always say +"*../goma-ninja chrome*" for example and the right thing happens. + +Finally, I have a file named bashrc-tail which I source inside the chroot with: + +> *. ~/chrome_root/cros-chroot-homedir/bashrc-tail* + +at the bottom of my chroot's *~/.bashrc*. This defines two shell functions +("lumpy" and "daisy") which set up environment variables facilitating building +for different CrOS boards, as well as shell functions that help run chrome and +other ninja outputs **on** the boards, without having to explicitly copy things +around, by using sshfs. After a build like *../goma-ninja chrome* from above is +done, I'll run *initcrosdevice* which will ssh into the device (**note:** make +sure to update the crosip() functions in your copy of bashrc-tail to point to +the right IP addresses of your boards, as well as the username/hostname/path in +the definition of *initcrosdevice*!) and echo a helpful message useful for +copy/paste to sshfs-mount the ninja output directory on the board. At that point +I can run a unittest like: + +> DISPLAY=:0 ./Debug/video_decode_accelerator_unittest + +or run a full chrome. Beware that running chrome on a board usually requires a +pile of switches (depending on what features are launched on CrOS at a given +time, and the state of the drivers on any given board at any given time), which +you are best off extracting from the "real" chrome running on the device. I +usually keep these switches in a script at *out_daisy/Debug/go*, so that it's +available via the sshfs mount above and I can just run it on the device as +*./Debug/go*. + +**Good luck!**
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/-quickly-building-for-cros-arm-x64/ninja b/chromium/docs/website/site/developers/how-tos/-quickly-building-for-cros-arm-x64/ninja new file mode 100644 index 00000000000..4a196843ad3 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/-quickly-building-for-cros-arm-x64/ninja @@ -0,0 +1,7 @@ +#!/bin/bash -e + +OUTPUT_DIR="$(echo $GYP_GENERATOR_FLAGS |sed -n -e 's/.*output_dir=\([^ ]*\).*/\1/p')" # +FLAVOR="$OUTPUT_DIR/$(echo $GYP_GENERATOR_FLAGS |sed -n -e 's/.*config=\([^ ]*\).*/\1/p')" # +if [ ! -d $FLAVOR ]; then mkdir -p $FLAVOR; fi + +ninja -C $FLAVOR -j32 "$@" diff --git a/chromium/docs/website/site/developers/how-tos/android-build-instructions/index.md b/chromium/docs/website/site/developers/how-tos/android-build-instructions/index.md new file mode 100644 index 00000000000..f2461a79d90 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/android-build-instructions/index.md @@ -0,0 +1,12 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: android-build-instructions +title: Build Instructions (Android) +--- + +This page has been replaced by +<https://chromium.googlesource.com/chromium/src/+/HEAD/docs/android_build_instructions.md>
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/angle-infra/index.md b/chromium/docs/website/site/developers/how-tos/angle-infra/index.md new file mode 100644 index 00000000000..a5763647653 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/angle-infra/index.md @@ -0,0 +1,12 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: angle-infra +title: ANGLE Standalone Testing Infrastructure (obsolete) +--- + +This page is now moved to +<https://chromium.googlesource.com/angle/angle/+/HEAD/infra/README.md>
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/angle-wrangling/index.md b/chromium/docs/website/site/developers/how-tos/angle-wrangling/index.md new file mode 100644 index 00000000000..c11eec4b29d --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/angle-wrangling/index.md @@ -0,0 +1,11 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: angle-wrangling +title: ANGLE Wrangling (obsolete) +--- + +## This page is now moved to <https://chromium.googlesource.com/angle/angle/+/HEAD/infra/ANGLEWrangling.md>
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/api-keys/index.md b/chromium/docs/website/site/developers/how-tos/api-keys/index.md new file mode 100644 index 00000000000..07e97e9498f --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/api-keys/index.md @@ -0,0 +1,179 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: api-keys +title: API Keys +--- + +## What is this doc? + +1. If there are features which use Google APIs that you need for a + custom build, fork, or integration of stock Chromium. +2. If you are building ChromiumOS yourself, as API access is required + for login. + +*Note: Software distribution with keys acquired for yourself is allowed, but the +keys themselves cannot be shared with parties outside the legal entity that +accepted the API ToS. Keep in mind that a number of the APIs will have no or +very limited quota and not all of the APIs have additional quota available for +purchase.* + +**Googlers only**: + +* for a simpler approach to API keys, see + <http://go/chrome-api-key-setup> +* if you need a new API enabled in chrome, use + <http://b/new?component=165132> + +**How-to:** + +First, acquire API keys. Then, specify the API keys to use either when you build +Chromium, or at runtime using environment variables. + +## Acquiring Keys + +1. Make sure you are a member of + [chromium-dev@chromium.org](https://groups.google.com/a/chromium.org/forum/?fromgroups#!forum/chromium-dev) + (you can just + [subscribe](https://groups.google.com/a/chromium.org/forum/?fromgroups#!forum/chromium-dev) + to chromium-dev and choose not to receive mail). *Note: the APIs + below are only visible to people subscribed to that group.* +2. Make sure you are logged in with the Google account associated with + the email address that you used to subscribe to chromium-dev. +3. Go to <https://cloud.google.com/console> +4. Click on the dropdown next to "Google Cloud Platform" and select + **Create Project** (upper right). +5. (Optional) You may add other members of your organization or team on + the Team tab. +6. Open the **APIs and Services > Library** from the hamburger menu, + search for all of the following APIs. If you're a member of the + chromeos-dev Google group you should see all of them. For each of + these APIs click on them when found by the search, and then click on + "Enable API" button at the top, read and agree to the Terms of + Service that is shown, check the "I have read and agree to <API + name> Terms of Service" checkbox and click Accept: *(This list + might be out of date; try searching for APIs starting with "Chrome" + or having "for Chrome" in the name.)* + * Cloud Search API + * Geolocation API (requires [enabling + billing](https://developers.google.com/console/help/#EnableBilling) + but is free to use; you can skip this one, in which case + geolocation features of Chrome will not work) + * Google Drive API (enable this for Files.app on Chrome OS and + SyncFileSystem API) + * Safe Browsing API + * Time Zone API + * Optional + * Admin SDK + * Cloud Translation API + * Geocoding API + * Google Assistant API + * Google Calendar API + * Nearby Messages API + + ***If any of these APIs are not shown, recheck step 1.*** + +1. Go to the **Credentials** sub tab under the **API & Services** + section in the hamburger menu. +2. Click the "**Create credentials**" button then click on the **OAuth + client ID** item in the drop-down list. + * Click on the "Configure consent screen" button. Fill in the + "Product name" (name it anything you want) and other details if + you have available then click on "Save" at the bottom. + * Return to the Credentials tab and click the "Add credentials" + button again, then select "OAuth 2.0 client ID" from the + drop-down list. + * In the "Application type" section check the "Other" option and + give it a name in the "Name" text box, then click "Create" +3. In the pop-up window that appears you'll see a **client ID** and a + "**client secret**" string. Copy and paste those in a text file on + your dev box then click OK to dismiss it. + * A new item should now appear in the "OAuth 2.0 client IDs" list. + You can click on the name of your client id to retrieve the ID + and secret at any time. In the next sections, we will refer to + the values of the “Client ID” and “Client secret” fields. +4. Click the **Create credentials** button *again* on the same page. + + * In the pop-over window that shows up click the **API key** + button. + * A pop-over should show up giving you the API key. Copy and paste + it in a text file to save it, although you can access it later + as well. + * Click OK to dismiss this. + +You should now have an API key and a OAuth 2.0 client ID in on the Credentials +tab. The next sections will refer to the value of the “API key” field too. + +*Note: that the keys you have now acquired are not for distribution purposes and +must not be shared with other users.* + +## Providing Keys at Build Time + +If you are building Chromium yourself, you can provide keys as part of your +build configuration, that way they are always baked into your binary. + +Specify three variables in your `args.gn` file (which you can edit by running +`gn args out/your_out_dir_here`) + +```none +google_api_key = "your_api_key" +google_default_client_id = "your_client_id" +google_default_client_secret = "your_client_secret" +``` + +## Providing Keys at Runtime + +If you prefer, you can build a Chromium binary (or use a pre-built Chromium +binary) without API keys baked in, and instead provide them at runtime. To do +so, set the environment variables `GOOGLE_API_KEY`, `GOOGLE_DEFAULT_CLIENT_ID` +and `GOOGLE_DEFAULT_CLIENT_SECRET` to your "API key", **"Client ID" and** +"Client secret" values respectively. +On Chromium OS to specify the keys as environment variables append them to the +end of `/etc/chrome_dev.conf`: + +<pre><code>GOOGLE_API_KEY=<i>your_api_key</i> +GOOGLE_DEFAULT_CLIENT_ID=<i>your_client_id</i> +GOOGLE_DEFAULT_CLIENT_SECRET=<i>your_client_secret</i> +</code></pre> + +## Signing in to Chromium is restricted + +Signing in to Chromium requires an OAuth 2.0 token for authentication. As this +OAuth 2.0 token gives access to various Google services that handle user data +(e.g. Chrome sync), for security and privacy reasons the generation of this +OAuth 2.0 token is restricted. This means that signing in to Chromium is +restricted (as the OAuth 2.0 token cannot be generated). In order to sign in +to Chromium builds, please add your test account to +[google-browser-signin-testaccounts@chromium.org](https://groups.google.com/u/1/a/chromium.org/g/google-browser-signin-testaccounts) +(accounts in this group are allowed to get access tokens bypassing the +restriction above). + +*Note: Starting with Chromium M69, when the browser is set up with an OAuth 2.0 +client ID and client secret, signing in with your Google Account to any Google +web property will also attempt to sign you in to Chromium (which will fail as +explained above). To avoid such errors, remove your OAuth 2.0 client ID and +client secret from your build to stop generating tokens when users sign in to +Google web properties (remove google_default_client_id, +google_default_client_secret from gn args and GOOGLE_DEFAULT_CLIENT_ID and +GOOGLE_DEFAULT_CLIENT_SECRET from your environment settings).* + +## Getting Keys for Your Chromium Derivative + +Many of the Google APIs used by Chrome are specific to Google and not intended +for use in derived products. In the API Console +(<http://developers.google.com/console>) you may be able to purchase additional +quota for some of the APIs listed above. **For APIs that do not have a "Pricing" +link, additional quota is not available for purchase.** + +### Polyfilling chrome.identity API in Your Chromium Derivative + +The default Chromium `chrome.identity.getAuthToken` API that extensions may +call to obtain auth tokens will fail outside of Google Chrome as the +implementation uses restricted APIs. + +A prototype CL for Chromium embedders might use to replace the implementation +with one not dependent upon private APIs can be found attached to [this +post](https://groups.google.com/a/chromium.org/g/embedder-dev/c/tGCJ3QNVzYE).
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/build-instructions-android-webview/index.md b/chromium/docs/website/site/developers/how-tos/build-instructions-android-webview/index.md new file mode 100644 index 00000000000..e71bdfe6a0e --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/build-instructions-android-webview/index.md @@ -0,0 +1,11 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: build-instructions-android-webview +title: Build Instructions (Android WebView) +--- + +## This content has moved: <https://chromium.googlesource.com/chromium/src/+/HEAD/android_webview/docs/build-instructions.md>
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/build-instructions-cast/index.md b/chromium/docs/website/site/developers/how-tos/build-instructions-cast/index.md new file mode 100644 index 00000000000..d112a9a2803 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/build-instructions-cast/index.md @@ -0,0 +1,14 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: build-instructions-cast +title: Build Instructions (Cast) +--- + +**Cast docs have moved! Linux instructions are +[here](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/linux/cast_build_instructions.md) +and Android are +[here](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/android_cast_build_instructions.md).**
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/build-instructions-chromeos/index.md b/chromium/docs/website/site/developers/how-tos/build-instructions-chromeos/index.md new file mode 100644 index 00000000000..c5b4cada824 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/build-instructions-chromeos/index.md @@ -0,0 +1,17 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: build-instructions-chromeos +title: Build Instructions (Chromium OS on Linux) +--- + +This page has been replaced by +<https://chromium.googlesource.com/chromium/src/+/HEAD/docs/chromeos_build_instructions.md> + +## Running Chromium on a Chromium OS device + +See [Building Chromium for Chromium OS (simple +chrome)](http://www.chromium.org/chromium-os/how-tos-and-troubleshooting/building-chromium-browser)
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/build-instructions-windows/index.md b/chromium/docs/website/site/developers/how-tos/build-instructions-windows/index.md new file mode 100644 index 00000000000..768d5385a1c --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/build-instructions-windows/index.md @@ -0,0 +1,12 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: build-instructions-windows +title: Build Instructions (Windows) +--- + +**Windows build instructions have been moved! See them +[here.](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/windows_build_instructions.md)**
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/chrome-frame-cfinstall/index.md b/chromium/docs/website/site/developers/how-tos/chrome-frame-cfinstall/index.md new file mode 100644 index 00000000000..fe7aeae3005 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/chrome-frame-cfinstall/index.md @@ -0,0 +1,107 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: chrome-frame-cfinstall +title: Chrome Frame CFInstall script +--- + +## Google Chrome Frame is no longer supported and retired as of February 25, 2014. For guidance on what you need to know as a developer or IT administrator, please read our [developer FAQs](https://developers.google.com/chrome/chrome-frame/) for Chrome Frame. + +## Introduction + +This page describes the latest version of the Chrome Frame CFInstall script that +allows easy prompting for Chrome Frame installation within your own site. + +This version supports a new streamlined and improved API, though it is expected +to be backwards compatible with previous versions of the API as well. + +## User Experience + +This version of the CFInstall script is designed to optimize the user's +installation experience and get them onto your site, with Chrome Frame +installed, as fast as possible. + +To use this install flow, simply: + +1. Provide the user with a prompt to install Chrome Frame, whether it + is optional or required for your site to function. +2. If the user chooses to install Chrome Frame, invoke + CFInstall.require(). You may pass optional success and failure + callbacks, in that order. + +CFInstall.require will check the user's browser for compatibility and, if Chrome +Frame is supported, launch a modal dialog with the Chrome Frame EULA and +installation flow. The appropriate callback will be invoked upon installation +success, failure, or cancellation. + +By default, the current page will be reloaded after installation completes, with +the Chrome Frame plugin active. Naturally, your site must be sending the Chrome +Frame header or meta tag in order to be activated in Chrome Frame. + +See +<http://src.chromium.org/viewvc/chrome/trunk/src/chrome_frame/cfinstall/examples/simple.html> +for an example of this integration. + +## Custom Look & Feel + +The default look & feel of the installation flow dialog can be replaced quite +easily to match the look of your site. See +<http://src.chromium.org/viewvc/chrome/trunk/src/chrome_frame/cfinstall/examples/jquery.html> +for an example using the JQuery library. + +## **Hosting the Scripts** + +You can access the CFInstall script directly off of Google's servers or host it +yourself. If you choose to host it yourself, please note that the script +consists of both the small initial script (the "stub") and a second, larger +script (the "implementation") that is only downloaded if the install flow is +launched. If you move the script elsewhere, you must either specify the +implementation location or recompile the stub with your intended hosting path +(see below). + +### Specifying a Custom Implementation URL + +The implementation is located at +<http://google.com/tools/dlpage/res/chromeframe/script/cf-xd-install-impl.js> . +If you wish to access it from elsewhere, you must make the following call before +CFInstall.require: + +```none +CFInstall.setImplementationUrl('/path/to/cf-xd-install-impl.js'); +``` + +Note that the path supplied may be absolute or scheme, host, or path relative +(i.e. 'http://host/path/to/...', '//host/path/to/...', '/path/to', +'../../path/to'). It will be resolved relative to the HTML document in which the +script is executed. + +## Compiling CFInstall from Source + +CFInstall uses the [Closure Library](http://code.google.com/closure/library/) +and is optimized using the [Closure +Compiler](http://code.google.com/closure/compiler/). The source code for +CFInstall is included in the Chromium source repository and may be checked out +using the following command: + +```none +svn co http://src.chromium.org/chrome/trunk/src/chrome_frame/cfinstall/ +``` + +Once you have checked out the code, you may simply run build.sh to download the +required dependencies and build the optimized scripts (see the 'out' directory). +The Closure Compiler requires Python and Java in order to run. If you are unable +to execute build.sh (due to a lack of a shell interpreter, for example), you +should find it pretty straightforward to manually invoke the compiler using the +script as an example. + +The build.sh script accepts two options for customizing the optimized output: + +```none +Usage: ./build.sh [-l //host.com/path/to/scripts/dir/] [-p] [-d] + -l <URL> The path under which the generated + scripts will be deployed. + -d Disable obfuscating optimizations. +```
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/chrome-frame-getting-started/index.md b/chromium/docs/website/site/developers/how-tos/chrome-frame-getting-started/index.md new file mode 100644 index 00000000000..1d2a76d118d --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/chrome-frame-getting-started/index.md @@ -0,0 +1,34 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: chrome-frame-getting-started +title: Chrome Frame +--- + +## Google Chrome Frame was an open source plug-in that seamlessly brought Google Chrome's open web technologies and speedy JavaScript engine to Internet Explorer. + +* ## If you have Chrome Frame installed, please uninstall it. It is no + longer supported or updated. +* ## You should continue to encourage your users to install and run + [evergreen + browsers](http://tomdale.net/2013/05/evergreen-browsers/), that is, + browsers that auto-update their users to the latest and greatest. + +## Google Chrome Frame is no longer supported and retired as of February 25, 2014. + +## Please read our June 2013 [Chromium blog post](http://blog.chromium.org/2013/06/retiring-chrome-frame.html) for details. + +### Chrome for Business + +## Deploying [Chrome for Business](http://www.google.com/chrome/work) lets you configure over 100 policies to fit your organization's needs. As an admin, you have solid control over the browser deployment, including managing updates, supporting compatibility of older apps, and installing extensions globally. + +### Chrome Legacy Browser Support + +## If your organization wants to take advantage of the Chrome browser, but your users still need to access older websites and apps that require Internet Explorer, you can use [Legacy Browser Support](https://www.google.com/intl/en/chrome/business/browser/lbs.html) to easily and automatically switch between browsers. When your user clicks a link that requires a legacy browser to open (such as a site that requires ActiveX), the URL will automatically open in the legacy browser from Chrome. You can specify which URLs to launch into a second browser and deploy this Chrome policy for the organization. More info on [Legacy Browser Support in our help center.](http://support.google.com/chrome/a/bin/answer.py?hl=en&answer=3019558) + +### How should I deliver feature-forward experiences across browsers now? + +## Continue to use feature detection to identify capabilities of a browser. Scaling experiences across desktop and mobile in a performant way may require reducing the amount of effects for older browsers. You can define a browser support policy that outlines the various levels of support and/or consider a low-res edition where the content is very accessible, though it's lacking significant visual and interaction design.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/chrome-frame-getting-started/screenshot-chromeframe.jpeg.sha1 b/chromium/docs/website/site/developers/how-tos/chrome-frame-getting-started/screenshot-chromeframe.jpeg.sha1 new file mode 100644 index 00000000000..cb10f9cf452 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/chrome-frame-getting-started/screenshot-chromeframe.jpeg.sha1 @@ -0,0 +1 @@ +2dbb4938cbd7d98d4945ccb390097637fbc0e0a1
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/chromium-modularization/index.md b/chromium/docs/website/site/developers/how-tos/chromium-modularization/index.md new file mode 100644 index 00000000000..3661fb391a0 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/chromium-modularization/index.md @@ -0,0 +1,201 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: chromium-modularization +title: Chromium Modularization +--- + +[TOC] + +## Background + +Chromium is a big project, and it makes sense to modularize. Many sub-teams work +largely independently, such as the sandbox and V8 teams, and the WebKit code is +merged on regular schedules. It makes sense to modularize such that these teams +can work independently, yet still share common code. + +For an overview of the modules that exist, please see [Chromium code +layout](/developers/how-tos/getting-around-the-chrome-source-code). + +## Quick start + +Say you need to make a change that adds or changes something in `base` for the +benefit of something in `chrome`. + +First you make your change, get it reviewed and checked in. At this point, +Chromium is still pulling a specific, older revision of base without your +changes. It does this by pulling in a specific version of `webkit`, and then +specifying that it should use the version of base that the `webkit` module is +currently using (see the "From" syntax below). Nobody will see your change +because of this. + +Then you update the `webkit` module to pull in your new version of `base`. First +you need to figure out which version your new version is. It's a good idea to +first do `svn update` in `base/` to make sure everything is up-to-date, then do +`svn info`. You'll see a `Revision` line that tells you the current revision +number of the current module. Put this revision number into the `webkit/DEPS` +file for the `base` module. Get this change reviewed and submitted. + +At this point, `chrome` is still pulling a specific version of `webkit` that +pulls `base` without your change. Repeat the same procedure as before, but this +time, make `chrome` pull the latest version of `webkit`. Along with this deps +file changes should go your corresponding changes to Chromium. This allows you +to atomically pull in the most recent version and update Chromium to be +compatible with it. + +Dependencies + +Each project depends on a variety of modules. For example, the WebKit project +depends on the networking code, our shared base code, and some third-party +libraries. Chromium and V8 in turn both depend on WebKit. (In practice, Chromium +depends on everything since we are in the Chromium tree). Each project must list +the projects it depends on, and which version it wants to pull. We do not +support transitive dependencies, so each project must list all of the projects +it depends on. + +A user's *client* specifies a set of target *solutions* to check out. (Yes, +please excuse the Visual Studio jargon.) In the simplest case, a user's client +only specifies a single solution, say the `chrome` solution. The root directory +of each solution has a text file named `DEPS` that defines the set of +dependencies for the project. Users can override these dependencies if desired. + +The contents of the `DEPS` file is a python associative array, which looks +something like the following: + +deps = { +"breakpad" : "http://google-breakpad.googlecode.com/svn/trunk@189", +"webkit" : "http://src.chromium.org/chrome/trunk/src/webkit@3395", +"v8" : "http://v8.googlecode.com/svn/trunk@77829", +... +} + +The `DEPS` file can easily be used to express a dependency on a subversion tag +and other subversion servers: + +deps = { +... +"breakpad" : "http://google-breakpad.googlecode.com/svn/tags/1.0.29.0", +... +} + +While it is possible for a `DEPS` file to specify that the trunk of a dependency +be used, it is intended that a `DEPS` file instead specify a known good revision +number or tag. This ensures that Chromium developers, for example, are insulated +from activity on the trunk of a dependency. When the maintainer(s) of the +dependency decide to make Chromium use the new revision of the dependency, they +just need to contribute a change to the `chrome/DEPS` file. + +### The "From" keyword + +Given that dependencies are not computed recursively, it can be a pain to +maintain complex dependency trees manually, especially if modules have multiple +overlapping dependencies. To simplify such situations, `gclient` supports the +`From` keyword which can be used to express a dependency in terms of the `DEPS` +file of another module. For example, you could have: + +deps = { +"breakpad" : "http://google-breakpad.googlecode.com/svn/trunk@189", +"webkit" : "http://src.chromium.org/chrome/trunk/src/webkit@3395", +"v8" : From("webkit"), +... +} + +The use of the `From` keyword above indicates that the version of "v8" to be +pulled should be determined by inspecting `webkit/DEPS`. + +## Test Data + +Some modules like `webkit` have very large amounts of test data. For these +modules, a good convention is to define a separate module for the test data. In +the case of the `webkit` module, `webkit/DEPS` can define a dependency on the +webkit test data module, but `chrome/DEPS` can exclude this dependency. As a +result, Chromium developers are exempted from having to checkout the WebKit test +data by default, but this also does not inconvenience WebKit developers who +prefer to check out the test data. Also, by having the test data in a parallel +directory, the cost of manually updating just the webkit directory is minimized. + +## Tooling + +To facilitate working with a bunch of separately versioned modules, some tooling +is needed. + +### Installation + +Checkout the `depot_tools` package, which includes `gclient`, `gcl`, and `svn`: +`$ `git clone https://chromium.googlesource.com/chromium/tools/depot_tools + +Add the `depot_tools` directory to your PATH. + +### Basic Usage + +To checkout Chromium the first time, follow [these +instructions](/developers/how-tos/get-the-code). + +### Advanced Usage + +The contents of a default `.gclient` file looks something like: + +solutions = \[ +{ "name" : "chrome", +"url" : "http://src.chromium.org/chrome/trunk/src/chrome", +"custom_deps" : {} +} +\] + +An element of the `solutions` array (a *solution*) describes a repository +directory that will be checked out into your working copy. Each solution may +optionally define additional dependencies (via its `DEPS` file) to be checked +out alongside the solution's directory. A solution may also specify custom +dependencies (via the `custom_deps` property) that override or augment the +dependencies specified by the `DEPS` file. + +Users can edit this file to add new solutions or alter dependencies for a +particular solution. + +For example, a V8 developer may wish to checkout the V8 trunk alongside a stable +version of Chromium. So, they might setup a `.gclient` file like so: + +solutions = \[ +{ "name" : "chrome", +"url" : "http://src.chromium.org/chrome/trunk/src/chrome@5000", +"custom_deps" : { +"v8" : "http://v8.googlecode.com/svn/trunk" +} +} +\] + +The above specifies that a particular revision of Chromium, r5000, should be +used instead of the Chromium trunk. It then specifies that the V8 trunk should +be used instead of the version of V8 specified by `chrome/DEPS`. + +The V8 example is somewhat simple since V8 does not itself have other +dependencies. For modules like webkit, specifying custom dependencies for each +of WebKit's dependencies is tedious and could potentially get out of sync with +what other developers are using (as specified in `webkit/DEPS`). So, an +alternative approach to working with the trunk of another module is to set up a +second solution: + +solutions = \[ +{ "name" : "chrome", +"url" : "http://src.chromium.org/chrome/trunk/src/chrome@5000", +"custom_deps" : { +"skia" : None, +"webkit" : None, +"v8" : None +} +}, +{ "name" : "webkit", +"url" : "http://src.chromium.org/chrome/trunk/src/webkit", +"custom_deps" : {} +} +\] + +The above `.gclient` file specifies that the svn URLs given in `chrome/DEPS` for +the skia, webkit, and v8 modules should be ignored. Those modules are then +fetched according to `webkit/DEPS`. Both `chrome/DEPS` and `webkit/DEPS`, in +this example, specify other common dependencies such as `base`. The tool will +complain if the two solutions specify conflicting dependencies. A user must +explicitly ignore a dependency that conflicts.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/closure-compilation/index.md b/chromium/docs/website/site/developers/how-tos/closure-compilation/index.md new file mode 100644 index 00000000000..0286e84e43d --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/closure-compilation/index.md @@ -0,0 +1,12 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: closure-compilation +title: Closure Compilation +--- + +See: +[wiki:ClosureCompilation](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/closure_compilation.md)
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/component-build/index.md b/chromium/docs/website/site/developers/how-tos/component-build/index.md new file mode 100644 index 00000000000..6ca24c07381 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/component-build/index.md @@ -0,0 +1,12 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: component-build +title: Component build / Shared Library / Multi-DLL build +--- + +This documentation has moved to the source tree. See t[he Chromium component +build](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/component_build.md).
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/cscope-emacs-example-linux-setup/cscope-update b/chromium/docs/website/site/developers/how-tos/cscope-emacs-example-linux-setup/cscope-update new file mode 100644 index 00000000000..a26d3aa6b10 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/cscope-emacs-example-linux-setup/cscope-update @@ -0,0 +1,11 @@ +#!/bin/bash -e + +S=$(pwd) +SRCDIRS=$(find ./src -mindepth 1 -maxdepth 1 -type d| + egrep -v '^\./(ninja|out|\.git)' |sed -e "sX^\./X-s $S/Xg"| tr '\012' ' ') +D=$(mktemp -d) +cd $D +cscope -Rbq $SRCDIRS +mv * $S +cd $S +rmdir $D diff --git a/chromium/docs/website/site/developers/how-tos/cscope-emacs-example-linux-setup/cscope.el b/chromium/docs/website/site/developers/how-tos/cscope-emacs-example-linux-setup/cscope.el new file mode 100644 index 00000000000..3cdfe5901e9 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/cscope-emacs-example-linux-setup/cscope.el @@ -0,0 +1,41 @@ +(load "/usr/share/emacs/site-lisp/xcscope.el") + +(setq cscope-do-not-update-database t) +(setq cscope-initial-directory nil) + +(defun ami-src-root-for-buffer () + "Return the source root for the current buffer" + (cond + ((null buffer-file-name) (error "Unexpected no path!")) + ((string-match "/chromium/src/" buffer-file-name) "~/src/chromium/src") + ((string-match "/wr/trunk/" buffer-file-name) "~/src/wr/trunk") + (t (error (concat "Unexpected path: " buffer-file-name))))) +(defun ami-cscope-symbol-feeling-lucky (sym) + "Do a cscope symbol lookup trying for the declaration of a type." + (interactive (list + (cscope-prompt-for-symbol "Find this symbol: " nil) + )) + (let* ((file-line + (shell-command-to-string + (format (concat "cd %s/.. && " + "cscope -dL -1 %s |egrep '[0-9] *((struct|class|#define)( [A-Z]*_EXPORT)? %s($| |\\()|typedef .* %s(;?| {)$)'|" ;; # + "head -1 |cut -d' ' -f1,3|tr ' ' ':'") + (ami-src-root-for-buffer) sym sym sym)))) + (if (not (string= "" file-line)) + (let* ((parts (split-string file-line ":")) + (file (car parts)) + (line (string-to-int (cadr parts)))) + (find-file file) + (goto-line line)) + (cscope-find-this-symbol sym)))) +(defun ami-cscope-at-point () + "Invoke reasonable cscope command depending on the context. +Useful in chromium." + (interactive) + (let ((line (buffer-substring-no-properties + (line-beginning-position) (line-end-position)))) + (if (string-match "^#include [\"<]" line) + (call-interactively 'cscope-find-this-file) + (call-interactively 'ami-cscope-symbol-feeling-lucky)))) + +(global-set-key '[?\M-.] 'ami-cscope-at-point) diff --git a/chromium/docs/website/site/developers/how-tos/cscope-emacs-example-linux-setup/index.md b/chromium/docs/website/site/developers/how-tos/cscope-emacs-example-linux-setup/index.md new file mode 100644 index 00000000000..6ea6a018cb4 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/cscope-emacs-example-linux-setup/index.md @@ -0,0 +1,24 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: cscope-emacs-example-linux-setup +title: 'cscope/emacs: example Linux setup' +--- + +This is a simple recipe for being setting up jump-to-file (for #includes) and +jump-to-declaration (for symbol names) in emacs, on gprecise (should work on +most posix systems). + +* Install cscope: `sudo apt-get install -y cscope cscope-el` +* Place the attached cscope-update script in the directory containing + `.gclient` (parent of `src/`). +* Run `./cscope-update` after each `gclient sync` to update the cscope + database +* Load the attached `cscope.el` from your `.emacs`; note you'll + probably want to edit this with your own client roots in + `ami-src-root-for-buffer`. +* While browsing source, hit meta-. (period) to jump to the file + `#include`d at point or to the declaration of the symbol at point.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/debugging-gpu-related-code/index.md b/chromium/docs/website/site/developers/how-tos/debugging-gpu-related-code/index.md new file mode 100644 index 00000000000..3cb3ca4642c --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/debugging-gpu-related-code/index.md @@ -0,0 +1,12 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: debugging-gpu-related-code +title: Debugging GPU related code +--- + +This page has moved to +<https://chromium.googlesource.com/chromium/src/+/HEAD/docs/gpu/debugging_gpu_related_code.md>.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/debugging-on-android/index.md b/chromium/docs/website/site/developers/how-tos/debugging-on-android/index.md new file mode 100644 index 00000000000..f7f0ab076f1 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/debugging-on-android/index.md @@ -0,0 +1,12 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: debugging-on-android +title: Debugging Chromium on Android +--- + +Moved to: +<https://chromium.googlesource.com/chromium/src/+/HEAD/docs/android_debugging_instructions.md>
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/debugging-on-os-x/building-with-ninja-debugging-with-xcode/index.md b/chromium/docs/website/site/developers/how-tos/debugging-on-os-x/building-with-ninja-debugging-with-xcode/index.md new file mode 100644 index 00000000000..cbec573cff2 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/debugging-on-os-x/building-with-ninja-debugging-with-xcode/index.md @@ -0,0 +1,13 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +- - /developers/how-tos/debugging-on-os-x + - Debugging Chromium on macOS +page_name: building-with-ninja-debugging-with-xcode +title: Building with Ninja, Debugging with Xcode +--- + +## This page has moved to <https://chromium.googlesource.com/chromium/src/+/main/docs/mac/debugging.md#Working-with-Xcode>
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/debugging-on-os-x/index.md b/chromium/docs/website/site/developers/how-tos/debugging-on-os-x/index.md new file mode 100644 index 00000000000..7109e37c2b5 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/debugging-on-os-x/index.md @@ -0,0 +1,11 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: debugging-on-os-x +title: Debugging Chromium on macOS +--- + +## This page has moved to <https://chromium.googlesource.com/chromium/src/+/main/docs/mac/debugging.md>
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/debugging-on-windows/StepIntoSpecific.png.sha1 b/chromium/docs/website/site/developers/how-tos/debugging-on-windows/StepIntoSpecific.png.sha1 new file mode 100644 index 00000000000..47097b5900b --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/debugging-on-windows/StepIntoSpecific.png.sha1 @@ -0,0 +1 @@ +6b63fe098008640b4079215c771a7eb0200c8c2f
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/debugging-on-windows/example-of-working-with-a-dump/index.md b/chromium/docs/website/site/developers/how-tos/debugging-on-windows/example-of-working-with-a-dump/index.md new file mode 100644 index 00000000000..cf4beabc0f8 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/debugging-on-windows/example-of-working-with-a-dump/index.md @@ -0,0 +1,304 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +- - /developers/how-tos/debugging-on-windows + - Debugging Chromium on Windows +page_name: example-of-working-with-a-dump +title: Example of working with a dump. +--- + +Let's say that you are looking at a crash dump, so following the first command +from [this +page](/developers/how-tos/debugging-on-windows/windbg-help#TOC-Common-commands-when-working-with-a-crash) +you do: + +```none +0:006> !analyze -v +``` + +Part of what the command prints is: + +```none +FAULTING_IP: +YCWebCameraSource+14c7e +1c414c7e 8b01 mov eax,dword ptr [ecx] +EXCEPTION_RECORD: ffffffff -- (.exr 0xffffffffffffffff) +ExceptionAddress: 1c414c7e (YCWebCameraSource+0x00014c7e) + ExceptionCode: c0000005 (Access violation) + ExceptionFlags: 00000000 +NumberParameters: 2 + Parameter[0]: 00000000 + Parameter[1]: 00000000 +Attempt to read from address 00000000 +CONTEXT: 00000000 -- (.cxr 0x0;r) +eax=00000000 ebx=0465c528 ecx=00000000 edx=00000500 esi=0465c498 edi=00000000 +eip=77c2e1a4 esp=0465c370 ebp=0465c4f0 iopl=0 nv up ei pl nz ac po nc +cs=0023 ss=002b ds=002b es=002b fs=0053 gs=002b efl=00200212 +PROCESS_NAME: chrome.exe +ERROR_CODE: (NTSTATUS) 0xc0000005 - The instruction at 0x%08lx referenced memory at 0x%08lx. The memory could not be %s. +EXCEPTION_CODE: (NTSTATUS) 0xc0000005 - The instruction at 0x%08lx referenced memory at 0x%08lx. The memory could not be %s. +EXCEPTION_PARAMETER1: 00000000 +EXCEPTION_PARAMETER2: 00000000 +READ_ADDRESS: 00000000 +FOLLOWUP_IP: +YCWebCameraSource+14c7e +1c414c7e 8b01 mov eax,dword ptr [ecx] +BUGCHECK_STR: APPLICATION_FAULT_NULL_POINTER_READ_INVALID_POINTER_READ_BEFORE_CALL +STACK_TEXT: +0465cab8 00000000 0465cbc4 096052c0 1c414fe1 YCWebCameraSource+0x14c7e +``` + +which basically says that there is an attempt to read from NULL: + +YCWebCameraSource+14c7e + +1c414c7e 8b01 mov eax,dword ptr \[ecx\] + +and ECX is 0. + +The problematic part is the last one: the stack is a single line of text, inside +a DLL that you know nothing about. Moving on to the next command, + +```none +0:006> .ecxr +eax=0bd00048 ebx=000000f0 ecx=00000000 edx=00000500 esi=0465cbc4 edi=00000140 +eip=1c414c7e esp=0465cabc ebp=000000f0 iopl=0 nv up ei pl nz na po nc +cs=0023 ss=002b ds=002b es=002b fs=0053 gs=002b efl=00210202 +YCWebCameraSource+0x14c7e: +1c414c7e 8b01 mov eax,dword ptr [ecx] ds:002b:00000000=???????? +``` + +confirms what we already know as the debugger loads the context when the +exception was received. The stack window shows only one line of text. + +```none +0:006> k + *** Stack trace for last set context - .thread/.cxr resets it +ChildEBP RetAddr +WARNING: Stack unwind information not available. Following frames may be wrong. +0465cab8 00000000 YCWebCameraSource+0x14c7e +``` + +Looking at the registers show the reason: EBP is 0xF0, which is not a pointer to +the stack. ESP looks fine, so let's see what's there using the next command from +the list: + +```none +0:006> dds esp +0465cabc 00000000 +0465cac0 0465cbc4 +0465cac4 096052c0 +0465cac8 1c414fe1 YCWebCameraSource+0x14fe1 +0465cacc 0b7b0000 +0465cad0 00000140 +0465cad4 000000f0 +0465cad8 00000500 +0465cadc 09710000 +0465cae0 00000140 +0465cae4 000000f0 +0465cae8 000003c0 +0465caec 00000000 +0465caf0 00000000 +0465caf4 00000140 +0465caf8 1c40c24e YCWebCameraSource+0xc24e +0465cafc 0b7b0000 +0465cb00 00000140 +0465cb04 000000f0 +0465cb08 00000000 +0465cb0c 00000500 +0465cb10 09710000 +0465cb14 00000140 +0465cb18 000000f0 +0465cb1c 00000000 +0465cb20 000003c0 +0465cb24 0465e074 +0465cb28 09158124 +0465cb2c 091561c8 +0465cb30 00000000 +0465cb34 09605848 +0465cb38 0b8007c8 +``` + +A few pointers to code close to the address that crashed, which is good because +it means the control flow before the crash is reasonable. But clearly that code +is not using EBP to maintain stack frames (more on that later). So see what else +is on the stack: + +```none +0:006> dds +0465cb3c 0b800960 +0465cb40 000003c0 +0465cb44 091561c8 +0465cb48 00022009 +0465cb4c 80004005 +0465cb50 1c4238f8 YCWebCameraSource+0x238f8 +0465cb54 09605848 +0465cb58 00000000 +0465cb5c 000000b2 +0465cb60 096052c0 +0465cb64 00000000 +0465cb68 00000000 +0465cb6c 00000140 +0465cb70 000000f0 +0465cb74 00000140 +0465cb78 000000f0 +0465cb7c 00000500 +0465cb80 00022009 +0465cb84 0b7b0000 +0465cb88 00000001 +0465cb8c 1c4238f8 YCWebCameraSource+0x238f8 +0465cb90 096046c8 +0465cb94 00000000 +0465cb98 0465cc28 +0465cb9c 00000140 +0465cba0 000000f0 +0465cba4 000003c0 +0465cba8 00021808 +0465cbac 09710000 +0465cbb0 00000002 +0465cbb4 557cf400 +0465cbb8 11d31a04 +``` + +Note that issuing the command without an argument just continues where the last +invocation left of. Furthermore, just hitting enter repeats the last command so +after this point is a matter of keep hitting enter. Which is good because in +this case interesting things happen after a long time: + +```none +0:006> +0465f22c f15f2bff +0465f230 0465f27c +0465f234 772b9b03 msvcrt!free+0x65 +0465f238 01700000 +0465f23c 00000000 +0465f240 772b9b10 msvcrt!free+0x84 +0465f244 f1a4c16f +0465f248 00000000 +0465f24c 0170b3f8 +0465f250 00000000 +0465f254 00000000 +0465f258 0465f238 +0465f25c ffffffff +0465f260 00000000 +0465f264 0465f244 +0465f268 82eaa80b +0465f26c 0465f98c +0465f270 772dc265 msvcrt!_except_handler4 +0465f274 82eaa80b +0465f278 fffffffe +0465f27c 772b9b10 msvcrt!free+0x84 +0465f280 732343a5 devenum!ATL::CComObject<CCreateSwEnum>::`scalar deleting destructor'+0x3d +0465f284 0170b3f8 +0465f288 73234566 devenum!ATL::CComObject<CCreateSwEnum>::Release+0x23 +0465f28c 03290d90 +0465f290 031f0b50 +0465f294 0465f4bc +0465f298 6fb647db chrome_6faf0000!media::GetDeviceNamesDirectShow+0x3ab +0465f29c 6fb647e5 chrome_6faf0000!media::GetDeviceNamesDirectShow+0x3b5 +0465f2a0 0465f2b8 +0465f2a4 6faf22b5 chrome_6faf0000!tcmalloc::FL_Push+0x71 +0465f2a8 01192308 +``` + +After a while of seeing symbols from various DLLs go through the stack we start +to see symbols from Chrome. The last part looks relatively good. Note that at +address 0465f298 there is a pointer to Chrome code, and more importantly, 4 +bytes before there is a pointer to another place in the stack, some bytes after +the current position: 0465f294 0465f4bc. This is the typical pattern of a call +to a function that use EBP to track stack frames. Time to use the next command +from the list: + +```none +0:006> k = 0465f294 0465f294 0465f294 +ChildEBP RetAddr +WARNING: Frame IP not in any known module. Following frames may be wrong. +0465f294 6fb647db 0x465f294 +0465f4bc 07554180 chrome_6faf0000!media::GetDeviceNamesDirectShow+0x3ab +0465f4cc 6fb643d2 0x7554180 +0465f4e8 6fb64386 chrome_6faf0000!media::VideoCaptureDeviceFactory::EnumerateDeviceNames+0x45 +0465f4f4 6fb55ece chrome_6faf0000!base::internal::Invoker<> +0465f5d4 6fb5552d chrome_6faf0000!base::MessageLoop::RunTask+0x50a +0465f718 6fb62bad chrome_6faf0000!base::MessageLoop::DoWork+0x359 +0465f744 6fb5503a chrome_6faf0000!base::MessagePumpDefault::Run+0xc7 +0465f768 6fb54f2d chrome_6faf0000!base::MessageLoop::RunHandler+0x6e +0465f794 6fb54ec4 chrome_6faf0000!base::MessageLoop::Run+0x65 +0465f79c 6fb5291e chrome_6faf0000!base::Thread::Run+0xb +0465f928 6fb52509 chrome_6faf0000!base::Thread::ThreadMain+0x26e +0465f94c 778a850d chrome_6faf0000!base::`anonymous namespace'::ThreadFunc+0xcb +0465f958 77c5bf39 kernel32!BaseThreadInitThunk+0xe +0465f99c 77c5bf0c ntdll!__RtlUserThreadStart+0x72 +0465f9b4 00000000 ntdll!_RtlUserThreadStart+0x1b +``` + +Strictly speaking the format that I just used is not correct, but the debugger +does a decent job figuring out what I want just complaining about the first +frame. The good part is that now we have a stack that looks reasonable. Time to +go up and try to get something better. + +The pattern that we just saw, a pointer a few bytes ahead followed by a symbol +should repeat itself... as in the pointer should point to another pointer +followed by a symbol. Se if we search up on the debugger output for 0465f294 we +should get to the previous frame. If there is no match, it means that either we +reached a function call that doesn't use EBP, or we are following stale data +from the stack (traces of something that happened before, and has not been +overwritten yet, but it is not the current call sequence). + +And that's exactly what happens in this case. But going up and following stack +manually a few times provides a better stack. Remember that the goal is not to +get a perfect stack trace but to get enough information to do something about +it. We already know that get the actual stack will be impossible because close +to the crash point there's no EBP and no symbols. But the type of symbols that +you see going through while executing dds gives you a rough idea of how the flow +ends up at the code that crashes. + +```none +0:006> k = 0465e0ac 0465e0ac 0465e0ac +ChildEBP RetAddr +WARNING: Frame IP not in any known module. Following frames may be wrong. +0465e0ac 76ec7543 0x465e0ac +0465e11c 76ec4fdf combase!CServerContextActivator::CreateInstance+0x18b +0465e15c 76ec7610 combase!ActivationPropertiesIn::DelegateCreateInstance+0x5c +0465e1b0 76ec7334 combase!CApartmentActivator::CreateInstance+0x75 +0465e1d4 76ec6d52 combase!CProcessActivator::CCICallback+0x3b +0465e1f4 76ec72cf combase!CProcessActivator::AttemptActivation+0x2c +0465e22c 76ec73a9 combase!CProcessActivator::ActivateByContext+0x97 +0465e25c 76ec4fdf combase!CProcessActivator::CreateInstance+0x5d +0465e29c 76ec50d7 combase!ActivationPropertiesIn::DelegateCreateInstance+0x5c +0465e4fc 76ec4fdf combase!CClientContextActivator::CreateInstance+0xdd +0465e53c 76ec5ba6 combase!ActivationPropertiesIn::DelegateCreateInstance+0x5c +0465ede8 76ebc9c2 combase!ICoCreateInstanceEx+0xfb6 +(Inline) -------- combase!CComActivator::DoCreateInstance+0x11a +(Inline) -------- combase!CoCreateInstanceEx+0x14e +0465ee3c 732352c3 combase!CoCreateInstance+0x169 +0465eef0 70cedfbd devenum!CDeviceMoniker::BindToObject+0x1ac +0465f0e0 70ce59df chrome_6faf0000!media::VideoCaptureDeviceWin::GetDeviceFilter+0x234 +0465f3ac 70ce56a2 chrome_6faf0000!media::GetDeviceSupportedFormatsDirectShow+0x335 +0465f3c0 6fb64995 chrome_6faf0000!media::VideoCaptureDeviceFactoryWin::GetDeviceSupportedFormats+0x20 +0465f44c 6fb648c1 chrome_6faf0000!content::VideoCaptureManager::ConsolidateDevicesInfoOnDeviceThread+0xc1 +0465f46c 6fb64883 chrome_6faf0000!base::internal::RunnableAdapter<>::Run+0x2e +0465f488 6fb64848 chrome_6faf0000!base::internal::InvokeHelper<>::MakeItSo+0x25 +0465f4b8 6fb64800 chrome_6faf0000!base::internal::Invoker<<media::VideoCaptureDevice::N+0x33 +0465f4cc 6fb643d2 chrome_6faf0000!base::Callback<>::Run+0x17 +0465f4e8 6fb64386 chrome_6faf0000!media::VideoCaptureDeviceFactory::EnumerateDeviceNames+0x45 +0465f4f4 6fb55ece chrome_6faf0000!base::internal::Invoker<2,base::internal::BindState<>::Run+0x10 +0465f5d4 6fb5552d chrome_6faf0000!base::MessageLoop::RunTask+0x50a +0465f718 6fb62bad chrome_6faf0000!base::MessageLoop::DoWork+0x359 +0465f744 6fb5503a chrome_6faf0000!base::MessagePumpDefault::Run+0xc7 +0465f768 6fb54f2d chrome_6faf0000!base::MessageLoop::RunHandler+0x6e +0465f794 6fb54ec4 chrome_6faf0000!base::MessageLoop::Run+0x65 +0465f79c 6fb5291e chrome_6faf0000!base::Thread::Run+0xb +0465f928 6fb52509 chrome_6faf0000!base::Thread::ThreadMain+0x26e +0465f94c 778a850d chrome_6faf0000!base::`anonymous namespace'::ThreadFunc+0xcb +0465f958 77c5bf39 kernel32!BaseThreadInitThunk+0xe +0465f99c 77c5bf0c ntdll!__RtlUserThreadStart+0x72 +0465f9b4 00000000 ntdll!_RtlUserThreadStart+0x1b +``` + +Note how this stack is slightly different right where the previous stack +started, but it flows nicely into a sequence of com calls. There's usually no +point in going too deep into code we don't control, so that is all we need in +this case.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/debugging-on-windows/gflags.png.sha1 b/chromium/docs/website/site/developers/how-tos/debugging-on-windows/gflags.png.sha1 new file mode 100644 index 00000000000..6beccca47d6 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/debugging-on-windows/gflags.png.sha1 @@ -0,0 +1 @@ +c55130c1788c9afbbf6f571e6583818431746c8b
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/debugging-on-windows/graphics-debugging-in-visual-studio-2013/graphicsdebugger.png.sha1 b/chromium/docs/website/site/developers/how-tos/debugging-on-windows/graphics-debugging-in-visual-studio-2013/graphicsdebugger.png.sha1 new file mode 100644 index 00000000000..26af945c9e2 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/debugging-on-windows/graphics-debugging-in-visual-studio-2013/graphicsdebugger.png.sha1 @@ -0,0 +1 @@ +6bb7834a243e91e54421f9d85e56cbe5482c37a2
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/debugging-on-windows/graphics-debugging-in-visual-studio-2013/index.md b/chromium/docs/website/site/developers/how-tos/debugging-on-windows/graphics-debugging-in-visual-studio-2013/index.md new file mode 100644 index 00000000000..f7e8e257e42 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/debugging-on-windows/graphics-debugging-in-visual-studio-2013/index.md @@ -0,0 +1,69 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +- - /developers/how-tos/debugging-on-windows + - Debugging Chromium on Windows +page_name: graphics-debugging-in-visual-studio-2013 +title: Graphics Debugging in Visual Studio 2013 +--- + +Visual Studio 2013 has a built-in graphics debugger that can capture a rendered +frame. This is a replacement for PIX. + +To use it with Chromium: + +* Pass the command arguments: --no-sandbox --in-process-gpu + * To enable gpu rasterization, include the command line arguments: + --force-gpu-rasterization --enable-impl-side-painting + * You might need following hack or something + diff --git a/content/app/content_main_runner.cc b/content/app/content_main_runner.cc index 05e45bd..46db961 100644 --- a/content/app/content_main_runner.cc +++ b/content/app/content_main_runner.cc @@ -401,6 +401,11 @@ int RunNamedProcessTypeMain( { switches::kGpuProcess, GpuMain }, #endif // !CHROME_MULTIPLE_DLL_BROWSER }; + base::CommandLine& command_line = + \*base::CommandLine::ForCurrentProcess(); + command_line.AppendSwitch(switches::kInProcessGPU); + command_line.AppendSwitch(switches::kNoSandbox); +* Within Visual Studio, show the Graphics toolbar +* Click File>Open>Project/Solution, and then click your + chrome.exe FYI, release build chrome.exe/content_shell.exe works + well. +* Click the "Start Diagnostics" button on the Graphics toolbar +* While hardware accelerated graphics are being rendered within + Chromium, press the Print Scrn key, or the "Capture Next Rendered + Frame" button on the Graphics toolbar + +Each frame time will be super imposed on top of Chrome. If you don't see this +then the Graphics Debugger is not working correctly and you won't be able to +capture frames. + +[<img alt="image" +src="/developers/how-tos/debugging-on-windows/graphics-debugging-in-visual-studio-2013/graphicsdebugger.png">](/developers/how-tos/debugging-on-windows/graphics-debugging-in-visual-studio-2013/graphicsdebugger.png) + +Here is a description of some of the more important elements of the Graphic +Debugger (numbers correspond to the highlighted part on the above image): + +1. The Graphic toolbar +2. The *Graphic Event List* pane keeps a complete history of the calls + to create the frame. Clicking through the list will generate a + preview of the frame up to the call that you have selected in the + .vsglog frame in the center. +3. Within the event list, you can find objects that were created by or + used in a function call +4. The *Graphics Object Table* contains a list of all objects used + during the frame +5. The name of an object is set within the chrome source. For example, + if you search for "Offscreen back buffer texture", you will find it + in the function "SwapChain11::resetOffscreenTexture" +6. Some calls within the *Graphics Event List* will give you a call + stack (usually, you must click directly on a DirectX function to get + a call stack) +7. If you double click an object in the *Graphics Object Table*, you + can get details on the object. If it is a texture, it will open and + display the texture +8. If you double click on a shader in the *Graphics Object Table*, you + can open a temporary file that shows the shader code + +You can find more information on the Graphics Debugger at +<http://msdn.microsoft.com/en-us/library/hh873207.aspx> and +<https://www.youtube.com/watch?v=j4SpasLF6Co> + +You may find it useful to use the configuration manager within Visual Studio to +create multiple debug targets. For example, you can set up a second +configuration to pass the gpu specific flags.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/debugging-on-windows/index.md b/chromium/docs/website/site/developers/how-tos/debugging-on-windows/index.md new file mode 100644 index 00000000000..590baa1e7d7 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/debugging-on-windows/index.md @@ -0,0 +1,469 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: debugging-on-windows +title: Debugging Chromium on Windows +--- + +First see [get the code](/developers/how-tos/get-the-code) for checkout and +build instructions. + +## Getting started + +### You can use Visual Studio's built-in debugger or [WinDBG](/developers/how-tos/debugging-on-windows/windbg-help) to debug Chromium. You don't need to use the IDE to build in order to use the debugger: Ninja is used to build Chromium and most developers invoke it from a command prompt, and then open the IDE for debugging as necessary. To start debugging an already-built executable with Visual Studio just launch Visual Studio (2019 or higher) and select File-> Open-> Project/Solution (Ctrl+Shift+O) and select the executable of interest. This will create a solution with that executable as the 'project'. You can then launch the debugger with F5 or F11 or from the Debug menu. If you right-click on the executable in Solution Explorer and select properties then you can edit things such as the executable path, command-line arguments, and working directory. + +You can add additional executables to the solution by using File-> Add-> +Existing Project and selecting another already-built executable. You can select +which one to debug by right-clicking on one of them in Solution Explorer and +selecting Set as Startup Project. + +When your solution file is customized to your taste you can save it to a +directory such as out\\solutions. Saving it there helps ensure that relative +paths to source files, printed from build commands, will correctly identify the +source files. + +The Tools menu can be used to add commands to do things like invoke ninja to +build Chrome, compile the selected source file, or other things. + +Visual Studio 2017 is not recommended for debugging of Chromium - use a newer +version for best performance and stability. + +symbol_level=2 is the default on Windows and gives full debugging information +with types, locals, globals, function names, and source/line information. +symbol_level=1 creates smaller PDBs with just function names, and source/line +information - source-level debugging is still supported (new from June 2019), +but local variables and type information are missing. symbol_level=0 gives +extremely limited debugging abilities, mostly just viewing call stacks when +Chromium crashes. + +#### Browsing source code + +If you use a solution file generated by gn (gn gen --ide=vs) then Intellisense +may help you navigate the code. If this doesn't work or if you use a solution +created as above then you may want to install +[VsChromium](https://chromium.github.io/vs-chromium/) to help navigate the code, +as well as using <https://source.chromium.org>. + +#### Profiles + +It's a good idea to use a different Chrome profile for your debugging. If you +are debugging Google Chrome branded builds, or use a Chromium build as your +primary browser, the profiles can collide so you can't run both at once, and +your stable browser might see profile versions from the future (Google Chrome +and Chromium use different profile directories by default so won't collide). Use +the command-line option: + +> --user-data-dir=c:\\tmp\\my_debug_profile (replace the path as necessary) + +Using the IDE, go to the **Debugging** tab of the properties of the chrome +project, and set the **Command Arguments.** + +#### Chrome debug log + +Enable Chrome debug logging to a file by passing --enable-logging --v=1 +command-line flags at startup. Debug builds place the chrome_debug.log file in +the out\\Debug directory. Release builds place the file in the top level of the +user data Chromium app directory, which is OS-version-dependent. For more +information, see [logging](/for-testers/enable-logging) and [user data +directory](/user-experience/user-data-directory) details. + +#### Symbol server + +If you are debugging official Google Chrome release builds, use the symbol +server: + +> https://chromium-browser-symsrv.commondatastorage.googleapis.com + +In Visual Studio, this goes in **Tools > Options** under **Debugging > +Symbols**. You should set up a local cache in a empty directory on your +computer. + +In windbg you can add this to your symbol server search path with the command +below, where c:\\Symbols is a local cache directory: + +> .sympath+ +> SRV\*c:\\Symbols\*https://chromium-browser-symsrv.commondatastorage.googleapis.com + +Alternately, You can set the _NT_SYMBOL_PATH environment variable to include +both the Microsoft and Google symbol servers - VS, windbg, and other tools +should both respect this environment variable: + +> _NT_SYMBOL_PATH=SRV\*C:\\symbols\*https://msdl.microsoft.com/download/symbols;SRV\*C:\\symbols\*https://chromium-browser-symsrv.commondatastorage.googleapis.com + +Note that symbol servers will let the debuggers download both the PE files (DLLs +and EXEs) and the PDB files. + +Chrome often loads third party libraries and partial symbols for some of these +are also public. For example: + +**AMD**: https://download.amd.com/dir/bin + +**Nvidia**: https://driver-symbols.nvidia.com/ + +**Intel**: https://software.intel.com/sites/downloads/symbols/ + +For example, for completeness, the following symbol server environment variable +will resolve all of the above sources - but this is more than is normally +needed: + +> _NT_SYMBOL_PATH=SRV\*C:\\symbols\*https://msdl.microsoft.com/download/symbols;SRV\*C:\\symbols\*https://chromium-browser-symsrv.commondatastorage.googleapis.com;SRV\*C:\\symbols\*https://download.amd.com/dir/bin;SRV\*C:\\symbols\*https://driver-symbols.nvidia.com/;SRV\*C:\\symbols\*https://software.intel.com/sites/downloads/symbols/ + +#### Source indexing + +You should set up source indexing in your debugger (.srcfix in windbg, +Tools-> Options-> Debugging-> General-> *Enable source server +support* in Visual Studio) so that the correct source files will automatically +be downloaded based on information in the downloaded symbols. + +Additionally, you must have python in your path in order for the [command that +fetches source +files](https://source.chromium.org/chromium/chromium/src/+/main:tools/symsrc/source_index.py;drc=374a3e7974dacf4423c2f44cf9dab69c31d34b48;l=492) +to succeed; launching the debugger from the same environment as where you build +Chromium is an easy way to ensure it's present. + +This is highly recommended when debugging released Google Chrome builds or +looking at crash dumps. Having the correct version of the source files +automatically show up saves significant time so you should definitely set this. + +## Multi-process issues + +Chromium can be challenging to debug because of its [multi-process +architecture](/developers/design-documents/multi-process-architecture). When you +select **Run** in the debugger, only the main browser process will be debugged. +The code that actually renders web pages (the Renderer) and the plugins will be +in separate processes that's not (yet!) being debugged. The +[ProcessExplorer](http://technet.microsoft.com/en-us/sysinternals/bb896653.aspx) +tool has a process tree view where you can see how these processes are related. +You can also get the process IDs associated with each tab from the Chrome Task +Manager (right-click on an empty area of the window title bar to open). + +**Automatically attach to child processes** + +There are two Visual Studio extensions that enable the debugger to automatically +attach to all Chrome processes, so you can debug all of Chrome at once. +Microsoft's [Child Process Debugging Power +Tool](https://blogs.msdn.microsoft.com/devops/2014/11/24/introducing-the-child-process-debugging-power-tool) +is a standalone extension for this, and +[VsChromium](https://chromium.github.io/vs-chromium/) is another option that +bundles many other additional features. In addition to installing one of these +extensions, you **must** run Visual Studio as Administrator, or it will silently +fail to attach to some of Chrome's child processes. + +### Single-process mode + +One way to debug issues is to run Chromium in single-process mode. This will +allow you to see the entire state of the program without extra work (although it +will still have many threads). To use single-process mode, add the command-line +flag + +> `--single-process` + +This approach isn't perfect because some problems won't manifest themselves in +this mode and some features don't work and worker threads are still spawned into +new processes. + +### Manually attaching to a child process + +### You can attach to the running child processes with the debugger. Select +**Tools > Attach to Process** and click the **chrome.exe** process you want +to attach to. Before attaching, make sure you have selected only Native code +when attaching to the process This is done by clicking Select... in the Attach +to Process window and only checking Native. If you forget this, it may attempt +to attach in "WebKit" mode to debug JavaScript, and you'll get an error message +"An operation is not legal in the current state." + +### You can now debug the two processes as if they were one. When you are +debugging multiple processes, open the **Debug > Windows > Processes** +window to switch between them. + +### Sometimes you are debugging something that only happens on startup, and want +to see the child process as soon as it starts. Use: + +> ### --renderer-startup-dialog --no-sandbox + +### You have to disable the sandbox or the dialog box will be prohibited from +showing. When the dialog appears, visit Tools > Attach to Process and attach +to the process showing the Renderer startup dialog. Now you're debugging in the +renderer and can continue execution by pressing OK in the dialog. + +### Startup dialogs also exist for other child process types: +--gpu-startup-dialog, --ppapi-startup-dialog, --utility-startup-dialog, +--plugin-startup-dialog (for NPAPI). + +### For utilities, you can add a service type +--utility-startup-dialog=data_decoder.mojom.DataDecoderService. + +### You can also try [the vs-chromium +plug-in](http://chromium.github.io/vs-chromium/#attach-to-chrome) to attach to +the right processes. + +### Semi-automatically attaching the debugger to child processes + +### The following flags cause child processes to wait for 60 seconds in a busy +loop for a debugger to attach to the process. Once either condition is true, it +continues on; no exception is thrown. + +> ### --wait-for-debugger-children\[=*filter*\] + +### The filter, if provided, will fire only if it matches the --type parameter +to the process. Values include renderer, plugin (for NPAPI), ppapi, gpu-process, +and utility. + +### When using this option, it may be helpful to limit the number of renderer +processes spawned, using: + +> ### --renderer-process-limit=1 + +### Image File Execution Options + +Using Image File Execution Options (IFEO) will not work because CreateProcess() +returns the handle to the debugger process instead of the intended child +process. There are also issues with the sandbox. + +## Time travel debugging + +You can do [time travel debugging using WinDbg +Preview](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/time-travel-debugging-overview) +(must be installed from the Microsoft Store). This lets you execute a program +forward and backwards. After capturing a trace, you can set breakpoints and step +through code as normal, but also provides 'backwards' commands (g-, t-, p-) so +that you can go back and forth through the execution. It is especially useful to +set data breakpoints ([ba +command](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/ba--break-on-access-)) +and reverse continuing, so you can see when a certain variable was last changed +to its current value. + +Chromium specifics: + +- The type of injection the time travel tracer needs to perform is incompatible +with the Chromium sandbox. In order to record a trace, you'll need to run with +\`--no-sandbox\`. + +- Chromium cannot run elevated with Administrator privileges, so the "Launch +executable (advance)" option won't work, you'll need to attach after the process +has already launched via the checkbox in the bottom right. <img alt="image" +src=""> + +- If you need to record startup-like things, you'll have to use +--{browser,gpu,renderer,utility}-startup-dialog, then attach (and hope the +relevant code hasn't executed before that point). + +## JsDbg -- data structure visualization + +You can install [JsDbg as a plugin for WinDbg or Visual +Studio](https://github.com/MicrosoftEdge/JsDbg). It interactively lets you look +at data structures (such as the DOM tree, Accessibility tree, layout object +tree, and others) in a web browser as you debug. See the [JsDbg +site](https://github.com/MicrosoftEdge/JsDbg/blob/master/docs/FEATURES.md) for +some screen shots and usage examples. This also works when examining memory +dumps (though not minidumps), and also works together with time travel +debugging. + +## Visual Studio hints + +### **Debug visualizers** + +Chrome's custom debug visualizers should be added to the pdb files and +automatically picked up by Visual Studio. The definitions are in +[//tools/win/DebugVisualizers](https://cs.chromium.org/chromium/src/tools/win/DebugVisualizers/) +if you need to modify them (the BUILD.gn file there has additional +instructions). + +### **Don't step into trivial functions** + +The debugger can be configured to automatically not step into functions based on +regular expression. Edit default.natstepfilter in the following directory: + +* For Visual Studio 2015: C:\\Program Files (x86)\\Microsoft Visual + Studio 14.0\\Common7\\Packages\\Debugger\\Visualizers (for all + users) + or %USERPROFILE%\\My Documents\\Visual Studio 2015\\Visualizers (for the + current user only) +* For Visual Studio 2017 Pro: C:\\Program Files (x86)\\Microsoft + Visual + Studio\\2017\\Professional\\Common7\\Packages\\Debugger\\Visualizers + (for all users) + or %USERPROFILE%\\My Documents\\Visual Studio 2017\\Visualizers (for the + current user only) + +Add regular expressions of functions to not step into. Remember to regex-escape +*and* XML-escape them, e.g. < for < and \\. for a literal dot. Example: + +<Function><Name>operator +new</Name><Action>NoStepInto</Action></Function> + +<Function><Name>operator +delete</Name><Action>NoStepInto</Action></Function> + +<!-- Skip everything in std --> + +<Function><Name>std::.\*</Name><Action>NoStepInto</Action></Function> + +<!-- all methods on WebKit OwnPtr and variants, ... WTF::\*Ptr<\*>::\* +--> + +<Function><Name>WTF::.\*Ptr<.\*>::.\*</Name><Action>NoStepInto</Action></Function> + +This file is read at start of a debugging session (F5), so you don't need to +restart Visual Studio after changing it. + +More info: [Andy Pennel's +Blog](http://blogs.msdn.com/b/andypennell/archive/2004/02/06/69004.aspx), +[microsoft email +thread](http://groups.google.com/group/microsoft.public.vsnet.debugging/msg/26addb1b539883e8) + +## V8 and Chromium + +V8 supports many command-line flags that are useful for debugging. V8 +command-line flags can be set via the Chromium command-line flag --js-flags; for +instance: + +chrome.exe --js-flags="--trace_exception --heap_stats" + +Note that some V8 command-line flags exist only in the debug build of V8. For a +list of all V8 flags try: + +chrome.exe --js-flags="--help" + +## Graphics debugging + +GPU Acceleration of rendering can be more easily debugged with tools. See: + +* [Graphics Debugging in Visual Studio + 2013](/developers/how-tos/debugging-on-windows/graphics-debugging-in-visual-studio-2013) +* [Graphical debugging with NVIDIA + NSight](/developers/design-documents/chromium-graphics/debugging-with-nsight) + +## Debugging on another machine + +Sometimes it's useful to debug installation and execution on a machine other +than your primary build box. To run the installer on said other machine, first +build the mini_installer target on your main build machine (e.g., ninja -C +out\\Debug mini_installer). Next, on the debug machine: + +* Make the build machine's build volume available on the debug machine + either by mounting it locally (e.g., Z:\\) or by crafting a UNC path + to it (e.g., \\\\builder\\src) +* Open up a command prompt and change to a local disk +* Run + src\\tools\\win\\[copy-installer.bat](https://code.google.com/p/chromium/codesearch#chromium/src/tools/win/copy-installer.bat) + in the remote checkout by way of the mount (e.g., + Z:\\PATHTOCHECKOUT\\src\\...) or UNC path (e.g., + \\\\builder\\src\\...). This will copy the installer, DLLs, and PDBs + into your debug machine's C:\\out or C:\\build (depending on if + you're rocking the component=shared_library build or not) +* Run C:\\out\\Debug\\mini_installer.exe with the flags of your choice + to install Chrome. This can take some time, especially on a slow + machine. Watch the Task Manager and wait until mini_installer.exe + exits before trying to launch Chrome (by way of the shortcut(s) + created by the installer) +* For extra pleasure, add C:\\out\\Debug to your _NT_SYMBOL_PATH + environment variable + +Consider reading the documentation at the top of copy-installer.bat to see how +you can run it. It tries to be smart and copy the right things, but you may need +to be explicit (e.g., "copy-installer.bat out Debug"). It is safe to re-run the +script to copy only modified files (after a rebuild, for example). + +You can also use the zip action of the isolate scripts (tools\\mb\\mb.py) to +package all the files for a target into a single zip file, for example: + +> python tools\\mb\\mb.py zip out/Release base_unittests base_unittests.zip + +## Finding all memory allocations + +It is possible to use Heap Snapshots (requires recent versions of Windows 10?) +to get call stacks on all outstanding allocations. This works particularly well +if heap snapshots are started as soon as the Chrome browser process is created, +but before it starts running. Details can be found in [this batch +file](https://github.com/google/UIforETW/blob/master/bin/etwheapsnapshot.bat). + +## Find memory leaks + +The Windows heap manager has a really useful debug flag, where it can be asked +to capture and store a stack trace with every allocation. The tool to scrape +these stack traces out of processes is UMDH, which comes with +[WinDbg](/developers/how-tos/debugging-on-windows/windbg-help). + +UMDH is great. It will capture a snapshot of the heap state as many times as you +like, and it'll do it fairly quickly. You then run it again against either a +single snapshot, or a pair of snapshots, at which time it'll symbolize the stack +traces and aggregate usage up to unique stack traces. + +Turning on the user stack trace database for chrome.exe with gflags.exe makes it +run unbearably slowly; however, turning on the user stack trace database on for +the browser alone is just fine. + +While it's possible to turn on the user stack database with the "!gflag" +debugging extension, it's too late to do this by the time the initial debugger +breakpoint hits. The only reasonable way to do this is to + +1. Launch GFlags.exe, +2. Enable the user stack trace database (per image below), +3. Launch Chrome under the debugger. +4. Set a breakpont when chrome.dll loads with "sxe ld chrome.dll". +5. Step up, to allow Chrome.dll to initialize. +6. Disable the stack trace database in GFlags.exe. +7. Continue chrome, optionally detaching the debugger. + +[<img alt="image" +src="/developers/how-tos/debugging-on-windows/gflags.png">](/developers/how-tos/debugging-on-windows/gflags.png) + +GFlags.exe settings for user mode stack trace database. + +If you then ever suffer a browser memory leak, you can snarf a dump of the +process with + +> umdh -p:<my browser pid> > chrome-browser-leak-umdh-dump.txt + +which can then typically be "trivially" analyzed to find the culprit. + +## Miscellaneous + +Note that until [crbug.com/1004989](http://crbug.com/1004989) is fixed you may +need to add --disable-features=RendererCodeIntegrity to avoid sandbox crashes in +renderer processes when using Application Verifier. See also [this +page](/developers/testing/page-heap-for-chrome). + +* [Application + Verifier](https://randomascii.wordpress.com/2011/12/07/increased-reliability-through-more-crashes/) + is a free tool from Microsoft (available as part of the Windows SDK) + that can be used to flush out programming errors. Starting with M68 + Application Verifier can be enabled for chrome.exe without needing + to disable the sandbox. After adding chrome.exe to the list of + applications to be stressed you need to expand the list of Basics + checks and disable the *Leak* checks. You may also need to disable + *Handles* and *Locks* checks depending on your graphics driver and + specific Chrome version, but the eventual goal is to have Chrome run + with *Handles* and *Locks* checks enabled. When bugs are found + Chrome will trigger a breakpoint so running all Chrome processes + under a debugger is recommended. Chrome will run much more slowly + because Application Verifier puts every allocation on a separate + page. +* You can check the undocumented 'Cuzz' checkbox in Application + Verifier to get the Windows thread scheduler to add some extra + randomness in order to help expose race conditions in your code. +* Putting every allocation on a separate page will *dramatically* + affect performance so you may want to only do this for some + applications. If you right-click on the Heaps checkbox and select + Properties you can edit things like the size range for what + allocations go into PageHeap (the page-per-allocation system) and + you can set a RandRate percentage to randomly put allocations in + PageHeap. + +* To put a breakpoint on CreateFile(), add this break point: + +> {,,kernel32.dll}_CreateFileW@28 + + * {,,kernel32.dll}specifies the DLL (context operator). + * _ prefix means extern "C". + * @28 postfix means _stdcall with the stack pop at the end of the + function. i.e. the number of arguments in BYTES. +* You can use [DebugView + ](https://docs.microsoft.com/en-us/sysinternals/downloads/debugview)from + SysInternals or + [sawbuck](https://github.com/google/sawbuck/releases/latest) to view + LOG() messages that normally go to stderr on POSIX.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/debugging-on-windows/windbg-help/index.md b/chromium/docs/website/site/developers/how-tos/debugging-on-windows/windbg-help/index.md new file mode 100644 index 00000000000..193d66f05ea --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/debugging-on-windows/windbg-help/index.md @@ -0,0 +1,249 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +- - /developers/how-tos/debugging-on-windows + - Debugging Chromium on Windows +page_name: windbg-help +title: WinDBG help +--- + +[WinDBG](http://www.microsoft.com/whdc/DevTools/Debugging/default.mspx) is a +great, free tool. It is more powerful than Visual Studio's built-in debugger, +but is harder to use (kind of like gdb on Linux). You can retrieve the [latest +version](http://msdn.microsoft.com/en-us/windows/hardware/hh852365) from +Microsoft's web site. You should end up with two versions of the tool: the +32-bit debugger and the 64-bit debugger. If you already have it installed or if +you are using the packaged Chromium toolchain (which includes windbg) then you +can launch it using tools\\win\\windbg32.bat or tools\\win\\windbg64.bat. These +batch files find and run the appropriate version, wherever it is. + +### Initial setup + +Once you're started, you may wish to fix a few things. If you have run WinDbg +before and saved any workspaces, you may wish to start with a clean slate by +deleting the key HKCU\\Software\\Microsoft\\Windbg using your favorite registry +editor. + +1. Set the environment variable **_NT_SYMBOL_PATH**, as per [Symbol + path for Windows + debuggers](https://msdn.microsoft.com/library/windows/hardware/ff558829.aspx#controlling_the_symbol_path) + (e.g., File -> Symbol Search Path), to: + https://chromium-browser-symsrv.commondatastorage.googleapis.com****SRV\*c:\\code\\symbols\*https://msdl.microsoft.com/download/symbols;SRV\*c:\\code\\symbols\* +2. Configure WinDbg to use a sensible window layout by navigating + explorer to "**C:\\Program Files (x86)\\Windows + Kits\\10\\Debuggers\\x64\\themes**" and double-clicking on + **standard.reg**. +3. Launch **windbg.exe** and: + 1. In the menu *File,* *Source File Path...*, set the path to + **srv\***. + * If you have a local checkout of the source, you can just + point *Source Path* to the root of your code (src). Multiple + paths are separated by semicolons. + * If you want to download the individual source files to a + given directory, add the destination to the path like so: + **srv\*c:\\path\\to\\downloaded\\sources;c:\\my\\checkout\\src** + 2. In the menu *View*, *Source language file extensions*..., add + **cc=C++** to have automatic source colors. + 3. Optionally, customize the window layout as desired via the + *View* menu, and dock the windows as you want them to be. Note + that the UI allows multiple "Docks" and each Dock can have + multiple tiled panels in it, and each panel can have multiple + tabbed windows. You may want to have source files to be tabbed + on the same panel, and visible at the same time as local + variables and the stack and command windows. It is useful to + realize that by default windbg creates a workspace per debugged + executable or minidump, so each target can have its own + configuration. The "default" workspace is applied to new + targets. + 4. Optionally, run additional customization commands such as: + 1. **.asm no_code_bytes** + * disables display of opcodes + 2. **.prompt_allow -sym -dis -ea -reg -src** + * Disables display of symbol for the current instruction, + disassembled instructions, effective address of current + instruction, current state of registers and source line + for the current instruction + 3. **.srcfix** + * Enables source server. This tells the debugger to use + information in the Chrome PDBs to download the correct + version of all necessary source files. + 5. Use *File, Save Workspace* to make this new configuration the + default for all future execution. + 6. Exit windbg. +4. In Windows Explorer, associate **.dmp** extension with windbg.exe. + You may have to manually add -z to the open command like so: + **"...\\windbg.exe" -z "%1"** to make this work properly. + Alternatively, run **windbg.exe -IA** +5. Register as the default just in time debugger: **windbg.exe -I** + +**To set your symbol and source environment variables permanently, you can run +the following commands:** + +**setx _NT_SYMBOL_PATH +SRV\*c:\\code\\symbols\*https://msdl.microsoft.com/download/symbols;SRV\*c:\\code\\symbols\*https://chromium-browser-symsrv.commondatastorage.googleapis.com** + +**setx _NT_SOURCE_PATH SRV\*c:\\code\\source;c:\\my\\checkout\\src** + +### Common commands + +* **dt this->member_** + * Displays the data + +* **x chrome\*!\*function_name** + * Finds a symbol. + +* **.open -a \[symbol address or complete symbol name found by using + x\]** + * Opens the source file containing the specified symbol. Pretty + neat. +* **k** + * Displays the stack. + * **kP**: Show all parameters. + * **kM**: Show links to each stack frame. + * Clicking on the links shifts into the other stack frame, + allowing you to browse locals, etc. + +* **?? \[data name\]** + * Quick evaluation of a C++ symbol (local variable, etc). You + don't need to specify this-> for member variables but it's + slower if you don't. + +* **dv \[/V\]** + * Displays local variables +* **dt varname** + * Displays a variable. + +* **dd address** + * Displays the contents of memory at the given address (as + doubles... **dc, dw, dq** etc) + +* **dt -r1 type address** + * Displays an object of the given type stored at the given + address, using 1 level of recursion. +* **uf symbol** + * Disassembles a function showing source line number. + +* **!stl** + * Displays some stl structures (visualizer) + +* **dt -n <type>** + * Displays a type forcing the name to the supplied type (when + there are problematic characters in the name) + +* **~\*n** + * Freezes all threads + +* **~4m** + * Thaws thread number 4 + +* **Ctrl-Shift-I** + * Sets the selected source line to be the next line to be executed + +* **F5, Ctrl-Shift-F5, F9, F10, F11** + * Run, restart, toggle breakpoint, step over, step into. + +One of the major benefits of WinDBG for debugging Chromium is its ability to +automatically debug child processes. This allows you to skip all the complicated +instructions above. The easiest way to enable this is to check "*Debug child +processes also*" in the "*Open Executable*" dialog box when you start debugging +or start "**windbg.exe -o**". **NOTE that on 64-bit Windows you may need to use +the [64-bit +WinDbg](http://www.microsoft.com/whdc/devtools/debugging/install64bit.mspx) for +this to work.** You can switch dynamically the setting on and off at will with +the **.childdbg 1|0** command, to follow a particular renderer creation. You can +also attach to a running process (**F6**) and even detach without crashing the +process (**.detach**) + +### **Common commands when working with a crash** + +* **!analyze -v** + * Displays a basic crash analysis report. + +* **.ecxr** + * Switch the context to the exception record. + +* **dds address** + * Displays symbols following address (as in a stack or vtable) + +* **k = address address address** + * Rebuilds a call stack assuming that address is a valid stack + frame. + +* **lm vmchr\*** + * Lists verbose information about all modules with a name that + starts with ch + +* **ln address** + * Lists all symbols that match a given address (dedups a symbol). + +* **.load wow64exts** + * On a 64-bit debugger, load the 32-bit extensions so that the + current architecture can be switched + +* **.effmach x86** + * Switches the current architecture to 32-bit. + +* **.effmach x86; k = @ebp @ebp @ebp** + * Shows the 32-bit call stack from a 64-bit dump + +For more info, see [this example of working with a crash +dump](/developers/how-tos/debugging-on-windows/example-of-working-with-a-dump), +consult the program help (really, it's exhaustive!), see [Common windbg +commands](http://windbg.info/doc/1-common-cmds.html) or use your favorite search +engine. + +### **Random handy hints** + +To set attach to child processes, and also skip the first breakpoint and the +extra breakpoint on process exit (this gives you a pretty responsive Chrome you +can debug): + +**sxn ibp** + +**sxn epr** + +**.childdbg 1** + +**g** + +You can also get this effect by using the -g -G -o options when launching +windbg, as in: + +**windbg -g -G -o chrome.exe** + +To automatically attach to processes you want to run over and over with complex +command lines, just attach WinDBG to your command prompt and then **.childdbg +1** the command prompt - any processes launched from there will automatically be +debugged. H/T pennymac@ + +To set a breakpoint in the current process you can use this module/function +syntax, among others: + +**bp msvcrt!invalid_parameter** + +To apply this to future processes that are created (assuming child process +debugging is enabled) you can use this syntax, which says to run the bp command +whenever a new process is created: + +**sxe -c "bp msvcrt!invalid_parameter" cpr** + +If you want a chance to do this when you first launch the browser process then +you need to launch it without -g (so that the first breakpoint will be hit). You +will probably then want to disable the "Create process" breakpoint and "Initial +breakpoint" with these commands: + +**sxn ibp; sxn epr;** + +These are equivalent to going to Debug-> Event Filters and setting "Create +process" and "Initial breakpoint" to "Ignore". + +Always use **--user-data-dir** when starting Chrome built with +**branding=Chrome** or else you're going to have a bad time. + +### Resources + +* [Extensive slide deck](http://windbg.info/doc/2-windbg-a-z.html) + \[windbg.info\]
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/depottools/gclient/index.md b/chromium/docs/website/site/developers/how-tos/depottools/gclient/index.md new file mode 100644 index 00000000000..d1eec12e46f --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/depottools/gclient/index.md @@ -0,0 +1,13 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +- - /developers/how-tos/depottools + - Using depot_tools +page_name: gclient +title: gclient +--- + +See [depot_tools](/developers/how-tos/depottools).
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/depottools/index.md b/chromium/docs/website/site/developers/how-tos/depottools/index.md new file mode 100644 index 00000000000..05ab321cec9 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/depottools/index.md @@ -0,0 +1,196 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: depottools +title: Using depot_tools +--- + +[TOC] + +View the [**updated depot_tools documentation** +here.](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools.html) +These same docs are also available as man pages. +Not all the information on this page has been migrated to the man pages yet, so +this resource will stay around for a while, but where there are discrepancies, +the man pages should be considered authoritative. + +The [depot_tools +tutorial](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html) +walks through a few key scenarios like managing branches. + +## Introduction + +Chromium uses a package of scripts, the depot_tools, to manage interaction with +the Chromium source code repository and the Chromium development process. It +contains the following utilities: + +* gclient: Meta-checkout tool managing both subversion and git + checkouts. It is similar to [repo + tool](https://gerrit.googlesource.com/git-repo) except that it works + on Linux, OS X, and Windows and supports both svn and git. On the + other hand, gclient doesn't integrate any code review functionality. +* **gcl**: [Rietveld](https://github.com/rietveld-codereview/rietveld) + code review tool for *subversion*. The gcl tool runs [presubmit + scripts](/developers/how-tos/depottools/presubmit-scripts). +* **git-cl**: + [Rietveld](https://github.com/rietveld-codereview/rietveld) code + review tool for *git*. The git-cl tool runs [presubmit + scripts](/developers/how-tos/depottools/presubmit-scripts). +* **svn** \[Windows only\]: [subversion + client](https://subversion.apache.org/) for Chromium development. + (Executable Subversion binaries are included in the depot_tools on + Windows systems as a convenience, so that working with Chromium + source code does not require a separate Subversion download.) +* **drover**: Quickly revert svn commits. +* **cpplint.py**: Checks for C++ style compliance. +* **pylint**: Checks for Python style compliance. +* **presubmit_support.py**: Runs PRESUBMIT.py presubmit checks. +* **repo**: The repo tool. +* **wtf**: Displays the active git branches in a chromium os checkout. +* **weekly**: Displays the log of checkins for a particular developer + since a particular date for git checkouts. +* **git-gs**: Wrapper for git grep with relevant source types. +* **zsh-goodies**: Completion for zsh users. + +It is highly encouraged to look around and open the files in a text editor as +this page can quickly become outdated. + +Please keep ~~this page~~ the man pages updated! + +## Installing + +See the +[depot_tools_tutorial](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up) +for set-up instructions. + +## Help! + +These tools don't have man pages but have integrated help! Try all of these +commands! If the doc is not adequate, send patches to fix them. + +* gclient help + * It works for subcommands too like: gclient help sync +* git-cl help + * It works for subcommands too like: git-cl help patch + +Otherwise, there are +[many](http://www.microsoft.com/resources/documentation/windows/xp/all/proddocs/en-us/app_notepad.mspx?mfr=true) +[great](https://www.vim.org/) [text](https://www.gnu.org/software/emacs/) +[editors](https://notepad-plus-plus.org/) that can help you out to read what the +tools are actually doing. + +## gclient + +`gclient` is a python script to manage a workspace of modular dependencies that +are each checked out independently from different subversion or git +repositories. Features are: + +* Dependencies can be specified on a per-OS basis. +* Dependencies can be specified relative to their parent dependency. +* Variables can be used to abstract concepts. +* Hooks can be specified to be run after a checkout. +* .gclient and DEPS are python scripts, you can hack in easily or add + additional configuration data. + +### .gclient file + +It's the primary file. It is, in fact, a python script. It specifies the +following variables: + +* **solutions**: an array of dictionaries specifying the projects that + will be fetched. +* **hooks**: additional hooks to be run when this meta checkout is + synced. +* **target_os**: an optional array of (target) operating systems to + fetch OS-specific dependencies for. +* **cache_dir**: Primarily for bots, multiple working sets use a + single git cache. See [gclient.py + --cache-dir](https://code.google.com/p/chromium/codesearch#chromium/tools/depot_tools/gclient.py&sq=package:chromium&type=cs&q=%22parser.add_option('--cache-dir'%22&l=1865). + +Additional variables are ignored. + +Each project described in the solutions array can contain an optional DEPS file +that will be processed. The .gclient file is generated with `gclient config +<url>` or by hand. Each solutions entry is a dictionary that can contain the +following variables: + +* **name**: really, the path of the checkout. +* **url**: the remote repository to fetch/clone. +* **custom_deps**: (optional) override the dependencies specified in + the deps and deps_os variables in child DEPS files. Useful when you + want to fetch a writable checkout instead of the default read-only + checkout of a dependency, e.g. you work on native_client from a + chromium checkout. +* **custom_vars**: (optional) override the variables defined in vars + in child DEPS files. Example: override the WebKit version used for a + chromium checkout. +* **safesync_url**: (optional) url to fetch to retrieve the revision + to sync this checkout to. + +### DEPS file + +A DEPS file specifies dependencies of a project. It is in fact a python script. +It specifies the following variables: + +* **deps**: a dictionary of child dependencies to fetch. +* **deps_os**: a dictionary of OSes for OS-specific dependencies, each + containing a dictionary of child dependencies to fetch. +* **vars**: a dictionary of variables to define. Mainly useful to + easily override a batch of revisions at once. +* **hooks**: hooks to run after a sync. +* **use_relative_paths**: relative paths should specify the checkout + relative to this directory instead of the root gclient checkout. + +Additional variables are ignored. Special keywords are: + +* **File()**: used for dependencies, specify to expect to checkout a + file instead of a directory. +* **From()**: used to fetch a dependency definition from another DEPS + file, for chaining. +* **Var()**: replace this string with a variable defined in vars or + overridden. + +### Pinned deps + +Each dependency checkout URL can (and usually does) contain a revision number or +git hash, which means you're going to check out and build from that specific +revision of the module in question. We call that **pinned deps**. The advantage +is that you can build from a known working revision, even if it comes from a +completely different SCM repository or going back in time. The drawback is you +have to update the revision number(s) constantly, what we call **deps rolls**. + +### DEPS examples + +Chromium's +[src/DEPS](https://chromium.googlesource.com/chromium/src/+/HEAD/DEPS) is a +fairly complex example that will show all the possibilities of a DEPS file. + +## Sending patches + +[Contributing code](/developers/contributing-code) is done the same way as in +other Chromium repositories. + +## Disabling auto update + +The `gclient` and `git-cl` scripts are actually wrapper scripts that will, by +default, always update the `depot_tools` to the latest versions of the tools +checked in at +<https://chromium.googlesource.com/chromium/tools/depot_tools.git>. If for some +reason you wish to disable this auto-update behavior, either: + +* Set the environment variable `DEPOT_TOOLS_UPDATE=0`. +* Remove `depot_tools/.git`. This may be appropriate if you choose to + install depot_tools in a common location for use by multiple users + (for example, `/usr/local/bin` on a Linux system). + +Note: If you aren't using either of these helper scripts (e.g. you're developing +Chromium OS), then you will need to manually update depot_tools yourself from +time to time with a simple: git pull + +### Caveat + +Chromium engineers expect the auto-updating behavior of depot_tools, checkout or +presubmit breakage may ensue.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/depottools/presubmit-scripts/index.md b/chromium/docs/website/site/developers/how-tos/depottools/presubmit-scripts/index.md new file mode 100644 index 00000000000..8c4c3c8b343 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/depottools/presubmit-scripts/index.md @@ -0,0 +1,275 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +- - /developers/how-tos/depottools + - Using depot_tools +page_name: presubmit-scripts +title: Presubmit Scripts +--- + +[TOC] + +### Overview + +`gcl` and `git-cl` will check for and run presubmit scripts before you upload +and/or commit your changes. Presubmit scripts are a way of applying automatic +verification to your changes before they are reviewed and/or before they are +committed. + +Presubmit scripts can perform automated checks on the files in your change and +the description of your change, and either fail your attempt to upload or +commit, show a warning that you must acknowledge before uploading/committing, or +simply show an informational message as part of the output of `gcl`. + +Examples of things presubmit scripts may be useful for include: + +* Ensuring your change is linked to a bug via a BUG= line. +* Ensuring you have run + [cpplint.py](http://src.chromium.org/viewvc/chrome/trunk/tools/depot_tools/cpplint.py?view=markup) + or automatically running cpplint for you. +* Enforcing coding conventions. +* Preventing you from breaking dependency rules e.g. by including a + header that code in your directory is not supposed to depend upon. +* Warning you if you haven't built your client and/or run unit tests + within the last X hours. + +Generally you want the same tests for upload and committing, but there are +exceptions. + +Firstly, the commit bot can autofix various problems, so these problems only +need to be checked on commit (to check that they have been fixed), not on upload +(another good reason to use the commit queue!). Secondly, you can skip slow +tests on upload and only run them on commit, if running these every time slows +development too much, but this can result in problems only being caught at the +last minute, and thus requiring last-minute changes after you think they're good +to go. + +### Bypassing tests + +To skip the scripts on upload, use the `--bypass-hooks` flag, as in: + +```none +git cl upload --bypass-hooks +``` + +To skip the scripts on commit, use --bypass-hooks and [directly +commit](/developers/contributing-code/direct-commit) your change. + +You should only do these if necessary, as the presubmit scripts are there for a +reason, but they're not perfect. + +If you have trouble with a presubmit script, it's preferable to *fix it,* rather +than simply bypassing it. See [depot_tools: sending +patches](http://www.chromium.org/developers/how-tos/depottools#TOC-Sending-patches) +for how to contribute. + +### Design + +When you run `gcl upload` or `gcl commit`, `gcl` will look for all files named +`PRESUBMIT.py` in folders enclosing the files in your change, up to the +repository root. + +For each such file, it will load the file into the Python interpreter and then +call either the `CheckChangeOnUpload` or `CheckChangeOnCommit` function +depending on whether you are calling \[gcl upload\] or \[gcl commit\]. + +The same applies to `git-cl upload`, `git-cl dcommit` and `git-cl push`. + +Please note that presubmit scripts are a best-effort kind of thing; they do not +prevent users from submitting without running the scripts, since one can always +dcommit, and in fact there is a --bypass-hooks (formerly `--no_presubmit`) flag +to gcl that skips presubmit checks. Further, since they use the local copy of +the `PRESUBMIT.py` files, users must sync their repos before the latest +presubmit checks will run when they upload or submit. + +More subtly, presubmit scripts do not guarantee invariants: even if presubmit +scripts pass prior to submission to CQ, once all changes land, the scripts may +fail! This is because 2 changes may individually pass the tests, and the patches +both apply cleanly together, but the combined change does not pass tests. Since +presubmit/precommit scripts run at upload or at start of CQ steps, if two such +changes are in the CQ at the same time, they can both pass, both be enqueued, +and both land, at which point the tests start failing. A common example is +change 1 adding a new test, and change 2 changing existing tests. After they +both land, there is a new test in the old style (from change 1), which is out of +sync with the new tests (from change 2). + +### Writing tests + +To create a new test, either create a new PRESUBMIT.py script or edit an +existing one, adding a new function for your test. + +To check your changes, first commit locally (else `git-cl` will complain about +the dirty tree), then: + +To test the upload checks (i.e., to run `CheckChangeOnUpload`): + +```none +git cl presubmit --upload +``` + +To test the submit checks (i.e., to run `CheckChangeOnCommit`): + +```none +git cl presubmit +``` + +The functions must match these method signatures. You do not need to define both +functions if you're only interested in one type of event, and if you want to run +the same tests in both events, just have them both call a single underlying +function: + +```none +def CheckChangeOnUpload(input_api, output_api): + pass +def CheckChangeOnCommit(input_api, output_api): + pass +``` + +The `input_api` parameter is an object through which you can get information +about the change. Using the `output_api` you can create result objects. + +Both `CheckChangeOnXXX` functions must return a list or tuple of result objects, +or an empty list or tuple if there is nothing to report. The types of result +objects you may use are `output_api.PresubmitError` (a critical error), +`output_api.PresubmitPromptWarning` (a warning the user must acknowledge before +the command will continue) and `output_api.PresubmitNotifyResult` (a message +that should be shown). Each takes a message parameter, and optional "items" and +"long_text" parameters. + +#### **Version 2** + +Presubmit version 2 reduces some of the overhead of managing which checks are +executed on upload and/or submit. To enable presubmit version 2, in the global +scope of your presubmit script, define: + +```none +PRESUBMIT_VERSION = '2.0.0' +``` + +In presubmit version 2, you are not required to use `CheckChangeOnUpload` and +`CheckChangeOnCommit` as your entry points. Any function that begins with the +prefix `Check` will be executed, receiving `input_api` and `output_api` as its +parameters. `CheckXXX` functions that end in `Upload` will only be executed on +upload and `CheckXXX` functions that end in `Commit` will only be executed on +commit. `CheckXXX` functions that do not end in either suffix will be executed +at both upload and commit. The format of return values of `CheckChangeOnXXX` +functions is the same as for `CheckChangeOnUpload/CheckChangeOnCommit. This +makes existing presubmit scripts backwards compatible with presubmit version 2 +provided there are no functions in the global scope of the script` that begin +with `Check`. + +#### InputApi + +The `input_api` parameter is an object of type `presubmit.InputApi`; see [`class +InputApi`](https://source.chromium.org/chromium/chromium/tools/depot_tools/+/main:presubmit_support.py?q=file:presubmit_support.py%20%22class%20InputApi%22) +in +[`presubmit_support.py`](https://source.chromium.org/chromium/chromium/tools/depot_tools/+/main:presubmit_support.py) +for implementation. + +This object can be used to transform from local to repository paths and vice +versa, and to get information on the files in the change that are contained in +the same directory as your `PRESUBMIT.py` file or subdirectories thereof. + +The `input_api.change` object represents the change itself. Using this object +you can retrieve the description of the change, any key-value pairs in the +description (e.g. BUG=123), and details on all of the files in the change (not +just the ones contained by the directory your `PRESUBMIT.py` file resides in). + +An `input_api.canned_checks` object contains a set of ready-made checks that you +can easily add to your presubmit script. + +The `os/os.path` module is available as `input_api.os_path`, so you do not need +to import this yourself. + +Files in the API are represented by an `AffectedFile` object through which you +can query the `LocalPath()`, `ServerPath()`, and the `Action()` being performed +('A', 'M' or 'D'). + +The `input_api.is_committing` attribute indicates whether the CL is being +committed or just uploaded. This is particularly useful if you wish the same +test to be run for both upload and committing, but with different behavior. A +common pattern is to prompt a warning on upload, but an error on committing, +which allows a CL to be uploaded and reviewed even if the test fails, but not +committed (without dcommit). This can be done as follows: + +```none +if input_api.is_committing: + message_type = output_api.PresubmitError +else: + message_type = output_api.PresubmitPromptWarning +``` + +### Caveats + +It is possible to run arbitrary Python code in the presubmit scripts. To avoid +side effects and hard-to-debug errors, it is safest to run tests in +subprocesses. The InputApi object provides various facilities to assist with +this; see example below. + +Please note that you should not use any functions or attributes on the API +objects that begin with an underscore (_) as these are private functions that +may change, whereas all public functions will be retained through future +versions of the API. + +### Details and Example + +The most detailed documentation for the presubmit API is in its [implementation +code](https://cs.chromium.org/chromium/tools/depot_tools/presubmit_support.py). + +The [canned +checks](https://source.chromium.org/chromium/chromium/tools/depot_tools/+/main:presubmit_canned_checks.py) +are good examples of what you can do with the presubmit API. + +An example simple file might be as follows: + +```none +def CheckChange(input_api, output_api): + results = [] + results += input_api.canned_checks.CheckDoNotSubmit(input_api, output_api) + results += input_api.canned_checks.CheckChangeHasNoTabs(input_api, output_api) + results += input_api.canned_checks.CheckLongLines(input_api, output_api) + # Require a BUG= line and a HOW_TO_TEST= line. + if not input_api.change.BUG or not input_api.change.HOW_TO_TEST: + results += [output_api.PresubmitError( + 'Must provide a BUG= line and a HOW_TO_TEST line.')] + return results +def CheckChangeOnUpload(input_api, output_api): + return CheckChange(input_api, output_api) +def CheckChangeOnCommit(input_api, output_api): + return CheckChange(input_api, output_api) +``` + +A simple example of a custom command (call from `CheckChangeOnUpload` or +`CheckChangeOnCommit`) is: + +```none +def MyTest(input_api, output_api): + test_path = input_api.os_path.join(input_api.PresubmitLocalPath(), 'my_test.py') + cmd_name = 'my_test' + if input_api.platform == 'win32': + # Windows needs some help. + cmd = [input_api.python_executable, test_path] + else: + cmd = [test_path] + test_cmd = input_api.Command( + name=cmd_name, + cmd=cmd, + kwargs={}, + message=output_api.PresubmitPromptWarning) + if input_api.verbose: + print('Running ' + cmd_name) + return input_api.RunTests([test_cmd]) +``` + +You can look at existing scripts for examples ([search: +PRESUBMIT.py](https://code.google.com/p/chromium/codesearch#search/&q=file:PRESUBMIT.py&sq=package:chromium&type=cs)). +[Chromium's +PRESUBMIT.py](http://src.chromium.org/viewvc/chrome/trunk/src/PRESUBMIT.py?view=markup) +and [Chromium-os +PRESUBMIT.py](http://src.chromium.org/cgi-bin/gitweb.cgi?p=chromium.git;a=blob;f=PRESUBMIT.py;hb=HEAD) +are detailed examples, while the [Blink bindings +PRESUBMIT.py](https://code.google.com/p/chromium/codesearch#chromium/src/third_party/WebKit/Source/bindings/PRESUBMIT.py) +is a very simple example.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/drover/1.png.sha1 b/chromium/docs/website/site/developers/how-tos/drover/1.png.sha1 new file mode 100644 index 00000000000..6dadca50408 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/drover/1.png.sha1 @@ -0,0 +1 @@ +b80d75ad2767ef59e3979eb9f36c8dcf24073f4d
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/drover/2.png.sha1 b/chromium/docs/website/site/developers/how-tos/drover/2.png.sha1 new file mode 100644 index 00000000000..03eaa6ee837 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/drover/2.png.sha1 @@ -0,0 +1 @@ +df03142b1df18425233a26fc17473f24c646c0e0
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/drover/index.md b/chromium/docs/website/site/developers/how-tos/drover/index.md new file mode 100644 index 00000000000..4c2f883b640 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/drover/index.md @@ -0,0 +1,11 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: drover +title: How to merge a change to a release branch +--- + +## This page has been deprecated, see [here](https://chromium.googlesource.com/chromium/src.git/+/refs/heads/main/docs/process/merge_request.md#Landing-an-approved-merge) instead.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/editing-the-spell-checking-dictionaries/index.md b/chromium/docs/website/site/developers/how-tos/editing-the-spell-checking-dictionaries/index.md new file mode 100644 index 00000000000..3904365002e --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/editing-the-spell-checking-dictionaries/index.md @@ -0,0 +1,163 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: editing-the-spell-checking-dictionaries +title: Editing the spell checking dictionaries +--- + +Each hunspell dictionary comes in two files. The .dic file which is the list of +words, and the .aff file which is a list of rules and other options. When adding +new words to existing dictionaries, you should only add to the .dic_delta file, +but you may need to refer to the .aff file for several things. The .dic files +are overwritten when dictionaries are updated, so they should not be modified. + +We maintain some additions to the dictionary files which we keep in a separate +file ending in .dic_delta. Keeping the original unchanged allows us to more +easily pull updated versions from the [dictionary +maintainers](http://lingucomponent.openoffice.org/). Chromium actually reads an +optimized format which uses the suffix .bdic. This file is generated from the +.aff, .dic, and .dic_delta files using the convert_dict tool in the Chromium +project. All of these files are checked into +[deps/third_party/hunspell_dictionaries/](http://src.chromium.org/viewvc/chrome/trunk/deps/third_party/hunspell_dictionaries/) +in Subversion, and checked out into src/third_party/hunspell_dictionaries when +syncing locally. + +#### Encoding issues + +The .dic and .aff files are normally in the encoding most appropriate for that +language, which is unfortunately not usually UTF-8. You will need to open the +files in an editor with that encoding enabled. Most of the Western European +languages use Latin1 which should be easy. For other ones, search in the .aff +file for the line that begins with "SET" to see which character set it uses. + +The .dic_delta files are always in UTF-8! This is confusing, but it allows us to +additional flexibility to add foreign words. The .bdic files are always UTF-8 +internally, and the convert_dict tool converts things appropriately when it +runs. + +## To help + +Our .dic_delta files do not generally have affix rules. These rules tell +Hunspell, for example, how to convert a word into its plural or possessive +forms. The rest of this document explains how to do this. + +The easiest way to get started is to find a word in the .dic file that is like +the word you're looking at in the .dic_delta file, and copy the rules. For +example, en_US.dic contains the entry cat/SM. If you want to add the word +"raccoon" and all of its variants to the dictionary, then add raccoon/SM to +en_US.dic_delta. + +If the .dic files contains incorrect rules for a word, then add the word with +the correct rules to .dic_delta. For example, if en_US.dic contains the entry +raccoon/M, but the rule should be /MS, then add raccoon/MS to en_US.dic_delta. +Rules for entries in .dic_delta override the rules for entries in .dic. + +You can also help by reviewing word lists of words we've identified as popular +but not in the dictionary. Please contact brettw AT chromium.org if you are +interested. + +## Full details + +Affix rules optionally follow each word in the dictionary file. These are +separated from the word using a slash. Each file uses one of two formats. It +will generally be obvious which one is which. Affix rules tell you what prefixes +and suffixes (affixes) can apply to the word. I will describe as much as you +need to know. There are additional details at +<http://sourceforge.net/docman/display_doc.php?docid=29374&group_id=143754> + +### Explicit affix rules + +Explicit affix rules look like a string of letters and numbers after each word. +This is the most common type. For example, here are some lines from the French +file: + +> aberrante/LMF +> aberration/LMS +> aberre/jnu +> aberré +> aberrer/nM + +Each one of the letters indicates a rule that can possibly apply. You can see +that aberré has no rules. This is OK. The other words have a sequence of rules: +each rule is identified by a unique letter. Case matters so "F" is different +than "f". + +Each rule is in the .aff file for that language. The rules come in two flavors: +SFX for suffixes, and PFX for prefixes. Each line begins with PFX/SFX and then +the rule letter identifier (the ones that follow the word in the dictionary +file: + +> PFX <*rule_letter_identifier*> <*combineable_flag*> +> <*number_of_rule_lines_that_follow*> + +You can normally ignore the combinable flag, it is Y or N depending on whether +it can be combined with other rules. Then there are some number of lines +(indicated by the <*number_of_rule_lines_that_follow*>) that list +different possibilities for how this rule applies in different situations. It +looks like this: + +> PFX <*rule_letter_identifier*> <*number_of_letters_to_delete*> +> <*what_to_add*> <*when_to_add_it*> + +For example: + +> SFX B Y 3 +> SFX B 0 able \[^aeiou\] +> SFX B 0 able ee +> SFX B e able \[^aeiou\]e + +If "B" is one of the letters following a word, then this is one of the rules +that can apply. There are three possibilities that can happen (because there are +three lines). Only one will apply: + +* *able* is added to the end when the end of the word is "not" + (indicated by "^") one of the letters in the set (indicated by "\[ + \]") of letters a, e, i, o, and u. For example, *question* → + *questionable* +* *able* is added to the end when the end of the word is "ee". For + example, *agree* → *agreeable.* +* *able* is added to the end when the end of the word is not a vowel + ("\[^aeiou\]") followed by an "e". The letter "e" is stripped (the + column before *able*). For example, *excite* → *excitable.* + +PFX rules are the same, but apply at the beginning of the word instead for +prefixes. + +### Numbered affix rules + +Some dictionaries use numbers instead of a list of affix rules. Each number is a +unique combination of rules, which is convenient since there are usually not +very many unique combinations of rules that can apply. This just means an extra +step. For example, the English dictionary has: + +> Abeu/6 +> abeyance/7 +> abeyant +> Abey/6 + +You can see that abeyant has no rules, so it is never conjugated. The other +rules are 6 and 7. To see what these are, look up in the .aff file. The "AF" +lines you which set of rules correspond to each number. For example, the +en-US.aff file has a bunch of lines like this: + +> AF mn # 1 +> AF 1n # 2 +> AF pt # 3 +> AF p # 4 +> AF ct # 5 +> AF M # 6 +> AF MS # 7 +> AF DGLRS # 8 + +You can then see that 6 corresponds to the rule sequence "M" and 7 corresponds +to the rule sequence "MS". You would look these sequences of rules up just like +the explicit affix rules discussed above. So you look up in the PFX and SFX +lines and find the rule for "M" is: + +> SFX M Y 1 +> SFX M 0 's . + +Which means to make it possessve. For example, *Abey* → *Abbey's.*
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/enterprise/adding-new-policies/index.md b/chromium/docs/website/site/developers/how-tos/enterprise/adding-new-policies/index.md new file mode 100644 index 00000000000..9b3dc95ea1c --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/enterprise/adding-new-policies/index.md @@ -0,0 +1,15 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +- - /developers/how-tos/enterprise + - Enterprise +page_name: adding-new-policies +title: Policy Settings in Chrome +--- + +**This documentation has been moved to** + +==<https://source.chromium.org/chromium/chromium/src/+/main:docs/enterprise/add_new_policy.md>==
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/enterprise/index.md b/chromium/docs/website/site/developers/how-tos/enterprise/index.md new file mode 100644 index 00000000000..c049187d9f5 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/enterprise/index.md @@ -0,0 +1,20 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: enterprise +title: Enterprise +--- + +This is a loose collection of enterprise relevant documents: + +* High-level overview [slide + deck](https://docs.google.com/a/chromium.org/presentation/d/1dPtXXOXiOvvvt9VCTJcFEgSxFG2_FGY6R9zCiACqCc0/present) +* [Adding New Group + Policies](/developers/how-tos/enterprise/adding-new-policies) +* [Running the cloud policy test + server](/developers/how-tos/enterprise/running-the-cloud-policy-test-server) +* [Working with protobuf-encoded policy + blobs](/developers/how-tos/enterprise/protobuf-encoded-policy-blobs)
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/enterprise/protobuf-encoded-policy-blobs/decode_policy_blob.sh b/chromium/docs/website/site/developers/how-tos/enterprise/protobuf-encoded-policy-blobs/decode_policy_blob.sh new file mode 100644 index 00000000000..b51c34105cf --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/enterprise/protobuf-encoded-policy-blobs/decode_policy_blob.sh @@ -0,0 +1,33 @@ +#!/bin/bash +# +# Copyright 2012 Google Inc. All Rights Reserved. +# Author: mnissler@google.com (Mattias Nissler) + +PROTO_DIR=/build/x86-generic/usr/include/proto + +# Decode PolicyFetchResponse. +echo 'Decoding PolicyFetchResponse.' 1>&2 +protoc --decode=enterprise_management.PolicyFetchResponse \ + -I "$PROTO_DIR" \ + "$PROTO_DIR/device_management_backend.proto" \ +> "policy_response.txt" + +# Decode PolicyData. +echo 'Decoding PolicyData.' 1>&2 +cat "policy_response.txt" | \ +awk -v ORS= '/^policy_data: ".*"$/ { print substr($0, 15, length($0) - 15); }' | \ +python -c "import sys; sys.stdout.write(sys.stdin.read().decode('string_escape'))" | \ +protoc --decode=enterprise_management.PolicyData \ + -I "$PROTO_DIR" \ + "$PROTO_DIR/device_management_backend.proto" \ +> "policy_data.txt" + +# Decode ChromeDeviceSettingsProto. +echo 'Decoding ChromeDeviceSettingsProto.' 1>&2 +cat "policy_data.txt" | \ +awk -v ORS= '/^policy_value: ".*"$/ { print substr($0, 16, length($0) - 16); }' | \ +python -c "import sys; sys.stdout.write(sys.stdin.read().decode('string_escape'))" | \ +protoc --decode=enterprise_management.ChromeDeviceSettingsProto \ + -I "$PROTO_DIR" \ + "$PROTO_DIR/chrome_device_policy.proto" \ +> "chrome_device_policy.txt" diff --git a/chromium/docs/website/site/developers/how-tos/enterprise/protobuf-encoded-policy-blobs/encode_policy_blob.sh b/chromium/docs/website/site/developers/how-tos/enterprise/protobuf-encoded-policy-blobs/encode_policy_blob.sh new file mode 100644 index 00000000000..43edc2370a1 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/enterprise/protobuf-encoded-policy-blobs/encode_policy_blob.sh @@ -0,0 +1,80 @@ +#!/bin/bash +# +# Copyright 2012 Google Inc. All Rights Reserved. +# Author: mnissler@google.com (Mattias Nissler) + +PROTO_DIR=/build/x86-generic/usr/include/proto +OWNER_KEY="-----BEGIN RSA PRIVATE KEY----- +MIIEowIBAAKCAQEAwpLFa4ecSAAf+SC+IZQd0v/WMdMn0gfFHHd2fxdsyOT4QhPb +rdaXpNCCx+41lYZXzPXh3y15iU4lSoUYaGVpbSBTw+BBL/FyZbmL8h3VClnNO033 +2B718z2fVbiOGxeCHfN3xotZumoZ74ko7sWnucPT8dvNaTU+c3lZpVNwjIpadKA/ +FWOJuYhdO8ujcXar7H66L+dr0m7Hg82uhTzxK6nT5yurjhQsGpK11pIjXGV6uJdq +VSEzja+Rrt5vpBB60QGIOSBkRbOyzNWomh8oUOcqPUq5GDOoPo/3tZzr/2PHj6XN +R4UjOBX+qnzr2SS7Iz5QawT4oU9HN5elj+hSKwIDAQABAoIBAQCgLbPYkgtWOsQX +k5zyh70FtxfebLabcUoT5UTn26DywYye2TpAIik0xXLkpHX4YmBlmwYXdJhZMLwC +XQ964gGolLRgzHzduycyF03eRDDeFI+gAs/GW7aeSFyjdQuHwhKcFZLFIHL9w9sW +FxRbfNxXUZ9pvEmeEvcWmQ/zyn0dNFYz7OY5EaXAysqCWvLVkmOuIiH5bhHAObfh +xtHxoghrb8nDZgdoY6EhPYoJq/8QaoQpj5p0ZdbYE0MtJWVLPzDOL3wRy2ZAVpcn +Vhp/ybdB362OaM7ZA0xIhI6JOvZ6rFxww42QYyKcfXs7JuHQPjoDS9RieByu5mCY +C5o3V4wBAoGBAP4S1DxX56k9FImtGV9/LjDSVakguqAbih4ZLducmwdg8L0K9KbA +wMsJ+3UXVpoOEMRCvzdz7gqAUI4SVyDtZNpaxnW3/KEXRE7B4oDSM5j1/R/bPHUn +b3TPILYYfSEWNXXmbVZrime9FjkrAbX+nlAhr80INY0CfjxgcP4PNguTAoGBAMQM +cui/WDNNdK8NwmlfR0xVWZQd+qLNT5f591dZDNX9K6B8oipjvtX1HUXgE7aSKEc4 +Gq9eUEKSLpmgSKmWAPqXLaltD8HpNjAfsFZxgQMATz5ll/7/Qb8SIDDYmZGQpUA2 +lRgEcOytj5obaNovZxcvFKBRvrjffD4rXRPmzK4JAoGAT8zKLEnP0TAGC1f66Cuh +7mOh1AUbmL4Nm3Z9GMUPTDn+YuHWBan049C20ggKg0h3q6zrMhePZGz44CaShx0I +2Cw6uS6YgmA0bCgpZByhaCGa5y6Mxp8kOqPzuj3mz0WSdP1yyfns9rhFCp+fYfIe +9zwdY2B4sVlfHMeNtb5BU1ECgYBT4eO0tFI/uS9oyyFYxpySC57FYkJgMCqTIy/y +XrbARI/LHiigrIb1sufwgtzMbCLxvg6k5FzA7x0jPFJ6xSTsE41FBdYNKQS3eIeR +pQUHTLWbRArR31O5Nj8xxyuF/fbGz9PhL91FV0mvLXUijc+1Or6/jdpl7bGSRCmS +H1mKSQKBgB9CP0v6kx1uZQX71qFkE8rmEgQoQ6aBqFTo6PhQTs73y+prJB9M7Rec +UOUPyRo2WvehDMW/xEUXBxAou+Kqx2Wjc1X8ksE4TTvWic0fnC43VTzq9BOw+X8o +jolEsTrkv6jPkizq4mYSxugWg8UTx0FzPfJqlt80FZ3JNgKI5vDA +-----END RSA PRIVATE KEY-----" + +function quote_and_label() { + echo -n "$1: \"" + hexdump -v -e '1/1 "q%03o"' | tr q '\\' + echo "\"" +} + +# Encode ChromeDeviceSettingsProto. +echo 'Encoding ChromeDeviceSettingsProto.' 1>&2 +sed -i -e '/^policy_value: ".*"$/ d' policy_data.txt +cat "chrome_device_policy.txt" | \ +protoc --encode=enterprise_management.ChromeDeviceSettingsProto \ + -I "$PROTO_DIR" \ + "$PROTO_DIR/chrome_device_policy.proto" | \ +quote_and_label 'policy_value' \ +>> policy_data.txt + +# Encode PolicyData. +echo 'Encoding PolicyData.' 1>&2 +cat "policy_data.txt" | \ +protoc --encode=enterprise_management.PolicyData \ + -I "$PROTO_DIR" \ + "$PROTO_DIR/device_management_backend.proto" | \ +quote_and_label 'policy_data' \ +> "policy_response.txt" + +# Sign PolicyData and recreate PolicyFetchResponse. +echo 'Generating signature.' 1>&2 +cat "policy_data.txt" | \ +protoc --encode=enterprise_management.PolicyData \ + -I "$PROTO_DIR" \ + "$PROTO_DIR/device_management_backend.proto" | \ +openssl dgst -sha1 -sign <(echo "$OWNER_KEY") | \ +quote_and_label 'policy_data_signature' \ +>> "policy_response.txt" + +echo -n "$OWNER_KEY" | \ +openssl rsa -pubout -outform DER | \ +quote_and_label 'new_public_key' \ +>> "policy_response.txt" + +# Encode PolicyFetchResponse. +echo 'Encoding PolicyFetchResponse.' 1>&2 +cat "policy_response.txt" | \ +protoc --encode=enterprise_management.PolicyFetchResponse \ + -I "$PROTO_DIR" \ + "$PROTO_DIR/device_management_backend.proto" diff --git a/chromium/docs/website/site/developers/how-tos/enterprise/protobuf-encoded-policy-blobs/index.md b/chromium/docs/website/site/developers/how-tos/enterprise/protobuf-encoded-policy-blobs/index.md new file mode 100644 index 00000000000..454a935450e --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/enterprise/protobuf-encoded-policy-blobs/index.md @@ -0,0 +1,81 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +- - /developers/how-tos/enterprise + - Enterprise +page_name: protobuf-encoded-policy-blobs +title: Protobuf-encoded policy blobs +--- + +Cloud policy blobs encode policy settings in a protobuf format, protected with a +signature. The signature facilitates authenticity checks, the key pair is +typically created and owned by the entity managing the device or user. Policy +blobs are also used as the canonical format for device settings on Chromium OS. +They are stored on disk by session_manager, which also takes care of +authenticating incoming protobufs. + +## Structure + +The term "policy blob" usually refers to a binary-encoded PolicyFetchResponse +protobuf message as defined here: +<https://chromium.googlesource.com/chromium/src/components/policy/proto/+/HEAD/device_management_backend.proto> + +This protobuf message is a nested structure and contains binary-encoded payload +protobufs. The layers are as follows: + +1. PolicyFetchResponse is the outer protobuf. It wraps the actual + payload - a PolicyData protobuf message - in binary form and + includes a signature that's computed on the payload binary. It also + contains fields for shipping a new key in case of key rotation. + Rotation requires the signature on the new key to verify against the + old key. +2. PolicyData hosts a fair amount of meta data about the policy, such + as policy type, timestamps, intended receiver etc. These are used + for further validity checks. The actual policy values are nested in + the binary policy_value field. The field contains a binary-encoded + protobuf, it's message type depends on the policy type. +3. The CloudPolicySettings message type is used for user-level policy, + which is indicated by type google/chromeos/user. The protobuf + definition is generated at compile time from + chrome/app/policy/policy_templates.json: + <https://chromium.googlesource.com/chromium/src/+/HEAD/components/policy/resources/policy_templates.json> +4. Chromium OS device policy is handled by ChromeDeviceSettingsProto + defined in + <https://chromium.googlesource.com/chromium/src/chrome/browser/chromeos/policy/proto/+/HEAD/chrome_device_policy.proto> + and is applicable if the policy type is google/chromeos/device. + +## Manipulating binary blobs + +Binary policy blobs are stored on Chromium OS in these locations: + +* /var/lib/whitelist/policy - device policy blob +* /home/root/<user-hash>/session_manager/policy/policy - user + policy blob + +To manipulate these files, the protoc compiler (part of the protobuf +distribution) comes in handy, as it is capable of decoding and encoding binary +protobuf messages to and from human-readable text format. We have some tools +that can help with this: + +* A pair of scripts, decode_policy_blob.sh and encode_policy_blob.sh, + which breaks up the policy blob and decode the individual layers. + Copies of the scripts are attached, you might have to adjust the + PROTO_DIR variable depending on the environment you use the scripts + in. It needs to point at a directory containing the proto definition + files, which are typically installed in /usr/include/proto a + Chromium OS build chroot. When run, the scripts operate on text + files in the current directory containing the textual protobuf + representations for the individual layers: + * policy_response.txt for PolicyFetchResponse + * policy_data.txt for PolicyData + * chrome_device_policy.txt for ChromeDeviceSettingsProto (note + that user policy is currently not supported, but that should be + straightforward to add) + Note that re-encoding the policy uses a key for the signature that is + hard-coded in the encoding script, so you might have to swap in the + appropriate owner key. +* A tool called policy_reader, which is installed on production images + and dumps the current device policy blob in textual representation. diff --git a/chromium/docs/website/site/developers/how-tos/enterprise/running-the-cloud-policy-test-server/index.md b/chromium/docs/website/site/developers/how-tos/enterprise/running-the-cloud-policy-test-server/index.md new file mode 100644 index 00000000000..946f6d1b1b8 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/enterprise/running-the-cloud-policy-test-server/index.md @@ -0,0 +1,288 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +- - /developers/how-tos/enterprise + - Enterprise +page_name: running-the-cloud-policy-test-server +title: Running the cloud policy test server +--- + +Chromium can pull down enterprise policy configuration from a cloud service. We +have a simplistic python implementation of the management service, so we are +able to test features without relying on a full cloud policy server +implementation. This page explains how to run it: + +## Running the test server + +1. You need a Linux Chromium checkout that's in good shape for building + the browser. See [Get the Code](/developers/how-tos/get-the-code) +2. Make sure you have the protocol buffer source compiled (add the + `device_policy_proto` to the line below if you're building for + Chrome OS): + + ```none + ninja -C out/Debug py_proto components/policy/core/common full_runtime_code_generate + ``` + +3. Start the test server. You can start testserver.py directly from the + src/ directory of your Chrome source tree: + + ```none + OUT_DIR=out/Debug \ + PYTHONPATH=third_party/tlslite:third_party/pywebsocket3/src:$OUT_DIR/pyproto:net/tools/testserver:third_party/protobuf/python:$OUT_DIR/pyproto/components/policy/proto:$OUT_DIR/pyproto/third_party/shell-encryption/src:$OUT_DIR/pyproto/third_party/private_membership/src \ + python components/policy/test_support/policy_testserver.py --data-dir ~/tmp/ --host 127.0.0.1 --port 8889 + ``` + + Note: replace out/Debug with out/Release if appropriate, depending on your + build configuration. + If this fails with a Python error, try running inside an isolated Python + environment via [virtualenv](https://virtualenv.pypa.io/en/stable/). + If you want logging, add these flags: + + ```none + --log-level DEBUG --log-to-console + ``` + + Notes on parameters: + * `--data-dir` specifies the directory from which the server will + read the policy file (see below). Up to you where to place it. + * `--port` specifies the port the server should listen on, you can + pick a port of your liking. + * `--host` The IP address the server should bind to. Note that if + you want to test a Chromium OS image running on a Chromebook or + in a Virtual Machine against the server, you need to specify the + host name or IP address of the public interface in your machine. + Note that the server only accepts connections from that IP. To + work around these restrictions you can use a port forwarding + (ssh is your friend) or local proxy server. + * --client-state specifies a file in which to persist current + server state. This is useful if you want the server to remember + registered clients and such across server restarts, for example + when your tinkering with the python code in policy_testserver.py + to create specific error conditions etc. + * --config-file specifies a file that contains server + configuration. If not specified, the server will default to the + device_management file in the data directory. + * --policy-key a PEM-encoded file containing a private RSA key + used to sign policy blobs. More information on the policy blob + format and signatures is + [here](/developers/how-tos/enterprise/protobuf-encoded-policy-blobs). + Note that for signing keys to be accepted by Chrome, a + verification signature is required that certifies the signing + key. These signatures are checked against a Google-owned key + pair, the public half of which is [baked into the chrome + binary](https://code.google.com/p/chromium/codesearch#chromium/src/components/policy/core/common/cloud/cloud_policy_constants.cc&l=65). + The policy test server contains [hardcoded verification + signatures](https://code.google.com/p/chromium/codesearch#chromium/src/chrome/browser/policy/test/policy_testserver.py&l=115) + for a couple test domains. If you specify a policy key on the + command line, the server will try to load a verification + signature from the file that's named like the policy key file, + but with ".sig" appended. Multiple policy keys may be specified + in the command line in order to test key rotation. +4. Check whether the server answers requests. Point your browser to + <http://localhost:8889/test/ping> (or the public IP you've passed to + the `--host` switch). The server should respond with a page saying + "Policy server is up." +5. Ready to roll! + +## Setting up a configuration file + +The configuration file is a JSON file containing server-global parameters. +Here's an example: + +```none +{ + "managed_users": [ "*" ], + "policy_user": "madmax@managedchrome.com", + "current_key_index": 0, + "service_account_identity": "", + "robot_api_auth_code": "", + "invalidation_source": 0, + "invalidation_name": "", + "device_state": { + "management_domain": "managedchrome.com", + "restore_mode": 2 + } +} +``` + +Notes on parameters: + +* `managed_users` specifies the list of clients the server is allowing + to register. Each entry is an oauth token, or the "\*" wildcard + which matches any client. + (Note that going by OAuth token actually isn't very useful, we should either + remove this parameter or give the server the ability to figure out the + actual user) +* `policy_user` is the user ID to put in policy responses to identify + the target of the policy settings. This needs to match the user on + the Chrome side or Chrome will reject the policy. +* `current_key_index` is the index of the signing key to use when + generating policy blob signatures. +* `service_account_identity` is the email address of the service + account. This is the account used on Chrome OS to enable Google + cloud services that require authentication. Note that the test + server can't create service accounts, so this parameter is likely + only useful for testing (i.e. you have a way to create a service + account separately and want to inject the proper service account + name). +* `robot_api_auth_code` specifies the authentication code the server + should return when a Chrome OS client asks for one during enterprise + enrollment. Since the server doesn't have the ability to create + robot accounts, it can't satisfy these request. Leave this parameter + empty unless you are testing robot auth setup and have a way to + create robot accounts and obtain auth codes separately. +* `invalidation_source` and invalidation_name are used in policy + change push notifications. Change notifications are not supported by + the test server. This parameter merely exists to facilitate testing + using a source identifier obtained elsewhere. +* `device_state` provides device state parameters requested by Chrome + OS clients that have gone through a hardware reset and are + performing a handshake with the server to discover their previous + state. This is part of the forced re-enrollment and device disabling + features. You should generally only need these parameters if you're + specifically testing the aforementioned features. + +## Setting up a policy file + +The test server reads policy to supply to clients from the data directory +specified with the `--data-dir`. The directory contains text files containing +protobuf messages that supply the payload to return to the client when it asks +for policy. The files are named according to the type of policy requested and +the entity the policy is intended for. + +### User policy + +The file names are: + +* policy_google_android_user.txt +* policy_google_chromeos_publicaccount_$PUBLICACCOUNTID.txt +* policy_google_chromeos_user.txt +* policy_google_chrome_user.txt +* policy_google_ios_user.txt + +The payload protocol buffer message is CloudPolicySettings. This is generated +from +[policy_templates.json](https://code.google.com/p/chromium/codesearch#search/&q=policy_templates.json&sq=package:chromium&type=cs) +and there is a message field with the name matching the policy name for each +supported policy. The value field within the nested message contains the policy +value. Here is an example with a few policy settings defined: + +```none +HomepageLocation { + value: "http://www.chromium.org" +} +ShowHomeButton { + value: true +} +``` + +### Device policy + +The file name is policy_google_chromeos_device.txt and the payload protocol +buffer is ChromeDeviceSettingsProto. Example contents: + +```none +device_policy_refresh_rate { + device_policy_refresh_rate: 60 +} +user_allowlist { + user_allowlist: "*@managedchrome.com" + user_allowlist: "*@gmail.com" +} +device_local_accounts { + account { + account_id: "publicsession@managedchrome.com" + type: ACCOUNT_TYPE_PUBLIC_SESSION + } +} +``` + +## Configuring Chromium OS to talk to the test server + +In order to do something useful with the test server, you can configure Chromium +built for Chromium OS to talk to the test server for device- and user-level +policy. Here is what you need to do: + +1. Get a root shell on the VM or Chromebook that you want to talk to + the test server. +2. Make sure you have a writable root file system. Try `mount -o + remount,rw /` if you don't, if that fails, you're likely on an + actual device with enabled root file system protection, in that case + check out `/usr/share/vboot/bin/make_dev_ssd.sh + --remove_rootfs_verification` +3. Edit `/etc/chrome_dev.conf`. Add the following flags: + + ```none + --device-management-url=http://<your-ip>:<yourport> + --enterprise-enrollment-skip-robot-auth + ``` + + This points the device at your test server and instructs it to skip robot + auth setup, which avoids an error during enrollment due to the test server + not being able to create robot accounts. +4. On a shell, say + + ```none + restart ui + ``` + +5. You're now set up to fetch policy from the test server! + +## Configuring Chromium to talk to the test server + +Pass the following command line flag to chrome: + +```none +--device-management-url=http://<your-ip>:<yourport> +``` + +## User policy + +To test some user policy setting, configure the policy file as desired and then +just log in. The browser should automatically pull policy. You can verify that +the policy is correctly pulled down from the server by inspecting +[chrome://policy](javascript:void(0);). To test policy changes, you can also +just update the policy in the file, and use the "Reload policies" button on +[chrome://policy](javascript:void(0);) to refresh policy at runtime. + +## Device policy + +For devices to receive device policy, they need to be enrolled for enterprise +management at device setup time. There are some requirements for that to +succeed: + +* The device's TPM needs to be clear. In particular, running + `cryptohome --action=tpm_status` should indicate that the TPM is not + yet owned. If you have an owned TPM, do the following: + + ```none + crossystem clear_tpm_owner_request=1 + echo "fast keepimg" > /mnt/stateful_partition/factory_install_reset + reboot + ``` + + The system will reboot, do a powerwash and reboot again. The device should + have a clear TPM and be in enrollable state afterwards. +* The device may not have a consumer owner already, i.e. you shouldn't + have logged in previously. Ownership is mainly indicated through + files in `/var/lib/whitelist`, which you can clear like this + + ```none + stop ui + rm -rf /var/lib/whitelist/* + start ui + ``` + + This works well in a VM, note that you probably need a TPM reset an actual + hardware (see above). + +To perform the actual enrollment, hit `Ctrl+Alt+E` on the sign in screen. +Provide credentials (note that in case of the test server, you must match the +"policy_user" field in your JSON config file) and speak a short prayer. If you +get lucky, the device will enroll. Log in and check +[chrome://policy](javascript:void(0);) for whether it says device policy is +present.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/file-web-bluetooth-bugs/index.md b/chromium/docs/website/site/developers/how-tos/file-web-bluetooth-bugs/index.md new file mode 100644 index 00000000000..7346f113c57 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/file-web-bluetooth-bugs/index.md @@ -0,0 +1,223 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: file-web-bluetooth-bugs +title: How to file Web Bluetooth bugs +--- + +[TOC] + +When [filing a Web Bluetooth +bug](https://bugs.chromium.org/p/chromium/issues/entry?components=Blink%3EBluetooth&source=chromium.org), +please attach some Bluetooth logs (both Chrome and platform logs) so we can +debug the issue. + +## General Bluetooth Inspection Tools + +These general tools will help you explore bluetooth devices that you are +attempting to communicate with: + +1. chrome://bluetooth-internals + * Displays Bluetooth information Chrome is able to access, + allowing you to experiment without going through the device + chooser dialog, blocklist, or other web platform security + aspects of Web Bluetooth. +2. [nRF Connect for + Android](https://play.google.com/store/apps/details?id=no.nordicsemi.android.mcp&hl=en) + or [nRF Connect for + iOS](https://itunes.apple.com/us/app/nrf-connect/id1054362403?mt=8) + * Generic tool that allows you to scan, advertise and explore your + Bluetooth low energy (BLE) devices and communicate with them. + +## Bluetooth Devices to Test With + +These devices are some that can be used to act as peripheral devices. + +1. [BLE Peripheral + Simulator](https://play.google.com/store/apps/details?id=io.github.webbluetoothcg.bletestperipheral) + Android app + * Simulates a devices with Battery, Heart Rate, Health Thermometer + services. Developers can connect to the app to Read and Write + Characteristics, Subscribe to Notifications for when the + Characteristics change, and Read and Write Descriptors. + * Code at: + https://github.com/WebBluetoothCG/ble-test-peripheral-android +2. [nRF + Connect](https://www.nordicsemi.com/Software-and-tools/Development-Tools/nRF-Connect-for-mobile/GetStarted) + Can also simulate a GATT server. +3. [Espruino](https://www.espruino.com/) devices ([Puck + JS](https://www.puck-js.com/) etc) + * Programable in JavaScript with a + [WebIDE](https://www.espruino.com/ide/). + +## chrome://device-log + +**chrome://device-log** displays a filtered view of logs on multiple platforms. + +* Change the **Log level** to **Debug** +* **Filter** to only **Bluetooth**. + +However, more detailed platform logs may be necessary to diagnose issues, see +below: + +## Mac + +#### Chrome logs + +1. Quit any running instance of Chrome. +2. Launch /Applications/Utilities/Terminal.app +3. At the command prompt enter: + /Applications/Google\\ Chrome.app/Contents/MacOS/Google\\ Chrome + --enable-logging=stderr --vmodule=\*bluetooth\*=2 + +#### Platform logs + +1. Install Apple's [Additional Tools for + XCode](https://developer.apple.com/download/more/?name=Additional%20Tools%20for%20XCode) + if you have XCode 8+, otherwise install Apple's [Hardware IO Tools + for + Xcode](https://developer.apple.com/downloads/?name=Hardware%20IO%20Tools). +2. Use **Bluetooth Explorer** in that package to try to discover and + connect to your device. + * Devices | Low Energy Devices will let you scan for and connect + to BLE devices. If you can't find or use your device with + Bluetooth Explorer, there's likely a bug in MacOS rather than + Chrome. Please file a bug in [Apple's bug + tracker](https://bugreport.apple.com/). + * "Tools" and select "Device Cache Explorer", from there you can + click "Delete All" button to clear **device cache** if needed to + help reproduce errors. +3. Use **PacketLogger** to capture a log of Bluetooth packets while + you're reproducing your bug. Remember to clear the packet log before + you start so you send us mostly relevant packets. + +## Linux + +#### Chrome logs + +1. Quit any running instance of chrome. +2. Execute in a console: + google-chrome --enable-logging=stderr --vmodule=\*bluetooth\*=9 + --enable-experimental-web-platform-features + +#### Platform logs + +1. Get BlueZ version with dpkg -l bluez +2. Get Linux kernel version with uname -r +3. Start monitoring bluetooth via sudo btmon or record traces in + btsnoop format via sudo btmon -w ~/Downloads/btmon.btsnoop + +## Chrome OS + +#### Chrome logs + +1. Put the device into [Developer + Mode](/chromium-os/chromiumos-design-docs/developer-mode) so you can + get a Root Shell +2. Open Chrome OS Shell with \[Ctrl\] + \[Alt\] + T +3. Enter shell and run these shell commands: + sudo su + cp /etc/chrome_dev.conf /usr/local/ + mount --bind /usr/local/chrome_dev.conf /etc/chrome_dev.conf + echo "--vmodule=\*bluetooth\*=9" >> /etc/chrome_dev.conf +4. Restart the UI via: + `restart ui` +5. Check out messages logged by Chrome at + file:///home/chronos/user/log/chrome + +#### Platform logs + +Check out System Logs: + +1. Go to file:///var/log/messages +2. Look for "bluetooth" + +Enter a Bluetooth debugging console: + +1. Open Chrome OS Shell with \[Ctrl\] + \[Alt\] + T +2. Enter bt_console and type help to get to know commands + +Monitor Bluetooth traffic: + +1. Put the device into [Developer + Mode](/chromium-os/chromiumos-design-docs/developer-mode) so you can + get a Root Shell +2. Open Chrome OS Shell with \[Ctrl\] + \[Alt\] + T +3. Enter shell +4. Start monitoring bluetooth via sudo btmon or record traces in + btsnoop format via sudo btmon -w ~/Downloads/btmon.btsnoop + +Monitor BlueZ messages going through a D-Bus message bus: + +1. Put the device into [Developer + Mode](/chromium-os/chromiumos-design-docs/developer-mode) so you can + get a Root Shell +2. Open Chrome OS Shell with \[Ctrl\] + \[Alt\] + T +3. Enter shell +4. Start monitoring with dbus-monitor --system + "interface=org.freedesktop.DBus.Properties" + "interface=org.freedesktop.DBus.ObjectManager" + +Getting the BlueZ package version: + +1. Put the device into [Developer + Mode](/chromium-os/chromiumos-design-docs/developer-mode) so you can + get a Root Shell +2. Open Chrome OS Shell with \[Ctrl\] + \[Alt\] + T +3. Enter shell +4. Get the version with more + /etc/portage/make.profile/package.provided/chromeos-base.packages | + grep bluez + +And if you're enthusiastic, you can also build [BlueZ](http://www.bluez.org/) +from source on your Chromebook in [Developer +Mode](/chromium-os/poking-around-your-chrome-os-device), with +[crouton](https://github.com/dnschneid/crouton) and run it by following these +[instructions](https://github.com/beaufortfrancois/sandbox/blob/gh-pages/web-bluetooth/Bluez.md). + +## Android + +#### ADB logs + +* If you have Android SDK installed + * Use adb logcat, perhaps filtering it through grep to highlight + interesting bits for you: + * adb logcat -v time | grep -E " + |\[Bb\]luetooth|cr.Bluetooth|BtGatt|BluetoothGatt|bt_btif_config" +* If you do not have Android SDK installed + * [Enable USB + Debugging](http://developer.android.com/tools/device.html) via + Developer options + * Settings > About phone and tap Build number seven times. + Return to the previous screen to find Developer options. + * Enable USB Debugging + * Take a bug report + * Settings > Debeloper options > Take a bug report + * Send the bug report to **yourself**, it contains more + information than we need. + * Extract the bug report .zip file + * Search within the bug report text file to find the logcat + output. + * Copy the relevant section that includes Bluetooth information to + a new file, and send that. + +## Windows + +**Packet capture** + +1. Install the [Windows Driver + Kit](https://docs.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk) + for Windows 10. +2. Open an administrator command prompt. +3. Run the command: logman create trace "bth_hci" -ow -o + C:\\bth_hci.etl -p {8a1f9517-3a8c-4a9e-a018-4f17a200f277} + 0xffffffffffffffff 0xff -nb 16 16 -bs 1024 -mode Circular -f bincirc + -max 4096 -ets +4. Reproduce your issue. +5. Run the command: logman stop "bth_hci" -ets +6. Find BtEtlParse.exe in the WDK and run the command: btetlparse + C:\\bth_hci.etl +7. The resulting file can be opened using Wireshark.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/get-the-code-v2/index.md b/chromium/docs/website/site/developers/how-tos/get-the-code-v2/index.md new file mode 100644 index 00000000000..eb5d811e21b --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/get-the-code-v2/index.md @@ -0,0 +1,313 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: get-the-code-v2 +title: Get the Code (Deprecated) +--- + +[TOC] + +## *This page is obsolete. Please see [Get the Code: Checkout, Build, & Run Chromium](/developers/how-tos/get-the-code) instead.* + +**Post Git Migration Update! Developer workflow and tools documentation has now +largely moved to the man pages provided with depot_tools.** + +Please see [the online version of those +docs](http://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools.html), +and especially the new [tutorial +page](http://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html) +for the most up-to-date information about getting and working with Chromium +sources. + +Not all the information here has been migrated to the depot_tools docs yet, so +this page will stay around for a while as a resource, but where there are +discrepancies, the depot_tools pages should be considered authoritative. + +--- + +# New to Git? + +If you're new to Git but experienced with Subversion, we recommend following the +[Git-SVN Crash Course](http://git-scm.com/course/svn.html). This guide should +help you understand how Git differs from Subversion and how to get up to speed +the fastest. + +# Prerequisites + +* Committers will need a Chromium access account. You can request one + at [Chromium access](https://chromium-access.appspot.com/) using the + [request form](https://chromium-access.appspot.com/request). Only + account holders (read-only or read-write) can send tryjobs. + +* [depot_tools](/developers/how-tos/install-depot-tools) is required + on every platform. Install it and make sure it's correctly in your + PATH. + +## Windows Prerequisites + +Run gclient **TWICE, FROM A CMD WINDOW** to download and setup everything else +you need. It's important to run twice, and not to use msysgit bash or other +non-cmd shells, because otherwise gclient may fail to properly install all its +dependencies. Using the "--version" flags just reduces the amount of output +spew; it's not necessary for the operations to succeed. If you run gclient +--version a third time it should succeed. + +gclient --version gclient --version + +After running gclient (twice), depot_tools will now contain a full stand-alone +installation of msysgit. **If you have a previous installation of msysgit, it is +strongly recommended that you use the version installed under depot_tools**. +This version of msysgit contains custom performance improvements that facilitate +working with very large git repositories (like chromium and blink). You can run +the shell from the provided version of msysgit using: + +/path/to/depot_tools/git-.../bin/sh.exe --login -i + +where git-... will depend on which version of msysgit was fetched (e.g. +git-1.9.0.chromium.5_bin). However you will normally just run git.bat, which +should now be in your path. + +## Mac and Linux Prerequisites + +You'll need to manually install: + +* Git 1.9 or above + +# Initial checkout + +First, tell git about yourself. + +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 + +## Git credentials setup for committers (.netrc file) + +If you plan to push commits directly to Git (bypassing Commit Queue, e.g. with +'git cl land') you would need to setup netrc file with your git password: + +1. Go to <https://chromium.googlesource.com/new-password> +2. Login with your **@chromium.org** account (e.g. your committer + account, non-chromium.org ones work too). +3. Follow the instructions in the "Staying Authenticated" section. It + would ask you to copy-paste two lines into ~/.netrc file. + +In the end, ~/.netrc (or %HOME%/_netrc on Windows) should have two lines that +look like: + +machine chromium.googlesource.com login git-yourusername.chromium.org password +<generated pwd> + +machine chromium-review.googlesource.com login git-yourusername.chromium.org +password <generated pwd> + +Make sure that ~/.netrc file's permissions are 0600 as many programs refuse to +read .netrc files which are readable by anyone other than you. + +On Windows, you must manually create HOME as a per-user environment variable and +set it to the same as %USERPROFILE%. + +You can check that you have everything set up properly by running +tools/check_git_config.py . + +## Actual Checkout + +We will use the fetch tool included in depot_tools to check out Chromium, +including all dependencies. This will create a new folder in your current +working directory named src. + +fetch --nohooks chromium # 'chromium' may alternatively be one of blink, +android, ios, see below. # or alternatively fetch --nohooks --no-history +chromium # get a shallow checkout (saves disk space and fetch time at the cost +of no git history) cd src git checkout master # if you are building for Linux +only: build/install-build-deps.sh # if you are building for Android: +build/install-build-deps-android.sh # if you are building for iOS: echo "{ +'GYP_DEFINES': 'OS=ios', 'GYP_GENERATOR_FLAGS': 'xcode_project_version=3.2', }" +> chromium.gyp_env + +gclient sync + +Alternatives to 'fetch chromium' are: + +fetch chromium # Blink from DEPS (most recent roll) - if you're not working on +Blink itself +fetch blink # Blink at Tip of Tree (latest) - if you are working on Blink +instead of or in addition to Chromium +fetch android # Blink from DEPS with additional Android tools - if you are +building for Android +fetch ios # Using iOS dependencies instead of Mac dependencies - if you are +building for iOS + +fetch chromium and fetch blink both fetch both Chromium and Blink, but the two +commands fetch different versions of Blink: fetching chromium will get a dated +Blink (most recent roll to Chromium), and is sufficient and easier if only +working on Chromium, while fetching blink will instead get the latest Blink +(ToT), and is useful if working on Blink. + +In other words, fetch X if you want to work on X. + +Note that, by default, fetch creates a local branch called "master". This can be +confusing if you mistake it for the upstream "origin/master". Unless you know +what you're doing, you should simply delete this branch as follows: + +git checkout origin/master git branch -D master + +Note that if e.g. you're developing Blink, you'll want to do this in you Blink +directory (likely third_party/WebKit) as well. + +Post initial checkout, you should be able to switch between projects via +`sync-webkit-git.py` but better tooling is being worked on. If you wish to later +add Android to an existing Chromium tree, `sync-webkit-git.py` will not help. It +may be better to make a separate top level directory and have a parallel tree. +While the projects can live happily in the same tree, we don't have tools yet to +help you configure the tree for both. + +## Additional environments + +If you're building Chrome for: + +* Chrome OS, see [these build + instructions](http://www.chromium.org/developers/how-tos/build-instructions-chromeos) +* Android, see [these build + instructions](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/android_build_instructions.md) +* iOS, see [these build instructions](/system/errors/NodeNotFound) + +## Using the last known good/compilable revision (LKGR/LKCR) + +If you'd like to only sync to the last known good revision (lkgr), you can +checkout **origin/lkgr** instead of **origin/master**. Similarly, the lkcr is +available at **origin/lkcr**. + +## Updating the code + +Update your current branch with `git pull` followed by `gclient sync`, as +follows. Note that if you're not on a branch, `git pull` won't work, and you'll +need to use `git fetch` instead (but you make all your changes on branches, +right? See "Contributing" below). + +cd "$CHROMIUM_DIR" +git pull +gclient sync + +If developing Blink, you'll need to pull Blink as well, as follows: + +cd "$CHROMIUM_DIR" && git pull +cd "$BLINK_DIR" && git pull +gclient sync + +To speed up updating, using more jobs, for example --jobs=16: + +cd "$CHROMIUM_DIR" +git pull +gclient sync --jobs=16 + +# Contributing + +Moved to [Committing and Reverting Changes +Manually](/system/errors/NodeNotFound). + +# Commit your change manually + +Moved to [Committing and Reverting Changes +Manually](/system/errors/NodeNotFound). + +# Tips + +See [GitTips](https://code.google.com/p/chromium/wiki/GitTips) for general tips, +and [GitCookbook](https://code.google.com/p/chromium/wiki/GitCookbook) for more +Chromium-specific tips. + +## Googler + +See <http://wiki/Main/ChromeBuildInstructions> + +## Multiple Working Directories + +Moved to [Managing Multiple Working +Directories](/developers/how-tos/get-the-code/multiple-working-directories). + +## Working with release branches + +Moved to [Working with Release +Branches](/developers/how-tos/get-the-code/working-with-release-branches). + +## Branches + +Moved to [Working with +Branches](/developers/how-tos/get-the-code/working-with-branches). + +## If gclient sync fails + +* Make sure you checked out master: run git branch +* Run git status to make sure you don't have any uncommitted changes +* Try running git rebase origin/master directly to get more specific + errors that gclient sync might not show +* Do the same in each subdirectory that belongs to a separate + repository that you might have worked in - for example, if you + hacked on + WebKit[?](https://code.google.com/p/chromium/w/edit/WebKit) code, cd + to + third_party/WebKit[?](https://code.google.com/p/chromium/w/edit/WebKit)/Source + and run git status there to make sure you're on the master branch + and don't have uncommitted changes. + +Sometimes you'll get the message "You have unstaged changes." when you +personally don't, often due to a directory that has been moved or delete. You +can fix this by moving the directory outside of the repo directory (or deleting +it), and then trying gclient sync again. + +It is also possible that you're getting this due to local changes (or other +problems) in the depot_tools directory. You can fix these by going to +depot_tools and resetting: + +git reset --hard HEAD + +## Working with repositories in subdirectories other than the main Chromium repository + +Moved to [Working with Nested +Repos](/developers/how-tos/get-the-code/working-with-nested-repos). + +## Reverting a change + +Moved to [Committing and Reverting Changes +Manually](/system/errors/NodeNotFound). + +## Seeing strange errors using Git on Windows? + +Moved to [Windows Build +Instructions](/developers/how-tos/build-instructions-windows). + +## Using Emacs as EDITOR for "git commit" on Mac OS + +Moved to [Mac build +instructions](https://code.google.com/p/chromium/wiki/MacBuildInstructions). + +## Tweaking similarity + +git-cl defaults to using 50% similarity as a threshold for detecting renames. +This is sometimes inappropriate, e.g., if splitting off a small file from a +large file (in which case you want a smaller threshold, to avoid false +negatives), or when adding a small file (in which case you want a larger +threshold, to avoid false positives from common boilerplate). This is controlled +by the add_git_similarity function in git_cl.py, and you can set threshold to a +given value for a branch (saved in config for that branch), or not look for +copies on a specific upload (but not saved in config for the branch): + +git cl upload --similarity=80 # set threshold to 80% for this branch +git cl upload --no-find-copies # don't look for copies on this upload + +# Managed mode + +Moved to [Gclient Managed +Mode](/developers/how-tos/get-the-code/gclient-managed-mode). + +# Need help? + +If you find yourself needing help with the new workflow, please file a bug with +the infrastructure team at +<https://code.google.com/p/chromium/issues/entry?template=Build%20Infrastructure>
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/get-the-code/gclient-managed-mode/index.md b/chromium/docs/website/site/developers/how-tos/get-the-code/gclient-managed-mode/index.md new file mode 100644 index 00000000000..13333f3e641 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/get-the-code/gclient-managed-mode/index.md @@ -0,0 +1,54 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +- - /developers/how-tos/get-the-code + - 'Get the Code: Checkout, Build, & Run Chromium' +page_name: gclient-managed-mode +title: Gclient Managed Mode +--- + +Managed mode is a **deprecated** feature of gclient. It was conceived to give an +easier workflow for newcomers to git, but turned out to be full of surprising +behaviors. It has thus been deprecated, unmanaged mode is the default, and +existing users of managed mode are encouraged to change to unmanaged mode. + +To check which mode you are using, check .gclient (the gclient config file) and +see the value of the "managed" flag. To switch to unmanaged mode from managed +mode: + +* edit your .gclient and set: + "managed": False, +* update your repository by using git pull (as described above), + followed by gclient sync, rather than just gclient sync. + +To make the Blink repo also unmanaged, first fetch blink and then: + +* edit your .gclient and set: + "managed": False, + "custom_deps": { + "src/third_party/WebKit": None, + }, +* update your repository by using git pull in Chromium, then git pull + in Blink (as described above), followed by gclient sync, rather than + just gclient sync. + +## Reference + +* “[PSA: fetch chromium now uses git unmanaged + mode](https://groups.google.com/a/chromium.org/forum/#!topic/chromium-dev/n9N5N3JL2_U)” + +The main difference between managed mode and unmanaged mode is that in managed +mode, local branches track local master branch instead of origin/master, and +gclient “manages” the branches so that they stay in sync. However in practice +this leads to two master branches (local master and origin/master) that go out +of sync and prevent further uploads/commits. With unmanaged mode you always have +only one master: origin/master. The local master still exists but is not treated +in any special way by the tools. + +## What's missing + +* Safesync is not supported for new managed git checkouts yet + (<http://crbug.com/109191>).
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/get-the-code/index.md b/chromium/docs/website/site/developers/how-tos/get-the-code/index.md new file mode 100644 index 00000000000..e474958e499 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/get-the-code/index.md @@ -0,0 +1,38 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: get-the-code +title: 'Get the Code: Checkout, Build, & Run Chromium' +--- + +## *If you work at Google, you probably want to read the [Google-specific instructions](https://goto.corp.google.com/building-chrome) instead, which are basically the same except for some details relating to the Google corporate computer images.* + +## Chromium supports building on Windows, Mac and Linux host systems. Linux is required for building Android, and a Mac is required for building iOS. + +Click on one of these links depending on what you want to build. + +* [Linux](https://chromium.googlesource.com/chromium/src/+/main/docs/linux/build_instructions.md) +* [Windows](https://chromium.googlesource.com/chromium/src/+/main/docs/windows_build_instructions.md) +* [Mac](https://chromium.googlesource.com/chromium/src/+/main/docs/mac_build_instructions.md) +* Chrome OS + * [linux-chromeos](https://chromium.googlesource.com/chromium/src/+/main/docs/chromeos_build_instructions.md) + (runs the Chrome OS version of Chrome on Linux) + * [cros-vm](https://chromium.googlesource.com/chromiumos/docs/+/HEAD/cros_vm.md) + (runs in a Chrome OS virtual machine) + * ["simplechrome"](https://chromium.googlesource.com/chromiumos/docs/+/HEAD/simple_chrome_workflow.md) + (runs on Chromebook hardware) +* [iOS](https://chromium.googlesource.com/chromium/src/+/main/docs/ios/build_instructions.md) +* Cast (these instructions are still old) + * [Android](https://chromium.googlesource.com/chromium/src/+/main/docs/android_cast_build_instructions.md) + * [Linux](https://chromium.googlesource.com/chromium/src/+/main/docs/linux/cast_build_instructions.md) +* [Android](https://chromium.googlesource.com/chromium/src/+/main/docs/android_build_instructions.md) + +### *The Chromium documentation is gradually moving into the source repository. The links above will take you there.* + +## If you need help, try the [chromium-dev Google Group](https://groups.google.com/a/chromium.org/forum/#!forum/chromium-dev), or the #chromium IRC channel on irc.freenode.net (see the [IRC page](/developers/irc) for more on how Chromium uses IRC). **These are not support channels for Chrome itself but forums for developers.** + +You can also, for a limited time, read [the old instructions for getting the +code](/developers/how-tos/old-get-the-code).
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/get-the-code/multiple-working-directories/index.md b/chromium/docs/website/site/developers/how-tos/get-the-code/multiple-working-directories/index.md new file mode 100644 index 00000000000..63f131a440f --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/get-the-code/multiple-working-directories/index.md @@ -0,0 +1,61 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +- - /developers/how-tos/get-the-code + - 'Get the Code: Checkout, Build, & Run Chromium' +page_name: multiple-working-directories +title: Managing Multiple Working Directories +--- + +**git worktree** + +If you only want to do some quick git operations, like merging/rebasing other +branches, but don't want to make your working directory dirty and cause +unnecessarily rebuild, git worktree is a good solution. It only handles one +single git repo though, and doesn't come with Chromium environment setup like +gclient and install-build-deps. + +If you need to have multiple working directories that you can actually build, +use gclient-new-workdir instead. Using git worktree and set up environment there +would be slower and use more disk space. + +**gclient-new-workdir** + +If you are a multitasker or want to build chromium for different targets without +clobbering each other, then perhaps you'll like the +[gclient-new-workdir.py](https://chromium.googlesource.com/chromium/tools/depot_tools.git/+/HEAD/gclient-new-workdir.py) +script located in +[depot_tools.](http://www.chromium.org/developers/how-tos/depottools) The script +works by creating a new working directory with symlinks pointing to the git +database(s) found in your original chromium checkout. You can have as many +working directories as you want without the overhead and hassle of cloning +chromium multiple times. + +```none +gclient-new-workdir.py /path/to/original/chromium chromium2 +``` + +If your file system supports copy-on-write, like btrfs, gclient-new-workdir is +smart enough to use reflink to save copying time and disk space. Better yet, if +the source repo is a btrfs subvolume, btrfs snapshot would be created, with all +the artifacts retained. You can skip environment setup, and rebuilding should be +incremental. This is the most space-efficient way to create a separate working +directory. See <https://crbug.com/721585> for details. + +### Windows devs + +gclient-new-workdir.py doesn't support Windows, but you can try[ +https://github.com/joero74/git-new-workdir](https://github.com/joero74/git-new-workdir) +to do the same thing **(needs to be run as admin)**. For the curious, the script +essentially uses mklink /D and other minor tricks to setup the mirrored .git +repo. + +### Chromium OS devs + +gclient-new-workdir.py uses symlinks that will not work inside the cros_sdk +chroot. If using a [local Chromium source for Chromium +OS](/chromium-os/developer-guide#TOC-Making-changes-to-non-cros_workon-able-packages), +be sure to use the original working directory.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/get-the-code/working-with-branches/index.md b/chromium/docs/website/site/developers/how-tos/get-the-code/working-with-branches/index.md new file mode 100644 index 00000000000..52f14a41843 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/get-the-code/working-with-branches/index.md @@ -0,0 +1,220 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +- - /developers/how-tos/get-the-code + - 'Get the Code: Checkout, Build, & Run Chromium' +page_name: working-with-branches +title: Working with Branches +--- + +*This applies to commits to Chromium repository branches. For changes to +Chromium OS repositories, see the information +[here](/chromium-os/how-tos-and-troubleshooting/working-on-a-branch).* + +### Basics + +Enumerate your local branches: + +cd src +git branch + +Switching from one branch to another: Example: Switching from branch 'branch1' +to branch 'branch2'. + +cd src +git checkout branch2 + +Note that `-` can be used to refer to the previous branch, which is useful when +switching between two branches. + +```none +git checkout some_branch +git checkout - # back to previous branch! +``` + +### Suggested branching workflow + +We normally do our feature work in branches to keep changes isolated from each +other. The recommended workflow is to make local branches off the server master, +referred to as the origin/master branch. The `git-new-branch` command (in +depot_tools) will do this: + + git new-branch branch_name + +Note that this is equivalent to the following: + + git checkout -b new_branch origin/master + +### Branch off a branch + +If you have dependent changes, a very productive workflow is to have a branch +off a branch. Notably, this means that your patch sets (in Rietveld) will show +the separate changes, and be easy to review, rather than showing the merged +changes (including irrelevant changes), and means you can commit downstream CLs +without having to rebase them after the upstream has landed. Do this as follows: + +```none +git checkout master +git checkout branch1 +# some edits, commit +git checkout -b branch2 +git branch --set-upstream-to=branch1 +# some edits, commit +``` + +Now when you update the first branch, you can simply git pull on the second +branch as normal to pull in your changes: + +```none +git checkout branch1 +# some edits, commit +git checkout branch2 +git pull +``` + +**Splitting up a CL** + +A common variant of "branch off a branch" is splitting up a large CL into +pieces. Given a local branch `big`, you'd like to split it up into `branch1` and +`branch2`. + +One way to do this is to split off `branch1`, have that reviewed and committed, +update local repo (`gclient sync`), and then rebase `big` to `master`. This is +ok, but adds latency, and you can get the same result locally, so the second +part of the CL can be uploaded and reviewed even before the first part is +committed. + +This can be done manually, particularly if the files don't overlap, by making a +new branch `branch1`, manually copying the changed files in the first part, then +branching `branch2` off of that, and manually copying the files in the second +part. + +However, this can be done more cleanly via git. The main points are `git-add -i` +([Interactive +Staging](http://git-scm.com/book/en/Git-Tools-Interactive-Staging): to +interactively choose files or hunks of a patch set) and `git-rebase` (to set the +second part to be dependent on the first part, removing the common changes); +[`git-cherry-pick`](http://git-scm.com/docs/git-cherry-pick) is a technicality: + +```none +# first split off branch1 +git checkout origin/master +git new-branch branch1 +git cherry-pick -n ..big # apply and stage all ancestors of big that are not ancestors of HEAD, do not commit +git add -i # interactively choose which files or hunks to stage +git commit # commit staged changes +git checkout -- . # discard unstaged changes +# next set big to be a branch off of branch1 +git checkout big +git branch --set-upstream-to=branch1 +git rebase branch1 # may need to resolve conflicts +git branch -m branch2 # done! +``` + +Concretely, `git-cherry-pick -n` applies and stages all changes, but does not +commit them. In `git-add -i`, you can unstage files via `3: **r**evert`, and +then stage files (or hunks of files, or edit the diff manually) via `5: +**p**atch`, with manually editing via by the `e - manually edit the current +hunk` option when staging a hunk. While tedious, this is often easier than +resolving conflicts during rebasing. + +### Deleting an obsolete branch + +You generally want to delete local branches after the changes have been +committed to master. It is safest to check that your work has, in fact, been +committed before deleting it. + +Remember that you can always apply a CL that has been posted via: + +git checkout -b myworkfrompatch +git cl patch 12345 # Using CL issue number, not bug number, applies latest patch +set +git cl patch https://codereview.chromium.org/download/issue12345_1.diff # Use +URL of raw patch for older patch sets + +...so as long as your CL has been posted, you can easily recover your work. +Otherwise, you'll need to dig through the git repository, so be careful. + +Simply, if master (remote or local) is up-to-date and your branch has been +rebased, git branch -d will delete the branch. If not, it will refuse; to force +deletion, use git branch -D. So make sure master is up-to-date, rebase branch, +and then try deleting (optionally check manually before). + +Beware that if your local branch has many revisions (instead of always amending +a single revision), rebasing to master may fail, since it will try to apply the +patches incrementally. You can avoid this by squashing your local revisions into +a single revision (see [6.4 Git Tools - Rewriting +History](http://git-scm.com/book/en/Git-Tools-Rewriting-History), or more simply +[squashing commits with +rebase](http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html)). +This may be more trouble than it's worth, but it's the safest way. + +To check that the branch has been committed upstream: + +git checkout mywork +git rebase origin/master +git diff --stat origin/master # optional check + +If there are no differences, delete the branch: + +git checkout origin/master +git branch -d mywork # will only work if has been merged + +**NOTE:** If you haven't waited long enough after your commit, it is possible +that 'git fetch' did not get your commit and git will continue to believe that +you have local changes, which will prevent "git branch -d" from succeeding. It's +best to redo the steps later, (The repo is updated every 3 minutes) but you can +also instruct git to force-delete your branch. + +Note that when you delete your branch, it will give you the SHA-1 hash for its +tip: + +Deleted branch mywork (was 123abc0). + +You can then recover the branch via: + +git checkout -b mywork 123abc0 + +If you forget the hash, you can find it via git reflog. (Reference: [Can I +recover branch after the deletion in +git?](http://stackoverflow.com/questions/3640764/can-i-recover-branch-after-the-deletion-in-git)) + +### Prevent commits to master + +If you commit to master, updating will be messy. (This is a good reason to +simply delete master entirely, as noted near the top of this document. You only +need to read the remainder of this section if you don't do this.) + +You can prevent this by adding a pre-commit hook that checks if you're in master +and stops you from doing this. Create a file named +chromium/src/.git/hooks/pre-commit and add the below to it, then mark +executable. (Blink developers: add in blink directory as well.) + +#!/bin/bash +# Prevent commits against the 'master' branch +if \[\[ \`git rev-parse --abbrev-ref HEAD\` == 'master' \]\] +then +echo 'You cannot commit to the master branch!' +echo 'Stash your changes and apply them to another branch, using:' +echo 'git stash' +echo 'git checkout <branch>' +echo 'git stash apply' +exit 1 +fi + +If you've accidentally uploaded a change list from master, you can clear the +association of an issue number with master via: + +git cl issue 0 + +If you've accidentally committed to master, then, after copying your work to a +new branch (e.g., make patch and then apply to new branch), you can clean up +master by deleting your accidental commit as per [this +answer](http://stackoverflow.com/a/6866485) to [How to undo the last Git +commit?](http://stackoverflow.com/questions/927358/how-to-undo-the-last-git-commit) +-- see more details there. + +git reset --hard HEAD~1
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/get-the-code/working-with-nested-repos/index.md b/chromium/docs/website/site/developers/how-tos/get-the-code/working-with-nested-repos/index.md new file mode 100644 index 00000000000..0898765d997 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/get-the-code/working-with-nested-repos/index.md @@ -0,0 +1,69 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +- - /developers/how-tos/get-the-code + - 'Get the Code: Checkout, Build, & Run Chromium' +page_name: working-with-nested-repos +title: Working with Nested Third Party Repositories +--- + +The Chromium source tree includes other repositories in third party directories +(src/third_party) and elsewhere. + +## Make changes + +## Do your work, on a branch here, and commit locally. + +git checkout -b work +vim third-party-file.cc +git commit -a -m "work done" + +## Upload for review + +git cl upload + +## Do the usual add-reviewers-seek-lgtm dance. Once reviewed, submit your change: + +git cl land + +## Done? Not quite: you need to roll your change into the Chromium tree. + +## Roll DEPS + +Since Chromium mirrors these projects with git, the DEPS file entry for the +project has a git hash. So how do you update the DEPS file hash for source code +changes that don't really live in git? + +Method #1: Use the depot_tools roll-dep script + +# cd to the main src directory for your checkout cd src # Create and switch to a +new branch git new-branch depsroll # Run roll-dep giving the path and the +desired revision # if you omit the revision, it will roll to the current repo +HEAD roll-dep src/third_party/foo +\[--roll-to=SVN_REVISION_NUMBER/GIT_COMMIT_HASH\] + +Method #2: Manual inspection (patch the hash into the DEPS file by hand). + +# cd to the main src directory for your checkout pushd src # Create and switch +to a new branch git new-branch depsroll # cd to the directory listed in the DEPS +file (e.g., src/third_party/cld_2/src for 'cld2') pushd third_party/foo/bar # +Fetch (but do not pull) the latest revisions from Chromium's git mirror of the +remote repository git fetch origin # Use 'git log' to list the commits in the +mirror and find the hash of the one you need git log origin # Go back to src/ +popd # Patch the revision hash into the DEPS file by hand. + +Regardless of method used, the result is a modified DEPS file. Commit it locally +and upload for review: + +git commit -a -m "roll third_party/whatever deps because ..." +git cl upload + +## Adding new repositories to DEPS + +Ensure the repository in question **is mirrored at chromium.googlesource.com**. +We do this to avoid swamping upstream hosts with loads of traffic from our +developers and bot fleet. To mirror a repository, please file an [infrastructure +ticket](https://code.google.com/p/chromium/issues/entry?template=Build%20Infrastructure).
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/get-the-code/working-with-release-branches/index.md b/chromium/docs/website/site/developers/how-tos/get-the-code/working-with-release-branches/index.md new file mode 100644 index 00000000000..b71ecc44393 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/get-the-code/working-with-release-branches/index.md @@ -0,0 +1,85 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +- - /developers/how-tos/get-the-code + - 'Get the Code: Checkout, Build, & Run Chromium' +page_name: working-with-release-branches +title: Working with Release Branches +--- + +*This applies to commits to Chromium repository branches. For changes to +Chromium OS repositories, see the information +[here](/chromium-os/how-tos-and-troubleshooting/working-on-a-branch).* + +## Checking out a release branch + +**Note: Prior to branch 3420 it is usually NOT possible to sync and build a +release branch** (i.e. with consistent third_party DEPS), The instructions below +will only work with branch 3420 or later. For old branches, please refer to the +internal documentation (*go/ChromeReleaseBranches*). + +# Make sure you are in 'src'. +# This part should only need to be done once, but it won't hurt to repeat it. +The first +# time checking out branches and tags might take a while because it fetches an +extra # 1/2 GB or so of branch commits. +gclient sync **--with_branch_heads --with_tags** # You may have to explicitly +'git fetch origin' to pull branch-heads/ +git fetch +# Checkout the branch 'src' tree. $BRANCH can be found under Chromium +[here](https://chromiumdash.appspot.com/branches). +git checkout -b branch_$BRANCH branch-heads/$BRANCH +# Checkout all the submodules at their branch DEPS revisions. +gclient sync --with_branch_heads --with_tags + +## Building a branch + +Once checked out, building a branch should be [the same as building +trunk](/developers/how-tos/get-the-code). To avoid clobbering other build +artifacts, you may want to specify a different build directory (e.g. +`//out/Branch1234` instead of `//out/Default`). + +## Merging a patch from another branch (e.g. trunk) + +Please see the [cherry-pick/drover instructions.](/developers/how-tos/drover) + +## Developing a patch directly on the branch + +**Note:** Bugs should generally be fixed and tested on trunk (canary) and then +merged to branches. However, if you cannot do that: # Make sure you are in +'src'. +# Create a branch for the patch. +git new-branch --upstream branch-heads/$BRANCH my_hack_on_the_branch # Develop +normally. +git commit git cl upload +# After your CL is carefully reviewed, land directly. Don't use the CQ on +branches. +git cl land + +## Syncing and building a release tag + +## Releases are tagged in git with the release version number. +## Note: You cannot commit to a release tag. This is purely for acquiring the sources that went into a release build. + +## # Make sure you have all the release tag information in your checkout. + +## git fetch --tags + +## # Checkout whatever version you need (known versions can be seen with 'git +show-ref --tags') + +## git checkout -b your_release_branch 74.0.3729.131 # or more explicitly, +tags/74.0.3729.131 + +## gclient sync --with_branch_heads --with_tags + +Then build as normal. + +## Get back to the "trunk" + +# Make sure you are in 'src'. +git checkout -f master +gclient sync
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/getting-around-the-chrome-source-code/Content.png.sha1 b/chromium/docs/website/site/developers/how-tos/getting-around-the-chrome-source-code/Content.png.sha1 new file mode 100644 index 00000000000..57a724ea3a2 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/getting-around-the-chrome-source-code/Content.png.sha1 @@ -0,0 +1 @@ +0032b62ea31908b0043324bf90386b0a7fcab9a9
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/getting-around-the-chrome-source-code/index.md b/chromium/docs/website/site/developers/how-tos/getting-around-the-chrome-source-code/index.md new file mode 100644 index 00000000000..fa4c4779386 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/getting-around-the-chrome-source-code/index.md @@ -0,0 +1,357 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: getting-around-the-chrome-source-code +title: Getting Around the Chromium Source Code Directory Structure +--- + +[TOC] + +## High-level overview + +Chromium is separated into two main parts (excluding other libraries): the +browser and the renderer (which includes Blink, the web engine). The browser is +the main process and represents all the UI and I/O. The renderer is the (often) +per-tab sub-process that is driven by the browser. It embeds Blink to do layout +and rendering. + +You will want to read and become familiar with our [multi-process +architecture](/developers/design-documents/multi-process-architecture) and [how +Chromium displays web +pages](/developers/design-documents/displaying-a-web-page-in-chrome). + +## Top-level projects + +When you check out Chromium, you will notice a number of top-level directories. +These projects are as follows: + +* **android_webview:** Provides a facade over src/content suitable for + integration into the android platform. NOT intended for usage in + individual android applications (APK). [More + information](https://docs.google.com/document/d/1a_cUP1dGIlRQFUSic8bhAOxfclj4Xzw-yRDljVk1wB0/edit?usp=sharing) + about the Android WebView source code organization. +* **apps**: [Chrome packaged + apps](http://developer.chrome.com/apps/about_apps.html). +* **base**: Common code shared between all sub-projects. This contains + things like string manipulation, generic utilities, etc. Add things + here only if it must be shared between more than one other top-level + project. +* **breakpad**: Google's open source crash reporting project. This is + pulled directly from Google Code's Subversion repository. +* **build**: Build-related configuration shared by all projects. +* **cc**: The Chromium compositor implementation. +* **chrome**: The Chromium browser (see below). +* **chrome/test/data**: Data files for running certain tests. +* **components**: directory for components that have the Content + Module as the uppermost layer they depend on. +* **content:** The core code needed for a multi-process sandboxed + browser (see below). [More information](/developers/content-module) + about why we have separated out this code. +* **device:** Cross-platform abstractions of common low-level hardware + APIs. +* **net**: The networking library developed for Chromium. This can be + used separately from Chromium when running our simple test_shell in + the `webkit` repository. See also `chrome/common/net`. +* **sandbox**: The sandbox project which tries to prevent a hacked + renderer from modifying the system. +* **skia + third_party/skia**: Google's Skia graphics library. Our + additional classes in ui/gfx wrap Skia. +* **sql:** Our wrap around sqlite. +* **testing**: Contains Google's open-sourced GTest code which we use + for unit testing. +* **third_party**: 200+ small and large "external" libraries such as + image decoders, compression libraries and the web engine Blink (here + because it inherits license limitations from WebKit). [Adding new + packages](/developers/adding-3rd-party-libraries). + * **.../blink/renderer**: The web engine responsible for turning + HTML, CSS and scripts into paint commands and other state + changes. +* **tools** +* **ui/gfx**: Shared graphics classes. These form the base of + Chromium's UI graphics. +* **ui/views**: A simple framework for doing UI development, providing + rendering, layout and event handling. Most of the browser UI is + implemented in this system. This directory contains the base + objects. Some more browser-specific objects are in + chrome/browser/ui/views. +* **url**: Google's open source URL parsing and canonicalization + library. +* **v8**: The V8 Javascript library. This is pulled directly from + Google Code's Subversion repository. + +For historical reasons, there are some small top level directories. Going +forward, the guidance is that new top level directories are for applications +(e.g. Chrome, Android WebView, Ash). Even if these applications have multiple +executables, the code should be in subdirectories of the application + +Here's a slightly dated diagram of the dependencies. In particular, WebKit is +replaced by blink/renderer. A module that is lower can't include code from a +higher module directly (i.e. content can't include a header from chrome), but +talks to it using embedder APIs. + +[<img alt="image" +src="/developers/how-tos/getting-around-the-chrome-source-code/Content.png">](/developers/how-tos/getting-around-the-chrome-source-code/Content.png) + +## Quick reference for the directory tree under "content/" + +* **browser**: The backend for the application which handles all I/O + and communication with the child processes . This talks to the + `renderer` to manage web pages. +* **common:** Files shared between the multiple processes (i.e. + browser and renderer, renderer and plugin, etc...). This is the code + specific to Chromium (and not applicable to being in base). +* **gpu:** Code for the GPU process, which is used for 3D compositing + and 3D APIs. +* **plugin:** Code for running browser plugins in other processes. +* **ppapi_plugin:** Code for the [Pepper + ](/developers/design-documents/pepper-plugin-implementation)plugin + process. +* **renderer**: Code for the subprocess in each tab. This embeds + WebKit and talks to `browser` for I/O. +* **utility:** Code for running random operations in a sandboxed + process. The browser process uses it when it wants to run an + operation on untrusted data. +* **worker:** Code for running HTML5 Web Workers. + +## Quick reference for the directory tree under "chrome/" + +* **app**: The "app" is the most basic level of the program. It is run + on startup, and dispatches to either the browser or renderer code + depending on which capabilities the current process is in. It + contains the projects for `chrome.exe` and `chrome.dll`. You won't + generally need to change this stuff except for resources like images + and strings. + * **locales**: Projects for building localized DLLs. + * **resources**: Icons and cursors. + * **theme**: Images for the theme of the window. +* **browser**: The frontend including the main window, UI, and the + backend for the application which handles all I/O and storage. This + talks to the `renderer` to manage web pages. + * **ui** model, view and controller code for UI features and + functionality +* **common**: Files shared between the browser and the renderer that + is specific to the Chrome module. + * **net**: Some Chromium-specific stuff on top of the `net` + top-level module. This should be merged with browser/net. +* **installer**: Source files and projects for making the installer + (MSI package). +* ****renderer**: Chrome specific code that runs in the renderer + process. This adds Chrome features like autofill, translate etc to + the content module.** +* **test**: + * **automation**: Used by tests to drive the browser UI, for + example, in `test/ui`, `test/startup`, etc. This communicates + with `browser/automation` in the browser. + * **page_cycler**: Code for running page cycler tests (for + performance measurement). See `tools/perf/dashboard`. + * **reliability**: Reliability tests for distributed testing of + page loads for reliability metrics and crash finding. + * **selenium**: Code for running the selenium tests, which is a + third-party test suite for Ajaxy and JavaScript stuff. See + `test/third_party/selenium_core`. + * **startup**: Tests for measuring startup performance. See + `tools/perf/dashboard` and `tools/test/reference_build`. + * **ui**: UI tests for poking at the browser UI, opening tabs, + etc. It uses `test/automation` for doing most operations. + * **unit**: The base code for the unit tests. The test code for + individual tests is generally alongside the code it is testing + in a `*_unittest.cc` file. +* **third_party**: Third party libraries that are specific to + Chromium. Some other third party libraries are in the top-level + `third_party` library. +* **tools** + * **build**: Tools and random stuff related to building. + * **memory**: Tools for memory stuff. Currently includes `gflags` + for setting page heap options. + * **perf/dashboard**: Code for converting performance logs (for + example `test/startup_test`) into data and graphs. + * **profiles**: Generator for random history data. Used to make + test profiles. + +## A personal learning plan + +Eventually you’ll have your build setup, and want to get to work. In a perfect +world, we would have all the time we needed to read every line of code and +understand it before writing our first line of code. In practice, we’d have a +hard time reading just the checkins that happen in one day if we did nothing +else, so none of us will ever be able to read all of the code. So, what can we +do? We suggest you develop your own plan for learning what you need, here are +some suggested starting points. + +Fortunately for us, Chromium has some top quality design docs +[here](/developers/design-documents). While these can go a bit stale (for +instance, when following along, you may find references to files that have been +moved or renamed or refactored out of existence), it is awesome to be able to +comprehend the way that the code fits together overall. + +**Read the most important dev docs** + +[multi-process-architecture](/developers/design-documents/multi-process-architecture) + +[displaying-a-web-page-in-chrome](/developers/design-documents/displaying-a-web-page-in-chrome) + +[inter-process-communication](/developers/design-documents/inter-process-communication) + +[threading](/developers/design-documents/threading) + +**See if your group has any startup docs** + +There may be some docs that people working on the same code will care about +while others don’t need to know as much detail. + +**Learn some of the code idioms:** + +[important-abstractions-and-data-structures +](/developers/coding-style/important-abstractions-and-data-structures) + +[smart-pointer-guidelines](/developers/smart-pointer-guidelines) + +[chromium-string-usage](/developers/chromium-string-usage) + +Later, as time permits, skim all the design docs, reading where it seems +relevant. + +Get good at using code search (or your code browsing tool of choice) + +Learn who to ask how the code works [hints +here](/developers/finding-somebody-who-knows-how-a-piece-of-code-works). + +Debug into the code you need to learn, with a debugger if you can, log +statements and grepping if you cannot. + +Look at the differences in what you need to understand and you currently +understand. For instance, if your group does a lot of GUI programming, then +maybe you can invest time in learning GTK+, Win32, or Cocoa programming. + +Use [source.chromium.org](https://source.chromium.org/) to search the source +code. This can be particularly helpful if code moves around and our +documentation is no longer accurate. + +## Code paths for common operations + +There is additional information and more examples on [how Chromium displays web +pages](/developers/design-documents/displaying-a-web-page-in-chrome). + +### Application startup + +1. Our `WinMain` function is in `chrome/app/main.cc`, and is linked in + the `chrome` project. +2. `WinMain` launches the Google Update Client, which is the + installer/autoupdater. It will find the subdirectory for the current + version, and load `chrome.dll` from there. +3. It calls `ChromeMain` in the newly loaded library, which is in + `chrome_main.cc` in the `chrome_dll` project. +4. `ChromeMain` does initialization for common components, and then + forwards to either `RendererMain` in + `chrome/renderer/renderer_main.cc` if the command line flag + indicates that this should be a subprocess, or `BrowserMain` in + `chrome/browser/browser_main.cc` if not to load a new copy of the + application. Since this is startup, we're launching the browser. +5. `BrowserMain` does common browser initialization. It has different + modes for running installed webapps, connecting to the automation + system if the browser is being tested, etc. +6. It calls `LaunchWithProfile` in `browser_init.cc` which creates a + new `Browser` object in `chrome/browser/ui/browser.cc`. This object + encapsulates one toplevel window in the application. The first tab + is appended at this time. + +### Tab startup & initial navigation + +1. `BrowserImpl::AddTab` in `weblayer/browser/browser_impl.cc` is + called to append a new tab. +2. It will create a new `TabContents` object from + `browser/tab_contents/tab_contents.cc` +3. `TabContents` creates a `RenderViewHost` + (`chrome/browser/renderer_host/render_view_host.cc`) via the + `RenderViewHostManager's` Init function in + `chrome/browser/tab_contents/render_view_host_manager.cc`). + Depending on the `SiteInstance`, the `RenderViewHost` either spawns + a new renderer process, or re-uses an existing `RenderProcessHost`. + `RenderProcessHost` is the object in the browser that represents a + single renderer subprocess. +4. The `NavigationController` in + `chrome/browser/tab_contents/navigation_controller.cc` which is + owned by the tab contents, is instructed to navigate to the URL for + the new tab in `NavigationController::LoadURL`. "Navigating from the + URL bar" from step 3 onward describes what happens from this point. + +### Navigating from the URL bar + +1. When the user types into or accepts an entry in the URL bar, the + autocomplete edit box determines the final target URL and passes + that to `AutocompleteEdit::OpenURL`. (This may not be exactly what + the user typed - for example, an URL is generated in the case of a + search query.) +2. The navigation controller is instructed to navigate to the URL in + `NavigationController::LoadURL`. +3. The `NavigationController` calls `TabContents::Navigate` with the + `NavigationEntry` it created to represent this particular page + transition. It will create a new `RenderViewHost` if necessary, + which will cause creation of a `RenderView` in the renderer process. + A `RenderView` won't exist if this is the first navigation, or if + the renderer has crashed, so this will also recover from crashes. +4. `Navigate` forwards to `RenderViewHost::NavigateToEntry`. The + `NavigationController` stores this navigation entry, but it is + marked as "pending" because it doesn't know for sure if the + transition will take place (maybe the host can not be resolved). +5. `RenderViewHost::NavigateToEntry` sends a `ViewMsg_Navigate` to the + new `RenderView` in the renderer process. +6. When told to navigate, `RenderView` may navigate, it may fail, or it + may navigate somewhere else instead (for example, if the user clicks + a link). `RenderViewHost` waits for a `ViewHostMsg_FrameNavigate` + from the `RenderView`. +7. When the load is "committed" by WebKit (the server responded and is + sending us data), the `RenderView` sends this message, which is + handled in `RenderViewHost::OnMsgNavigate`. +8. The `NavigationEntry` is updated with the information on the load. + In the case of a link click, the browser has never seen this URL + before. If the navigation was browser-initiated, as in the startup + case, there may have been redirects that have changed the URL. +9. The `NavigationController` updates its list of navigations to + account for this new information. + +### Navigations and session history + +Each `NavigationEntry` stores a page ID and a block of history state data. The +page ID is used to uniquely identify a page load, so we know which +`NavigationEntry` it corresponds to. It is assigned when the page is committed +commit, so a pending `NavigationEntry` will have a page ID of -1. The history +state data is simply a `WebCore::HistoryItem` serialized to a string. Included +on this item are things like the page URL, subframe URLs, and form data. + +1. When the browser initiates the request (typing in the URL bar, or + clicking back/forward/reload) + 1. A `WebRequest` is made representing the navigation, along with + extra information like a page ID for bookkeeping. New + navigations have an ID of -1. Navigations to old entries have + the ID assigned to the `NavigationEntry` when the page was first + visited. This extra information will be queried later when the + load commits. + 2. The main `WebFrame` is told to load the new request. +2. When the renderer initiates the request (user clicks a link, + javascript changes the location, etc): + 1. `WebCore::FrameLoader` is told to load the request via one of + its bajillion varied load methods. +3. In either case, when the first packet from the server is received, + the load is committed (no longer "pending" or "provisional"). +4. If this was a new navigation, `WebCore` will create a new + `HistoryItem` and add it to the `BackForwardList`, a `WebCore` + class. In this way, we can differentiate which navigations are new, + and which are session history navigations. +5. `RenderView::DidCommitLoadForFrame` handles the commit for the load. + Here, the previous page's state is stored in session history, via + the `ViewHostMsg_UpdateState` message. This will tell the browser to + update the corresponding `NavigationEntry` (identified by + `RenderView's` current `page ID`) with the new history state. +6. `RenderView's` current `page ID` is updated to reflect the committed + page. For a new navigation, a new unique `page ID` is generated. For + a session history navigation, it will be the `page ID` originally + assigned when it was first visited, which we had stored on the + `WebRequest` when initiating the navigation. +7. A `ViewHostMsg_FrameNavigate` message is sent to the browser, + updating the corresponding `NavigationEntry` (identified by + `RenderView's` newly updated `page ID`) with the new URL and other + information.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/gpu-gardening/index.md b/chromium/docs/website/site/developers/how-tos/gpu-gardening/index.md new file mode 100644 index 00000000000..7fd007d1fd3 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/gpu-gardening/index.md @@ -0,0 +1,11 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: gpu-gardening +title: '' +--- + +[GPU Pixel Wrangling](/developers/how-tos/gpu-wrangling)
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/gpu-overdraw-debugging-tool/index.md b/chromium/docs/website/site/developers/how-tos/gpu-overdraw-debugging-tool/index.md new file mode 100644 index 00000000000..af8364cabbe --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/gpu-overdraw-debugging-tool/index.md @@ -0,0 +1,103 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: gpu-overdraw-debugging-tool +title: GPU Overdraw Debugging Tool +--- + +Debugging GPU Overdraw in Chrome + +# Intro + +When diagnosing performance problems it can be valuable to visualize GPU +overdraw. This can show you where Chrome might be doing more rendering work than +necessary and help you see where you might be able to reduce rendering overhead. + +The primary audience for this tool is Chrome developers but it can also be used +to diagnose performance problems with web pages. + +# Getting Started + +The GPU overdraw feedback tool built into Chrome has been inspired by the [GPU +overdraw debug +feature](https://developer.android.com/studio/profile/dev-options-overdraw.html) +that exists on Android and developers familiar with that feature will feel at +home using this tool to improve the Chrome UI or web pages. + +To visualizing GPU overdraw in Chrome navigate to about:flags and enable the +Show overdraw feedback experiment. If you are on Chrome OS then it is also +recommended to disable the Partial swap experiment as that produces output that +is easier to analyze. + +When enabled, this tool visualize overdraw by color-coding interface elements +based on how many elements are drawn underneath. The element colors are hinting +at the amount of overdraw on the screen for each pixel, as follows: + +True color: No overdraw + +Blue: Overdrawn once + +Green: Overdrawn twice + +Pink: Overdrawn three times + +Red: Overdrawn four or more times + +<img alt="image" +src="https://docs.google.com/a/google.com/drawings/d/sKYz4g05kUmYRmx8p5qR50w/image?w=599&h=386&rev=1&ac=1" +height=386 width=599> + +Example of GPU overdraw feedback output. + +<img alt="image" +src="https://docs.google.com/a/google.com/drawings/d/s0J4KvzwLwH8-dNJuiC8UOQ/image?w=599&h=435&rev=22&ac=1" +height=435 width=599> + +Some overdraw is unavoidable. As you are tuning your UI elements or web page, +the goal is to arrive at a visualization that shows mostly true colors and 1X +overdraw in blue. The calculator UI shown above is an example of undesirable +amount of GPU overdraw. + +Examples of undesirable and desirable Debug GPU Overdraw output. + +<img alt="image" +src="https://docs.google.com/a/google.com/drawings/d/shfmR54KvCMtndr2_oPSxDg/image?w=624&h=473&rev=102&ac=1" +height=473 width=624> + +# Fixing Overdraw + +There are several strategies you can pursue to reduce or eliminate overdraw. If +you are working on the Chrome OS UI then it usually comes down to using fewer +Aura windows with opacity set to TRANSLUCENT. For Chrome apps and web-pages in +general, the following strategies will likely apply: + + Removing unnecessary use of “position:fixed;”. + + Avoid use of 3D transformations and translateZ=0. + + Use { alpha: false } for <canvas> elements unless alpha is needed. + +# Tracing + +If you are analyzing GPU overdraw for animations or creating automated +performance tests then overdraw feedback in the form of trace events can be +useful. See [The Trace Event Profiling Tool +(about:tracing)](http://www.chromium.org/developers/how-tos/trace-event-profiling-tool) +for more details about how to record tracing runs. Enable the viz.overdraw +tracing category to have Chrome record the amount of overdraw for each frame. +The result is presented as a GPU Overdraw counter that changes over time as +overdraw increase or decrease. + +<img alt="image" +src="https://docs.google.com/a/google.com/drawings/d/sLB42g9KPAjoPQGg8bqA4Sg/image?w=599&h=435&rev=21&ac=1" +height=435 width=599> + +The value of the counter is the percentage of overdraw in the last frame +presented. No overdraw for one half the screen and 1X overdraw for the other +half results in a Gpu Overdraw counter value of 50. This metric is only +available when ARB_occlusion_query is available. + +*Under construction...*
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/gpu-wrangling/Step1.png.sha1 b/chromium/docs/website/site/developers/how-tos/gpu-wrangling/Step1.png.sha1 new file mode 100644 index 00000000000..2149a39551c --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/gpu-wrangling/Step1.png.sha1 @@ -0,0 +1 @@ +3aca56b5c10e827e01cd1653b123d2eee34039de
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/gpu-wrangling/Step2.png.sha1 b/chromium/docs/website/site/developers/how-tos/gpu-wrangling/Step2.png.sha1 new file mode 100644 index 00000000000..b21602825a9 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/gpu-wrangling/Step2.png.sha1 @@ -0,0 +1 @@ +c379322ffda434bf6df24b7d2ffa529a80c8480c
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/gpu-wrangling/check_gpu_bots-script/check_gpu_bots.py b/chromium/docs/website/site/developers/how-tos/gpu-wrangling/check_gpu_bots-script/check_gpu_bots.py new file mode 100644 index 00000000000..bbdd5c23361 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/gpu-wrangling/check_gpu_bots-script/check_gpu_bots.py @@ -0,0 +1,498 @@ +#!/usr/bin/env python + +# Copyright 2014 The Chromium Authors. All rights reserved. +# Use of this source code is governed by a BSD-style license that can be +# found in the LICENSE file. + +import argparse +import datetime +import getpass +import json +import os +import smtplib +import sys +import time +import urllib +import urllib2 + +BASEURL = 'http://build.chromium.org/p/' +BASEBUILDERURL = BASEURL + '%s/builders/%s' +BASEJSONBUILDERSURL = BASEURL + '%s/json/builders' +BASEJSONBUILDSURL = BASEURL + '%s/json/builders/%s/builds' +SPECIFICBUILDURL = BASEURL + '%s/builders/%s/builds/%s' + +DEFAULTEMAILPASSWORDFILE = '.email_password' +DEFAULTPREVIOUSRESULTSFILE = '.poll_gpu_scripts_previous_results' + +GMAILSMTPSERVER = 'smtp.gmail.com:587' + +def getJsonFromUrl(url): + c = urllib2.urlopen(url) + js = c.read() + c.close() + return json.loads(js) + +def getBuildersJsonForWaterfall(waterfall): + querystring = '?filter' + return getJsonFromUrl((BASEJSONBUILDERSURL + '%s') % (waterfall, querystring)) + +def getLastNBuildsForBuilder(n, waterfall, builder): + if n == 0 or n < -1: + return {} + + querystring = '' + if n > 0: + querystring = '?' + for i in range(n): + querystring += 'select=-%d&' % (i + 1) + querystring += 'filter' + + return getJsonFromUrl((BASEJSONBUILDSURL + '%s') % + (waterfall, urllib.quote(builder), querystring)) + +def getFilteredBuildersJsonForWaterfall(waterfall, filter): + querystring = '?' + for botindex in range(len(filter)): + bot = filter[botindex] + querystring += 'select=%s&' % urllib.quote(bot) + querystring += 'filter' + + return getJsonFromUrl((BASEJSONBUILDERSURL + '%s') % (waterfall, querystring)) + +def getAllGpuBots(): + regularwaterfalls = ['chromium.gpu', + 'tryserver.chromium.gpu', + 'chromium.gpu.fyi'] + + WEBKITGPUBOTS = ['GPU Win Builder', + 'GPU Win Builder (dbg)', + 'GPU Win7 (NVIDIA)', + 'GPU Win7 (dbg) (NVIDIA)', + 'GPU Mac Builder', + 'GPU Mac Builder (dbg)', + 'GPU Mac10.7', + 'GPU Mac10.7 (dbg)', + 'GPU Linux Builder', + 'GPU Linux Builder (dbg)', + 'GPU Linux (NVIDIA)', + 'GPU Linux (dbg) (NVIDIA)'] + filteredwaterfalls = [('chromium.webkit', WEBKITGPUBOTS)] + + allbots = {k: getBuildersJsonForWaterfall(k) for k in regularwaterfalls} + filteredbots = {k[0]: getFilteredBuildersJsonForWaterfall(k[0], k[1]) + for k in filteredwaterfalls} + allbots.update(filteredbots) + + return allbots + +def timestr(t): + return time.strftime("%a, %d %b %Y %H:%M:%S", t) + +def roughTimeDiffInHours(t1, t2): + dt = [] + for t in [t1, t2]: + dt.append(datetime.datetime(t.tm_year, t.tm_mon, t.tm_mday, t.tm_hour, + t.tm_min, t.tm_sec)) + dtd = dt[0] - dt[1] + + hours = float(dtd.total_seconds()) / 3600.0 + + return abs(hours) + +def getBotStr(bot, t): + s = ' %s::%s\n' % (bot['waterfall'], bot['name']) + + if 'failurestring' in bot: + s += ' failure: %s\n' % bot['failurestring'] + if 'endtime' in bot: + s += (' last build end time: %s (roughly %f hours ago)\n' % + (timestr(bot['endtime']), roughTimeDiffInHours(t, bot['endtime']))) + if 'boturl' in bot: + s += ' bot url: %s\n' % bot['boturl'] + if 'buildurl' in bot: + s += ' build url: %s\n' % bot['buildurl'] + s += '\n' + + return s + +def getBotsStr(bots): + t = time.localtime() + s = '' + for bot in bots: + s += getBotStr(bot, t) + s += '\n' + return s + +def getOfflineBots(bots): + offlinebots = [] + for waterfallname in bots: + waterfall = bots[waterfallname] + for botname in waterfall: + bot = waterfall[botname] + if bot['state'] != 'offline': + continue + botspec = {'waterfall': waterfallname, 'name': botname, 'impl': bot} + mrbuild = getMostRecentlyCompletedBuildForBot(botspec) + if mrbuild: + botspec['endtime'] = time.localtime(mrbuild['times'][1]) + botspec['boturl'] = BASEBUILDERURL % (waterfallname, + urllib.quote(botname)) + else: + print 'no most recent build available: %s::%s' % (waterfallname, + botname) + offlinebots.append(botspec) + return offlinebots + +def getOfflineBotsStr(offlinebots): + return 'Offline bots:\n%s' % getBotsStr(offlinebots) + +def getMostRecentlyCompletedBuildForBot(bot): + if 'impl' in bot and 'mrbuild' in bot['impl']: + return bot['impl']['mrbuild'] + + numbuilds = 10 # TODO? + builds = getLastNBuildsForBuilder(numbuilds, bot['waterfall'], bot['name']) + for i in range(numbuilds): + currbuildname = '-%d' % (i + 1) + currbuild = builds[currbuildname] + if 'results' in currbuild and currbuild['results'] is not None: + if 'impl' in bot: + bot['impl']['mrbuild'] = currbuild + return currbuild + +def getFailedBots(bots): + failedbots = [] + for waterfallname in bots: + waterfall = bots[waterfallname] + for botname in waterfall: + bot = waterfall[botname] + botspec = {'waterfall': waterfallname, 'name': botname, 'impl': bot} + mrbuild = getMostRecentlyCompletedBuildForBot(botspec) + if mrbuild and 'text' in mrbuild and 'failed' in mrbuild['text']: + botspec['failurestring'] = ' '.join(mrbuild['text']) + botspec['boturl'] = BASEBUILDERURL % (waterfallname, + urllib.quote(botname)) + botspec['buildurl'] = SPECIFICBUILDURL % (waterfallname, + urllib.quote(botname), mrbuild['number']) + failedbots.append(botspec) + elif not mrbuild: + print 'no most recent build available: %s::%s' % (waterfallname, + botname) + return failedbots + +def getFailedBotsStr(failedbots): + return 'Failed bots:\n%s' % getBotsStr(failedbots) + +def getShallowBots(bots): + shallowbots = [] + for bot in bots: + shallowbot = {} + for k in bot: + if k != 'impl': + shallowbot[k] = bot[k] + shallowbots.append(shallowbot) + return shallowbots + +def jsonableToTime(j): + return time.struct_time((j['year'], j['mon'], j['day'], j['hour'], j['min'], + j['sec'], 0, 0, 0)) + +# mutates bots +def offlineBotsJsonableToTime(bots): + for bot in bots['offline']: + bot['endtime'] = jsonableToTime(bot['endtime']) + return bots + +def getPreviousResults(previous_results_file): + file = (previous_results_file if previous_results_file is not None + else DEFAULTPREVIOUSRESULTSFILE) + previous_results = {} + if os.path.isfile(file): + with open(file, 'r') as f: + previous_results = offlineBotsJsonableToTime(json.loads(f.read())) + return previous_results + +def timeToJsonable(t): + return {'year': t.tm_year, 'mon': t.tm_mon, 'day': t.tm_mday, + 'hour': t.tm_hour, 'min': t.tm_min, 'sec': t.tm_sec} + +# this mutates the offline bots, do it last +def offlineBotsTimeToJsonable(bots): + t = time.localtime() + for bot in bots: + bot['hourssincelastrun'] = roughTimeDiffInHours(bot['endtime'], t) + bot['endtime'] = timeToJsonable(bot['endtime']) + return bots + +def getSummary(offlinebots, failedbots): + shallowofflinebots = offlineBotsTimeToJsonable(getShallowBots(offlinebots)) + shallowfailedbots = getShallowBots(failedbots) + return {'offline': shallowofflinebots, 'failed': shallowfailedbots} + +def writeResults(summary, previous_results_file): + file = (previous_results_file if previous_results_file is not None + else DEFAULTPREVIOUSRESULTSFILE) + with open(file, 'w') as f: + f.write(json.dumps(summary)) + +def findBot(name, lst): + for bot in lst: + if bot['name'] == name: + return bot + return None + +def getNoteworthyEvents(offlinebots, failedbots, previous_results): + t = time.localtime() + + CRITICALNUMHOURS = 1.0 + + previousoffline = (previous_results['offline'] if 'offline' + in previous_results else []) + previousfailures = (previous_results['failed'] if 'failed' + in previous_results else []) + + noteworthyoffline = [] + for bot in offlinebots: + if roughTimeDiffInHours(bot['endtime'], t) > CRITICALNUMHOURS: + previousbot = findBot(bot['name'], previousoffline) + if (previousbot is None or + previousbot['hourssincelastrun'] < CRITICALNUMHOURS): + noteworthyoffline.append(bot) + + noteworthynewfailures = [] + for bot in failedbots: + previousbot = findBot(bot['name'], previousfailures) + if previousbot is None: + noteworthynewfailures.append(bot) + + noteworthynewofflinerecoveries = [] + for bot in previousoffline: + if bot['hourssincelastrun'] < CRITICALNUMHOURS: + continue + currentbot = findBot(bot['name'], offlinebots) + if currentbot is None: + noteworthynewofflinerecoveries.append(bot) + + noteworthynewfailurerecoveries = [] + for bot in previousfailures: + currentbot = findBot(bot['name'], failedbots) + if currentbot is None: + noteworthynewfailurerecoveries.append(bot) + + return {'offline': noteworthyoffline, 'failed': noteworthynewfailures, + 'recoveredfailures': noteworthynewfailurerecoveries, + 'recoveredoffline': noteworthynewofflinerecoveries} + +def getNoteworthyStr(noteworthy): + t = time.localtime() + + s = '' + + if noteworthy['offline']: + s += 'IMPORTANT bots newly offline for over an hour:\n' + for bot in noteworthy['offline']: + s += getBotStr(bot, t) + s += '\n' + + if noteworthy['failed']: + s += 'IMPORTANT new failing bots:\n' + for bot in noteworthy['failed']: + s += getBotStr(bot, t) + s += '\n' + + if noteworthy['recoveredoffline']: + s += 'IMPORTANT newly recovered previously offline bots:\n' + for bot in noteworthy['recoveredoffline']: + s += getBotStr(bot, t) + s += '\n' + + if noteworthy['recoveredfailures']: + s += 'IMPORTANT newly recovered failing bots:\n' + for bot in noteworthy['recoveredfailures']: + s += getBotStr(bot, t) + s += '\n' + + return s + +def hasEmailable(noteworthy, send_email_for_recovered_offline_bots, + send_email_for_recovered_failing_bots): + if noteworthy['offline'] or noteworthy['failed']: + return True + + if send_email_for_recovered_offline_bots and noteworthy['recoveredoffline']: + return True + + if (send_email_for_recovered_failing_bots and + noteworthy['recoveredfailures']): + return True + + return False + +def get_email_body(tstr, offlinestr, failedstr, noteworthystr): + return '%s%s%s%s' % (tstr, offlinestr, failedstr, noteworthystr) + +def send_email(email_from, email_to, email_password, body): + subject = 'Chrome GPU Bots Notification' + message = 'From: %s\r\nTo: %s\r\nSubject: %s\r\n\r\n%s' % (email_from, + ','.join(email_to), subject, body) + + try: + server = smtplib.SMTP(GMAILSMTPSERVER) + server.starttls() + server.login(email_from, email_password) + server.sendmail(email_from, email_to, message) + server.quit() + except Exception as e: + print 'Error sending email: %s' % str(e) + +def testEmailLogin(email_from, email_password): + server = smtplib.SMTP(GMAILSMTPSERVER) + server.starttls() + server.login(email_from, email_password) + server.quit() + +def getEmailPassword(email_password_file): + password = '' + + password_file = (email_password_file if email_password_file is not None + else DEFAULTEMAILPASSWORDFILE) + + if os.path.isfile(password_file): + with open(password_file) as f: + password = f.read().strip() + else: + password = getpass.getpass( + 'Please enter email password for source account: ') + + return password + +def checkBots(email_from, email_to, send_email_for_recovered_offline_bots, + send_email_for_recovered_failing_bots, send_email_on_error, + email_password, previous_results_file): + tstr = 'Current time: %s\n\n' % (timestr(time.localtime())) + print tstr + + try: + # TODO(hartmanng) parallelize the http requests + bots = getAllGpuBots() + + offlinebots = getOfflineBots(bots) + offlinestr = getOfflineBotsStr(offlinebots) + print offlinestr + + failedbots = getFailedBots(bots) + failedstr = getFailedBotsStr(failedbots) + print failedstr + + previous_results = getPreviousResults(previous_results_file) + noteworthy = getNoteworthyEvents(offlinebots, failedbots, previous_results) + noteworthystr = getNoteworthyStr(noteworthy) + print noteworthystr + + # this mutates the offline bots, do it last + summary = getSummary(offlinebots, failedbots) + writeResults(summary, previous_results_file) + + if (email_from is not None and email_to is not None and + hasEmailable(noteworthy, send_email_for_recovered_offline_bots, + send_email_for_recovered_failing_bots)): + send_email(email_from, email_to, email_password, + get_email_body(tstr, offlinestr, failedstr, noteworthystr)) + except Exception as e: + errorstr = 'Error: %s' % str(e) + print errorstr + if send_email_on_error: + send_email(email_from, email_to, email_password, errorstr) + +def parseArgs(sysargs): + parser = argparse.ArgumentParser(prog=sysargs[0], + description='Query the Chromium GPU Bots Waterfall, output ' + + 'potential problems, and optionally repeat automatically and/or ' + + 'email notifications of results.') + parser.add_argument('--repeat-delay', type=int, dest='repeat_delay', + required=False, + help='How often to automatically re-run the script, in minutes.') + parser.add_argument('--email-from', type=str, dest='email_from', + required=False, + help='Email address to send from. Requires also specifying ' + + '\'--email-to\'.') + parser.add_argument('--email-to', type=str, dest='email_to', required=False, + nargs='+', + help='Email address(es) to send to. Requires also specifying ' + + '\'--email-from\'') + parser.add_argument('--send-email-for-recovered-offline-bots', + dest='send_email_for_recovered_offline_bots', action='store_true', + default=False, + help='Send an email out when a bot which has been offline for more ' + + 'than 1 hour goes back online.') + parser.add_argument('--send-email-for-recovered-failing-bots', + dest='send_email_for_recovered_failing_bots', + action='store_true', default=False, + help='Send an email when a failing bot recovers.') + parser.add_argument('--send-email-on-error', + dest='send_email_on_error', + action='store_true', default=False, + help='Send an email when the script has an error. For example, if ' + + 'the server is unreachable.') + parser.add_argument('--email-password-file', + dest='email_password_file', + required=False, + help=(('File containing the plaintext password of the source email ' + + 'account. By default, \'%s\' will be tried. If it does not exist, ' + + 'you will be prompted. If you opt to store your password on disk ' + + 'in plaintext, use of a dummy account is strongly recommended.') + % DEFAULTEMAILPASSWORDFILE)) + parser.add_argument('--previous-results-file', + dest='previous_results_file', + required=False, + help=(('File to store the results of the previous invocation of ' + + 'this script. By default, \'%s\' will be used.') + % DEFAULTPREVIOUSRESULTSFILE)) + + args = parser.parse_args(sysargs[1:]) + + if args.email_from is not None and args.email_to is None: + parser.error('--email-from requires --email-to.') + elif args.email_to is not None and args.email_from is None: + parser.error('--email-to requires --email-from.') + elif args.email_from is None and args.send_email_for_recovered_offline_bots: + parser.error('--send-email-for-recovered-offline-bots requires ' + + '--email-to and --email-from.') + elif (args.email_from is None and args.send_email_for_recovered_failing_bots): + parser.error('--send-email-for-recovered-failing-bots ' + + 'requires --email-to and --email-from.') + elif (args.email_from is None and args.send_email_on_error): + parser.error('--send-email-on-error ' + + 'requires --email-to and --email-from.') + elif (args.email_password_file and + not os.path.isfile(args.email_password_file)): + parser.error('File does not exist: %s', args.email_password_file) + + return args + +def main(sysargs): + args = parseArgs(sysargs) + + email_password = None + if args.email_from is not None and args.email_to is not None: + email_password = getEmailPassword(args.email_password_file) + try: + testEmailLogin(args.email_from, email_password) + except Exception as e: + print 'Error logging into email account: %s' % str(e) + sys.exit(1) + + while True: + checkBots(args.email_from, args.email_to, + args.send_email_for_recovered_offline_bots, + args.send_email_for_recovered_failing_bots, + args.send_email_on_error, + email_password, + args.previous_results_file) + if args.repeat_delay is None: + break + print 'Will run again in %d minutes...\n' % args.repeat_delay + time.sleep(args.repeat_delay * 60) + +if __name__ == '__main__': + main(sys.argv) diff --git a/chromium/docs/website/site/developers/how-tos/gpu-wrangling/check_gpu_bots-script/index.md b/chromium/docs/website/site/developers/how-tos/gpu-wrangling/check_gpu_bots-script/index.md new file mode 100644 index 00000000000..0ed18dc2cb7 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/gpu-wrangling/check_gpu_bots-script/index.md @@ -0,0 +1,91 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +- - /developers/how-tos/gpu-wrangling + - GPU Bots & Pixel Wrangling +page_name: check_gpu_bots-script +title: check_gpu_bots script +--- + +This is a script I hacked up during my wrangling shift. Hopefully this is only a +temporary measure, and will be deprecated by the awesome work being done on the +hackability CY and the sheriff-o-matic. + +#### Purpose + +While wrangling, I found it cumbersome and time consuming to keep track of +various waterfalls in a browser window with 10+ tabs. This script is meant to be +a quick-and-dirty way to avoid having to stare at the waterfalls quite so much +during a shift. + +#### How to get it + +[Here](/developers/how-tos/gpu-wrangling/check_gpu_bots-script/check_gpu_bots.py) +is an older version of the script available for direct download for convenience, +but there will be little continued support for it. The canonical version is now +checked into the Chromium repository at src/gpu/tools/check_gpu_bots.py. + +#### Features + +The script, when run directly with no args, simply polls the waterfall's [JSON +API](http://build.chromium.org/p/chromium/json/help), gathers some information +about (hopefully all of) the relevant GPU bots. It then prints out a summary of +the offline or failing bots, and exits. + +It can also be set up to repeat itself periodically, sort of like an +auto-refresh. + +The feature that made it most useful to me is that it can also optionally email +you when there's something that needs to be looked into. By default, "needs to +be looked into" is roughly defined as + +* there is at least one bot whose most recent build failed, and whose + most recent build had passed on the previous execution of the + script, OR +* there is at least one bot which has been in the "offline" state for + over an hour, and hadn't been the last time the script executed + +As described above, it only sends an email *once* per bot, the first time +something goes wrong. I did that to prevent getting spammed. Currently this +can't be overridden with command-line arguments, but I intend to add the ability +to override this. + +**NOTE** that currently only gmail addresses are supported as the source email +address, since the script hard-codes gmail's smtp server address. In addition, +if you use a weak password, gmail may require you to explicitly allow "[less +secure apps](https://support.google.com/accounts/answer/6010255)". + +Running the script on repeat, and having it set up to email you in case of a +problem, takes away a good deal of staring at waterfalls. I recommend that you +take a look at the waterfall from time to time, just because this script is not +time-tested, and bugs aren't outside the realm of possibility. + +### Examples + +* ./check_gpu_bots.py + * This runs once, and prints the results to stdout. +* ./check_gpu_bots.py --help + * This prints basic usage information, including the list of + possible command-line arguments. +* ./check_gpu_bots.py --email-from <source email> --email-to + <dest email> --send-email-on-error --repeat-delay 10 + * '--repeat-delay 10' sets the script to poll the waterfall every + 10 minutes. '--send-email-on-error' tells the script to email + you in case of error/exception (for example, an unreachable + server), as well as the normal cases. The rest tells the script + to send an email from <source email> to <dest + email>. You do have to be in control of <source email> + and will need to supply the password, either by saving it in a + file on disk, or supplying it to the script's prompt. If you opt + to save the password on disk, it is very strongly recommended + that you use a dummy account for the source email address. Also + note that the script can accept multiple destination email + addresses. + +#### Bugs + +Please report bugs to [hartmanng@chromium.org](mailto:hartmanng@chromium.org). +Feedback, features requests, and suggestions are also welcome.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/gpu-wrangling/index.md b/chromium/docs/website/site/developers/how-tos/gpu-wrangling/index.md new file mode 100644 index 00000000000..669e33e8948 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/gpu-wrangling/index.md @@ -0,0 +1,12 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: gpu-wrangling +title: GPU Bots & Pixel Wrangling +--- + +This page has moved to +<https://chromium.googlesource.com/chromium/src/+/HEAD/docs/gpu/pixel_wrangling.md>.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/gpu-wrangling/wrangler.png.sha1 b/chromium/docs/website/site/developers/how-tos/gpu-wrangling/wrangler.png.sha1 new file mode 100644 index 00000000000..69b73bf2115 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/gpu-wrangling/wrangler.png.sha1 @@ -0,0 +1 @@ +e5eff2b13f0cec322db6d9a08c0d3708ec82a5d8
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/how-to-set-up-visual-studio-debugger-visualizers/index.md b/chromium/docs/website/site/developers/how-tos/how-to-set-up-visual-studio-debugger-visualizers/index.md new file mode 100644 index 00000000000..55bdac46b33 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/how-to-set-up-visual-studio-debugger-visualizers/index.md @@ -0,0 +1,39 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: how-to-set-up-visual-studio-debugger-visualizers +title: Setting up Visual Studio Debugger Visualizers +--- + +[TOC] + +## Introduction + +Visual Studio (2013 and 2015) allows you to plug in additional "visualizers" to +display data in the watch windows. This makes debugging some of our more complex +data types much easier. To add macros: + +* Copy the contents of Chrome\\src\\tools\\win\\DebugVisualizers\\ to + %USERPROFILE%\\My Documents\\Visual Studio 2013\\Visualizers\\ (or + for newer versions, %USERPROFILE%\\Documents\\Visual Studio + 2015\\Visualizers\\) +* Start the debugger, and be amazed at the fancy new way it displays + your favorite objects. When you edit the file, you shouldn't have to + restart all of Visual Studio - it will get re-loaded when you start + the debugger. + +## Definitions + +* DisplayString: an expression (string literal or expression) to be + shown in the Watch, QuickWatch or Command window; if the preview + section is present and you also have a AutoExpand rule for it, the + AutoExpand rule is ignored. +* Expand: offer the possibility to construct hierarchies. + +## References + +* <http://blogs.msdn.com/b/vcblog/archive/2013/06/28/using-visual-studio-2013-to-write-maintainable-native-visualizations-natvis.aspx> +* <https://code.msdn.microsoft.com/windowsdesktop/Writing-type-visualizers-2eae77a2>
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/index.md b/chromium/docs/website/site/developers/how-tos/index.md new file mode 100644 index 00000000000..71dc8997c76 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/index.md @@ -0,0 +1,34 @@ +--- +breadcrumbs: +- - /developers + - For Developers +page_name: how-tos +title: How-Tos +--- + +* Build instructions: + [Windows](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/windows_build_instructions.md), + [Mac OS + X](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/mac_build_instructions.md), + [Linux](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/linux_build_instructions.md), + [ChromeOS](http://www.chromium.org/developers/how-tos/build-instructions-chromeos), + [Android](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/android_build_instructions.md), + and + [iOS](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/ios/build_instructions.md) +* Debugging instructions: + [Windows](/developers/how-tos/debugging-on-windows), [Mac OS + X](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/mac/debugging.md), + [Linux](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/linux/debugging.md), + and + [Android](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/android_debugging_instructions.md) +* [Running Chrome + tests](http://code.google.com/p/chromium/wiki/RunningChromeUITests) +* [Linux + Development](http://code.google.com/p/chromium/wiki/LinuxDevelopment) + tips and porting guide +* [Using Git](http://code.google.com/p/chromium/wiki/UsingGit) for + version control and code reviews + +For more, see this list of sub-pages: + +{% subpages collections.all %} diff --git a/chromium/docs/website/site/developers/how-tos/inspecting-ash/Screenshot from 2017-08-28 14_28_36.png.sha1 b/chromium/docs/website/site/developers/how-tos/inspecting-ash/Screenshot from 2017-08-28 14_28_36.png.sha1 new file mode 100644 index 00000000000..63a385cedbb --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/inspecting-ash/Screenshot from 2017-08-28 14_28_36.png.sha1 @@ -0,0 +1 @@ +52e45f4adaa97e6521101b5bca90ad607dfeb27b
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/inspecting-ash/XoWGyYBg5EA.png.sha1 b/chromium/docs/website/site/developers/how-tos/inspecting-ash/XoWGyYBg5EA.png.sha1 new file mode 100644 index 00000000000..1a88f4ac3d8 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/inspecting-ash/XoWGyYBg5EA.png.sha1 @@ -0,0 +1 @@ +b03a321a3d40a7dfed7253685b1643a02b30f015
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/inspecting-ash/chrome_inspect_other.png.sha1 b/chromium/docs/website/site/developers/how-tos/inspecting-ash/chrome_inspect_other.png.sha1 new file mode 100644 index 00000000000..4ff9e28d952 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/inspecting-ash/chrome_inspect_other.png.sha1 @@ -0,0 +1 @@ +bd3dd24dd111cae39013a26a374e812ee0ddb31a
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/inspecting-ash/distances.png.sha1 b/chromium/docs/website/site/developers/how-tos/inspecting-ash/distances.png.sha1 new file mode 100644 index 00000000000..5ced44e39f1 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/inspecting-ash/distances.png.sha1 @@ -0,0 +1 @@ +704ef674cccccb5cdbf22b4b7cd556c7afa20dfd
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/inspecting-ash/dom_tree.png.sha1 b/chromium/docs/website/site/developers/how-tos/inspecting-ash/dom_tree.png.sha1 new file mode 100644 index 00000000000..a9f9bf8433a --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/inspecting-ash/dom_tree.png.sha1 @@ -0,0 +1 @@ +fe3985fd776e65456fc85c54bd68d613b2f063a7
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/inspecting-ash/index.md b/chromium/docs/website/site/developers/how-tos/inspecting-ash/index.md new file mode 100644 index 00000000000..2ba47d63908 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/inspecting-ash/index.md @@ -0,0 +1,108 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: inspecting-ash +title: Inspecting Chrome Native UI with Chrome UI DevTools +--- + +Aura/Views UI can now be 'inspected' just like a webpage inspect-able using +Chrome DevTools. This is accomplished by re-using the existing frontend DevTools +inspector and creating a backend in Chrome and Components which interact with +DevTools inspector using the DevTools protocol language. We name this tool +Chrome UI Devtools. The design document for this tool can be found +[here](https://docs.google.com/document/d/1zpXnSLFrTbLRBJNnO2lWXV--nTOUWfBLPXwA9BDEsKA/edit?usp=sharing). + +And, +[here](https://docs.google.com/presentation/d/1q3RBp-QEIx5snjbi3_FNl1pp8wf74DXFpt_NgT0KMB0/edit?usp=sharing) +is a slideshow containing numerous GIFs showing what this is like to use. + +**Distances between a pinned element (in solid blue border) and a hovered +element (in solid green border). Guide lines are displayed along the pinned +element (could be either window,widget, or view):** + +[<img alt="image" +src="/developers/how-tos/inspecting-ash/distances.png">](/developers/how-tos/inspecting-ash/distances.png) + +**Picture 1: Distances between a pinned element and a hovered element.** + +**UI Element hierarchy tree:** + +[<img alt="UI Element hierarchy tree" +src="/developers/how-tos/inspecting-ash/dom_tree.png">](/developers/how-tos/inspecting-ash/dom_tree.png) + +**Picture 2:** **UI Element hierachy tree.** + +**Current Features** + +* Display window/widget/view in UI Element hierarchy tree (picture 2). +* Selecting nodes in the inspector displays their attributes (height, + width, x, y, visibility, view text tool tip if exist) in the CSS + side panel (picture 2). +* Attributes (except tooltip) can be edited in the CSS side panel. +* Any changes in the UI such as addition/removal/rearranging of + elements in Aura/Views UI will be reflected in the Chrome UI + Inspector. +* Hovering over elements in the inspector highlights them in + Aura/Views UI, displays guide lines around the elements and and + expands them in the inspector. +* Entering inspect mode by clicking on the arrow-in-box [<img + alt="https://sites.google.com/a/chromium.org/dev/developers/how-tos/inspecting-ash/Screenshot%20from%202017-08-28%2014_28_36.png?attredirects=0" + src="/developers/how-tos/inspecting-ash/Screenshot%20from%202017-08-28%2014%3A28%3A36.png">](/developers/how-tos/inspecting-ash/Screenshot%20from%202017-08-28%2014_28_36.png) + and hovering on any window/widget/view will show the corresponding + node in DOM tree and element guide lines. +* Entering inspect mode by clicking on the arrow-in-box [<img + alt="https://sites.google.com/a/chromium.org/dev/developers/how-tos/inspecting-ash/Screenshot%20from%202017-08-28%2014_28_36.png?attredirects=0" + src="/developers/how-tos/inspecting-ash/Screenshot%20from%202017-08-28%2014%3A28%3A36.png">](/developers/how-tos/inspecting-ash/Screenshot%20from%202017-08-28%2014_28_36.png) + and hovering on any DOM node will show the corresponding UI Element + in Chrome UI and element guide lines. +* Entering inspect mode and clicking on any element will pin the + element. While the element is being pinned, hovering on another + element displays the distances between the pinned element and the + hovered element (as in picture 1). There are 7 position arrangements + between 2 elements as described in [this design + document.](https://docs.google.com/document/d/1ySba9uad3ClqlA9CExlII6r0kgyhRnE0QWo11x2Wmbg) +* Pressing ESC or clicking on the arrow-in-box [<img + alt="https://sites.google.com/a/chromium.org/dev/developers/how-tos/inspecting-ash/Screenshot%20from%202017-08-28%2014_28_36.png?attredirects=0" + src="/developers/how-tos/inspecting-ash/Screenshot%20from%202017-08-28%2014%3A28%3A36.png">](/developers/how-tos/inspecting-ash/Screenshot%20from%202017-08-28%2014_28_36.png) + to exit inspect mode. +* Display hit test target window under mouse cursor in inspect mode. + Steps are shown in this [presentation + slide](https://docs.google.com/presentation/d/1ldW2rPAexu-nf-gIS1hUgcyPNpgF1fBaqppezyxBRLE)[.](https://docs.google.com/presentation/d/1ldW2rPAexu-nf-gIS1hUgcyPNpgF1fBaqppezyxBRLE) +* Support platforms: ChromeOS, Linux and Windows. + +**Planned Features** + +* Any animations initiated in in Aura/Views UI are displayed in the + inspector under the "Animations" tab and can be replayed. + +**Instructions** + +1. Run Chromium with default port 9223 using one of these 2 ways: + * Start with UI DevTools flag: + * On Windows : $ chrome.exe --enable-ui-devtools + * On ChromeOS, Linux: $ ./chrome --enable-ui-devtools + * If you want to use different port, add port in the flag + --enable-ui-devtools=<port> + * Start Chrome without flag (./chrome or chrome.exe): + * Go to Chrome Omnibox, type about:flags + * Go to enable native UI inspection, click Enable and restart + Chrome. This will start Chrome will listening port 9223. +2. In your Chrome browser, go to Omnibox, either + * Type `**chrome://inspect#other** then click` `**inspect**` under + UiDevToolsClient in the listing. This will open up the inspector + in a new tab (Picture 3). + * Type direct link: + **devtools://devtools/bundled/devtools_app.html?uiDevTools=true&ws=localhost:9223/0** + +**[<img alt="image" +src="/developers/how-tos/inspecting-ash/chrome_inspect_other.png">](/developers/how-tos/inspecting-ash/chrome_inspect_other.png)** + +Picture 3: Open Chrome UI Inspection window + +To remotely debug from different Chrome browser, navigate to +***devtools://devtools/bundled/devtools_app.html?uiDevTools=true&ws=<ip +address>:<port>/0*** (the 0 stands for the first inspect-able component +which is in Aura/Views UI*,* for now).
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/inspecting-ash/screenshot2.gif.sha1 b/chromium/docs/website/site/developers/how-tos/inspecting-ash/screenshot2.gif.sha1 new file mode 100644 index 00000000000..ff8c760f908 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/inspecting-ash/screenshot2.gif.sha1 @@ -0,0 +1 @@ +d07f136ef73b27c1b9aa06017e000de9c4e6368f
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/install-depot-tools/index.md b/chromium/docs/website/site/developers/how-tos/install-depot-tools/index.md new file mode 100644 index 00000000000..60fa7a5cebb --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/install-depot-tools/index.md @@ -0,0 +1,23 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: install-depot-tools +title: Install depot_tools +--- + +Chromium and Chromium OS use a package of scripts called +[**depot_tools**](/developers/how-tos/depottools) to manage checkouts and code +reviews. + +The depot_tools package includes `gclient`, `gcl`, `git-cl`, `repo`, and others. + +View the [**updated depot_tools set-up documentation** in the depot_tools +tutorial](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up). +Then continue with the tutorial or [see the depot_tools +documentation](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools.html) +for usage. These same docs are also available as man pages. + +See also [How-To: Using depot_tools](/developers/how-tos/depottools)
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/leak-gdi-object-in-windows/index.md b/chromium/docs/website/site/developers/how-tos/leak-gdi-object-in-windows/index.md new file mode 100644 index 00000000000..3ff3c670ded --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/leak-gdi-object-in-windows/index.md @@ -0,0 +1,114 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: leak-gdi-object-in-windows +title: Leak GDI Objects in Windows +--- + +## Tools + +* Windows Task Manager + * Add "GDI Objects" column by \[View\]-\[Select Columns...\] + * You may also want to add "Handle", "Thread" and "USER Objects" +* GDIView (works Win7 32bit and 64bit) + * <http://www.nirsoft.net/utils/gdi_handles.html> + * Note: GdiQueryTable (undocumented GDI32.DLL Win32 API) and + PEB->GetSharedGdiHandleTable don't work on Win7. + * I'm studying how to enumerate GDI handles on Win7. + +## Anti Patterns + +### DeleteObject with HICON + +**DeleteObject WIN32 API works all GDI objects except for icon** +([97559](http://code.google.com/p/chromium/issues/detail?id=97559)) + +We must use DestroyIcon. + +> In tabe_view.cc(237) + +> <http://src.chromium.org/viewvc/chrome/trunk/src/views/controls/table/table_view.cc?annotate=101329> + +> 810 HICON empty_icon = 811 +> IconUtil::CreateHICONFromSkBitmap(canvas.ExtractBitmap()); 812 +> ImageList_AddIcon(image_list, empty_icon); 813 ImageList_AddIcon(image_list, +> empty_icon); 814 DeleteObject(empty_icon); + +### Leak Screen DC aka GetDC(NULL) + +GetDC(NULL) returns newly created screen DC. So, you must release it by using +ReleaseDC. You may want to use ScopedGetDC +(<http://codesearch.google.com/#OAMlx_jo-ck/src/base/win/scoped_hdc.h>) + +**I would like to draw in bitmap** (<http://crbug.com/98523>) + +> In print_web_view_helper_win.cc(237) + +> <http://src.chromium.org/viewvc/chrome/trunk/src/chrome/renderer/print_web_view_helper_win.cc?annotate=103082> + +> 235 // Page used alpha blend, but printer doesn't support it. Rewrite the + +> 236 // metafile and flatten out the transparency. + +> 237 HDC bitmap_dc = CreateCompatibleDC(GetDC(NULL)); + +> 238 if (!bitmap_dc) + +**Easy way to know screen DPI**: + +> In chrome_content_utility_cline.cc(299) + +> <http://src.chromium.org/viewvc/chrome/trunk/src/chrome/utility/chrome_content_utility_client.cc?annotate=101911> + +> 299 int screen_dpi = GetDeviceCaps(GetDC(NULL), LOGPIXELSX); + +> 300 xform.eM11 = xform.eM22 = + +> 301 static_cast<float>(screen_dpi) / +> static_cast<float>(render_dpi); + +### Play Enhanced Metafile Record More Than Once + +Oops, some devices don't support alpha blending. We should do alpha blending by +ourselves by using bitmap DC (<http://crbug.com/98523>) + +Since, metafile records having GDI object creation command and stores into +*lpHandleTable* of second parameter of **EnhMetaFileProc**. + +> In crhome/renderer/print_web_view_helper_win.cc(40-69) + +> <http://src.chromium.org/viewvc/chrome/trunk/src/chrome/renderer/print_web_view_helper_win.cc?annotate=103082> + +> 40 // Play this command to the bitmap DC. + +> 41 PlayEnhMetaFileRecord(\*bitmap_dc, handle_table, record, num_objects); + +> ... + +> 68 // Play this command to the metafile DC. + +> 69 PlayEnhMetaFileRecord(dc, handle_table, record, num_objects); + +## References + +* GdIQueryTable + * Explanation of GDI handle table + * <http://www.fileinview.com/chms/Windows%20Graphics%20Programming%20Win32%20GDI%20and%20DirectDraw/Win32GDI/32.htm> + * Implementation of GDIQueryTable in + [ReactOS](http://www.reactos.org) + * <http://doxygen.reactos.org/d9/db3/dll_2win32_2gdi32_2misc_2misc_8c_a4086f8e85c3c92a3c6d518ef5bf8a690.html> + * WinXP/32bit returns 0x00410000. +* Process Environment Block (PEB) + * <http://en.wikipedia.org/wiki/Win32_Thread_Information_Block> + * <http://undocumented.ntinternals.net/UserMode/Undocumented%20Functions/NT%20Objects/Thread/TEB.html> + * reinterpret_cast<PEB\*>(__readfsdword(0x30))->GdiSharedHandleTable + (PEB+0x94) +* GDI Object Handle Encoding + * \[0:15\] Index + * \[16:22\] Object Type (1=DC, 4=Region, 5=Bitmap, 8=Pallete, + A=Font, 10=Brush, 21=EnhMF, 30=Pen, 50=ExtPen) + * \[23:23\] Stock Object + * \[24:31\] Unknown
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/mac-development/index.md b/chromium/docs/website/site/developers/how-tos/mac-development/index.md new file mode 100644 index 00000000000..c535ec964df --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/mac-development/index.md @@ -0,0 +1,46 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: mac-development +title: Mac Development +--- + +Resources for developers new to the Mac platform: + +* Depending on what you're touching, you may not need to modify UI + code or write Objective C at all in which case you don't really need + any of this. +* [Cocoa Programming for Mac OS + X](http://www.amazon.com/exec/obidos/ASIN/0321503619) by Aaron + Hillegass is a great starter book on Cocoa programming, working + through the examples will get you pretty far in terms of + understanding the fundamentals of Cocoa. +* [From C++ to + Objective-C](http://ktd.club.fr/programmation/fichiers/cpp-objc-en.pdf) + by Pierre Chatelier is a free online book introducing Objective C. +* [Objective-C Development in + Chrome](https://docs.google.com/a/chromium.org/document/d/1HDxOA0TD97e8MhS__7KBSAJRzKWyi0hqVTc13WSHFqc/edit?usp=sharing) + by krstnmnlsn is a collection of basic information about working + with Objective C in Chrome along with pitfalls to avoid. +* [Intro to Chrome Mac + Development](https://docs.google.com/presentation/d/1H8UOJmSJFQl3hgzDAjmObYTqHDTF98hj_ENpVydJ4OE/edit?usp=sharing) + is a shorter summary of things specific to Chrome + Mac, with links + to useful parts of the code. + +More in-depth stuff: + +* [Mac OS X + Internals](http://www.amazon.com/Mac-OS-Internals-Systems-Approach/dp/0321278542) + by Amit Singh is the defacto reference for low level OS X + programming topics. +* [Advanced Mac OS X + Programming](http://www.amazon.com/Advanced-Mac-Programming-Core-Unix/dp/0974078514) + by Mark Dalrymple and Aaron Hillegass . + +Stuff you should read on this site: + +* [Mac debugging tips](/developers/how-tos/debugging-on-os-x) - a page + with details pertaining to debugging Chrome on Mac.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/make-a-web-standards-proposal/index.md b/chromium/docs/website/site/developers/how-tos/make-a-web-standards-proposal/index.md new file mode 100644 index 00000000000..87e50cc389e --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/make-a-web-standards-proposal/index.md @@ -0,0 +1,11 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: make-a-web-standards-proposal +title: How to make a web standards proposal +--- + +**Please see <https://www.chromium.org/blink/launching-features>**
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/old-get-the-code/index.md b/chromium/docs/website/site/developers/how-tos/old-get-the-code/index.md new file mode 100644 index 00000000000..68ada5560b8 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/old-get-the-code/index.md @@ -0,0 +1,205 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: old-get-the-code +title: The old instructions for getting the code +--- + +## *This page is obsolete. Please see [Get the Code: Checkout, Build, & Run Chromium](/developers/how-tos/get-the-code) instead.* + +## Prerequisites + +Chromium supports building on Windows, Mac and Linux host systems. Linux is +required for building Android, and a Mac is required for building iOS. + +### Platform-specific requirements + +This page documents common checkout and build instructions. There are +platform-specific pages with additional information and requirements: + +* [Linux](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/linux_build_instructions.md) +* [Windows](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/windows_build_instructions.md) +* [Mac](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/mac_build_instructions.md) +* [ChromeOS](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/chromeos_build_instructions.md) +* [iOS](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/ios_build_instructions.md) +* [Cast](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/cast_build_instructions.md) +* [Android](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/android_build_instructions.md) + +### Set up your environment + +Check out and install the [depot_tools +package](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up). +This contains the custom tools necessary to check out and build. + +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): + +```none +mkdir chromium +cd chromium +``` + +## Check out the source code + +Use the "fetch" tool that came with depot_tools: + +```none +fetch chromium # [fetch --no-history chromium] +cd src # All other commands are executed from the src/ directory. +``` + +Use `--no-history` if you don't need repo history and want a faster checkout. +Expect a checkout to take at least 30 minutes on fast connections, and many +hours on slower connections. + +### Post-sync hooks + +Some platform-specific pages (linked above) may have extra instructions. In +particular, on Ubuntu Linux run: + +```none +./build/install-build-deps.sh +``` + +**Optional:** [install API keys](/developers/how-tos/api-keys) which allow your +build to use certain Google services. This isn't necessary for most development +and testing purposes. + +Run hooks to fetch everything needed for your build setup. + +```none +gclient runhooks +``` + +### Update the checkout + +To sync to newer versions of the code (not necessary the first time), run the +following in your src/ directory: + +```none +git rebase-update +gclient sync +``` + +The first command updates the primary Chromium source repository and rebases +your local development branches on top of tip-of-tree. The second command +updates all of the dependencies specified in the DEPS file. See also "More help +managing your checkout" below. + +## Setting up the build + +GN is our meta-build system. It reads build configuration from `BUILD.gn` files +and writes Ninja files to your build directory. To create a GN build directory: + +```none +gn gen out/Default +``` + +* You only have to do this once, it will regenerate automatically when + you build if the build files changed. +* You can replace `out/Default` with another name inside the `out` + directory. +* To specify build parameters for GN builds, including release + settings, see [GN build + configuration](/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://chromium.googlesource.com/chromium/src/+/HEAD/tools/gn/docs/quick_start.md). + +## Building + +Build Chromium (the "chrome" target) with Ninja using the command: + +```none +ninja -C out/Default chrome +``` + +List all GN targets by running `gn ls out/Default` from the command line. To +compile one, pass to Ninja the GN label with no preceding "//" (so for +`//ui/display:display_unittests` use `ninja -C out/Default +ui/display:display_unittests`). + +## Running + +You can run chrome with (substituting "Default" with your build directory): + +* Linux/ChromeOS: `out/Default/chrome` +* Windows: `out\Default\chrome.exe` +* Mac: `out/Default/Chromium.app/Contents/MacOS/Chromium` +* [Android](/developers/how-tos/android-build-instructions) +* [iOS](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/ios_build_instructions.md) + +### Running tests + +Run the test targets listed above in the same manner. You can specify only a +certain set of tests to run using `--gtest_filter`, e.g. + +```none +out/Default/unit_tests --gtest_filter="PushClientTest.*" +``` + +You can find out more about GoogleTest on the [GoogleTest wiki +page](https://github.com/google/googletest) + +## Quick start to submit a patch + +See [contributing code](/developers/contributing-code) for a more in-depth +guide. + +<pre><code>git checkout -b my_patch +<i>...write, compile, test...</i> +git commit -a +git cl upload +</code></pre> + +The `git cl upload` command will upload your code review to +[codereview.chromium.org](https://codereview.chromium.org/) for review. + +* Add reviewers and submit your code for review by clicking on + "Publish+Mail Comments" (you can leave the mail message empty). +* If you have try bot access, you can click "CQ dry run" which will + compile and run the tests. +* Once your patch has been reviewed and marked LGTM ("Looks Good To + Me") by an authorized reviewer, click the "Commit" checkbox below + the patch to submit to the commit queue. + +### More help managing your checkout + +* [Depot tools + manpage](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools.html) + and + [tutorial](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html). +* [Working with release + branches](/developers/how-tos/get-the-code/working-with-release-branches). +* [Working with nested + repositories](/developers/how-tos/get-the-code/working-with-nested-repos). +* [Commit or revert changes manually](/system/errors/NodeNotFound). +* [git-drover](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/git-drover.html) + for merging changes to release branches. + +## Getting help + +* Ensure your checkout has been properly updated (`git + rebase-update`). +* Check you're on a stable, unmodified branch from master (`git + map-branches`). +* Check you have no uncommitted changes (`git status`). +* Join the `#chromium` IRC channel on `irc.freenode.net` (see the [IRC + page](/developers/irc) for more). +* Join the [chromium-dev Google + Group](https://groups.google.com/a/chromium.org/forum/#!forum/chromium-dev), + and other [technical discussion + groups](/developers/technical-discussion-groups). **These are not + support channels for Chrome itself but forums for developers.** +* If you think there is an infrastructure problem that affects many + developers, file [a new bug with the label + 'Infra'](https://bugs.chromium.org/p/chromium/issues/entry?template=Build%20Infrastructure). + It will be looked at by our infrastructure team. +* If you work at Google, check out the [Googler-specific Chrome + documentation](http://wiki/Main/ChromeBuildInstructions).
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/optimizing-energy-consumption/index.md b/chromium/docs/website/site/developers/how-tos/optimizing-energy-consumption/index.md new file mode 100644 index 00000000000..3665ad35451 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/optimizing-energy-consumption/index.md @@ -0,0 +1,190 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: optimizing-energy-consumption +title: Optimizing Energy Consumption +--- + +# Background Info + +Here are two really great talks on optimizing battery life: + + Mac: [Maximizing Battery Life on OS X, WWDC + 2013](https://developer.apple.com/videos/wwdc/2013/#701) is a great + overview. + + Android, [project volta](https://www.youtube.com/watch?v=KzSKIpJepUw) talk. + (Google-internal [project + volta](https://sites.google.com/a/google.com/volta/) [tech + talk](http://go/volta-tech-talk-video) and + [slides](http://go/volta-tech-talk)) + +# Telemetry tests + +We use Telemetry benchmarks for testing and analyzing energy usage. See [code +concepts](http://www.chromium.org/developers/telemetry#TOC-Code-Concepts) for +details on benchmarks, measurements, and page sets. + +## Measurements + + On desktop, the tab_switching measurement opens a group of tabs and measures + energy after they are all loaded. All except the last tab are backgrounded. + You can use the benchmark with a blank page in the foreground to understand + how background tabs behave, or with a regular page in the foreground to + focus on the foreground tab. + + On android, our chromium.perf tests and most of our development is on chrome + shell, which does not support tabs. So we use the power test instead. It + will load each page in the set, with a 20 second pause, a scroll, and + another 20 second pause in between each load. + +## Page sets + +It might be a good idea to [record a custom page +set](http://www.chromium.org/developers/telemetry/record_a_page_set) if you’re +working on a very specific issue, for example below-the-fold animated gif. But +we generally use the below page sets for most of our testing and debugging: + +Desktop: + + [typical_25](https://code.google.com/p/chromium/codesearch#chromium/src/tools/perf/page_sets/typical_25.py) + - This is a set of 25 web pages designed to represent general web browsing. + + [top_10](https://code.google.com/p/chromium/codesearch#chromium/src/tools/perf/page_sets/top_10.py) + - The Alexa top 10 sites. + + [top_10_mobile](https://code.google.com/p/chromium/codesearch#chromium/src/tools/perf/page_sets/top_10_mobile.py) + - Mobile versions of the Alexa top 10 + + [five_blank_pages](https://code.google.com/p/chromium/codesearch#chromium/src/tools/perf/page_sets/five_blank_pages.py) + - For debugging background noise that occurs regardless of which page you’re + on. + + [tough_energy_cases](https://code.google.com/p/chromium/codesearch#chromium/src/tools/perf/page_sets/tough_energy_cases.py) + - Very complex or energy-heavy pages. + +Android: + + [typical_10_mobile](https://code.google.com/p/chromium/codesearch#chromium/src/tools/perf/page_sets/typical_10_mobile.py) + - 10 typical mobile pages. + +## Metrics + +Each platform has different techniques for measuring energy usage, and often +there are multiple techniques (hardware devices, software estimation). Below are +the names of the metrics, the platforms they are available on, and how they are +gathered. + + energy_consumption_mwh - This is the energy consumption in milliwatt hours. + In general, this is a software estimation. You can see all the methods we + have for measuring energy consumption in the + [power_monitor](https://code.google.com/p/chromium/codesearch#chromium/src/tools/telemetry/telemetry/core/platform/power_monitor/) + directory in telemetry, but here is a quick run-down of how the bots on the + waterfall calculate this: + + Android uses + [dumpsys](https://code.google.com/p/chromium/codesearch#chromium/src/tools/telemetry/telemetry/core/platform/power_monitor/android_dumpsys_power_monitor.py&q=dumpsys&sq=package:chromium&l=12) + software estimation on L release and above. + + Except Nexus 10, which uses the built in + [ds2784](https://code.google.com/p/chromium/codesearch#chromium/src/tools/telemetry/telemetry/core/platform/power_monitor/android_ds2784_power_monitor.py) + fuel gauge on L release and above. + + Mac OS uses + [powermetrics](https://code.google.com/p/chromium/codesearch#chromium/src/tools/telemetry/telemetry/core/platform/power_monitor/powermetrics_power_monitor.py) + on 10.9 and above ([more details + here](https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man1/powermetrics.1.html)). + + Windows and Linux use + [MSR](https://code.google.com/p/chromium/codesearch#chromium/src/tools/telemetry/telemetry/core/platform/power_monitor/msr_power_monitor.py) + on intel processors with sandybridge or later. + + application_energy_consumption_mwh - This is derived by measuring + energy_consumption_mwh during a quiescent period before running chrome, then + subtracting that from the energy_consumption_mwh used during the test run. + The goal is to find the amount of energy used by chrome and ignore the + steady state energy used by the OS and background processes. However, if + there is too much noise this number can be off. + + idle_wakeups_total - This is the total number of idle wakeups across all + processes. It’s currently only available on Mac through powermetrics, but we + are working on Linux (bug [422170](http://crbug.com/422170)) and Android + (bug [422967](http://crbug.com/422967)). + This number is important because it’s a proxy for energy consumption, and it + figures heavily in the [Energy Impact](http://support.apple.com/kb/HT5873) + score in OS X. See the [Maximizing Battery Life on OS + X](https://developer.apple.com/videos/wwdc/2013/#701) talk for more info + about how reducing idle wakeups improves battery life. + + board_temperature - Temperature in degrees celsius. Available through MSR on + Windows/Linux (intel sandybridge and later). Also available on Android + devices running L release+. + +# Developing/Testing Locally + + Choose or record a telemetry page set that matches the use case you want to + test. + + Run the correct telemetry benchmark for your platform (tab_switching for + desktop, acceptance test for android). Use the --profiler=trace and + --pageset-repeat=1 flags; this will output a trace and only repeat the test + once. Example: + tools/perf/run_benchmark tab_switching.five_blank_pages \\ + --browser=release --profiler=trace --pageset-repeat=1 + + Telemetry outputs a trace file. You’ll see the file name in stdout. Open it + up in + [about:tracing](http://www.chromium.org/developers/how-tos/trace-event-profiling-tool). + Look for places where: + + Chrome is doing unexpected work. For example, a timer that wakes every + 1s on a blank page should not be needed. Removing unneeded timers is a + great way to reduce idle wakups. + + Work is happening too frequently and could be coalesced. Could two IPCs + be grouped into one? Doing the same amount of work with fewer IPCs + reduces idle wakeups. + +Comparing traces between two builds that have different energy usage can also be +helpful. You can use the --browser argument in telemetry to easily run the test +on your stable, beta, or dev channel and compare that with a local build +(--browser=release or --browser=debug). + +# Verifying Results on Perf Bots + +Energy measurements are very sensitive to noise. Sometimes you make a change +locally that drives down idle wakeups and you believe will reduce energy +consumption, but the energy numbers you get are just noise. Sometimes you don’t +have access to the OS or hardware you want to test. The chromium.perf and +tryserver.chromium.perf bots can help! + +Perf Try Jobs + +You can run tab_switching tests on the perf trybots on the +[tryserver.chromium.perf +waterfall](http://build.chromium.org/p/tryserver.chromium.perf/waterfall). Here +is the [documentation for perf try +jobs](http://www.chromium.org/developers/performance-try-bots). If idle wakeups +numbers are available, they will be in the “memory” tab of the results html +page. + +chromium.perf waterfall + +Several energy tests are running on the chromium.perf waterfall: + + [tab_switching.five_blank_pages](https://chromeperf.appspot.com/report?masters=ChromiumPerf&bots=chromium-rel-mac9%2Cchromium-rel-win7-dual%2Cchromium-rel-win7-gpu-ati%2Cchromium-rel-win7-gpu-intel%2Cchromium-rel-win7-gpu-nvidia%2Cchromium-rel-win7-single%2Cchromium-rel-win7-x64-dual%2Cchromium-rel-win8-dual%2Cchromium-rel-xp-dual%2Clinux-oilpan-release%2Clinux-release&tests=tab_switching.five_blank_pages%2Fenergy_consumption_mwh&rev=299488&checked=energy_consumption_mwh%2Cblank_page.html_ref%2Cref%2Cenergy_consumption_mwh%2Cblank_page.html_ref%2Cref) + + [tab_switching.top_10](https://chromeperf.appspot.com/report?masters=ChromiumPerf&bots=chromium-rel-mac9%2Cchromium-rel-win7-dual%2Cchromium-rel-win7-gpu-ati%2Cchromium-rel-win7-gpu-intel%2Cchromium-rel-win7-gpu-nvidia%2Cchromium-rel-win7-single%2Cchromium-rel-win7-x64-dual%2Cchromium-rel-win8-dual%2Cchromium-rel-xp-dual%2Clinux-oilpan-release%2Clinux-release&tests=tab_switching.top_10%2Fenergy_consumption_mwh&rev=299488&checked=energy_consumption_mwh%2Cref) + + [tab_switching.typical_25](https://chromeperf.appspot.com/report?masters=ChromiumPerf&bots=chromium-rel-mac9%2Cchromium-rel-win7-dual%2Cchromium-rel-win7-gpu-ati%2Cchromium-rel-win7-gpu-intel%2Cchromium-rel-win7-gpu-nvidia%2Cchromium-rel-win7-single%2Cchromium-rel-win7-x64-dual%2Cchromium-rel-win8-dual%2Cchromium-rel-xp-dual%2Clinux-oilpan-release%2Clinux-release&tests=tab_switching.typical_25%2Fenergy_consumption_mwh&rev=299488&checked=energy_consumption_mwh%2Cref%2Cenergy_consumption_mwh%2Cref) + + [tab_switching.tough_energy_cases](https://chromeperf.appspot.com/report?masters=ChromiumPerf&bots=chromium-rel-mac9%2Cchromium-rel-win7-dual%2Cchromium-rel-win7-gpu-ati%2Cchromium-rel-win7-gpu-intel%2Cchromium-rel-win7-gpu-nvidia%2Cchromium-rel-win7-single%2Cchromium-rel-win7-x64-dual%2Cchromium-rel-win8-dual%2Cchromium-rel-xp-dual%2Clinux-oilpan-release%2Clinux-release&tests=tab_switching.tough_energy_cases%2Fenergy_consumption_mwh&rev=299488&checked=energy_consumption_mwh%2Cref%2Cenergy_consumption_mwh%2Cref) + + [power.android_acceptance](https://chromeperf.appspot.com/report?masters=ChromiumPerf&bots=android-motoe%2Candroid-nexus10%2Candroid-nexus4%2Candroid-nexus5%2Candroid-nexus7v2&tests=power.android_acceptance%2Fenergy_consumption_mwh&checked=core) + +You can look at the effects of a submitted change. After [bug +423394](http://crbug.com/423394) is fixed, you will be able to get traces for +some of the runs as well.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/order-file-development-guide/index.md b/chromium/docs/website/site/developers/how-tos/order-file-development-guide/index.md new file mode 100644 index 00000000000..a40b57bb34f --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/order-file-development-guide/index.md @@ -0,0 +1,86 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: order-file-development-guide +title: Order file development guide +--- + +1. Build chromeos-chrome with profile instrumentation + +```none +export USE="$USE -reorder" +export EXTRA_BUILD_ARGS="order_profiling=1 order_text_section=''" +``` + +2. Add `--no-sandbox` to chrome start arguments (in the buttom of +/sbin/session_manager_setup.sh). + +3. As you prepare, you may have run chrome collecting logs (which you don't want +yet). Remove them and reboot. + +```none +rm /var/log/chrome/cyglog.*; sudo reboot +``` + +4. After you browse several sites (google.com, maps.google.com, youtube.com), +copy logs to your host machine to some directory. + +5. Sanitize logs. + +```none +head -1 cyglog.* +``` + +If some log does not contain header (containing /opt/google/chrome/chrome), +remove it. This log left from before you removed all cyglogs last boot. + +6. Merge logs to a single file. This may take some minutes to run. + +```none +$CHROME_SRC/tools/cygprofile/mergetraces.py `ls cyglog.* -Sr` > merged_cyglog +``` + +7. Symbolize the log using your instrumented image (from p.1). + +```none +$CHROME_SRC/tools/cygprofile/symbolize.py -t orderfile merged_cyglog /build/x86-alex/opt/google/chrome/chrome > unpatched_orderfile +``` + +8. Rebuild chromeos-chrome with new orderfile. + +```none +export USE="$USE -reorder" +export EXTRA_BUILD_ARGS="order_profiling=0 order_text_section='/home/$USER/trunk/src/scripts/cyglog/unpatched_orderfile'" +``` + +9. Patch the orderfile to + +```none +$CHROME_SRC/tools/cygprofile/patch_orderfile.py unpatched_orderfile /build/x86-alex/opt/google/chrome/chrome > orderfile +``` + +9. If you want to visually check that the resulting image is reordered, use + +```none +nm -Sn /build/x86-alex/opt/google/chrome/chrome | less +``` + +And note, that ChromeMain symbol is not at the beginning of symbols. + +In the image built without reordering, ChromeMain immediately follows main and +is about 10th symbol in the image. + +10. Update the repository containing orderfiles. + +The repo, containing orderfiles is here: +http://git.chromium.org/gitweb/?p=chromiumos/profile/chromium.git + +Intructions on how to update the repo: +http://www.chromium.org/chromium-os/how-tos-and-troubleshooting/git-server-side-information + +11. Update +src/third_party/chromiumos-overlay/chromeos-base/chromeos-chrome/chromeos-chrome-9999.ebuild +to grab the latest version of the orderfile (that you updated in p.10).
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/retrieving-crash-reports-on-ios/index.md b/chromium/docs/website/site/developers/how-tos/retrieving-crash-reports-on-ios/index.md new file mode 100644 index 00000000000..72fd97566a4 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/retrieving-crash-reports-on-ios/index.md @@ -0,0 +1,88 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: retrieving-crash-reports-on-ios +title: Retrieving Crash Reports on iOS +--- + +## [TOC] + +There are multiple ways to retrieve crash reports from an iOS device. They are +listed below from (roughly) easiest to hardest. Please use whichever method +works best for you. + +## Syncing with iTunes + +This method involves syncing your device with iTunes. After syncing, crash +reports will be copied to a specific location on your hard drive. This method is +also documented at +<https://developer.apple.com/library/ios/#qa/qa1747/_index.html>. + +1. Sync your device with iTunes on your desktop. +2. After syncing, look for crash logs in the correct directory. See + below for a list of directories for each operating system. +3. In this directory, look for files starting with "Chrome_". + +(NOTE FOR MAC USERS: ~/Library is hidden by default on Mac OS X. To easily get +this folder, open the Finder application, then hold the "option" key while +clicking on the "Go" menu. You should see a menu item for "Library." Click on +that, then continue navigating to Logs, CrashReporter, etc. + +<table> +<tr> + +Operating System + +Location + +</tr> +<tr> + +<td>Mac OS X:</td> + +<td>~/Library/Logs/CrashReporter/MobileDevice/<DEVICE_NAME></td> + +</tr> +<tr> + +<td>Windows XP</td> + +<td>C:\\Documents and Settings\\<USERNAME>\\Application Data\\Apple Computer\\Logs\\CrashReporter\\MobileDevice\\<DEVICE_NAME></td> + +</tr> +<tr> + +<td>Windows Vista or 7</td> + +<td>C:\\Users\\<USERNAME>\\AppData\\Roaming\\Apple Computer\\Logs\\CrashReporter\\MobileDevice\\<DEVICE_NAME></td> + +</tr> +</table> + +## Emailing from a device + +1. Start by opening up the Settings app. +2. Navigate to General -> About -> Diagnostics & Usage -> + Diagnostic & Usage Data. +3. Select a Chrome crash from the list. This will start with “Chrome_” + and contain the timestamp of the crash. +4. Tap on the crash and you will see a text field with a crash log. + Long press to Select All and then Copy the crash text. +5. Paste it into something you can get off of your device (for example, + an email to yourself). + +## Using the Xcode Organizer + +NOTE: This method will only work for iOS developers. If you are not a developer, +you will not have Xcode installed on your machine. + +1. Launch Xcode on your desktop machine. +2. Open the Xcode Organizer window. (Window menu -> Organizer, or + Cmd-Shift-2.) +3. Find your device in the left sidebar, then select “device logs”. +4. Choose a Chrome crash (or multiple crashes) and select “Export” at + the bottom of the Organizer window. This will copy the crash reports + to your hard drive.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/run-chromium-with-flags/index.md b/chromium/docs/website/site/developers/how-tos/run-chromium-with-flags/index.md new file mode 100644 index 00000000000..91eed9a74ad --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/run-chromium-with-flags/index.md @@ -0,0 +1,162 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: run-chromium-with-flags +title: Run Chromium with flags +--- + +[TOC] + +There are command line flags (or "switches") that Chromium (and Chrome) accept +in order to enable particular features or modify otherwise default +functionality. + +Current switches may be found at +<http://peter.sh/examples/?/chromium-switches.html> + +It is important to note that some switches are intended for development and +temporary cases. They may break, change, or be removed in the future without +notice. IT admins looking to manage Chrome for their organization should +instead use [enterprise policies](http://chromeenterprise.google/polices). + +Note that if you look at `chrome://flags` to see if the command line option is +active, the state might not be accurately reflected. Check `chrome://version` +for the complete command line used in the current instance. + +## Windows + +1. Exit any running-instance of Chrome. +2. Right click on your "Chrome" shortcut. +3. Choose properties. +4. At the end of your "Target:" line add the command line flags. For + example: + * `--disable-gpu-vsync` +5. With that example flag, it should look like below (replacing + "--disable-gpu-vsync" with any other command line flags you want to + use): + `chrome.exe --disable-gpu-vsync` +6. Launch Chrome like normal with the shortcut. + +## macOS + +1. Quit any running instance of Chrome. +2. Run your favorite Terminal application. +3. In the terminal, run commands like below (replacing + "--remote-debugging-port=9222" with any other command line flags you + want to use): + + ```none + /Applications/Chromium.app/Contents/MacOS/Chromium --remote-debugging-port=9222 + # For Google Chrome you'll need to escape spaces like so: + /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 + ``` + +## Linux + +1. Quit any running instance of Chrome. +2. Run your favorite terminal emulator. +3. In the terminal, run commands like below (replacing + "--remote-debugging-port=9222" with any other command line flags you + want to use): + + ```none + chromium-browser --remote-debugging-port=9222 + google-chrome --foo --bar=2 + ``` + +## iOS + +If you are building Chromium from the source, you can run it with flags by +adding them in the Experimental Settings. + +1. Open the Settings app +2. Go to Chromium/Experimental Settings +3. Add your flags in the "Extra flags (one per line)". Don't forget to + switch on the "Append Extra Flags" setting. + +It is not possible to run with flags the official releases (Google Chrome from +App Store or Testflight). + +## V8 Flags + +V8 can take a number of flags as well, via Chrome's `js-flags` flag. For +example, this traces V8 optimizations: + +```none +chrome.exe --js-flags="--trace-opt --trace-deopt --trace-bailout" +``` + +To get a listing of all possible V8 flags: + +```none +chrome.exe --js-flags="--help" +``` + +Browse [the V8 wiki](http://code.google.com/p/v8/w/list) for more flags for V8. + +## Android + +Visit '`about:version`' to review the flags that are effective in the app. + +If you are running on a rooted device or using a debug build of Chromium, then +you can set flags like so: + +```none +out/Default/bin/chrome_public_apk argv # Show existing flags. +out/Default/bin/content_shell_apk argv --args='--foo --bar' # Set new flags +``` + +You can also install, set flags, and launch with a single command: + +```none +out/Default/bin/chrome_public_apk run --args='--foo --bar' +out/Default/bin/content_shell_apk run # Clears any existing flags +``` + +For production build on a non-rooted device, you need to enable "Enable command +line on non-rooted devices" in chrome://flags, then set command line in +/data/local/tmp/chrome-command-line. When doing that, mind that the first +command line item should be a "_" (underscore) followed by the ones you actually +need. Finally, manually restart Chrome ("Relaunch" from chrome://flags page +might no be enough to trigger reading this file). See +<https://crbug.com/784947>. + +### ContentShell on Android + +There's an alternative method for setting flags with ContentShell that doesn't +require building yourself: + +1. Download a [LKGR build of + Android](https://download-chromium.appspot.com/?platform=Android&type=continuous). +2. This will include both ChromePublic.apk and ContentShell.apk +3. Install ContentShell APK to your device. +4. Run this magic incantation + +```none +adb shell am start \ + -a android.intent.action.VIEW \ + -n org.chromium.content_shell_apk/.ContentShellActivity \ + --es activeUrl "http://chromium.org" \ + --esa commandLineArgs --show-paint-rects,--show-property-changed-rects +``` + +This will launch contentshell with the supplied flags. You can apply whatever +commandLineArgs you want in that syntax. + +### Android WebView + +This is documented [in the chromium +tree](https://chromium.googlesource.com/chromium/src/+/HEAD/android_webview/docs/commandline-flags.md). + +## Chrome OS + +1. Put the device into [dev mode, disable rootfs verification, and + bring up a command + prompt](/chromium-os/poking-around-your-chrome-os-device). +2. Modify /etc/chrome_dev.conf (read the comments in the file for more + details). +3. Restart the UI via: + `sudo restart ui` diff --git a/chromium/docs/website/site/developers/how-tos/run-mojo-shell/index.md b/chromium/docs/website/site/developers/how-tos/run-mojo-shell/index.md new file mode 100644 index 00000000000..ae14142c847 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/run-mojo-shell/index.md @@ -0,0 +1,11 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: run-mojo-shell +title: Run Mojo Shell +--- + +## These instructions now live here: <https://github.com/domokit/mojo/blob/master/README.md>
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/scopedlogger/index.md b/chromium/docs/website/site/developers/how-tos/scopedlogger/index.md new file mode 100644 index 00000000000..d47cedb1bf9 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/scopedlogger/index.md @@ -0,0 +1,11 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: scopedlogger +title: ScopedLogger +--- + +## This page moved to [third_party/blink/renderer/platform/wtf/ScopedLogger.md](https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/blink/renderer/platform/wtf/ScopedLogger.md).
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/submitting-a-performance-bug/Screenshot from 2015-03-10 14_52_09.png.sha1 b/chromium/docs/website/site/developers/how-tos/submitting-a-performance-bug/Screenshot from 2015-03-10 14_52_09.png.sha1 new file mode 100644 index 00000000000..d34605ce81a --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/submitting-a-performance-bug/Screenshot from 2015-03-10 14_52_09.png.sha1 @@ -0,0 +1 @@ +99c28ed2fd8fb02940d00bd75ecd30724c879bcd
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/submitting-a-performance-bug/Screenshot from 2015-03-10 14_52_29.png.sha1 b/chromium/docs/website/site/developers/how-tos/submitting-a-performance-bug/Screenshot from 2015-03-10 14_52_29.png.sha1 new file mode 100644 index 00000000000..40d8426915c --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/submitting-a-performance-bug/Screenshot from 2015-03-10 14_52_29.png.sha1 @@ -0,0 +1 @@ +103d270f392c7fbc7aec7c4e276b981e257f48f1
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/submitting-a-performance-bug/Screenshot from 2015-03-10 14_54_06.png.sha1 b/chromium/docs/website/site/developers/how-tos/submitting-a-performance-bug/Screenshot from 2015-03-10 14_54_06.png.sha1 new file mode 100644 index 00000000000..469a5e947d7 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/submitting-a-performance-bug/Screenshot from 2015-03-10 14_54_06.png.sha1 @@ -0,0 +1 @@ +e1c341726e0818ad5c87152bceed241101c58103
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/submitting-a-performance-bug/Screenshot from 2015-03-10 14_55_28.png.sha1 b/chromium/docs/website/site/developers/how-tos/submitting-a-performance-bug/Screenshot from 2015-03-10 14_55_28.png.sha1 new file mode 100644 index 00000000000..0e531576586 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/submitting-a-performance-bug/Screenshot from 2015-03-10 14_55_28.png.sha1 @@ -0,0 +1 @@ +bf8ab4082db32504ad1b49bae48bf56af7aac4ca
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/submitting-a-performance-bug/Screenshot from 2015-03-24 11_16_39.png.sha1 b/chromium/docs/website/site/developers/how-tos/submitting-a-performance-bug/Screenshot from 2015-03-24 11_16_39.png.sha1 new file mode 100644 index 00000000000..683a3d0203c --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/submitting-a-performance-bug/Screenshot from 2015-03-24 11_16_39.png.sha1 @@ -0,0 +1 @@ +36a2e6086990b1ff70059f064d7e53f9d5c2dd11
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/submitting-a-performance-bug/Screenshot from 2019-11-27 23-09-36.png.sha1 b/chromium/docs/website/site/developers/how-tos/submitting-a-performance-bug/Screenshot from 2019-11-27 23-09-36.png.sha1 new file mode 100644 index 00000000000..eedb534e79b --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/submitting-a-performance-bug/Screenshot from 2019-11-27 23-09-36.png.sha1 @@ -0,0 +1 @@ +919c42db050099e580c0a983216d83e00c7b4df7
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/submitting-a-performance-bug/index.md b/chromium/docs/website/site/developers/how-tos/submitting-a-performance-bug/index.md new file mode 100644 index 00000000000..fb6b3af8950 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/submitting-a-performance-bug/index.md @@ -0,0 +1,67 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: submitting-a-performance-bug +title: Submitting a Performance Bug +--- + +For more advanced use cases, click for [advanced +instructions](/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs). + +**Note: Uploading a trace to Google may share personal information such as the +titles and URLs of open tabs.** + +**Android:** + +1. Connect the Android device to a host PC + +2. Navigate the host PC to **chrome://inspect?tracing** + +3. Find the instance of Chrome on your device you'd like to trace and click on +the "trace" link. + + + +4. Follow the **Desktop** instructions starting from step 2. + +**Desktop:** + +1. In the address bar of a new tab, type **chrome://tracing** + +2. In the upper left, press the **Record** button. + + + +3. In the dialog that opens, select **Manually select settings** + + + +4. Under **Record Categories**, click **All**. + +5. In the lower right, click **Record**. + +6. Complete whatever action reproduces the performance issue: opening a new tab, +navigating to a certain website, scrolling a page, etc. If possible, the +duration of your recording should be about 10 seconds or less. + +7. Return to the tracing tab and press **Stop**. + + + +8. When the recording has been imported, click **Save** at the top of the +screen, then choose where to save it on your computer. + + + +9. File a [new performance +bug](https://code.google.com/p/chromium/issues/entry?summary=Performance+issue:&comment=Chrome+Version+++++++%3A%0AOperating+System+and+Version%3A+%0AURLs+(if+applicable)+%3A%0A%0ADescription+of+performance+problem:%0A%0A%0A%0ARemember%20to%20attach%20your%20trace%20file%20to%20this%20bug!&labels=Type-Bug,Pri-2,Hotlist-Slow,Performance&). +Make sure to add a descriptive title, your Chrome version, your operating system +and version, URLs (if applicable), and details about your issue. + +10. Click **Attach a file** and locate the trace file you saved in step 7. There +is a 10MB limit, so you may need to compress the file first. + +11. In the bottom left, click **Submit Issue**. Thank you! diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/3dtracing2.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/3dtracing2.png.sha1 new file mode 100644 index 00000000000..21555a20483 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/3dtracing2.png.sha1 @@ -0,0 +1 @@ +0c8f370fc01b98ef8574b38d6664f408d07b67f6
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/Screenshot-about_gpu.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/Screenshot-about_gpu.png.sha1 new file mode 100644 index 00000000000..f229a3aac50 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/Screenshot-about_gpu.png.sha1 @@ -0,0 +1 @@ +da4486b7c8ef2af915942dd886a22f60722a5dac
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/abouttracing2.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/abouttracing2.png.sha1 new file mode 100644 index 00000000000..8a8b3456b7c --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/abouttracing2.png.sha1 @@ -0,0 +1 @@ +8099bbc8add3709b79d4f2e5e2455a96b9600668
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/abouttracingfinal.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/abouttracingfinal.png.sha1 new file mode 100644 index 00000000000..7e8f2b5bc05 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/abouttracingfinal.png.sha1 @@ -0,0 +1 @@ +07fdfe89c591142835cae1d644d13bf9df5f6edc
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/anatomy-of-jank/index.md b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/anatomy-of-jank/index.md new file mode 100644 index 00000000000..9a05487ba53 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/anatomy-of-jank/index.md @@ -0,0 +1,273 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +- - /developers/how-tos/trace-event-profiling-tool + - The Trace Event Profiling Tool (about:tracing) +page_name: anatomy-of-jank +title: Anatomy of Jank +--- + +author: wiltzius@ + +## Intro + +Rendering performance is a huge topic of great interest to the Chrome project +and web developers. As the web platform is essentially an application +development framework, ensuring it has the capability to handle input and put +new pixels on the screen at a speed that keeps up with the display’s refresh +rate is critical. + +“Performance” is an oft-cited problem area for web developers. We spend a lot of +time investigating and (hopefully) improving performance of the platform, often +guided by specific bad examples. This is the pursuit and elimination of jank. + +But what does jank mean? What are people complaining about when they say a web +page “feels slow”? This document attempts to categorize the various symptoms +that all get put under the “jank” category, for the purposes of accurate +identification and precise discussion. + +To understand the descriptions of potential causes of jank, it's important to +understand roughly how rendering works. See [The Rendering Critical +Path](/developers/the-rendering-critical-path) for a primer; these two documents +should be read together. + +Finally, a note on the videos of examples -- video playback performance can +tragically mask subtle performance problems as it frequently isn't rendered at +60Hz. The examples here should be obvious enough that the problem is still +visible, but the originals of these videos are attached to the page, which you +can download for slightly more accurate recordings. + +## Symptom Taxonomy + +[TOC] + +### Incomplete content + +##### Checkerboarding + +#### YouTube Video + +<pre><code><i>Brief:</i> Parts of the page not showing up, particularly during a fast scroll or animation, and instead patches of either a gray checkerboard pattern or the background of the page showing through. +</code></pre> + +Some background, for the curious. The checkerboarding problem is a very +fundamental one for a document viewer: do you preserve responsiveness to user +input or do you only show fully correct content? Chrome has developed a lot of +(expensive) machinery to combat this problem, preferencing responsiveness. +Checkerboarding occurs mainly during fast scrolling, when the page cannot be +rasterized quickly enough to put up a new viewport’s worth of content every +frame. When this happens Chrome will continue to scroll in an attempt to +preserve the physical metaphor of page under the user’s finger... but in place +of the missing content there will just be a blank space. On desktop platforms +Chrome will draw a greyish checkerboard pattern; on Android (where this is more +common) it draws the background color of the page. + +To try to avoid having to checkerboard Chrome will pre-rasterize content around +the viewport and keep it as bitmaps in memory. This policy trades CPU and memory +resource consumption for a greater likelihood that the page content will be +ready if/when the user starts scrolling. It’s essentially a giant buffer to +guard against how slow software rasterization can be. + +This approach has several limitations. For one, it’s a bit of a resource hog. It +also isn’t under the control of the app developer at all, so if for instance +they would prefer to jank (not produce a frame) instead of checkerboard when the +scroll hits an unrasterized region of the page, they’re out of luck. It’s also +ineffective if parts of the page that are pre-rasterized get invalidated by +JavaScript -- now that pre-rasterized content is stale. It’s still useful to +have around, since at least Chrome can display the pre-rasterized content until +the new content is ready (this is the whole pending tree vs. active tree +architecture; see the compositing design doc for an explanation), but it isn’t a +replacement for fast rasterization. This is one of the (many) reasons motivating +the move to GL-based rasterization (Ganesh), and when using Ganesh Chrome +pre-paints only a very small buffer around the screen. + +> ###### Checkerboarding special case: low resolution tiles + +> #### YouTube Video + +> `*Brief:* Parts of the page displaying, but displaying at low resolution +> instead of high resolution.` + +> This is a “feature” of impl-side painting, designed mainly to gracefully +> handle pinch/zoom scenarios. Chrome will quickly rasterize large sections of +> the pending tree (i.e. the content that’s queued up to go on screen) at low +> resolution first, with the aim of at least showing something. The cause here +> is identical to the cause of checkerboarding; this is essentially an +> intermediate state between having the content fully rasterized and not +> rasterized at all (checkerboard). + +> ###### Checkerboarding common cause: URL bar jank + +> `*Brief:* Full-screen invalidations caused by the URL bar’s showing / hiding +> on scroll.` + +> There are times when Chrome doesn’t have a chance to rasterize enough content +> before a scroll gets to a region of the page (e.g. on very long pages), but +> for the most part impl-side painting handles static content well. As mentioned +> in the checkerboarding section, however, it copes poorly when the page is +> frequently invalidated by JavaScript. The resize event fired when the URL bar +> appears and disappears (per the current Chrome for Android omnibox UX) is a +> tragically common, totally unnecessary cause of invalidation on many mobile +> websites. Chrome itself has to do a re-layout to account for the additional +> pixels that just got added or subtracted from the total document height, but +> this is an optimized layout pass that shouldn’t (theoretically) cause +> full-document invalidations. Unfortunately many pages listen for the resize +> event, assume getting it means the page has actually changed dimensions +> dramatically as in the case of e.g. a rotation, and then modify their entire +> document’s style in response. This typically ends up looking exactly the same, +> but invalides everything as a result. + +> ##### *Partial content during network load* + +> `*Brief:* When loading a web page from the network Chrome will attempt to +> render the page as quickly as possible, even if it doesn’t have all the +> required resources yet. This is a long-standing feature of the platform to let +> you read content as quickly as possible, and not technically jank, but is +> included for completeness.` + +> Unfortunately, it also looks significantly less polished than the style of +> many native applications, which show nothing (or a splash screen) until a +> basic UI shell is ready, and fill that shell in with data atomically when the +> data is ready. It’s possible to emulate this behavior on the web platform, and +> it looks much more polished to do so, but that’s unfortunately not a very +> common practice at this point. + +### Framerate + +##### Low sustained framerate during any kind of animation (“janky animations”) + +#### YouTube Video + +<pre><code><i>Brief:</i> animation with a mostly-steady framerate that’s below 60Hz. +</code></pre> + +There’s typically a consistent bottleneck in the system when this is the case, +and about:tracing is designed for diagnosing exactly this case. If encountered, +a standard trace (no need for Frame Viewer) of the low-framerate animation +should show what operations are the long pole for the animation. + +It’s worth noting that there are two types of animation: those handled entirely +by the compositor thread (so-called “accelerated” animations) and those that +need to synchronously call into Blink or v8. The only type of accelerated +animations are CSS animations (and CSS transitions and Web Animation) on +opacity, transform, and certain CSS filters; plus scrolling and pinch/zoom. +Everything else goes through Blink. Accelerated animations will never be +bottlenecked on anything in the RendererMain thread, but non-accelerated +animations can be. + +##### Delayed beginning to any animation + +#### YouTube Video + +<pre><code><i>Brief:</i> a discernible pause between when an animation is meant to begin (e.g. in response to a finger tap) and when it actually begins. This is distinct from low framerate since sometimes the animation itself is fine, there’s just a pause before it starts. +</code></pre> + +This is commonly caused by accelerated animations that are set up but require +rasterization before beginning. E.g. creating a new layer and setting a CSS +animation on its transform -- the animation will not start until the new layer +is done being painted. The timeline delay here is designed to prevent animations +beginning immediately only to drop a number of frames. The result is typically a +much smoother-looking interaction overall, but it can be surprising. + +##### Low framerate during to swipe input (throughput) + +<pre><code><i>Brief:</i> special case of low-framerate animation, specifically when the animation is moving something in response to a touch movement. All touch-event-driven animations are non-accelerated animations. +</code></pre> + +Unlike the delay at the beginning of an animation, which can be stretched out +tens of milliseconds without the user really noticing, the only acceptable frame +time for a running animation is the vsync interval (e.g. 16ms). Touch input can +only be programmatically handled by JavaScript on the RendererMain thread, which +means that all visual touch-input-based effects are technically non-accelerated +animations. Note that they can still avoid painting by using an accelerated +animation property, but they’ll subject to jank from all other activity on the +main thread because the JavaScript input events can be blocked. + +##### Isolated long pauses (“jank”) during JS-driven animations (incl touch) + +<pre><code><i>Brief:</i> Single long pauses, rather than a consistent low framerate, during animations +</code></pre> + +Sometimes an animation is mostly fine, but stutters at one point. This is often +harder to isolate, but about:tracing and the Dev Tools timeline are invaluable +for figuring out what went wrong. Special cases of this include the delay at the +beginning of animations. All non-accelerated animations are subject to jank of +this type from any other activity on the Blink main thread (e.g. JavaScript +timers executing). + +### Latency + +Long input latency (rather than low framerate) + +<pre><code><i>Brief:</i> Most jank is related to interruptions in frame production, but latency represents another class of problem manifesting as longer delays between input events entering the system and corresponding new frames being output. It’s possible to have a good / high framerate but bad / long latency +</code></pre> + +Some examples of high latency are covered in the framerate examples, for +instance delays at the beginning of an animation that’s kicked off in response +to input. Generally if the entire pipeline takes long enough that it doesn’t fit +into frame budget, we categorize it as a framerate rather than a latency issue. +However, there are some edge cases where latency can be increased by seemingly +unrelated issues. + +##### High scrolling latency or delays beginning scrolling when the document has touch event handlers + +#### YouTube Video + +<pre><code><i>Brief:</i> Calling preventDefault on a touch move event is spec’d to prevent scrolling from happening. Chrome therefore tries to give JavaScript a chance to run any registered touch move event handlers before scrolling the page. If JavaScript takes a while to respond, however, it can increase input latency during the scroll. +</code></pre> + +There’s a delicate balance between honoring the contract with touch event +handlers the page has registered and staying responsive. In particular, becuase +JavaScript touch event handlers are stuck on the main thread with everything +else, completely unrelated activity such as XHR parsing or style recalculation +or JavaScript timers that run on the main thread will all block touch event +handlers from running (none of these tasks currently yield, and as of this +writing Blink’s entire event loop is a FIFO queue with no prioritization, +although that’s changing with the advent of the Blink scheduler). The result is +that if style recalculation runs for 100ms right when the user is dragging the +page around, the scroll won’t move for 100ms until style recalc is finished, the +touch event gets run and preventDefault doesn’t get called during it. + +Note that browser behavior here is wildly under-specified. Chrome’s behavior has +evolved over time, and changed significantly recently with the advent of +[asynchronous touch move +processing](http://updates.html5rocks.com/2014/05/A-More-Compatible-Smoother-Touch). +One of the more egregious behavior hacks here is that Chrome typically gave +touch events a ~200ms deadline to run, and if the event wasn’t processed by then +it would get dropped and the page would scroll anyway. This was designed to +preserve basic responsiveness even in the face of adversarial content. + +##### Scroll-linked effects out of sync + +<pre><code><i>Brief:</i> visual effects linked to the scroll position can become 1-2 frames out of sync from the actual scroll +</code></pre> + +This is somewhat complicated, but boils down to two different modes of operation +in Chrome’s multi-stage rendering pipeline. In low-latency mode each stage of +the pipeline will complete fast enough that all of the stages complete within +16ms. If any of the stages run long, Chrome will fall out of low latency mode +into high latency mode. At that point there will be an extra frame of latency in +the entire rendering pipeline, which effectively increases frame budget by +allowing thread parallelism but at the cost of latency. + +Note that technically there is currently a low/high latency mode for both the +main thread > compositor thread step and the compositor thread > browser +UI thread step. The problem described here is specific to the main thread > +compositor thread step. + +The synchronization issue is that scrolling is a compositor-thread operation +whereas the scroll-linked effects are necessarily main thread operations. This +means that in high latency mode the main thread may be 1 frame behind the +compositor thread, which means that the scroll position that the compositor is +using to position the page and the scroll position Blink/JavaScript is currently +aware of will be 1 step out of sync. Other than keeping the page in low latency +mode by never blowing frame budget, there’s currently nothing a page can do +about this. + +It’s also worth noting, though, that input latency is rarely a visible problem +outside of these scroll-linked effects (like pull to refresh, or poorly +implemented parallax, etc). The platform’s biggest problem remains that it’s +incredibly difficult to maintain a high framerate.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/anatomy-of-jank/mov1.mp4.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/anatomy-of-jank/mov1.mp4.sha1 new file mode 100644 index 00000000000..6858e4b3fb0 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/anatomy-of-jank/mov1.mp4.sha1 @@ -0,0 +1 @@ +fc24e98d316d180a4a3fa70d4328951a9243b7f8
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/anatomy-of-jank/mov2.mp4.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/anatomy-of-jank/mov2.mp4.sha1 new file mode 100644 index 00000000000..fe82369a1b9 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/anatomy-of-jank/mov2.mp4.sha1 @@ -0,0 +1 @@ +ad0aba92c337cd755fd4c397b5e55213d4805f4e
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/anatomy-of-jank/mov3.mp4.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/anatomy-of-jank/mov3.mp4.sha1 new file mode 100644 index 00000000000..75850a8f952 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/anatomy-of-jank/mov3.mp4.sha1 @@ -0,0 +1 @@ +43428f9d7d1925fa5bf7c53ef49fc1c8c7b0845c
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/anatomy-of-jank/mov4.mp4.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/anatomy-of-jank/mov4.mp4.sha1 new file mode 100644 index 00000000000..e95f75d5516 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/anatomy-of-jank/mov4.mp4.sha1 @@ -0,0 +1 @@ +95a0deaacba87720dc9e87d7ac9966b209ccf0b0
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/frame-viewer/Screen Shot 2013-05-14 at 9.10.55 PM.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/frame-viewer/Screen Shot 2013-05-14 at 9.10.55 PM.png.sha1 new file mode 100644 index 00000000000..2e4e6418382 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/frame-viewer/Screen Shot 2013-05-14 at 9.10.55 PM.png.sha1 @@ -0,0 +1 @@ +4b230685cf2ba5f397bd78d91cba650d41d8d962
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/frame-viewer/frameviewer.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/frame-viewer/frameviewer.png.sha1 new file mode 100644 index 00000000000..0a9a198149a --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/frame-viewer/frameviewer.png.sha1 @@ -0,0 +1 @@ +bf007ac2c59af2c52820da0c2b2dd35a90572439
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/frame-viewer/index.md b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/frame-viewer/index.md new file mode 100644 index 00000000000..0114402be5d --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/frame-viewer/index.md @@ -0,0 +1,79 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +- - /developers/how-tos/trace-event-profiling-tool + - The Trace Event Profiling Tool (about:tracing) +page_name: frame-viewer +title: Chrome Frame Viewer Overview and Getting Started +--- + +The frame viewer is a feature in Chrome's about:tracing for studying difficult +rendering performance problems. + +[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/frame-viewer/frameviewer.png" +height=269 +width=400>](/developers/how-tos/trace-event-profiling-tool/frame-viewer/frameviewer.png) + +## Getting started + +Frame viewer is best used in Chrome Canary, but viewing traces requires that you +launch with special flags. On OSX, the appropriate incantation is: + +> **/Applications/Google\\ Chrome\\ Canary.app/Contents/MacOS/Google\\ Chrome\\ +> Canary --enable-skia-benchmarking** + +When you have such a build: + +* Go to about:tracing and press record +* Check the **Frame Viewer** option. +* Press **Record** +* Go to some other tab, refresh, then do the janky action. +* Go back to tracing and press stop. +* Scroll through the tracks (using W, A, S, and D) looking for the + "cc::LayerTreehostImpl" track. Click a dot on that track and you + will get a viewer for that frame. + +## Reporting Rendering Performance Bugs + +## The best performance bug reports come with two traces: one taken with frame viewer on, and one taken with frame viewer off. We use both because frame viewer, while fast, is still intrusive to total performance. To do this: + +* Start up chrome with the frame viewer command line, above. +* Record a trace of your slow action, with **cc.debug** and + **cc.debug.display_items** ==unchecked==. This is your true + performance trace. We will use that to understand whether the + performance issue is functional \[requiring the frame viewer data\] + or raw performance related \[requiring just the performance data\] +* Without rebooting chrome or changing its command line, record a + second trace, now with **cc.debug** and + **cc.debug.**display_items**** ==checked==. This is the frame viewer + trace and lets us understand functional issues in the page that may + lead to performance problems. + +## Frame Viewer on Android + +You can trace a USB-connected Android device remotely from the +***chrome://inspect/?tracing#devices*** URL. Alternatively, there is a command +line script in the Chrome repository that provides the same functionality. For +example, this command captures a 5 second trace with frame viewer data from the +stable version of Chrome on an Android device: + +> **build/android/adb_profile_chrome --browser=stable --trace-frame-viewer -t +> 5** + +## The script downloads the resulting trace file to the current directory. You can view it by opening Chrome on your desktop, going to about:tracing and clicking on "Load". The chrome you load it into must be a similar version of chrome (within ~2 major versions) of your Android build for it to load properly. The viewing browser must have the **--enable-skia-benchmarking** flag set to see the frame images. + +## Some notes + +* Arrow keys move between frames, once you have selected them + +## Demo Video + +#### JSConf.Eu demo + +## More info + +## For details on how it works, see the [design doc](https://docs.google.com/a/chromium.org/document/d/13FAQ9ckY7RDihv6aW5ehz15Pm2aheQFR7cY6FPdBmIQ/edit#heading=h.uyhrrm74z5nq). For more information, you can join/read the [trace-viewer mailing list](https://groups.google.com/forum/#!forum/trace-viewer), or review the code, which is located inside <https://code.google.com/p/trace-viewer/>.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/index.md b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/index.md new file mode 100644 index 00000000000..10f56c3fe6b --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/index.md @@ -0,0 +1,96 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: trace-event-profiling-tool +title: The Trace Event Profiling Tool (about:tracing) +--- + +When diagnosing performance problems it can be valuable to see what Chrome is +doing "under the hood." One way to get a more detailed view into what's going on +is to use the about:tracing tool. + +Tracing records activity in Chrome's processes (see [multi-process +architecture](http://www.chromium.org/developers/design-documents/multi-process-architecture) +for more on what each process is doing). It records C++ or javascript method +signatures in a hierarchical view for each thread in each process. This is a lot +of information, but sifting through it can help identify performance +bottlenecks, slow operations, and events with irregular lengths (leading to e.g. +framerate variation). + +[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/abouttracing2.png" +height=269 +width=400>](/developers/how-tos/trace-event-profiling-tool/abouttracing2.png) + +## Getting Started Using about:tracing + +1. [Recording Tracing + Runs](/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs); + start with this, it's prerequisite for using about:tracing. +2. [How to use the Frame Viewer to Bust + Jank](/developers/how-tos/trace-event-profiling-tool/using-frameviewer); + read this next, to understand how to diagnose rendering performance + problems. +3. [Jank Case Study 1](/developers/rendering-performance-case-study-1); + then read this, for further examples of how to effectively use + about:tracing in conjunction with the Dev Tools timeline + +Note that to understand what's happening in trace events you'll need a basic +understanding of how the browser works. The above articles provide enough to get +started, but it's recommended to first read at minimum: + +* [The Rendering Critical + Path](/developers/the-rendering-critical-path) for a little more + background, and... +* [Anatomy of + Jank](/developers/how-tos/trace-event-profiling-tool/anatomy-of-jank) + for precise explanations of various rendering performance problems + +**Further reading:** + +* [A presentation from + pdr@](https://docs.google.com/a/google.com/presentation/d/1pw9kbUFMD7s9KME8yIsCpCNKaSwjkGa89tt4M5rxIGM/edit) + on how to debug the graphics stack with tracing +* [Frame Viewer + Basics](/developers/how-tos/trace-event-profiling-tool/frame-viewer), + a short guide for how to navigate the frame viewer view. This is + more succinct but less informative than [frame viewer + how-to](/developers/how-tos/trace-event-profiling-tool/using-frameviewer) + above. +* [Saving Skia + Pictures](/developers/how-tos/trace-event-profiling-tool/saving-skp-s-from-chromium); + this is useful if you want to capture isolated SkPictures for the + Skia team. +* [Tracking memory + allocations](https://chromium.googlesource.com/chromium/src/+/HEAD/components/tracing/docs/memory_infra.md) + with memory-infra tracing + +**Even further reading:** + +* [How to Understand about:tracing + results](/developers/how-tos/trace-event-profiling-tool/trace-event-reading) + (somewhat out of date; refer to the [Frame Viewer + how-to](/developers/how-tos/trace-event-profiling-tool/using-frameviewer) + instead) + +## Contributing to about:tracing + +Start by perusing the [Tracing Ecosystem +Explainer](https://docs.google.com/a/chromium.org/document/d/1QADiFe0ss7Ydq-LUNOPpIf6z4KXGuWs_ygxiJxoMZKo/edit#) +to understand the various different pieces of code involved. + +* To instrument Chrome and add your own custom traces, see + [Instrumenting Chromium or Javascript code to get more + detail](/developers/how-tos/trace-event-profiling-tool/tracing-event-instrumentation). +* To add functionality to the about:tracing viewer itself, see + [contributing to + trace-viewer](https://github.com/google/trace-viewer/wiki/Contributing). + * [trace-viewer](https://github.com/google/trace-viewer) lives in + its own repository on GitHub, not in the Chromium tree. + +Please file bugs as you find them! If you find any bugs, please [let us +know](https://github.com/google/trace-viewer/issues/new). You review the [known +bugs](https://github.com/google/trace-viewer/issues) as well.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/2. MemoryInfra- From trace JSON to Tracks.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/2. MemoryInfra- From trace JSON to Tracks.png.sha1 new file mode 100644 index 00000000000..22077453136 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/2. MemoryInfra- From trace JSON to Tracks.png.sha1 @@ -0,0 +1 @@ +444ac6d1f1d89a96c79e2f4c7965be2de2a627de
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/Screen Shot 2015-06-12 at 5.30.33 PM.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/Screen Shot 2015-06-12 at 5.30.33 PM.png.sha1 new file mode 100644 index 00000000000..e359a0c752b --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/Screen Shot 2015-06-12 at 5.30.33 PM.png.sha1 @@ -0,0 +1 @@ +9980aed92edf9030b3a9e7f5fdacab4ba1890e1d
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/Screen Shot 2015-06-12 at 7.42.47 PM.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/Screen Shot 2015-06-12 at 7.42.47 PM.png.sha1 new file mode 100644 index 00000000000..a3adff44b3d --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/Screen Shot 2015-06-12 at 7.42.47 PM.png.sha1 @@ -0,0 +1 @@ +99ef4e18dc707d3113f0eb161ebee360885c1e0d
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/dump.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/dump.png.sha1 new file mode 100644 index 00000000000..7e3f756f019 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/dump.png.sha1 @@ -0,0 +1 @@ +d6d6efd67254fe8faed4791770d4999e90e13346
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/gpu-memory/Screen Shot 2015-09-24 at 8.34.32 PM.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/gpu-memory/Screen Shot 2015-09-24 at 8.34.32 PM.png.sha1 new file mode 100644 index 00000000000..71731e74faf --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/gpu-memory/Screen Shot 2015-09-24 at 8.34.32 PM.png.sha1 @@ -0,0 +1 @@ +5b8d6674cfbdb88df18b561f27a949c51ba2ac89
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/gpu-memory/Screen Shot 2015-09-24 at 8.38.32 PM.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/gpu-memory/Screen Shot 2015-09-24 at 8.38.32 PM.png.sha1 new file mode 100644 index 00000000000..1d9ce39e9e2 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/gpu-memory/Screen Shot 2015-09-24 at 8.38.32 PM.png.sha1 @@ -0,0 +1 @@ +2b5dbb4732be9ddb6d20b2175bd5c120cc98af45
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/gpu-memory/index.md b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/gpu-memory/index.md new file mode 100644 index 00000000000..f6dca542e2e --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/gpu-memory/index.md @@ -0,0 +1,16 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +- - /developers/how-tos/trace-event-profiling-tool + - The Trace Event Profiling Tool (about:tracing) +- - /developers/how-tos/trace-event-profiling-tool/memory + - OBSOLETE. Memory profiling in chrome://tracing +page_name: gpu-memory +title: OBSOLETE. GPU Memory Tracing +--- + +Moved to +<https://chromium.googlesource.com/chromium/src/+/HEAD/docs/memory-infra/probe-gpu.md>
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/gpu-memory/sXTqTORl7xn0ijvmBV3etcA (1).png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/gpu-memory/sXTqTORl7xn0ijvmBV3etcA (1).png.sha1 new file mode 100644 index 00000000000..158c5b344c9 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/gpu-memory/sXTqTORl7xn0ijvmBV3etcA (1).png.sha1 @@ -0,0 +1 @@ +6ac8bd15753f7f699b14099ba640481e78e4f613
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/gpu-memory/sXTqTORl7xn0ijvmBV3etcA.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/gpu-memory/sXTqTORl7xn0ijvmBV3etcA.png.sha1 new file mode 100644 index 00000000000..1421641229e --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/gpu-memory/sXTqTORl7xn0ijvmBV3etcA.png.sha1 @@ -0,0 +1 @@ +987aa713f589011db2278f7be006a5d462196170
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/heap-profiling-with-memory-infra/detailed_dump.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/heap-profiling-with-memory-infra/detailed_dump.png.sha1 new file mode 100644 index 00000000000..2c03bf1850a --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/heap-profiling-with-memory-infra/detailed_dump.png.sha1 @@ -0,0 +1 @@ +0df67e2cd56c15cc8c4134d5c87a2edf758e22ca
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/heap-profiling-with-memory-infra/heap.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/heap-profiling-with-memory-infra/heap.png.sha1 new file mode 100644 index 00000000000..d0c403e2ea8 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/heap-profiling-with-memory-infra/heap.png.sha1 @@ -0,0 +1 @@ +1c98f53a95b92804ebdfc1b106e3bf7a0b36e952
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/heap-profiling-with-memory-infra/index.md b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/heap-profiling-with-memory-infra/index.md new file mode 100644 index 00000000000..f8785404936 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/heap-profiling-with-memory-infra/index.md @@ -0,0 +1,16 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +- - /developers/how-tos/trace-event-profiling-tool + - The Trace Event Profiling Tool (about:tracing) +- - /developers/how-tos/trace-event-profiling-tool/memory + - OBSOLETE. Memory profiling in chrome://tracing +page_name: heap-profiling-with-memory-infra +title: OBSOLETE. Heap Profiling with memory-infra +--- + +Moved to +<https://chromium.googlesource.com/chromium/src/+/HEAD/docs/memory-infra/heap_profiler.md>
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/heap-profiling-with-memory-infra/new.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/heap-profiling-with-memory-infra/new.png.sha1 new file mode 100644 index 00000000000..9062817d40d --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/heap-profiling-with-memory-infra/new.png.sha1 @@ -0,0 +1 @@ +e801f55cdc79b8f5497f8399c1d25c131b442c0b
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/howto-adding-memory-infra-tracing-to-a-component/index.md b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/howto-adding-memory-infra-tracing-to-a-component/index.md new file mode 100644 index 00000000000..5df036ad1ae --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/howto-adding-memory-infra-tracing-to-a-component/index.md @@ -0,0 +1,226 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +- - /developers/how-tos/trace-event-profiling-tool + - The Trace Event Profiling Tool (about:tracing) +- - /developers/how-tos/trace-event-profiling-tool/memory + - OBSOLETE. Memory profiling in chrome://tracing +page_name: howto-adding-memory-infra-tracing-to-a-component +title: 'HowTo: Adding Memory Infra Tracing to a Component' +--- + +## Motivation + +If you have a component that manages memory allocations, you should be +registering and tracking those allocations with Chrome's memory-infra system. +This lets you: + +* See an overview of your allocations, giving insight into total size + and breakdown. +* Understand how your allocations change over time and how they are + impacted by other parts of Chrome. +* Catch regressions in your component's allocations size by setting up + telemetry tests which monitor your allocation sizes under certain + circumstances. + +Some existing components which make use of memory tracing infra: + +* Discardable Memory - Tracks usage of discardable memory throughout + chrome. +* GPU - tracks GL and other GPU object allocations. +* V8 - tracks heap size for JS. +* many more.... + +## Overview + +In order to hook into Chrome's memory infra system, your component needs to do +two things: + +1. Create a + [base::trace_event::MemoryDumpProvider](https://code.google.com/p/chromium/codesearch#chromium/src/base/trace_event/memory_dump_provider.h) + for your component. +2. Register/Unregister your + [base::trace_event::MemoryDumpProvider](https://code.google.com/p/chromium/codesearch#chromium/src/base/trace_event/memory_dump_provider.h) + with the + [base::trace_event::MemoryDumpManager](https://code.google.com/p/chromium/codesearch#chromium/src/base/trace_event/memory_dump_manager.h). + +## Creating a MemoryDumpProvider + +In order to tie into the memory infra system, you must write a +[base::trace_event::MemoryDumpProvider](https://code.google.com/p/chromium/codesearch#chromium/src/base/trace_event/memory_dump_provider.h) +for your component. You can implement this as a stand-alone class, or as an +additional interface on an existing class. For example, this interface is +frequently implemented on classes which manage a pool of allocations (see +[cc::ResourcePool](https://code.google.com/p/chromium/codesearch#chromium/src/cc/resources/resource_pool.h) +for an example). + +A MemoryDumpProvider has one basic job, to implement +[MemoryDumpProvider::OnMemoryDump](https://code.google.com/p/chromium/codesearch#chromium/src/skia/ext/skia_memory_dump_provider.h). +This function is responsible for iterating over the resources allocated/tracked +by your component, and creating a +[base::trace_event::MemoryAllocatorDump](https://code.google.com/p/chromium/codesearch#chromium/src/base/trace_event/memory_allocator_dump.h) +for each using +[ProcessMemoryDump::CreateAllocatorDump](https://code.google.com/p/chromium/codesearch#chromium/src/base/trace_event/process_memory_dump.h). +Here is a simple example: + +> <table> +> <tr> +> <td>bool MyComponent::OnMemoryDump(</td> +> <td> const base::trace_event::MemoryDumpArgs& args,</td> +> <td> base::trace_event::ProcessMemoryDump\* process_memory_dump) {</td> +> <td> for (const auto& allocation : my_allocations_) {</td> +> <td> auto\* dump = process_memory_dump->CreateAllocatorDump(</td> +> <td> "path/to/my/component/allocation_" + allocation.id().ToString());</td> +> <td> dump->AddScalar(base::trace_event::MemoryAllocatorDump::kNameSize,</td> +> <td> base::trace_event::MemoryAllocatorDump::kUnitsBytes,</td> +> <td> allocation.size_bytes());</td> +> <td> // While you will typically have a kNameSize entry, you can add additional</td> +> <td> // entries to your dump with free-form names. In this example we also dump</td> +> <td> // an object's "free_size", assuming the object may not be entirely in use.</td> +> <td> dump->AddScalar("free_size",</td> +> <td> base::trace_event::MemoryAllocatorDump::kUnitsBytes,</td> +> <td> allocation.free_size_bytes());</td> +> <td> }</td> +> <td> }</td> +> </tr> +> </table> + +For many components, this may be all that is needed. See Handling Shared Memory +Allocations and Sub Allocations for information on more complex use cases. + +## Registering/Unregistering a MemoryDumpProvider + +### Registration + +Once you have created a +[base::trace_event::MemoryDumpProvider](https://code.google.com/p/chromium/codesearch#chromium/src/base/trace_event/memory_dump_provider.h), +you need to register it with the +[base::trace_event::MemoryDumpManager](https://code.google.com/p/chromium/codesearch#chromium/src/base/trace_event/memory_dump_manager.h) +before the system can start polling it for memory information. Registration is +generally straightforward, and involves calling +[MemoryDumpManager::RegisterDumpProvider](https://code.google.com/p/chromium/codesearch#chromium/src/base/trace_event/memory_dump_manager.h): + +> <table> +> <tr> +> <td>...</td> +> <td> // Each process uses a singleton MemoryDumpManager</td> +> <td> base::trace_event::MemoryDumpManager::GetInstance()->RegisterDumpProvider(</td> +> <td> my_memory_dump_provider_, my_single_thread_task_runner_);</td> +> <td>...</td> +> </tr> +> </table> + +In the above code, my_memory_dump_provider_ is the +[base::trace_event::MemoryDumpProvider](https://code.google.com/p/chromium/codesearch#chromium/src/base/trace_event/memory_dump_provider.h) +outlined in the previous section. my_single_thread_task_runner_ is more complex +and may be a number of things: + +* Most commonly, if your component is always used from the main + message loop, my_single_thread_task_runner_ may just be + [base::ThreadTaskRunnerHandle::Get()](https://code.google.com/p/chromium/codesearch#chromium/src/base/thread_task_runner_handle.h). +* If your component already uses a custom + [base::SingleThreadTaskRunner](https://code.google.com/p/chromium/codesearch#chromium/src/base/single_thread_task_runner.h) + for executing tasks on a specific thread, you should likely use this + runner. + +In all cases, if your +[base::trace_event::MemoryDumpProvider](https://code.google.com/p/chromium/codesearch#chromium/src/base/trace_event/memory_dump_provider.h) +accesses data that may be used from multiple threads, you should make sure the +proper locking is in place in your implementation of +[MemoryDumpProvider::OnMemoryDump](https://code.google.com/p/chromium/codesearch#chromium/src/skia/ext/skia_memory_dump_provider.h). + +### Unregistration + +Unregistering a +[base::trace_event::MemoryDumpProvider](https://code.google.com/p/chromium/codesearch#chromium/src/base/trace_event/memory_dump_provider.h) +is very similar to registering one: + +> <table> +> <tr> +> <td>...</td> +> <td> // Each process uses a singleton MemoryDumpManager</td> +> <td> base::trace_event::MemoryDumpManager::GetInstance()->UnregisterDumpProvider(</td> +> <td> my_memory_dump_provider_);</td> +> <td>...</td> +> </tr> +> </table> + +The main complexity here is that unregistration must happen on the thread +belonging to the +[base::SingleThreadTaskRunner](https://code.google.com/p/chromium/codesearch#chromium/src/base/single_thread_task_runner.h) +provided at registration time. Unregistering on another thread can lead to race +conditions if tracing is active when the provider is unregistered. + +## Handling Shared Memory Allocations + +When an allocation is shared between two components, it may be useful to dump +the allocation in both components, but you also want to avoid double-counting +the allocation. This can be achieved using memory infra's concept of "ownership +edges". An ownership edge represents that the "source" memory allocator dump +owns a "target" memory allocator dump. If multiple "source" dumps own a single +"target", then the cost of that "target" allocation will be split between the +"source"s. Additionally, importance can be added to a specific ownership edge, +allowing the highest importance "source" of that edge to claim the entire cost +of the "target". + +In the typical case, you will use +[base::trace_event::ProcessMemoryDump](https://code.google.com/p/chromium/codesearch#chromium/src/base/trace_event/process_memory_dump.h) +to create a shared global allocator dump. This dump will act as the target of +all component-specific dumps of a specific resource: + +> <table> +> <tr> +> <td>...</td> +> <td> // Component 1 is going to create a dump, source_mad, for an allocation,</td> +> <td> // alloc_, which may be shared with other components / processes.</td> +> <td> MyAllocationType\* alloc_;</td> +> <td> base::trace_event::MemoryAllocatorDump\* source_mad;</td> +> <td> // Component 1 creates and populates source_mad;</td> +> <td> ...</td> +> <td> // In addition to creating a source dump, we must create a global shared</td> +> <td> // target dump. This dump should be created with a unique GUID which can be</td> +> <td> // generated any place the allocation is used. I recommend adding a GUID</td> +> <td> // generation function to the allocation type.</td> +> <td> base::trace_event::MemoryAllocatorDumpGUID guid(alloc_->GetGUIDString());</td> +> <td> // From this GUID we can generate the parent allocator dump.</td> +> <td> base::trace_event::MemoryAllocatorDump\* target_mad =</td> +> <td> process_memory_dump->CreateSharedGlobalAllocatorDump(guid);</td> +> <td> // We now create an ownership edge from the source dump to the target dump.</td> +> <td> // When creating an edge, you can assign an importance to this edge. If all</td> +> <td> // edges have the same importance, the size of the allocation will be split</td> +> <td> // between all sources which create a dump for the allocation. If one</td> +> <td> // edge has higher importance than the others, its soruce will be assigned the</td> +> <td> // full size of the allocation.</td> +> <td> const int kImportance = 1;</td> +> <td> process_memory_dump->AddOwnershipEdge(</td> +> <td> source_mad->guid(), target_mad->guid(), kImportance);</td> +> <td>...</td> +> </tr> +> </table> + +If an allocation is being shared across process boundaries, it may be useful to +generate a GUID which incorporates the ID of the local process, preventing two +processes from generating colliding GUIDs. As it is not recommended to pass a +Process ID between processes for security reasons, a function +[MemoryDumpManager::GetTracingProcessId](https://code.google.com/p/chromium/codesearch#chromium/src/base/trace_event/memory_dump_manager.cc) +is provided which generates a unique ID per process that can be passed with the +resource without security concerns. Frequently this ID is used to generate a +GUID that is based on the allocated resource's ID combined with the allocating +process' tracing ID. + +## Sub Allocations + +Another advanced use case involves tracking sub-allocations of a larger +allocation. For instance, this is used in +[gpu::gles2::TextureManager](https://code.google.com/p/chromium/codesearch#chromium/src/gpu/command_buffer/service/texture_manager.cc) +to dump both the sub-allocations which make up a texture. Creating a sub +allocation is easy - instead of calling +[ProcessMemoryDump::CreateAllocatorDump](https://code.google.com/p/chromium/codesearch#chromium/src/base/trace_event/process_memory_dump.h) +to create a +[base::trace_event::MemoryAllocatorDump](https://code.google.com/p/chromium/codesearch#chromium/src/base/trace_event/memory_allocator_dump.h), +you simply call +[ProcessMemoryDump::AddSubAllocation](https://code.google.com/p/chromium/codesearch#chromium/src/base/trace_event/process_memory_dump.h), +providing the GUID of the parent allocation as the first parameter.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/index.md b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/index.md new file mode 100644 index 00000000000..3574941accc --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/index.md @@ -0,0 +1,14 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +- - /developers/how-tos/trace-event-profiling-tool + - The Trace Event Profiling Tool (about:tracing) +page_name: memory +title: OBSOLETE. Memory profiling in chrome://tracing +--- + +Moved to +<https://chromium.googlesource.com/chromium/src/+/HEAD/docs/memory-infra/README.md>
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/memory_infra_logo.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/memory_infra_logo.png.sha1 new file mode 100644 index 00000000000..329bd7f1a52 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/memory_infra_logo.png.sha1 @@ -0,0 +1 @@ +62123f2712d8e90c3a09264ff2091f7026c03448
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/startup-tracing-with-memory-profiling/index.md b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/startup-tracing-with-memory-profiling/index.md new file mode 100644 index 00000000000..2bc8152cdb8 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/memory/startup-tracing-with-memory-profiling/index.md @@ -0,0 +1,74 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +- - /developers/how-tos/trace-event-profiling-tool + - The Trace Event Profiling Tool (about:tracing) +- - /developers/how-tos/trace-event-profiling-tool/memory + - OBSOLETE. Memory profiling in chrome://tracing +page_name: startup-tracing-with-memory-profiling +title: Startup tracing with memory profiling +--- + +**Related wiki pages** + +* See [this + page](/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs) + for general information on startup tracing. +* See [this + page](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/memory-infra/README.md) + for general information about memory tracing. + +There are two ways to perform memory tracing at startup: + +**Simple way with default configuration (one memory dump every 250 ms., one +detailed memory dump every 2 s.)** + +$chrome --no-sandbox \\ + +--trace-startup=-\*,disabled-by-default-memory-infra \\ + +--trace-startup-file=/tmp/trace.json \\ + +--trace-startup-duration=7 + +Then just load /tmp/trace.json in chrome://tracing + +**Advanced, memory tracing configuration** + +If you need more advanced configuration (e.g., higher granularity dumps, no need +for detailed memory dumps) specify a custom trace config file, as follows: + +$ cat > /tmp/trace.config + +{ + +"startup_duration": 4, + +"result_file": "/tmp/trace.json", + +"trace_config": { + +"included_categories": \["disabled-by-default-memory-infra"\], + +"excluded_categories": \["\*"\], + +"memory_dump_config": { + +"triggers": \[ + +{"mode":"light", "periodic_interval_ms": 50}, + +{"mode":"detailed", "periodic_interval_ms": 1000} + +\] + +} + +} + +} + +$chrome --no-sandbox --trace-config-file=/tmp/trace.config
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/Screen Shot 2015-06-04 at 1.37.00 PM.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/Screen Shot 2015-06-04 at 1.37.00 PM.png.sha1 new file mode 100644 index 00000000000..a43ccaaeebe --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/Screen Shot 2015-06-04 at 1.37.00 PM.png.sha1 @@ -0,0 +1 @@ +8ff999184a6c70f3af0f70edbaa327201f1a6d2d
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/Screen Shot 2015-06-04 at 12.46.58 PM.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/Screen Shot 2015-06-04 at 12.46.58 PM.png.sha1 new file mode 100644 index 00000000000..2500b93e11a --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/Screen Shot 2015-06-04 at 12.46.58 PM.png.sha1 @@ -0,0 +1 @@ +fc70edf239917af2d0f7e4407b42062c2955214d
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/Screen Shot 2015-06-04 at 12.47.34 PM.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/Screen Shot 2015-06-04 at 12.47.34 PM.png.sha1 new file mode 100644 index 00000000000..fd38d310425 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/Screen Shot 2015-06-04 at 12.47.34 PM.png.sha1 @@ -0,0 +1 @@ +d42bf23825cc5a431d723f437d7048e2bdd523aa
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/Screenshot from 2014-10-14 10-18-30.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/Screenshot from 2014-10-14 10-18-30.png.sha1 new file mode 100644 index 00000000000..d479ecadfe3 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/Screenshot from 2014-10-14 10-18-30.png.sha1 @@ -0,0 +1 @@ +3409e18a95bb54ca1f54ecb7e4c5cdb41678ce0f
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/Screenshot from 2014-10-14 10-18-44.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/Screenshot from 2014-10-14 10-18-44.png.sha1 new file mode 100644 index 00000000000..ae8aaba76df --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/Screenshot from 2014-10-14 10-18-44.png.sha1 @@ -0,0 +1 @@ +1f673f14edabc1b165b8710c87abd6b7c79de141
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/Screenshot from 2014-10-14 10-19-11.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/Screenshot from 2014-10-14 10-19-11.png.sha1 new file mode 100644 index 00000000000..032f2167db1 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/Screenshot from 2014-10-14 10-19-11.png.sha1 @@ -0,0 +1 @@ +27573f4af39ccc572f8cfcdc5993788c2662f1b7
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/index.md b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/index.md new file mode 100644 index 00000000000..718b4baf37a --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/index.md @@ -0,0 +1,299 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +- - /developers/how-tos/trace-event-profiling-tool + - The Trace Event Profiling Tool (about:tracing) +page_name: recording-tracing-runs +title: Recording Tracing Runs +--- + +When diagnosing performance problems it can be valuable to see what Chrome is +doing "under the hood." One way to get a more detailed view into what's going on +is to use the about:tracing tool. + +See [Trace Event Profiling Tool +(about:tracing)](/developers/how-tos/trace-event-profiling-tool) for more +information on what this tool does. + +[TOC] + +## Capture a trace on Chrome desktop + +Sometimes Chromium developers will ask for about:tracing results in a bug report +to help us understand what's going on. +**Here's an easy step-by-step guide: [ Submitting an Awesome Performance +Bug](/developers/how-tos/submitting-a-performance-bug)** + +The TL;DR: + +1. Open a new tab and type "**about:tracing**" in the Omnibox. +2. Press "**Record**". Choose the "**Manually select settings**" + preset, click the **All** button above the left column and press + "**Record**". +3. Switch back to the tab with the content you're debugging and do + whatever it is that's slower than it should be (or behaving + incorrectly). A few seconds of the bad activity is usually + sufficient. +4. Switch back to the tracing tab and press "**Stop**", then "**Save**" +5. (Optional) If this is for a bug report, upload the output file as an + attachment to bug. If the file is bigger than 10MB, zip it first + (the files compress well, and files bigger than 10MB can be + truncated during upload). + +**IMPORTANT:** *Before attaching a trace to a bug keep in mind that it will +contain the URL and Title of all open tabs, URLs of subresources used by each +tab, extension IDs, hardware identifying details, and other similar information +that you may not want to make public.* + +### *Capturing chrome desktop startup* + +> Assuming $CHROME is set to the command you need on your OS to start chrome, +> the following will record the first 7 seconds of Chrome's lifetime into +> /tmp/foo.json + +> > > `$CHROME --trace-startup --trace-startup-file=/tmp/foo.json +> > > --trace-startup-duration=7` + +> On Windows you can modify the properties for your Chrome shortcut to add this +> after where it says chrome.exe (don't forget to modify it back when you are +> done): + +> > > `--trace-startup --trace-startup-file=%temp%\foo.json +> > > --trace-startup-duration=7` + +## Capture a trace from Chrome on Android (on device) + +First you need to enable Chrome's developer options. To do this, open **Settings +> About Chrome**. Then tap **"Application version"** 7 times in a row: + +[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/s.png" +height=400 +width=194>](/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/s.png) + +After this you can access developer settings from **Settings > Developer +options**. From this menu, select **Tracing**: + +[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/s2.png" +height=400 +width=194>](/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/s2.png) + +Select your categories and tap **"Record trace"** to start recording: + +[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/s3.png" +height=400 +width=194>](/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/s3.png) + +To stop the recording, pull down on the notification shade and tap **"Stop +recording"**. After this, you can access the trace with the **"Share trace"** +button: + +[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/s4.png" +height=400 +width=194>](/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/s4.png) + +## Capture a trace from Chrome on Android (with DevTools) + +> **Tip:** this also works with tracing the system Android WebView. + +> 1. If you're debugging a WebView app: edit the app to call the **static** +> method `WebView.setWebContentsDebuggingEnabled(true)` ([API +> docs](/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs)) + +> 2. Connect Chrome DevTools on your desktop to the Android device. Follow +> [these instructions for +> Chrome](/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs) +> or [these instructions for +> WebView](https://developer.chrome.com/docs/devtools/remote-debugging/webviews/) +> 3. Go to `chrome://inspect?tracing` on desktop chrome. Find the app to be +> traced, and click on the trace link beside the title. + +> [<img alt="image" +> src="/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/Screen%20Shot%202015-06-04%20at%2012.46.58%20PM.png" +> height=277 +> width=400>](/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/Screen%20Shot%202015-06-04%20at%2012.46.58%20PM.png) + +> 3. Click on "Record" at top left. + +> [<img alt="image" +> src="/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/Screen%20Shot%202015-06-04%20at%2012.47.34%20PM.png">](/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/Screen%20Shot%202015-06-04%20at%2012.47.34%20PM.png) + +> 4. Select trace categories. Hit Record, then Stop. +> [<img alt="image" +> src="/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/Screenshot%20from%202014-10-14%2010-19-11.png" +> height=313 +> width=400>](/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/Screenshot%20from%202014-10-14%2010-19-11.png) + +## Capture a trace from Chrome on Android (on the command line) + +> You'll need: + +> * Your device running Chrome on Android +> * USB debugging enabled and the device attached. +> * [ADB](http://developer.android.com/guide/developing/tools/adb.html) +> * Linux or Mac desktop. Sorry Windows friends! + +> You can use \`adb_profile_chrome\` from the build/android/ directory in +> Chromium's source checkout. + +> Follow these steps to record a trace: + +> #### **1. Launch the browser** + +> Run Chrome normally. +> Developers, however, may want to launch from the command line: +> > `$ build/android/adb_run_content_shell URL `# run content shell + +> > `$ clank/bin/adb_run_chrome URL # run clank (Googlers only) ` + +> #### **2. Optionally, make a screen recording (optional)** + +> ` $ build/android/screenshot.py --video ` + +> ` # or ` + +> ` $ adb shell screenrecord /sdcard/recording.mp4 && adb pull +> /sdcard/recording.mp4` + +> #### **3. Record a trace** + +> #### Look at the [usage documentation for adb_trace and profile_chrome](https://github.com/johnmccutchan/adb_trace/blob/master/README.md#basics). + +> > [<img alt="image" src="/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/Screen%20Shot%202015-06-04%20at%201.37.00%20PM.png" height=215 width=320>](https://github.com/johnmccutchan/adb_trace/blob/master/README.md#basics) + +> For example: + +> ` $ build/android/adb_profile_chrome --browser build --time 5 --view` + +> Note: build here refers to the version of Chrome you are tracing. Other valid +> values are stable, beta (see --help for a full list). + +### Tracing options for Android + +> You can also use additional command line flags to capture more data. For +> example: + +> **1. Systrace:** --systrace gfx,view,input,freq,sched + +> > [ <img alt="image" +> > src="/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/tracing-systrace.png" +> > height=109 +> > width=400>](/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/tracing-systrace.png) + +> Captures data about system-level events. Generally useful categories are + +> > > sched = Kernel scheduling decisions + +> > > freq = CPU core frequency scaling + +> > > gfx = SurfaceFlinger events, Vsync + +> > > view = Android Framework events + +> > > input = Framework input event processing + +> adb shell atrace --list_categories shows the rest. + +> **2. IPC messages:** --trace-flow + +> > [ <img alt="image" +> > src="/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/tracing-flow.png" +> > height=143 +> > width=400>](/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/tracing-flow.png) + +> Adds arrows showing IPC message flows, making it easier to see message +> traffic. + +> 3. More trace categories, e.g.: +> --categories=disabled-by-default-cc.debug.scheduler,\* + +> > [ <img alt="image" +> > src="/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/tracing-scheduler.png" +> > height=106 +> > width=400>](/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/tracing-scheduler.png) + +> Adding more trace categories makes it possible to see events that are normally +> disabled. This particular example gives information about why the compositor +> scheduler decided to run a given action. To see the full list of categories, +> use --categories=list. + +> **4. Frame viewer data:** --trace-frame-viewer + +> > [ <img alt="image" +> > src="/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/tracing-frame-viewer.png" +> > height=233 +> > width=400>](/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/tracing-frame-viewer.png) + +> Captures rich layer data from the compositor. This is useful for understanding +> how the DOM affects the compositor's layer tree structure. When viewing traces +> like this, make sure to launch Chrome (on the desktop) with the +> --enable-skia-benchmarking command line flag so that all features are +> available. + +> **5. Perf profiling data:** --perf +> [Perf](https://perf.wiki.kernel.org/index.php/Main_Page) is a sampling +> profiler which can help you find performance intensive parts of the source +> code. The --perf switch runs perf and automatically combines the data with all +> other enabled event sources. + +> > [ <img alt="image" +> > src="/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/sunburst.png" +> > height=400 +> > width=396>](/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/sunburst.png) + +> You can also view the raw recorded perf data using the command line which is +> printed out by adb_profile_chrome. + +## Making a Good Recording + +* Keep the recording to a max of 10 seconds +* Try to keep to 1 activity per recording. If you see two slowdowns, + do one recording each. Or leave a second long pause between each. +* Pause and leave the computer completely idle for 2 seconds before + and after demonstrating the slowdown. This helps make the slow part + obvious in the recording. + +### Step by step: + +1. Start with only the tab you’re investigating and about:tracing open + in a fresh browser session (see below for other methods of figuring + out which tab is which if you need multiple). +2. Set up the tab for investigation to right before the point where the + problem will occur (e.g. right before an animation is going to be + triggered, or right before part of the page that scrolls slowly) +3. Start a tracing run in the about:tracing tab +4. Switch to the tab under investigation +5. Pause for a couple seconds to record empty space on the timeline + (makes finding it later easier) +6. Perform the action to trigger the bad performance behavior (e.g. + start the animation or scroll the page). Keeping the recorded + activity under 10 seconds is a good idea. +7. Pause again +8. Switch back to the about:tracing tab and stop the recording. + +## Tracing in Telemetry + +For more repeatable trace recordings you may want to consider using +[Telemetry](/developers/telemetry) to automate the process. In particular the +--profiler=trace, --profiler=v8 and --profiler=android-systrace flags will save +a trace for each tested page. + +## Trace Report File Formats + +After recording one can save a trace report by pressing the Save button. This +will save the trace in JSON format. + +It is also possible to convert it to HTML (which is easier to link to) using +[Catapult](https://github.com/catapult-project/catapult)'s +[trace2html](https://github.com/catapult-project/catapult/blob/master/tracing/bin/trace2html) +script. + +## Slide deck of Android Tracing tricks + +This information is already detailed above.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/s.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/s.png.sha1 new file mode 100644 index 00000000000..68731331e44 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/s.png.sha1 @@ -0,0 +1 @@ +78e0eabaa692a4e50aee5306aac4a87b4fa04f55
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/s2.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/s2.png.sha1 new file mode 100644 index 00000000000..64eab40962c --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/s2.png.sha1 @@ -0,0 +1 @@ +0bb4fa7cea5b84e6cbac818f5747b9b0b15a30ed
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/s3.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/s3.png.sha1 new file mode 100644 index 00000000000..08020bc80fb --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/s3.png.sha1 @@ -0,0 +1 @@ +b93306edd28037317c831aac1a224bc8ed376a3f
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/s4.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/s4.png.sha1 new file mode 100644 index 00000000000..5c658d733d6 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/s4.png.sha1 @@ -0,0 +1 @@ +448c3933a8c0e94f623c76833391bafc4ce47f61
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/sunburst.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/sunburst.png.sha1 new file mode 100644 index 00000000000..9e629c2a80d --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/sunburst.png.sha1 @@ -0,0 +1 @@ +4391d42d0c035acb397dc06730b354a14716cd10
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/tracing-flow.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/tracing-flow.png.sha1 new file mode 100644 index 00000000000..e15b03021b5 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/tracing-flow.png.sha1 @@ -0,0 +1 @@ +d95b8d43159394050f45849a1f193678c5acd672
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/tracing-frame-viewer.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/tracing-frame-viewer.png.sha1 new file mode 100644 index 00000000000..71c88d3b096 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/tracing-frame-viewer.png.sha1 @@ -0,0 +1 @@ +6c4e0beb32bbb5d92e5838597abf3537c6ec2395
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/tracing-scheduler.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/tracing-scheduler.png.sha1 new file mode 100644 index 00000000000..15f09723f5d --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/tracing-scheduler.png.sha1 @@ -0,0 +1 @@ +53221b8d435d896b51fa699d979c2a84c623b0c8
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/tracing-systrace.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/tracing-systrace.png.sha1 new file mode 100644 index 00000000000..6ca9d4b35c1 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs/tracing-systrace.png.sha1 @@ -0,0 +1 @@ +c756f33588b819b30d742ceba8900354dcb039e9
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/saving-skp-s-from-chromium/checkboxes.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/saving-skp-s-from-chromium/checkboxes.png.sha1 new file mode 100644 index 00000000000..36c997db072 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/saving-skp-s-from-chromium/checkboxes.png.sha1 @@ -0,0 +1 @@ +44cf2e6d887133c4d4a0c9ba460716d194e308a5
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/saving-skp-s-from-chromium/index.md b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/saving-skp-s-from-chromium/index.md new file mode 100644 index 00000000000..df8006a05df --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/saving-skp-s-from-chromium/index.md @@ -0,0 +1,99 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +- - /developers/how-tos/trace-event-profiling-tool + - The Trace Event Profiling Tool (about:tracing) +page_name: saving-skp-s-from-chromium +title: How to save .skp files from Chromium +--- + +Skia pictures or ".skp's" are a binary format for the draw commands Chromium +sends to Skia for rasterization. You can view these in the [Skia +debugger](https://skia.org/dev/tools/debugger). To get the SkPicture you have +two options: + +**Option 1: save the whole page** + +1. Grab Chrome Canary or a tip-of-tree Chromium Release build and + launch it with the following flags (for help, see \[1\]): + --enable-gpu-benchmarking --no-sandbox +2. Load your favorite page +3. In the DevTools console, type + chrome.gpuBenchmarking.printToSkPicture('/path/to/skp_dir/') +4. In the Skia checkout , run ./out/Debug/debugger + /path/to/skp_dir/layer_0.skp + +**Option 2: save an individual picture** + +You can view and export these files from Chrome's +[about:tracing](/developers/how-tos/trace-event-profiling-tool) tool + +1. Grab Chrome Canary or a tip-of-tree Chromium Release build and + launch it with the following flag (for help, see \[1\]): + --enable-skia-benchmarking +2. Navigate to "about:tracing". + + [<img alt="image" + src="/developers/how-tos/trace-event-profiling-tool/saving-skp-s-from-chromium/smallabouttracing.png" + height=162 + width=400>](/developers/how-tos/trace-event-profiling-tool/saving-skp-s-from-chromium/smallabouttracing.png) + +3. Open a new tab and navigate to your favorite knitting website. + + [<img alt="image" + src="/developers/how-tos/trace-event-profiling-tool/saving-skp-s-from-chromium/skpsite.png" + height=341 + width=400>](/developers/how-tos/trace-event-profiling-tool/saving-skp-s-from-chromium/skpsite.png) + +4. Go back to the about:tracing tab and press record. Choose the "Frame + viewer", or check “cc” and “cc.debug.display_items”. Uncheck + everything else for this demo, then press record. + + [<img alt="image" + src="/developers/how-tos/trace-event-profiling-tool/saving-skp-s-from-chromium/checkboxes.png" + height=341 + width=400>](/developers/how-tos/trace-event-profiling-tool/saving-skp-s-from-chromium/checkboxes.png) + +5. Go back to your knitting webpage and refresh the page. You can + scroll around, select text, etc (each generated skpicture will be + saveable). +6. Go back to “about:tracing” and press “stop tracing”. +7. Now for some fun! Use the W, A, S, and D keys like you’re playing a + video game. Your goal in this game is to find the + “cc::DisplayItemList” dot that you’d like to save. When you’ve found + the one, click “Save SkPicture”. Note: you can use the left and + right arrow keys to cycle through cc::DisplayItemLists. You may + notice there are two copies of most pictures--this is for low + resolution (first) and high resolution (second). + + [<img alt="image" + src="/developers/how-tos/trace-event-profiling-tool/saving-skp-s-from-chromium/picture.png" + height=341 + width=400>](/developers/how-tos/trace-event-profiling-tool/saving-skp-s-from-chromium/picture.png) + +8. You can now open this picture in the [Skia + debugger](https://sites.google.com/site/skiadocs/developer-documentation/skia-debugger). + + [<img alt="image" + src="/developers/how-tos/trace-event-profiling-tool/saving-skp-s-from-chromium/skdebugger2.png" + height=334 + width=400>](/developers/how-tos/trace-event-profiling-tool/saving-skp-s-from-chromium/skdebugger2.png) + +**\[1\] How to launch Chrome with flags on OSX** + +> Chrome Canary can be launched with: + +> > ./Applications/Google\\ Chrome\\ Canary.app/Contents/MacOS/Google\\ Chrome\\ +> > Canary --enable-threaded-compositing --force-compositing-mode +> > --enable-impl-side-painting --enable-skia-benchmarking +> > --allow-webui-compositing + +> If you build yourself, make sure to use a Release build and launch with: + +> > ./out/Release/Chromium.app/Contents/MacOS/Chromium +> > --enable-threaded-compositing --force-compositing-mode +> > --enable-impl-side-painting --enable-skia-benchmarking +> > --allow-webui-compositing
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/saving-skp-s-from-chromium/picture.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/saving-skp-s-from-chromium/picture.png.sha1 new file mode 100644 index 00000000000..c903f294f71 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/saving-skp-s-from-chromium/picture.png.sha1 @@ -0,0 +1 @@ +a42cabe115682e8223600e3f83685e0e3968d8df
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/saving-skp-s-from-chromium/skdebugger2.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/saving-skp-s-from-chromium/skdebugger2.png.sha1 new file mode 100644 index 00000000000..0f8c36821ce --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/saving-skp-s-from-chromium/skdebugger2.png.sha1 @@ -0,0 +1 @@ +464355355e250db334044c20094415ff119a3f15
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/saving-skp-s-from-chromium/skpsite.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/saving-skp-s-from-chromium/skpsite.png.sha1 new file mode 100644 index 00000000000..648e7ecd0ca --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/saving-skp-s-from-chromium/skpsite.png.sha1 @@ -0,0 +1 @@ +84ea8ed8e646f33238b2c791566eadc69ac29100
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/saving-skp-s-from-chromium/smallabouttracing.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/saving-skp-s-from-chromium/smallabouttracing.png.sha1 new file mode 100644 index 00000000000..3e5a3f60505 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/saving-skp-s-from-chromium/smallabouttracing.png.sha1 @@ -0,0 +1 @@ +fdaeccda3078be255df72343dfe5f37b84f1cc5f
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/Screen Shot 2015-09-02 at 8.39.51 PM.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/Screen Shot 2015-09-02 at 8.39.51 PM.png.sha1 new file mode 100644 index 00000000000..fe318c0bba9 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/Screen Shot 2015-09-02 at 8.39.51 PM.png.sha1 @@ -0,0 +1 @@ +df9aa45fd8002e8cbe1c02969c59716cde961d6b
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/Screen Shot 2015-09-02 at 8.46.48 PM.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/Screen Shot 2015-09-02 at 8.46.48 PM.png.sha1 new file mode 100644 index 00000000000..8527bef637f --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/Screen Shot 2015-09-02 at 8.46.48 PM.png.sha1 @@ -0,0 +1 @@ +f8b173f46dfee6b5e91e512aa45afa281d36a985
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/Selection.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/Selection.png.sha1 new file mode 100644 index 00000000000..678306a0d70 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/Selection.png.sha1 @@ -0,0 +1 @@ +691e9cdbbb7453270424c836a02af22f59b0fd49
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/fifth.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/fifth.png.sha1 new file mode 100644 index 00000000000..2d815cc4cc4 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/fifth.png.sha1 @@ -0,0 +1 @@ +806e3a615c8941ba5eb7bbd810382758c185665b
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/first.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/first.png.sha1 new file mode 100644 index 00000000000..9ef42c71894 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/first.png.sha1 @@ -0,0 +1 @@ +31268d87366497d689ed57b0094ef2c59a62fcd0
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/fourth.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/fourth.png.sha1 new file mode 100644 index 00000000000..db5ce44fa8a --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/fourth.png.sha1 @@ -0,0 +1 @@ +bed4b84f47f32402acb4c11866045cc06a67d7c9
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/index.md b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/index.md new file mode 100644 index 00000000000..02cbf00cd28 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/index.md @@ -0,0 +1,623 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +- - /developers/how-tos/trace-event-profiling-tool + - The Trace Event Profiling Tool (about:tracing) +page_name: trace-event-reading +title: Understanding about:tracing results +--- + +*Getting down with performance in web apps: not for the faint of heart.* + +**[TOC]** + +### Intro + +Chrome’s DevTools are great, but sometimes you’ve got a hitchy animation or page +that scrolls slowly and you just need more info on what’s going on. If you want +to dig into the guts of Chrome and figure out what the browser’s really doing +under the hood, about:tracing is for you. +This document will walk you through about:tracing and how to use it to diagnose +common, basic rendering performance problems. For background we’ll also cover a +few concepts central to Chrome’s overall rendering architecture, since artifacts +of this architecture show up all over tracing results. + +### Background: How Chrome Renders Web Pages + +A key mental backflip one has to do when reading a trace is understand how web +concepts are actually executed by Chrome. Once you understand how Chrome works, +and its words for common web concepts, you'll feel a lot better moving around in +a trace. This section covers a few key concepts to get you started. + +#### Chrome's use of multiple processes + +Full article: [Chrome’s Multi-Process +Architecture](/developers/design-documents/multi-process-architecture) +There are three types of processes in Chrome you need to worry about when +dealing with graphics: + +##### 1. The Browser Process + +The browser process is the central coordination point for all of Chrome’s +renderers (i.e. things actually drawing web pages). We call the browser process +CrBrowserMain, and any threads with the same PID as CrBrowserMain are threads +within that process. +The browser process receives input from the OS, controls the browser UI (e.g. +omnibox, back buttons, the tabstrip, menus, etc). In software mode, it actually +puts the image of the webpage on the screen. + +##### 2. Renderer Processes + +The renderer process is responsible for a given web page. There are typically +many renderer processes running in Chrome at any given time, but just one +Browser process. The renderers are all instances of CrRendererMain, and threads +with the same PID as a given CrRendererMain are that process’s threads. +Chrome tries to put each tab in its own render process, subject to various +restrictions. In general, the rule is different domains go into different +processes, up to some memory-defined limit on process count. CrRendererMain is +where javascript/html/css/etc is running, and in most cases, it is the +bottleneck in your application! + +##### 3. The GPU Process + +Chrome has a single GPU process where GPU accelerated operations are issued to +the graphics driver. We call this process CrGpuMain. +GPU operations are done in a separate process/thread for security and stability +reasons. When you use WebGL in JavaScript, or 3D CSS, or accelerated canvas, +they are being made in the renderer but then sent asynchronously for actual +execution in the GPU process. + +#### The Message Loop + +All threads in Chrome use a message loop, which is roughly a bit of code that +does "while(true) { pop message; run message; }". A nice feature of +about:tracing is that anytime chrome is running a message, it will be traced. +This means that if there is no MessageLoop task on a thread, you can have high +confidence that that thread is idle. + +#### Web page rendering/CSS/layout/reflow/etc is lazy + +Positioning and rendering of renderable elements (divs, etc) is done lazily by +Webkit. For instance: + +* When you move a div, we just set a dirty bit and come around later + and actually move it and update the screen. +* Similarly, when you change an element’s class, we don’t recalculate + its new computed style until the last possible minute. We just set a + dirty bit. + +The actual costs of this laziness show up in the following ways: + +* When javascript code asks for a computed style, or we decide it is + time \[here be dragons\], you may see a trace for recalculateStyle. + If you see that spiking, you're seeing the interaction of classnames + with style cascades and your DOM size/shape. That’s WebKit + inspecting your css and classnames and figuring out what things are + supposed to look like. +* At the beginning of a frame \[see below for definition\], we + recompute styles AND get ready to render. There, you will see + WebViewImpl::layout, which is both style recalc and also us figuring + out what part of (and how) your page should be drawn. +* Painting/Updating: when we go to make a picture of the screen, we + call it painting or updating. This is picture generation, and will + usually include costs like bitmap decompression (if needed), complex + gradient shading, rounded edges, blurriness, text rendering, and so + on. + +#### Compositing vs Software Mode + +Full article: [GPU Accelerated Compositing in +Chrome](/developers/design-documents/gpu-accelerated-compositing-in-chrome) +Chrome renders in either "software mode" or "accelerated compositing mode": + +* In software mode, Chrome software rasterizes the webpage into an + image and blits it onto the screen using the underlying OS' software + drawing primitives. Chrome tracks a "dirty region" on the screen to + minimize the size of the blits for common operations like blinking + cursors, playing videos, and scrolling. + +* In accelerated compositing mode, Chrome breaks the webpage up into + layers, and then each layer is composited together using the GPU. + +Additionally, accelerated mode operates in either single or multi-threaded +modes: + +* In single threaded mode, we periodically stop the webpage to update + the screen. +* In multi-threaded (often referred to as just ‘threaded’) mode, we + can update the screen without stopping the webpage, which allows us + to scroll the page smoothly or run animations without hitching. + +What does stopping the web page entail? In effect, the main thread in the +renderer process is the thing that needs to do the screen updating. When it’s +doing that, it can’t be doing any of the other things that it normally would -- +like running JavaScript. Being able to run script while the screen updates is a +main motivation both for threaded compositing and for web workers. +The configurations to keep in mind, based on Chrome 18, are: + +* Android: multi-threaded accelerated mode +* CrOS: single-threaded accelerated mode +* Desktop: depends on page content. + * When WebGL, Canvas, or 3D CSS is used, single-threaded + accelerated mode. + * Otherwise, software mode is on. + +We’re going to change this as time goes on: we eventually intend to enable +multi-threaded accelerated mode on all platforms and pages. + +#### Frames (as in Frames Per Second) + +It’s important to understand the entire lifecycle of a frame when Chrome is +drawing. The key lifecycle events are outlined for each mode below: + +##### Software Mode + +In software mode, a frame can be found by looking for DoDeferredUpdate in the +trace. DoDeferredUpdate will run requestAnimationFrame, perform a layout (which +is css style recalc plus preparation for rendering), and then paint the screen. +We then send the bitmap to the browser where you will see an +"UpdateBackingStore" which is us putting the resulting picture on the screen. + +##### Single-threaded Accelerated Mode + +In single-threaded accelerated mode, a frame can be found by looking for +DoDeferredUpdate. DoDeferredUpdate does the same steps as before, but instead of +sending the results as pictures to the browser, it sends GL draw calls to the +CrGPuMain for every layer. + +##### Multi-threaded Accelerated Mode + +In threaded accelerated mode, you have to think of there being two types of +frame: the frames generated by the renderer (i.e. what JavaScript can touch), +and copies of these frames that are handed to the compositor to draw. +From the renderer / JavaScript perspective, frames can be identified by the +"CCThreadProxy::beginFrame" trace event, which does the usual steps of calling +requestAnimationFrame, doing layout/style recalc, and painting/updating. At the +end of a beginFrame, we then "commit" the world to the compositor thread. The +renderer has produced a single frame. +The compositor thread is then free to draw many frames based on the world it was +handed. This is extremely useful because the compositor thread can render many +frames e.g. in response to a scroll. Those frames will all be generated from the +same “world” (i.e. page state) -- i.e. nothing will have changed from +JavaScript, but the compositor thread knows how to handle certain types of other +changes like input events (scrolling again) or CSS animations. So even if the +renderer is choking on running all your fatty JavaScript, the compositor can +continue to serenely scroll the page and run CSS animations on elements. On the +compositor’s side of the world, you will see a frame as a +CCThreadProxy::scheduledActionDrawAndSwap. + +#### HTML5 Canvas + +Canvas can be software-accelerated or GPU-accelerated. `about:gpu` will show you +which is the case for your browser / computer configuration. In non-accelerated +mode, canvas calls are executed immediately using software rasterization and are +blocking operations in the main thread of the renderer. In accelerated mode, +canvas calls are converted to GL commands and issued to the CrGpuMain process +for execution. This rendering is ‘deferred’ so the commands are issued to the +GPU process and the main thread is free to continue to run JavaScript while the +GPU process actually renders them and updates the screen. + +#### WebGL + +WebGL is always GPU accelerated. Your WebGL calls are marshalled into a command +buffer and shipped to CrGpuMain where we unpack the commands and make the +equivalent GL or DirectX calls. +If your command buffer fills up, or you call a GL function that requires an +answer from the underlying driver, e.g. glGetError or glGetUniform, you will see +FlushSync call. This FlushSync blocks on the GPU process executing whatever +command you issued and ruins performance. + +#### Input + +Input events are received from the system by the Browser process and then +forwarded to the renderer process. +When tracing an input event, first look for a (very small) ForwardInputEvent +message in CrBrowserMain. This is the browser receiving the input event and +forwarding it to the renderer. After the ForwardInputEvent happens, the render +process will get a HandleInputEvent message. You will see events inside that +HandleInputEvent if it got forwarded into JavaScript. +Note that for flow control reasons, CrBrowserMain will not send more than 1 +input to the renderer process at a time. Rather, it waits on sending another +input until the previous one is acknowledged. The renderer will acknowledge +input events immediately, most of the time. The one exception is mouse +moves/scrolls -- if the screen is dirty (e.g. a DoDeferredUpdate is necessary), +then the renderer will not reply to an input until the DoDeferredUpdate +completes. + +#### Javascript/V8 + +When JavaScript is running, you will (usually) see traces for things that begin +with V8. We haven't instrumented every single thing, but you will see v8.run or +v8.callfunction for common cases. See the below glossary of common trace events +for additional V8 functions that are instrumented (e.g. for event listener +callbacks, setTimeout/setInterval callbacks, etc). +Many JS APIs interact with the browser process synchronously. E.g. cookie +access, IndexedDB operations, synchronous XHR/network operations. When that +happens, you can bracket the suspicious operation with console.time/timeEnd +calls and look on the browser process for activity that appears correlated with +your JS code. See More Investigation Strategies below for examples of how to do +this. + +### Navigating the Tracing View + +Now that you’ve got the theory down, how do you actually interact with the +tracing tool? +This trace assumes that you have opened up a fresh browser, and opened Wikipedia +in one tab and about:tracing in another, hit record in the tracing tab and +scrolled a bit in the WikiPedia tab, then stopped the recording. More detailed +directions on how to do that are[ +here](http://www.chromium.org/developers/how-tos/trace-event-profiling-tool). + +#### Processes & Timelines + +Once you have a trace recorded, you should get something like the following: + +**[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/trace-event-reading/Screen%20Shot%202015-09-02%20at%208.46.48%20PM.png" +width=700>](/developers/how-tos/trace-event-profiling-tool/trace-event-reading/Screen%20Shot%202015-09-02%20at%208.46.48%20PM.png)** + +**This is a visualization of the recorded trace. What you’re seeing is Chrome's multi-process architecture at work, scrolling your page. The first thing to notice is that there are three processes running: the browser (pid=17965), the renderer process for about:tracing (pid=17974) and the renderer process for Wikipedia (pid=17982).** +**Each process has a separate horizontal track, filled with trace events. The track is basically an event timeline for events on that thread/process. Events are the colored, rectangular blocks on the timeline tracks. Time moves from left to right.** + +**[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/trace-event-reading/second.png">](/developers/how-tos/trace-event-profiling-tool/trace-event-reading/second.png)** + +**#### Trace Events** + +**In this case, the data being shown is ~10 seconds, broken down as follows:** + +**[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/trace-event-reading/third.png">](/developers/how-tos/trace-event-profiling-tool/trace-event-reading/third.png)** + +**The keyboard can be used to zoom and pan around inside the timeline. The ‘w’ +and ‘s’ keys zoom in centered around the mouse, and the ‘a’ and ‘d’ keys pan the +timeline left and right. So, with a bit of zooming around, we can look at how a +single mousewheel event propagates through Chrome:** + +### [<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/trace-event-reading/fourth.png">](/developers/how-tos/trace-event-profiling-tool/trace-event-reading/fourth.png) + +**A single rectangle represents a TRACE_EVENT: where it began, and where it ended. When you see a stack of different rectangles on top of each other, it means that trace events were issued inside one another on the same thread. For example:** + +**foo() {** + +**sleep 10ms** + +**bar()** + +**sleep 5ms** + +**}** + +**bar() {** + +**sleep 5ms** + +**}** + +**Would look like this:** + +**[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/trace-event-reading/fifth.png">](/developers/how-tos/trace-event-profiling-tool/trace-event-reading/fifth.png)** + +**To study individual rectangles, you can click on them. This will display +information about the rectangle: its Duration, ThreadDuration (CPU time), +SelfTime (time spent in the current slice, subtracting the time** + +of all the children slices), **ThreadSelfTime** (CPU time spent in the current +slice, subtracting the CPU time for all the children) and **Occurrences** (the +number of times that event appeared in the selection). + +The information is sortable. Clicking on a title from the info table will expand +all the slices for that event. +For the Foo/Bar example, the SelfTime for Foo will be 15ms (20 - 5), while the +SelfTime for Bar will be 5ms (Since it has no know children). + +The ThreadDuration is not available for all events and for all platforms, the +SelfTime is omitted in cases where the Slice has no known children. Asynchronous +events has no SelfTime by definition. + +In addition to clicking, you can drag the mouse in a rectangle over a group of +trace events. This will give you a list of events that intersect that rectangle +and summarize them for you: + +**[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/trace-event-reading/Selection.png">](/developers/how-tos/trace-event-profiling-tool/trace-event-reading/Selection.png)** + +#### Import and Export + +Once recorded, you can give a trace file to someone else. Just press the save +button. The resulting file is just JSON. +To load a trace, use the load button, or grab the standalone trace viewer from +<https://github.com/catapult-project/catapult/tree/master/tracing> + +### Investigating Performance Problems + +Now that you can navigate the basic view, let’s dive into a basic strategy for +investigating a performance problem. Here’s an overview: + +#### Setting up a good trace run + +1. Start with only the tab you’re investigating and about:tracing open + in a fresh browser session (see below for other methods of figuring + out which tab is which if you need multiple). +2. Set up the tab for investigation to right before the point where the + problem will occur (e.g. right before an animation is going to be + triggered, or right before part of the page that scrolls slowly) +3. Start a tracing run in the about:tracing tab +4. Switch to the tab under investigation +5. Pause for a couple seconds to record empty space on the timeline + (makes finding it later easier) +6. Perform the action to trigger the bad performance behavior (e.g. + start the animation or scroll the page). Keeping the recorded + activity under 10 seconds is a good idea. +7. Pause again +8. Switch back to the about:tracing tab and stop the recording. + +#### Investigation strategy + +Now let’s find a problematic frame and see what caused the hitch or slowdown. +See below for more details on the trace events + +1. Look for the pause right before you started the problem action +2. Once you’ve found the beginning of the problem area, look for + regular patterns that indicate drawing updates. + 1. The entire time the renderer process is busy (i.e. doing + anything at all) will be marked by MessageLoop::RunTask + 2. A regular draw update will usually start with one of: + 1. an input event (RenderWidget::OnHandleInputEvent) + 2. a requestAnimationFrame callback + (RenderWidget::AnimationCallback) + 3. a timer firing (ScheduledAction::Execute) + 3. ...and the actual drawing is done in + RenderWidget::DoDeferredUpdate +3. Once you’ve found the pattern indicating frame updates by looking + for a regular block of trace events and zooming in to confirm that + they’re being called from what you expect, zoom back out to look for + a problem area + 1. If you’re investigating a hitch, look for an interruption to the + regular pattern -- a block of tracing events that takes longer + than the others. + 2. If you’re investigating general slowness (e.g. scrolling), check + to see if the entire draw block from the triggering event to the + end of the deferred update are over frame budget (i.e. longer + than 16ms on a 60hz screen). +4. Once you’ve identified a problem frame, it’s time to figure out what + caused that frame to take too long. Options are: + 1. Paint time + 1. Look for PaintRect or CCLayerTreeHost::UpdateLayers events + that take too long + 2. Layout + 1. Look for WebViewImpl::layout events that take too long + 3. JPEG decode/resize + 1. Look for ImageOperations::ResizeSubPixel or + ImagerOperations::ResizeBasic + 4. Heavy input handling + 1. Look for too much activity in + RenderWidget::OnHandleInputEvent +5. An orthogonal option is that you’re GPU bound. + 1. If you have a ton of activity in the GPU process the card can be + swamped -- in this case the renderer process might not be doing + anything (won’t be in MessageLoop::RunTask) while the GPU is + working feverishly. Look for lots of events in the GPU process + but few in the renderer. + 2. Content updates as the GPU draws are under + GPUScheduler::PutChanged, while the actual screen is updated + (timed with a screen refresh, as Chrome vsyncs) during + GLContext::SwapBuffers + +#### Next: Fixing it! + +What to do next depends on the nature of the problem. Options are: + +* Long paint times or long layout + +* Paint’s show up in the web inspector’s timeline, too, so if you + determine that your problem is heavy paints you can use the + inspector to figure out when these paints are happening relative to + your JavaScript events. +* You can also turn on the Chrome flag --show-paint-rects to see which + areas of the screen are painted when, which can help identify what’s + being painted (and from there try to reduce the amount or frequency + of what’s being painted). +* Modify your CSS styles to try to isolate and remove the problem. + This is by far the highest leverage way to make a site faster! + Iterate in the following loop: + * Remove one of: + * An entire element + * A single CSS style (e.g. CSS class) + * A single style modification (e.g. if you set style in JS) + * Grab another trace of the page + * Check if the paint times (PaintRect or UpdateLayers) or style + recalculation and layout (WebViewImpl::layout) times have gone + down. + * If they have, you’ve found your culprit (possibly one of + many). Start adding parts of the style back in (if you + removed a whole class) or experiment with an alternative way + of getting the same visual effect but with different style + rules. + * If they haven’t, repeat the whole process and remove more. + +* Heavy input + * You should be doing as little as possible in your input + handlers. Ensure that your V8EventListener::callListenerFunction + inside of RenderWidget::OnHandleInputEvent take minimal time by + simply saving some state in your input handler and then actually + acting on that state in your requestAnimationFrame callback, for + instance. +* JPEG decode/resize + * Unfortunately there isn’t a lot to do here at the moment. You + can attempt to size your source images such that they won’t get + resized, and you can attempt to invalidate them less frequently, + but if necessary JPEG operations are what’s causing your woes + there isn’t much you can do. +* GPU bound + * If your page is composited and drawing to the GPU, make sure you + aren’t invalidating more layers than necessary. + * If only one thing is moving on the screen (e.g. an + animation) it should be in its own layer + * If you’re scrolling and everything needs to be updated, you + want to ensure that things that aren’t changing are in their + own layers so they don’t get invalidated and can just be + translated on the GPU + * But, if you have too many layers you’ll overwhelm the GPU -- + so don’t put everything in its own layer just for the sake + of it. + * In the future, we’ll have a way to see which layers are + invalidated when (like --show-paint-rects but for composited + mode), but it’s not finished yet. + * An easy way to force layer creation is to add a + -webkit-transform:translateZ(0) to an element, which will stick + it in its own layer but have no visual effect. + * An easy way to see what layers are being created for what + content is to use the “show composited layer render borders” in + about:flags. + +#### Tip: trace event color + +Trace event types will have a common color across all runs and processes. This +means that common events like MessageLoop::RunTask are always the same color, +making them easy to identify. + +#### Tip: which tab am I looking at? + +It can be difficult to discern which tab is which in the renderer process. The +easiest way by far to do this is just not to run any other tabs when you’re +doing a tracing run. This way you’ll only end up with two renderer processes +(one for about:tracing, one for your content tab) +Another method is to use about:memory, which lists all tabs, apps, and +background pages along with their titles and process IDs. You can figure out +which process ID you’re interested in here and then refer to the renderer with +that process ID in about:tracing. + +### Glossary: Common Trace Events + +There are a few common scenarios that can cause performance to suffer that the +tracing tool is good at identifying. These examples are meant to give you some +guidance on common signposts to look for. + +#### Common Events + +* MessageLoop::RunTask + * This notes that the process is busy. It’s important to tell when + the process is even attempting to do anything vs. not, + especially when trying to track down if performance problems are + in the renderer, browser, or GPU processes. +* RenderWidget::OnHandleInputEvent + * This is the browser handling an input event. Your JS event + handling will also be in here as a sub-event + (V8EventListener::callListenerFunction), and you can determine + if that’s taking longer than it should. +* RenderWidget::DoDeferredUpdate + * This is the renderer process updating the screen. + * Note that content may not go to the screen immediately + because it’s a deferred update -- textures may be passed to + the GPU process and from there to an eventual screen buffer, + but these various buffering layers can cause delays. + * The basic steps in a draw are: + * Animation + * Layout (see + * Painting and compositing in software, or updating and + drawing on the GPU +* V8EventListener::callListenerFunction + * This is V8 executing an event listener callback, probably + deferring to JS code you actually wrote. It’s a good place to + stick your own trace events for further detail (see below). +* WebViewImpl::layout + * This is page re-layout, which can be caused by DOM structure and + style changes. + * Page layout shows up in the web inspector’s timeline, too, so if + you determine your problem is layout taking too long you can use + the web inspector’s timeline to track it down (i.e. making + changes to your page to try to reduce the time or frequency of + layout). +* PaintRect + * This is the renderer painting part of the screen that was + invalidated. + * See “Fixing it” above for strategies on what to do if this is + taking too long. +* ScheduledAction::Execute + * This is a setTimeout or setInterval event firing. + * Again, these show up in the web inspector so if you determine + that a setTimeout event is getting in the way (blocking the + renderer from drawing and causing a hitch, for instance) you can + use the inspector to more easily identify and disect the related + JavaScript. +* ImageOperations::ResizeBasic and ImageOperations::ResizeSubPixel + * This is an image being resized, which can be expensive. + * The best way to optimize these is probably to avoid them + entirely whenever possible, e.g. by sizing your images + correctly, but sometimes they’re unfortunately unavoidable. + +### More Investigation Strategies + +#### Adding your own trace events + +If you’re having trouble figuring out what part of your code maps to what part +of the trace, it can be invaluable to add your own trace events. By doing so +from JavaScript you can drop annotations onto the trace timeline, allowing easy +identification of key points in your code (for instance, the beginning of a draw +loop or the entrance of a particularly complicated bit of JS you fear is blowing +your frame budget). +Adding your own events is as simple as calling console.time() and +console.timeEnd(): + +function Foo() { + +console.time(“Foo”); + +var now = Date.now(); + +while (Date.now() < now + 1000); + +console.timeEnd("Foo"); + +} + +See [this +page](http://www.chromium.org/developers/how-tos/trace-event-profiling-tool/tracing-event-instrumentation) +for more information on adding your own trace events to C++ code. + +#### *Determining which IPC message is active* + +To determine what IPC message corresponds with the class and line shown in the +trace: + +1. Click on the event and note the class and line values. + * e.g. `class: 41, line: 783` +2. Open the + [ipc/ipc_message_start.h](https://chromium.googlesource.com/chromium/src/+/HEAD/ipc/ipc_message_start.h) + for your build. + * Protip: If it's not ToT, you can pull the git hash from + about:version and replace \`master\` in the URL with the hash. +3. Look at the IPCMessageStart enum to find your class. (If the enum + values start at line 12, you'll find your class type on line `x+12 + `;) + * e.g. class 41 maps to [line + 53](https://chromium.googlesource.com/chromium/src/+/4d31269c6cafb98eced74df70f5d1ccde3af0a44/ipc/ipc_message_start.h): + `ExtensionMsgStart` +4. Amongst [the xxx_messages.h + files](https://code.google.com/p/chromium/codesearch#search/&q=f:_messages.h&sq=package:chromium&type=cs), + open the one that contains your class. + * e.g. Our match is in[ + extension_messages.h](https://code.google.com/p/chromium/codesearch#chromium/src/extensions/common/extension_messages.h&q=f:_messages.h%20ExtensionMsgStart&sq=package:chromium&type=cs&l=33) +5. Look at the corresponding line number in the xxx_messages.h file. + Your desired declaration will typically be *ending* on the given + line. + * e.g. Line 783 is the end of the + `ExtensionHostMsg_DetailedConsoleMessageAdded` declaration. + We've found our message! + +[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/trace-event-reading/Screen%20Shot%202015-09-02%20at%208.39.51%20PM.png">](/developers/how-tos/trace-event-profiling-tool/trace-event-reading/Screen%20Shot%202015-09-02%20at%208.39.51%20PM.png) + +### Staying Current + +We continuously add new events and features to about:tracing to help us figure +out what’s going on inside of Chrome. Some of the images above may not reflect +all of these features, so don’t be surprised if there are new threads and events +in your about:tracing view that aren’t listed here -- all follow the same basic +pattern. We welcome additional documentation and use cases.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/second.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/second.png.sha1 new file mode 100644 index 00000000000..0003e3644ee --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/second.png.sha1 @@ -0,0 +1 @@ +5a232213d4a5a13836dd2850a2cbe3193c87639c
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/sixth-before-import.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/sixth-before-import.png.sha1 new file mode 100644 index 00000000000..5b972aa9700 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/sixth-before-import.png.sha1 @@ -0,0 +1 @@ +f401fc27483e0fa6310e4e2e3fa212051d5937ab
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/synchanell.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/synchanell.png.sha1 new file mode 100644 index 00000000000..e6fcdf81361 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/synchanell.png.sha1 @@ -0,0 +1 @@ +13c0875afc8ea161bbcebd3fe0c749cb13bd9d17
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/third.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/third.png.sha1 new file mode 100644 index 00000000000..1868215e93b --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace-event-reading/third.png.sha1 @@ -0,0 +1 @@ +e722b024596e73bfae203c5d3f83797a76c475eb
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace.png.sha1 new file mode 100644 index 00000000000..7ee142d4790 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace.png.sha1 @@ -0,0 +1 @@ +99a1d6830576639a6bca1eb1ae09ce0eb8e5a3b6
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace3.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace3.png.sha1 new file mode 100644 index 00000000000..ffb8e9685f7 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/trace3.png.sha1 @@ -0,0 +1 @@ +ad67d35668d92ed44b5b26feafbab6ef5220b46d
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/tracing-event-instrumentation/index.md b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/tracing-event-instrumentation/index.md new file mode 100644 index 00000000000..2e6bcf14113 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/tracing-event-instrumentation/index.md @@ -0,0 +1,149 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +- - /developers/how-tos/trace-event-profiling-tool + - The Trace Event Profiling Tool (about:tracing) +page_name: tracing-event-instrumentation +title: Adding Traces to Chromium/WebKit/Javascript +--- + +See [Trace Event Profiling Tool +(about:tracing)](/developers/how-tos/trace-event-profiling-tool) for more +information on about:tracing + +Sometimes, about:tracing wont show you all the detail you want. Don't worry, you +can add more instrumentation yourself. + +****Trace macros are very low overhead. When tracing is not turned on, trace +macros cost at most a few dozen clocks. When running, trace macros cost a few +thousand clocks at most. Arguments to the trace macro are evaluated only when +tracing is on --- if tracing is off, the value of the arguments dont get +computed.**** + +**[trace_event_common.h](https://code.google.com/p/chromium/codesearch#chromium/src/base/trace_event/common/trace_event_common.h&q=f:trace_event_common.h&sq=package:chromium&type=cs&l=1) +defines the below behavior.** + +## Function Tracing + +The basic trace macros are TRACE_EVENTx, in 0, 1, and 2 argument flavors. These +time the enclosing scope. In Chrome code, just do this: + +> #include "base/trace_event/trace_event.h" + +> // This traces the start and end of the function automatically: + +> void doSomethingCostly() { + +> TRACE_EVENT0("MY_SUBSYSTEM", "doSomethingCostly"); + +> ... + +> } + +In WebKit/Source/WebCore/, you can trace this way: + +> #include "platform/TraceEvent.h" + +> void doSomethingCostly() { + +> TRACE_EVENT0("MY_SUBSYSTEM", "doSomethingCostly"); + +> ... + +> } + +****The "MY_SUBSYSTEM" argument is a logical category for the trace event. This +category can be used by the UI to hide certain kinds events, or even skip them +from being collected. A common practice is to use the chromium module in which +the code lies, so for example, code in content/renderer gets the "renderer" +category.**** + +**TRACE_EVENT1 and 2 allows you to capture 1 and 2 pieces of data long with the +event. So, for example, this records the paint dimensions number along with the +paint:** + +**void RenderWidget::paint(const Rect& r) {** + +**TRACE_EVENT2("renderer", "RenderWidget::paint", "width", r.width(), "height", +r.height());** + +## Javascript Tracing + +You + +**********can instrument javascript code as well:********** + +function Foo() { + +console.time(“Foo”); +var now = Date.now(); + +while (Date.now() < now + 1000); + +console.timeEnd("Foo"); + +} + +**Note that currently, console.time/timeEnd spam the inspector console when it +is open --- when inspector is closed, there is little or no performance penalty +to the API.** + +## Counters +## To track a value as it evolves over time, use TRACE_COUNTERx or TRACE_COUNTER_IDx. For example: + +> ## #include "base/trace_event/trace_event.h" + +> ## shmAlloc(...) { +> ## ... +> ## TRACE_COUNTER2("shm", "BytesAllocated", "allocated", g_shmBytesAllocated, +> "remaining", g_shmBytesFree); +> ## } + +> ## shmFree(...) { +> ## ... +> ## TRACE_COUNTER2("shm", "BytesAllocated", "allocated", g_shmBytesAllocated, +> "remaining", g_shmBytesFree); +> ## } + +## Sometimes a counter is specific to a class instance. For that, use the _ID variant: + +> ## Document::didModifySubtree(...) { +> ## TRACE_COUNTER2("dom", "numDOMNodes", calcNumNodes()); + +> ## } + +## This will create a different counter for each ID. + +## Asynchronous Events + +Sometimes, you will have an asynchronous event that you want to track. For this, +use TRACE_EVENT_ASYNC_BEGINx and TRACE_EVENT_ASYNC_ENDx. For example: + +> #include "base/trace_event/trace_event.h" + +> AsyncFileOperation::AsyncFileOperation(...) { +> TRACE_EVENT_ASYNC_BEGIN("io", "AsyncFileOperation", this); + +> } + +> void AsyncFileOperation::OnReady() { + +> TRACE_EVENT_ASYNC_END("io', "AsyncFileOperation", this); +> ... +> } + +Async operations can start and finish on different threads, or even different +proceses. Association is done by the concatenation of the name string and the +third "id" argument. The nearest match in time establishes the relationship. + +## Resources + +* [trace_event_common.h](https://code.google.com/p/chromium/codesearch#chromium/src/base/trace_event/common/trace_event_common.h&q=f:trace_event_common.h&sq=package:chromium&type=cs&l=1), + the basic readme for trace_event instrumentation +* [Tracing Ecosystem + Explainer](https://docs.google.com/document/d/1QADiFe0ss7Ydq-LUNOPpIf6z4KXGuWs_ygxiJxoMZKo/edit?pli=1#heading=h.dytg6ymhhy0b) +* [Trace Event + Format](https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/edit?pli=1)
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/01-followalong.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/01-followalong.png.sha1 new file mode 100644 index 00000000000..545eb4f0e13 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/01-followalong.png.sha1 @@ -0,0 +1 @@ +b729fce8e136eb430da529918ee2367e2d749849
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/02-lefttoright.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/02-lefttoright.png.sha1 new file mode 100644 index 00000000000..7065716e7dd --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/02-lefttoright.png.sha1 @@ -0,0 +1 @@ +b2dfa1aeec41da838ec3877146b7784e87e3fe32
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/03-individual trace.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/03-individual trace.png.sha1 new file mode 100644 index 00000000000..961e08d5c8c --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/03-individual trace.png.sha1 @@ -0,0 +1 @@ +639e1bf844cb7eb8a0c580b6c3786bb246f2a6db
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/04-information is.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/04-information is.png.sha1 new file mode 100644 index 00000000000..7da84b31583 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/04-information is.png.sha1 @@ -0,0 +1 @@ +579a50b9604f5485ba4c6b82bf0fc6f248b22bd6
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/1.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/1.png.sha1 new file mode 100644 index 00000000000..2d815cc4cc4 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/1.png.sha1 @@ -0,0 +1 @@ +806e3a615c8941ba5eb7bbd810382758c185665b
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/10.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/10.png.sha1 new file mode 100644 index 00000000000..e3ec36ade3c --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/10.png.sha1 @@ -0,0 +1 @@ +4942738f244d7459e1b9227abff9fdfaad829ffb
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/11.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/11.png.sha1 new file mode 100644 index 00000000000..84b44bfb9e3 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/11.png.sha1 @@ -0,0 +1 @@ +d9f11f7b9d16db5248e12cedf7e0a8ea2c0de267
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/12.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/12.png.sha1 new file mode 100644 index 00000000000..c9dd7281f56 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/12.png.sha1 @@ -0,0 +1 @@ +9ea43c12b5eb9e7796ca6661e90d418f13dadb18
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/13.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/13.png.sha1 new file mode 100644 index 00000000000..99219760d4c --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/13.png.sha1 @@ -0,0 +1 @@ +a40267b5171b63410ab5178bebc916be7f0aee58
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/14.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/14.png.sha1 new file mode 100644 index 00000000000..26b3a6ec97b --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/14.png.sha1 @@ -0,0 +1 @@ +5dc833db1ff85b97867baa982d2f77eb024cdfb5
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/15.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/15.png.sha1 new file mode 100644 index 00000000000..8eeb1c63f24 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/15.png.sha1 @@ -0,0 +1 @@ +7cdfd69c03a41a728331e69c3bca710b0008a9a2
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/16.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/16.png.sha1 new file mode 100644 index 00000000000..52730e98f9d --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/16.png.sha1 @@ -0,0 +1 @@ +84a2560a4fd84ac472abb0248ef6c63e287ee03c
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/17.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/17.png.sha1 new file mode 100644 index 00000000000..9c0a8726493 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/17.png.sha1 @@ -0,0 +1 @@ +62c42bf85ee8f35b85b7aa96eaea286168cfadfa
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/18.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/18.png.sha1 new file mode 100644 index 00000000000..2e92fe28043 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/18.png.sha1 @@ -0,0 +1 @@ +06ffc4c9b95077fdd3e0c6f1238e3f191ea51831
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/19.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/19.png.sha1 new file mode 100644 index 00000000000..22f0199e030 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/19.png.sha1 @@ -0,0 +1 @@ +1b846b513689e76d59fba87d07593973aabfa53c
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/2.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/2.png.sha1 new file mode 100644 index 00000000000..2c727595fa0 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/2.png.sha1 @@ -0,0 +1 @@ +2052eb1e45d19b0391d7cc675c7a8b2de33bdb1a
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/20.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/20.png.sha1 new file mode 100644 index 00000000000..0bfb24c21a8 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/20.png.sha1 @@ -0,0 +1 @@ +40c2c5068273ccf1354a2b62f88b974291b388d8
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/21.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/21.png.sha1 new file mode 100644 index 00000000000..61c946730bd --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/21.png.sha1 @@ -0,0 +1 @@ +b7144bba70bfa028486d6e47e3b392a778086019
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/22.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/22.png.sha1 new file mode 100644 index 00000000000..d3ae56170bd --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/22.png.sha1 @@ -0,0 +1 @@ +b6b63e80c9ec2026bb891216944892eae7c91e8a
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/3.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/3.png.sha1 new file mode 100644 index 00000000000..36d6a0c7d55 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/3.png.sha1 @@ -0,0 +1 @@ +f32b55e7b3010f4bccc7e339f422dbc30ac9ee77
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/4.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/4.png.sha1 new file mode 100644 index 00000000000..b02361269ad --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/4.png.sha1 @@ -0,0 +1 @@ +dd110013d006387da6a6d7a4d95bba6de3f7b566
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/5.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/5.png.sha1 new file mode 100644 index 00000000000..f8663346fc6 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/5.png.sha1 @@ -0,0 +1 @@ +0d2f411135727c6276006bb8c6e36f7e5b8ac075
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/6.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/6.png.sha1 new file mode 100644 index 00000000000..10f18b1eb89 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/6.png.sha1 @@ -0,0 +1 @@ +e47313d1c0d53ecb71ace8948d5663f117dca008
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/7.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/7.png.sha1 new file mode 100644 index 00000000000..4f49fbb278b --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/7.png.sha1 @@ -0,0 +1 @@ +36f8743c20bdf136d57aafadcbec7061576033db
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/8.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/8.png.sha1 new file mode 100644 index 00000000000..83a93e26ed7 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/8.png.sha1 @@ -0,0 +1 @@ +7b847085802a03a400b5434c9fff49441ec9a208
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/9.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/9.png.sha1 new file mode 100644 index 00000000000..6fdf4530543 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/9.png.sha1 @@ -0,0 +1 @@ +631209d413507717fed7b9e5d4948bf5c669dede
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/inbox_frameviewer_trace.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/inbox_frameviewer_trace.sha1 new file mode 100644 index 00000000000..4400597f717 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/inbox_frameviewer_trace.sha1 @@ -0,0 +1 @@ +2313091f96299278fbd1a3f038bc137e4bb86509
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/inbox_normal_trace.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/inbox_normal_trace.sha1 new file mode 100644 index 00000000000..821436b4e28 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/inbox_normal_trace.sha1 @@ -0,0 +1 @@ +d1f2ae7442ecb87cec30259a08390d816aaf3847
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/index.md b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/index.md new file mode 100644 index 00000000000..dbe2838b7ac --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/index.md @@ -0,0 +1,566 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +- - /developers/how-tos/trace-event-profiling-tool + - The Trace Event Profiling Tool (about:tracing) +page_name: using-frameviewer +title: FrameViewer How-To +--- + +# *wiltzius@* + +For a web application to respond smoothly to user touch input the application +needs to receive input events in JavaScript, react to them, and then allow time +for the browser to render any changes made to the page -- all within a 16ms +frame budget. + +This can be challenging, and it can be instructive to look under the hood to see +what the browser is doing each frame. This is what Chromium’s Frame Viewer does, +although it was built with debugging Chrome in mind, not debugging web apps. +Chromium devs and adventurous outsiders may nevertheless be curious what’s +happening in the browser on a per-frame basis. + +Prerequisites: + + [Get set up to record + traces](http://www.chromium.org/developers/how-tos/trace-event-profiling-tool/recording-tracing-runs); + recommended to use adb_profile_chrome.py from + <https://github.com/johnmccutchan/adb_trace> (also in Chrome’s source tree + under src/tools/perf/) + + Read the [Frame Viewer + Overview](/developers/how-tos/trace-event-profiling-tool/frame-viewer) for + information on how to record a frame viewer trace, rather than a standard + trace. The short version is you need a number of non-default tracing + categories enabled; the easiest way to do this is to use the + adb_prorfile_chrome script (see above) and pass --trace-frame-viewer to it. + + Frame-viewer only works on the latest versions of Chrome, and with the + latest rendering architecture. For some features to work both the version of + Chrome used to view traces and the version used to record traces must be run + with impl-side-painting enabled (--enable-impl-side-painting), and the + version of Chrome used to view the trace must be run additionally with + --enable-skia-benchmarking. See Frame Viewer’s [Getting + Started](/developers/how-tos/trace-event-profiling-tool/frame-viewer) for an + example command line. + + This entire document assume you know a lot about how the web platform works + and a lot about how Chrome works. Performance of a sophisticated rendering + system like a modern browser is very complicated, so please do not use this + to blindly infer that any particular operation is cheap or expensive -- + rather, use this tool to inform your own experimentation and debugging. + +### Simplified Version of Browser Rendering + +Before trying to read a Frame Viewer trace, a few fundamentals: + +After its loaded, the page changes in response to two inputs: user interaction +mediated by the user agent (default pressed button styles, scrolling, etc) and +updates to the DOM from JavaScript. From there, a cascade of effects through +several rendering sub-systems eventually produces new pixels on the user’s +screen. + +The main subsystems are: + + Parsing, which turns a chunk of HTML into DOM nodes + + Style, which resolves CSS on the DOM + + Layout, which figures out where DOM elements end up relative to one another + + Paint setup, sometimes referred to as recording, which converts styled DOM + elements into a display list (SkPicture) of drawing commands to paint later, + on a per-layer basis + + Painting, which converts the SkPicture of drawing commands into pixels in a + bitmap somewhere (either in system memory or on the GPU if using Ganesh) + + Compositing, which assembles all layers into a final screen image + + and, less obviously, the presentation infrastructure responsible for + actually pushing a new frame to the OS (i.e. the browser UI and its + compositor, the GPU process which actually communicates with the GL driver, + etc). + +We’ll focus on 1-6; the browser compositor and GPU process take up resources too +but these operations don't map very meaningfully to page content. + +Adding a new DOM element that’s visible on-screen will trigger work in every one +of the systems above. In bad cases any one of them can cost tens of milliseconds +(or more), meaning every one of them can be considered a liability for staying +within frame budget. + +One way to keep your animations inexpensive is to avoid stages of this pipeline +altogether. For instance, if the DOM remains untouched in a given frame but one +particular <div> changes from a red background to a blue background, no +parsing needs to happen -- but style needs to be updated on at least that +<div>, and because CSS’s inherited nature this can often trigger style +recalculation on other parts of the DOM as well. + +Note that user interactions that the browser handles, rather than the +application, are largely unexceptional: clicking a button changes its style +(adding pseudo-classes) and those style changes need to be resolved and later +stages of the pipeline run (e.g. the depressed button state needs to be painted, +and then the page needs to be re-composited with that new painted content). + +The browser has multiple threads, and because of the dependencies implied in the +above pipeline which thread an operation runs on matters a lot when it comes to +finding the rendering bottleneck. Style, layout, and some paint setup operations +run on the renderer’s main thread, which is the same place that JavaScript runs. +Parsing gets its own thread (in most cases), as does compositing and painting. + +Keep in mind that JavaScript is single threaded and does not yield by default, +which means that JavaScript events, style, and layout operations will block one +another. That means if e.g. the style system is running, Javascript can’t +receive new events. More obviously, it also means that other JavaScript events +(such as a timer firing, or an XHR success callback, etc) will block JS events +that may be very timely -- like touch events. NB this essentially means +applications responding to touch input must consider the JavaScript main thread +the application’s UI thread, and not block it for more than a few milliseconds. + +The above explanation simplifies a lot, but should be enough to get going. Two +exceptions worth pointing out though: first, scrolling is “special” in that it +happens outside of the main JavaScript context, and scroll positions are +asynchronously reported back to the main thread and updated in the DOM. This +prevents janky scrolling even if the page executes a lot of JavaScript, but it +can get in the way if the page is well-behaved and wants to respond to +scrolling. Second, the pipeline above isn’t strictly hierarchically ordered -- +that is, sometimes you can update style without needing to re-lay-out anything +and without needing to repaint anything. A key example is CSS transforms, which +don’t alter layout and hence can skip directly from style resolution (e.g. +changing the transform offset) to compositing if the necessary content is +already painted. + +### Introducing Frameviewer + +For the rest of this document to make sense you’ll need to get set up to record +frame viewer traces. See the [Frame Viewer +Overview](/developers/how-tos/trace-event-profiling-tool/frame-viewer) for +instructions. + +Caveats: Frame Viewer only works on the very latest Chrome rendering +architecture (both for the Chrome where the trace is recorded and the Chrome +where its viewed; see the above link for info on how to get Chrome into that +mode), and it… can be buggy. Don’t say we didn’t warn you. + +Let’s start with something simple. Here’s a frame viewer trace of scrolling +mobile.nytimes.com + +The trace file being screenshotted in this section is attached to this page, as +are all the traces referenced here, and can be +[downloaded](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/nytimes_scroll_trace) +and opened in about:tracing to follow along. + +[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/using-frameviewer/01-followalong.png">](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/01-followalong.png) + +Lots of stuff on the screen. Let’s try to make sense of it. + +### Navigating the Basic Tracing View + +Before even touching the Frame Viewer, let’s examine some standard trace events +as a refresher. There’s more detail in [this +document](http://www.chromium.org/developers/how-tos/trace-event-profiling-tool/trace-event-reading) +about trace events and how to read them, but it’s a bit stale. Below is an +updated, shortened recap. + +#### Processes & Timelines + +#### What you’re seeing is Chrome's multi-process architecture at work, scrolling your page. The first thing to notice is that there are three processes running: the browser (pid=16099) and the renderer process for nytimes.com (pid=23360). + +#### Each process has a separate horizontal track, filled with trace events. The track is basically an event timeline for events on that thread/process. Events are the colored, rectangular blocks on the timeline tracks. Time moves from left to right. + +[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/using-frameviewer/02-lefttoright.png">](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/02-lefttoright.png) + +#### Panning and Zooming with the Keyboard + +#### **The keyboard can be used to zoom and pan around inside the timeline. The ‘w’ and ‘s’ keys zoom in centered around the mouse, and the ‘a’ and ‘d’ keys pan the timeline left and right.** + +#### Trace Events + +#### In this case, the data being shown is ~5 seconds. Zooming in on a section of the trace for more detail, we can make out individual trace event records. + +[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/using-frameviewer/03-individual%20trace.png">](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/03-individual%20trace.png) + +A single rectangle represents a TRACE_EVENT: where it began, and where it ended. +When you see a stack of different rectangles on top of each other, it means that +trace events were issued inside one another on the same thread. For example: + +```none +foo() { +``` + +```none + sleep 10ms +``` + +```none + bar() +``` + +```none + sleep 5ms +``` + +```none +} +``` + +```none +bar() { +``` + +```none + sleep 5ms +``` + +```none +} +``` + +Would look like this: + +[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/using-frameviewer/1.png">](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/1.png) + +To study individual rectangles, you can click on them. This will display +information about the rectangle: its Duration, ThreadDuration (CPU time), +SelfTime (time spent in the current slice, subtracting the time of all the +children slices), ThreadSelfTime (CPU time spent in the current slice, +subtracting the CPU time for all the children) and Occurrences (the number of +times that event appeared in the selection). The information is sortable. +Clicking on a title from the info table will expand all the slices for that +event. + +[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/using-frameviewer/04-information%20is.png">](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/04-information%20is.png) + +For the Foo/Bar example, the SelfTime for Foo will be 15ms (20 - 5), while the +SelfTime for Bar will be 5ms (Since it has no traced children). + +The ThreadDuration is not available for all events and for all platforms, the +SelfTime is omitted in cases where the Slice has no known children. Asynchronous +events have no SelfTime by definition. + +In addition to clicking, you can drag the mouse in a rectangle over a group of +trace events. This will give you a list of events that intersect that rectangle +and summarize them for you: + +[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/using-frameviewer/summarize.png">](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/summarize.png) + +### Navigating Frame Viewer Mode + +What Frame Viewer adds beyond the basic trace event system is a dump of the +page’s state taken each time the renderer produces aframe. This is very useful +when trying to visualize what’s happening from frame to frame. To see the state +of the page’s layer tree for a frame, click one of the green circles along the +top of the Renderer process track: + +[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/using-frameviewer/process.png">](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/process.png) + +You’ll get frames on the bottom of the screen that show the browser’s layer tree +for this frame (on the left) as well as an image of the page with outlines for +all the page’s layers (on the right). + +[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/using-frameviewer/2.png">](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/2.png) + +Checkboxes in the layer view control what information is included in the page +visualization: the most useful are typically “other layer’s / passes” (to view +the whole page, rather than just the layer selected), “invalidations” which +shows what got dirtied that frame for repainting, and “contents” which attempts +to fill in the actual pixels for each layer by rasterizing the SkPictures for +each layer (the SkPicture being essentially a DisplayList Chrome internally uses +to store paint operations and which also gets dumped along with the layer tree +each frame when frame viewer is on). The “contents” view doesn’t always work +well (e.g. text gets garbled) and you’ll need --enable-skia-benchmarking passed +to whatever Chrome you’re using to view the trace. + +[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/using-frameviewer/3.png">](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/3.png) + +The layer visualization can get crowded, so the mouse controls are very useful. +You can pan with [<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/using-frameviewer/4.png">](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/4.png), +zoom in and out with [<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/using-frameviewer/5.png">](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/5.png), +and rotate (in 3D, because we’re nerds) with [<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/using-frameviewer/6.png">](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/6.png), +while [<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/using-frameviewer/7.png">](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/7.png) +allows you to select a layer for more detail about it. + +[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/using-frameviewer/8.png">](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/8.png) + +When selected everything the compositor knows about the layer is shown in the +bottommost frame. The “layerName” property is interesting because it maps the +layer back to its root element in the DOM, such as div#content or the #document + +Selecting an invalidation tells you what layer the invalidation happened on as +well as the invalidation’s bounds. Cross-reference the layer number with one of +the layers in the layer tree on the left for more info about that layer. + +Layers with invalidations have SkPictures associated with them. Clicking on the +SkPicture link will show you more information about the relevant SkPicture +recording. You can also access these recordings by selecting the blue dots along +the top of the Renderer’s track in the trace view; the pictures will appear at +different times than the frames because they’re located at the time they got +recorded, rather than the time they were played back to produce a frame. This +might be within the same frame, if an on-screen invalidation occurred that +frame, or it might be much earlier if a picture was recorded and the compositor +has been using the picture to produce frames for some time afterward (this will +happen with composited scrolls and with CSS transform animations in particular, +since the compositor can run these on its own). + +[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/using-frameviewer/9.png">](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/9.png) + +Frame viewer’s best feature is that is captures all of this information on a +per-frame basis. The arrow keys move between frames while trying to retain the +same view, so you can step through frame by frame and watch layer positions move +with respect to one another or see invalidations appear. + +[<img alt="image" src="http://jankfree.org/images/output_optimized_frame.gif" +height=376 width=400>](http://jankfree.org/images/output_optimized_frame.gif) + +This information, combined with the timing information encoded in the trace +events, provides a powerful view into the performance of a web application. + +### The Critical Path + +Taking a trace of a page that makes a change that requires repainting in +response to touch input illustrates the entire pipeline in action (and in this +case, working well). + +The traces in this section are all from +[inbox_app.html](http://git.chromium.org/gitweb/?p=chromium/src.git;a=blob_plain;f=tools/perf/page_sets/key_silk_cases/inbox_app.html;hb=HEAD) +in the Silk page set. The trace files used are available here ([normal +trace](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/inbox_normal_trace)) +and here ([frameviewer +trace](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/inbox_frameviewer_trace)). + +[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/using-frameviewer/10.png">](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/10.png) + +Zooming in it’s possible to follow a frame propagating through the Renderer +process: + +[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/using-frameviewer/11.png">](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/11.png) + +*Open the trace file yourself to zoom in further and see individual events* + + Input event comes in from the browser process (not shown, but visible in its + own track higher up in the trace) and gets delivered to the compositor + thread. This is a tiny slice in the above trace that includes + “InputEventFilter::ForwardToHandler” + + The input event gets routed from the compositor thread to the main thread. + This kicks off Blink’s input event handling, bottoming out in V8 (i.e. the + JavaScript touchmove event handler running) + + Blink begins a new animation frame, doing some of its own bookkeeping as + well as calling requestAnimationFrame callback inside of + “WebViewImpl::animate” + + JavaScript has modified the page since the last frame (presumably either in + the rAF callback or the input event handler), triggering a layout. The first + part of this is style recalculation, visible as Document::updateStyle + + Part of the on-screen DOM has been invalidated, so Blink repaints a chunk of + the screen covering the invalidated area. This records drawing commands into + an SkPicture, visible in the trace as Picture::Record events. Layer + properties (such as transforms, scroll offsets, and opacity) are also + updated in Blink’s copy of the layer tree. + + The new recordings and updated layer tree are transferred from the Blink + thread to the compositor thread in ThreadProxy::BeginMainFrame::Commit. + During this time the main thread is blocked on the compositor thread. + + The compositor considers the position of all layers and sorts all of the + document’s content layer tiles to decide what order to rasterize them (this + is for prioritization; on-screen tiles get highest priority followed by any + prepainted tiles that might be on the screen soon). This is the + ::UpdateTilePriorities and ::ManageTiles + + Some tiles needed for this frame get rasterized in Picture::Raster events + (this trace is using Ganesh to rasterize tiles, so rasterization occurs on + the compositor thread and actually represents the generation of GL commands + for the tile contents, not filling in a bitmap which happens on the GPU). + + Shortly after the rasterization completes the compositor thread’s draw + deadline arrives, so it does a bunch of bookkeeping to decide where exactly + to draw each tile on the screen (LayerTreeHostImpl::PrepareToDraw) and then + sends this frame to the browser compositor (DelegatingRenderer::DrawFrame) + and swaps the framebuffer (DelegatingRenderer:SwapBuffers) + +That’s the event flow, but it’s difficult (/impossible) to look at a trace and +understand what actually changing on-screen in this frame. + +This is where Frame Viewer comes in. In a Frame Viewer trace of the same +interaction, inspecting a couple frames around this one shows how the layers are +moving from frame to frame. Here’s one: + +[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/using-frameviewer/12.png">](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/12.png) + +Pressing one of the right/left arrow keys lets us step to the previous/next +frame. Here’s the next one: + +[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/using-frameviewer/13.png">](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/13.png) + +They look almost the same, but the rectangle offset from the others, which is a +layer that’s moving in response to touch input, has changed offsets slightly. +Also note that a different green circle in the list of frames along the top of +the Renderer track is now selected. + +It becomes more obvious what’s changing when we enable the “Contents” checkbox: + +[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/using-frameviewer/14.png">](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/14.png) + +Remember from earlier we saw rasterization happen in this frame though, not just +a layer changing position. You can see what got invalidated by turning on the +“Invalidations” checkbox: + +[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/using-frameviewer/15.png">](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/15.png) + +Clicking on the red invalidation rect, we see that it’s for layer 32: + +[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/using-frameviewer/16.png">](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/16.png) + +Selecting layer 32 in the list of layers on the left, or disabling the +invalidations and selecting the layer itself in the viewer rather than the +invalidation rect, tells us more about that layer: + +[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/using-frameviewer/17.png">](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/17.png) + +There’s a lot of information here, but the most interesting is probably the +layerName which links this layer to the DOM; in this case, “RenderBlock +APP-DISMISSABLE-ITEM class='message'” + +We can also get more info on the associated SkPicture for this layer for this +frame by clicking the picture link. This opens up the SkPicture debugger: + +[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/using-frameviewer/18.png">](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/18.png) + +Which has a list of all the draw operations stored in the SkPiture on the left +and a timing graph that shows the cost of each draw operations as a vertical +line. Selecting vertical lines will replay the picture up to that point, which +helps identify what a given draw op is doing and letting you understand what the +most expensive draw operations in the SkPicture are. + +Important caveat: this works by replaying the SkPicture locally, on the machine +used to view tracing. That means that the timing information will not be an +accurate representation of performance on the device the trace was taken on! +Furthermore, at this point all picture playback in tracing uses the software +rasterizer, even if the picture was actually rastered with Ganesh when +displaying the frame originally! Despite these two big limitations, the picture +debugger can still be helpful to understand relative operation costs. + +### Anatomy of a Performance Problem + +Lastly, a couple isolated examples of performance problems. A real app usually +has a combination of problems and may go beyond these simple examples, but these +are common bottlenecks shown on their own. + +Important caveat: tracing always imposes some amount of overhead on the +browser’s regular operation. This is usually negligible for standard traces, but +Frame Viewer traces are expensive and timing is not necessarily representative +for Frame Viewer traces. It’s more useful to see what’s going on, rather than +how long a particular operation took. In particular the DrawLayers operation on +the compositor thread is expensive since it does most of the frame dump. + +#### Excess Javascript / Touch Responsiveness + +Remember, the JavaScript main thread is a web app’s UI thread. Here’s an example +where a JS event handler that spends 50ms in V8 during the requestAnimationFrame +callback gets in the way of touch events, causing a long stall in the rendering +pipeline: + +[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/using-frameviewer/19.png">](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/19.png) + +Note the compositor thread is essentially idle during this time since the main +thread can’t run additional JavaScript to process new touch events while its +busy running the long rAF callback. The user would not see a new Renderer frame +during this period (jank). + +The compositor is capable of running certain animations on its own (composited +scroll and accelerated CSS animations), which it can run without waiting on JS. +However with a touch event handler registered, as is the case on this page, the +compositor thread must wait on the Blink main thread to process the touch event +before responding to it by e.g. scrolling because JavaScript might call +preventDefault on the touch event. + +#### Unexpected Painting + +Sometimes the only reasonable way to achieve an effect is to paint, but +sometimes either Blink gets overeager and invalidates more than seems necessary +or JavaScript manipulates style that invalidates more than it needs to. + +Frame viewer is great for catching these cases. + +For instance, look at this jsfiddle example from the Silk page set: +<http://jsfiddle.net/ugkd4/9/embedded/result/> + +Here’s a trace ([trace +file](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/repaint_example_trace)) +of that animation running for a few seconds. + +It’s supposed to demonstrate performing a clip with composited layers, so there +shouldn’t be any painting going on. Stepping through the frames, though, we +notice an odd invalidation at the beginning of each animation: + +[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/using-frameviewer/20.png">](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/20.png) + +What’s that red rectangle doing there? Clicking on its associated layer and +looking at layerName reveals it as “RenderButton BUTTON id=’button’” + +OK, so what’s going on with the button? The main thread frame that produced this +invalidation precedes it in the CrRendererMain timeline, and shows a JavaScript +timer firing: + +[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/using-frameviewer/21.png">](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/21.png) + +This makes sense, since referring to our example code the timer is firing once a +second to restart the animation. + +So we know something in that timer’s JS block caused a style recalculation +(visible under the timer’s V8 execution block). Unfortunately there the trail +goes cold, because we don’t know what style change did it. We can start +commenting out style changes and seeing if the invalidation goes away, however. + +A few rounds of that later, we have a simple reduction: + +<http://jsfiddle.net/3wMzq/1/embedded/result/> + +And its [corresponding +trace](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/repaint_example_reduced_trace). + +[<img alt="image" +src="/developers/how-tos/trace-event-profiling-tool/using-frameviewer/22.png">](/developers/how-tos/trace-event-profiling-tool/using-frameviewer/22.png) + +Nothing is changing on screen, and we’ve stripped out the additional DOM and all +JavaScript except the empty click handler, which gets called once a second… and +it’s still repainting! + +At which point it becomes clear that this is in fact a bug in Chrome, which one +[files](https://code.google.com/p/chromium/issues/detail?id=369358). + +Happy hacking!
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/nytimes_scroll_trace.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/nytimes_scroll_trace.sha1 new file mode 100644 index 00000000000..bc30169eeb7 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/nytimes_scroll_trace.sha1 @@ -0,0 +1 @@ +31f8efd0218500ee0c8916dd5575987129ec9111
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/output_optimized_frame.gif.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/output_optimized_frame.gif.sha1 new file mode 100644 index 00000000000..821e9fdbe64 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/output_optimized_frame.gif.sha1 @@ -0,0 +1 @@ +b774396339433982f409599d05b85a33a4b792de
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/process.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/process.png.sha1 new file mode 100644 index 00000000000..84b44bfb9e3 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/process.png.sha1 @@ -0,0 +1 @@ +d9f11f7b9d16db5248e12cedf7e0a8ea2c0de267
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/repaint_example_reduced_trace.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/repaint_example_reduced_trace.sha1 new file mode 100644 index 00000000000..b9dc0db24b1 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/repaint_example_reduced_trace.sha1 @@ -0,0 +1 @@ +2d6590425df9e92b39fa46b9250a071faaf16baf
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/repaint_example_trace.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/repaint_example_trace.sha1 new file mode 100644 index 00000000000..7364e645a7e --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/repaint_example_trace.sha1 @@ -0,0 +1 @@ +202fc924c87d8f6875b94af68066f0592b89db21
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/summarize.png.sha1 b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/summarize.png.sha1 new file mode 100644 index 00000000000..678306a0d70 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/trace-event-profiling-tool/using-frameviewer/summarize.png.sha1 @@ -0,0 +1 @@ +691e9cdbbb7453270424c836a02af22f59b0fd49
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/using-drmemory/index.md b/chromium/docs/website/site/developers/how-tos/using-drmemory/index.md new file mode 100644 index 00000000000..5791820f319 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/using-drmemory/index.md @@ -0,0 +1,232 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: using-drmemory +title: Using Dr. Memory +--- + +[TOC] + +### Note: Dr.Memory bot has retired and the documentation here is obsolete (added on Jul. 27, 2017) + +### Dr. Memory is a new open-source tool for finding memory errors - similar to Memcheck (Valgrind) but with Windows support, including detection of Windows handle leaks and GDI usage errors. + +Dr. Memory is running on the MFYI waterfall [MFYI +waterfall](http://build.chromium.org/p/chromium.memory.fyi/waterfall?builder=Chromium+Windows+Builder+(DrMemory)&builder=Windows+Unit+(DrMemory)&builder=Windows+Browser+(DrMemory)+(1)&builder=Windows+Browser+(DrMemory)+(2)&reload=none) +where it finds bugs in Chromium on Windows. + +If you want to try Dr. Memory on your machine, please do the following: + +* First of all, you need Windows. Win7 x64 is preferred. DrMemory + supports Linux, but the support is not as robust. + +* [Build](/developers/how-tos/build-instructions-windows) Chromium + tests on Windows with the following GN configuration (you can save + some time by building only the small tests like googleurl, ipc, + base, net to start with). Build with the following setting in order + to disable inlining and FPO for better callstacks: + + enable_iterator_debugging = false + + is_component_build = true + is_debug = false + +* The Dr. Memory binaries are downloaded from Google Storage + automatically (on Windows) into the third_party/drmemory directory. +* Now you can run chromium tests like this: + tools\\valgrind\\chrome_tests.bat -t *<test>* --tool drmemory_light # + only search for unaddressable accesses and uses-after-free + or + tools\\valgrind\\chrome_tests.bat -t *<test>* --tool drmemory_full # + search for uninits and leaks etc as well + Alternatively, if you prefer Msysgit, you can also use + tools/valgrind/chrome_tests.sh with the same arguments. Just be aware that + the bots use the .bat script. +* You can use --build-dir to select between Debug and Release, for + example: tools\\valgrind\\chrome_tests.bat -t base_unittests --tool + drmemory_light --build-dir=out\\Release +* You can use --gtest_filter to run an individual test or a subset of + tests, for examle: + tools\\valgrind\\chrome_tests.bat -t base_unittests --tool drmemory_light + --gtest_filter=A\* +* You can use --drmemory_ops to add additional Dr. Memory options, for + example: tools\\valgrind\\chrome_tests.bat -t base_unittests --tool + drmemory_light --drmemory_ops "-pause_at_error" + +* Extra Dr. Memory specific options can be passed via option + --drmemory_ops, for example: tools\\valgrind\\chrome_tests.bat + --drmemory_ops "-fuzz" for [fuzzing the test with Dr. + Memory](/developers/testing/dr-fuzz). +* It will print you some error reports at the end. + +If for some reason you cannot reproduce a bot failure on your Windows machine, +look for the exact command that started the tests and run that. For example, +here is one variation of the test command that catches some memory bugs that the +above commands may not catch: + +src\\tools\\valgrind\\chrome_tests.bat --brave-new-test-launcher +--test-launcher-bot-mode --test <test> --tool drmemory_full --target +Release --build-dir src\\out + +### OK, I've found a real bug + +Great! + +Please file a crbug and add the +[Stability-Memory-DrMemory](http://code.google.com/p/chromium/issues/list?q=Stability-Memory-DrMemory) +label. + +### drmemory_light vs drmemory_full + +Light: searches for unaddressable accesses like OOB or use-after-frees, handle +leaks, and graphical library usage errors, incurring a moderate execution +slowdown. + +Full: additionally searches for uninitialized reads but adds a large slowdown. + +More on the "full" mode: + +If you're familiar with the Valgrind guts you probably know that tools like +Valgrind and Dr. Memory need to intercept and handle all system calls to know +precisely what data is uninitialized, what is read and so on. + +In contrast to the open-source Linux kernel with just a hundred system calls or +so, on Windows we have an open-ended problem of handling undocumented system +calls. +We're trying hard to do that but we haven't finished yet. We have some +heuristics that work pretty well to ignore errors stemming from system libraries +making system calls as opposed to Chromium code, but if you do see an error +report that you believe is a false positive, please create a short reproducer +and file it into our [issue +tracker](http://code.google.com/p/drmemory/issues/list?can=2&q=Bug%3DFalsePositive). + +### Suppressing error reports from the bots + +**TODO(rnk): When the DrMemory bots have moved to the chromium.memory.fyi +waterfall, this information will be moved into the [memory +sheriff](/system/errors/NodeNotFound) page.** + +**timurrrr: most of this info sounds DrMemory-specific, do we really want to put +it onto the "common" page?** + +The DrMemory suppression file is at +tools/valgrind/drmemory/suppressions\[_full\].txt. +Generally speaking, suppressions in these files are maintained in exactly the +same way as those for all of the other memory tools we use for Chromium, except +that DrMemory uses a slightly different suppression format. + +When the bot generates a report, follow the link to the bot's stdio and search +for "hash=#" to find the report quickly. You should see something similar to: + +UNADDRESSABLE ACCESS: reading 0x00000000-0x00000004 4 byte(s) # 0 +TestingProfile::FinishInit \[chrome\\test\\base\\testing_profile.cc:211\] # 1 +TestingProfile::TestingProfile \[chrome\\test\\base\\testing_profile.cc:164\] # +2 BrowserAboutHandlerTest_WillHandleBrowserAboutURL_Test::TestBody +\[chrome\\browser\\browser_about_handler_unittest.cc:110\] # 3 +testing::Test::Run \[testing\\gtest\\src\\gtest.cc:2162\]Note: @0:00:08.656 in +thread 1900 Note: instruction: mov (%ebx) -> %esi Suppression (error +hash=#30459DB8320B1FA3#): { UNADDRESSABLE ACCESS +name=<insert_a_suppression_name_here> \*!TestingProfile::FinishInit +\*!TestingProfile::TestingProfile +\*!BrowserAboutHandlerTest_WillHandleBrowserAboutURL_Test::TestBody +\*!testing::Test::Run } + +As a starting point, you can copy the suppression (the portion between the curly +brackets **not including the brackets**) into the suppressions.txt file and then +widen it so it covers any similar reports on other bots. +The curly brackets are **not** part of the suppression as in all the other +memory tools! DrMemory suppressions are separated by blank lines instead, so +make sure your suppression does not run into an existing suppression. + +Each frame from the stack trace is of the form +"<module>!<function>". For functions from Chrome, we generally link +the code statically into many different binaries, so we always use a wildcard +for the module. +For third party code, it is generally helpful to identify which DLL the frame +came from, especially since we often do not have debug info for windows system +libraries. + +As in the other tool suppression formats, '\*' is a single frame variable-width +wildcard, '?' is a single-character wildcard, and '...' will match any number of +frames. + +DrMemory has support for a handful of other pattern matching mechanisms. +In particular, if you paste the instruction from the report on a line starting +with "instruction=", you can match the exact instruction producing the report. +The instruction= qualifier is mostly useful when suppressing bit-level false +positive uninitialized reads in third party libraries where we don't have an +accurate callstack and want to make a tight suppression. + +Once you have your suppression, you can test that it suppresses the existing +reports using tools/valgrind/waterfall.sh as you would with the other memory +tools. + +### Running Chromium under Dr. Memory on a given set of URLs + +First, put the list of URLs into tools\\valgrind\\reliability\\url_list.txt, one +URL per line without the http:// prefix. You can also put in the local URLs like +file://c:\\mypath\\repro.htm + +Then, run + +tools\\valgrind\\chrome_tests.bat -t reliability --tool drmemory +--tool_flags="-no_check_uninitialized -no_count_leaks" + +If you're searching for some stability/security bugs, you may consider running +Chromium in the single process mode to increase the probability of the report by +applying this patch: + +Index: tools/valgrind/chrome_tests.py +=================================================================== +--- tools/valgrind/chrome_tests.py ([revision +96002](http://code.google.com/p/chromium/source/detail?r=96002)) ++++ tools/valgrind/chrome_tests.py (working copy) +@@ -271,7 +271,8 @@ +# Valgrind timeouts are in seconds. +UI_VALGRIND_ARGS = \["--timeout=7200", "--trace_children", "--indirect"\] +# UI test timeouts are in milliseconds. +- UI_TEST_ARGS = \["--ui-test-action-timeout=120000", ++ UI_TEST_ARGS = \["--single-process=yes", ++ "--ui-test-action-timeout=120000", +"--ui-test-action-max-timeout=280000"\] +def TestAutomatedUI(self): + +### Running your custom command line under Dr. Memory + +Sometimes you may need to run your own program or your own custom command line +under Dr. Memory. For example, if you want to prefix your own "chrome.exe +--my-flags" command with Dr. Memory, do the following: +`tools\valgrind\drmemory.bat chrome.exe -- --my-flags # don't forget to increase +the timeouts` +If the command line runs Chrome, you may consider increasing the timeouts by +appending + +--ui-test-action-timeout=120000 --ui-test-action-max-timeout=280000 +--ui-test-terminate-timeout=120000 + +to the commandline. + +Random notes for the curious ones + +You can find the Dr. Memory suppression file for Chrome at +tools\\valgrind\\drmemory\\suppressions\[_full\].txt + +The report files are parsed and re-formatted to be more familiar for Valgrind +users (see tools\\valgrind\\drmemory_analyze.py). + +Excluded tests are listed in tools\\valgrind\\gtest_exclude - see [Using +Valgrind](/system/errors/NodeNotFound) more for information. + +Some debugging tips while using Dr. Memory can be found +[here](https://github.com/DynamoRIO/drmemory/wiki/Debugging). + +For those still wanting to use Valgrind, be aware Valgrind requires Chrome be +built using the system memory allocator. To do this, add use_allocator = "none" +to your gn args. + +### Feedback? + +Drop drmemory-team@ a message
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/using-r-to-reduce-page-cycler-regressions/index.md b/chromium/docs/website/site/developers/how-tos/using-r-to-reduce-page-cycler-regressions/index.md new file mode 100644 index 00000000000..72ce99532f5 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/using-r-to-reduce-page-cycler-regressions/index.md @@ -0,0 +1,202 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: using-r-to-reduce-page-cycler-regressions +title: Using R to reduce Page Cycler Regressions +--- + +See also +<https://sites.google.com/a/chromium.org/dev/developers/testing/page-cyclers/analyzing-page-cycler-results>. + +IMPORTANT: When you see a page cycler regression, make sure to upload a saved +copy of the before/after stdio data off the bot. We regularly delete that data +off of buildbot, and you'll need it to do any of the analysis below. + +Most of the time, with page cycler regressions, there are a handful of pages in +that test suite that regress. If you can narrow down which pages regressed, it's +easier to make a reduce suite that you can iterate on quickly to address the +regression. + +R is a programming language for statistical analysis that make it easy to do +analysis on these results. I got a copy at +<http://cran.r-project.org/bin/macosx/>. I know very little R. If you have more +experience with R, please fix up this page to be moar awesome. + +The page cycler stdio page has a detailed output of the runtime of each page in +the page cycler test. For example, page_cycler_moz spits out: + +Pages: +\[bugzilla.mozilla.org,espn.go.com,home.netscape.com,hotwired.lycos.com,lxr.mozilla.org,my.netscape.com,news.cnet.com,slashdot.org,vanilla-page,web.icq.com,www.altavista.com,www.amazon.com,www.aol.com,www.apple.com,www.cnn.com,www.compuserve.com,www.digitalcity.com,www.ebay.com,www.excite.com,www.expedia.com,www.google.com,www.iplanet.com,www.mapquest.com,www.microsoft.com,www.moviefone.com,www.msn.com,www.msnbc.com,www.nytimes.com,www.nytimes.com_Table,www.quicken.com,www.spinner.com,www.sun.com,www.time.com,www.tomshardware.com,www.travelocity.com,www.voodooextreme.com,www.w3.org_DOML2Core,www.wired.com,www.yahoo.com,www.zdnet.com,www.zdnet.com_Gamespot.com\] +\*RESULT times: t= +\[376,292,128,85,178,79,87,38,9,54,27,40,43,20,73,35,32,92,37,45,8,44,21,77,34,47,24,52,68,69,42,18,91,71,39,153,144,47,46,80,101,27,35,34,27,53,32,31,29,10,43,22,25,39,14,57,28,25,24,33,35,8,17,14,20,25,44,19,38,66,22,37,15,38,50,32,95,122,40,18,47,49,27,34,35,27,53,31,30,28,10,44,19,26,39,14,57,29,26,24,33,36,8,17,15,19,25,44,19,38,65,24,37,15,40,49,33,94,123,42,18,46,48,26,35,33,27,53,33,30,29,10,44,20,26,40,15,56,29,26,24,33,37,9,17,15,19,26,43,18,38,66,23,37,15,38,51,32,94,121,41,18,47,49,26,35,34,26,54,31,29,28,10,45,21,25,39,14,56,29,26,24,32,36,7,17,14,19,25,43,18,39,65,21,36,15,38,50,31,92,122,41,18,47,49,26,35,35,26,53,31,30,29,9,44,20,25,38,14,57,29,26,25,33,37,8,16,15,20,25,41,19,39,66,23,34,15,39,50,32,93,122,41,19,47,50,26,35,35,25,53,31,31,29,9,44,21,25,39,14,56,30,25,25,33,36,9,17,15,19,25,44,19,38,67,22,36,14,40,51,31,94,122,41,18,47,50,25,36,33,27,53,33,29,29,10,45,21,25,39,14,57,30,27,24,33,37,8,17,15,20,25,43,19,38,66,22,35,14,39,51,33,95,124,40,19,47,49,26,35,35,25,53,32,29,28,10,45,20,25,40,14,56,30,26,25,33,37,9,17,15,20,25,43,19,38,66,22,38,14,40,51,32,94,123,42,19,45,50,27,35,35,26,52,32,30,29,9,44,20,25,39,15,57,29,27,25,34,37,8,17,16,20,27,43,20,39,66,22,37,13,38,51,33,96,123,41,19,45,50\] +ms + +The pages listed under "Pages:" are loaded in a loop 10 times. So, t\[0\] is the +time to load bugzilla.mozilla.org the first time, and t\[10\] is the time to +load it the second time around. + +Lets create some dummy page cycler data to work with. Lets stay that someone +commits a patch that causes a regression. + +Before patch: + +Pages: \[ojan.com, glens-head.org\]; + +\*RESULT times: t= \[0,99,2,56,0,99,2,56,0,99,2,56,0,99,2,56,0,99,2,56\] ms + +After patch: + +Pages: \[ojan.com, glens-head.org\]; + +\*RESULT times: t= +\[105,34,206,57,105,34,206,57,105,34,206,57,105,34,206,57,105,34,206,57\] ms + +Clearly, looking at this, ojan.com got a lot slower. Looking at real page cycler +data, it's a lot hard to make sense of. + +## Get the data into R + +So, start the R interpreter and copy-paste the before and after runtimes: + +> before = c(0,99,2,56,0,99,2,56,0,99,2,56,0,99,2,56,0,99,2,56) + +> after = +c(105,34,206,57,105,34,206,57,105,34,206,57,105,34,206,57,105,34,206,57) + +> pages = c('ojan.com','glens-head.org') + +## Working with the data + +// Get an easy summary of before + +> summary(before) + +Min. 1st Qu. Median Mean 3rd Qu. Max. + +0.00 1.50 29.00 39.25 66.75 99.00 + +// Get all the before times for ojan.com + +> seq(1, 10 \* length(pages), length(pages)) + +\[1\] 1 3 5 7 9 11 13 15 17 19 + +> before\[seq(1, 10 \* length(pages), length(pages))\] + +\[1\] 0 2 0 2 0 2 0 2 0 2 + +// Get all the before times for glens-head.org + +> before\[seq(2, 10 \* length(pages), length(pages))\] + +\[1\] 99 56 99 56 99 56 99 56 99 56 + +// Now lets make that a function + +> oneSite = function(data, index) { + +data\[seq(index, 10 \* length(pages), length(pages))\]; + +} + +> oneSite(before, 1) + +\[1\] 0 2 0 2 0 2 0 2 0 2 + +// And we can make a function to print the before/after summaries for a given +index. + +> summaries = function(index) { + +print(pages\[index\]); + +print(summary(oneSite(before, index))); + +print(summary(oneSite(after, index))); + +} + +// Before/after summaries for ojan.com + +> summaries(1) + +\[1\] "ojan.com" + +Min. 1st Qu. Median Mean 3rd Qu. Max. + +0 0 1 1 2 2 + +Min. 1st Qu. Median Mean 3rd Qu. Max. + +105.0 105.0 155.5 155.5 206.0 206.0 + +// Now we can loop and see before/after summaries for each site in the cycler. + +> for (i in 1:length(pages)) { + +summaries(i); + +} + +\[1\] "ojan.com" + +Min. 1st Qu. Median Mean 3rd Qu. Max. + +0 0 1 1 2 2 + +Min. 1st Qu. Median Mean 3rd Qu. Max. + +105.0 105.0 155.5 155.5 206.0 206.0 + +\[1\] "glens-head.org" + +Min. 1st Qu. Median Mean 3rd Qu. Max. + +56.0 56.0 77.5 77.5 99.0 99.0 + +Min. 1st Qu. Median Mean 3rd Qu. Max. + +34.0 34.0 45.5 45.5 57.0 57.0 + +// Print all sites where the mean regressed by more than 10ms. + +> threshold = 10; + +> for (i in 1:length(pages)) { + +if (mean(oneSite(before, i)) < (mean(oneSite(after, i) - threshold))) { + +summaries(i); + +} + +} + +## Graphs + +// Bloxplot visualizing the median and stddev. + +> boxplot(before, after) + +// Plot with the dots from before as one color and the dots of after as another. + +> plot(before, after, col=2:3) + +// Plot each site individually using the oneSite function from above. + +> boxplot(oneSite(before, 1), oneSite(after, 1)) + +// Plot all the sites in separate graphs. + +> par(mfrow=c(ceiling(sqrt(length(pages))),ceiling(sqrt(length(pages))))) // +Make a graphics context big enough for all the graphs. Might need to make the +window that pops up very large for the next loop to work. + +> for (i in 1:length(pages)) { + +boxplot(oneSite(before, i), oneSite(after, i), main=pages\[i\]) + +}
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/vectorized-icons-in-native-chrome-ui/index.md b/chromium/docs/website/site/developers/how-tos/vectorized-icons-in-native-chrome-ui/index.md new file mode 100644 index 00000000000..fe80df18c28 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/vectorized-icons-in-native-chrome-ui/index.md @@ -0,0 +1,12 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: vectorized-icons-in-native-chrome-ui +title: Vectorized icons in native Chrome UI +--- + +the docs have migrated to markdown: +<https://chromium.googlesource.com/chromium/src/+/HEAD/components/vector_icons/README.md>
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/visualstudio-tricks/index.md b/chromium/docs/website/site/developers/how-tos/visualstudio-tricks/index.md new file mode 100644 index 00000000000..1de8a96f2e5 --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/visualstudio-tricks/index.md @@ -0,0 +1,83 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: visualstudio-tricks +title: VisualStudio Tricks +--- + +Here is an incomplete stack of tricks to help you work with Chromium in Visual +Studio. + +### **Faster Solution Loading / IntelliSense** + +### Loading a huge solution (like all.sln as generated by gn) makes Visual +Studio very slow, and certain operations like IntelliSense can be somewhat +unusable. Some tips for speeding it up: + +* ### Use the "filters" argument to gn to exclude parts of Chromium + you're not interested in, e.g. "gn gen --ide=vs + --filters=//components/omnibox/\* --sln=omnibox out/Debug" will only + create projects for components/omnibox/ and its dependencies. + However, be aware that Code Search (see below) will not work on code + that's been filtered out! +* ### A very useful extension which helps manage this is + [VsFunnel](https://marketplace.visualstudio.com/items?itemName=DimitriDering.Funnel). + This extension allows you to select which projects in a solution + will be loaded at solution load time, and which will remain in the + "unloaded" state. Unloaded projects are not indexed by VS, so this + extension can drastically speed up VS responsiveness. The unloaded + projects will remain searchable via VsChromium (see below). + +### After opening the solution, give Visual Studio about 10-15 minutes to finish +parsing files etc; it'll become more responsive after that. + +### Code Search + +### The [VsChromium](http://chromium.github.io/vs-chromium/) extension provides +fast code search, among other useful features. Code from unloaded solutions (via +VsFunnel, see above) is still searchable! + +### Column Limit + +You can set up column guidelines at 80 columns or wherever you would like by +installing [this Visual Studio +extension](https://visualstudiogallery.msdn.microsoft.com/da227a0b-0e31-4a11-8f6b-3a149cf2e459) +and using the context menu options. + +### cpplint.py integration + +cpplint.py integration makes it easy to check that a source file conforms to the +style guide. To do this, just go to Tools > External Tools > Add. Specify: + +* Title: cpplint.py +* Command: c:\\src\\depot_tools\\cpplint.bat +* Arguments: --output=vs7 $(ItemPath) +* Initial directory: $(ItemDir) +* Check Use Output window + +To create a keyboard shortcut: + +1. Go to Tools > Options > Environment > Keyboard. +2. Select Tools.ExternalCommand1. (This assumes cpplint.py is your + first external command in your Tools menu.) +3. Press a shortcut key (let's say Alt+L) and Assign it. +4. Press OK. + +Or, make the title something like c&pplint.py, and invoke it with Alt+t,p. + +### Text Editor (No tabs, indentation, line numbers) + +The style guide requires no tabs and 2 char indentation. To set this, go to +Tools > Options. On the Text Editor/All languages/Tabs page, set + +* Indenting radio to Smart +* Tab size and Indent Size to 2 +* Check Insert spaces + +### Debugging visualization, macros, more + +See +<http://dev.chromium.org/developers/how-tos/how-to-set-up-visual-studio-debugger-visualizers>.
\ No newline at end of file diff --git a/chromium/docs/website/site/developers/how-tos/webkit-gardening/index.md b/chromium/docs/website/site/developers/how-tos/webkit-gardening/index.md new file mode 100644 index 00000000000..534659eec4a --- /dev/null +++ b/chromium/docs/website/site/developers/how-tos/webkit-gardening/index.md @@ -0,0 +1,11 @@ +--- +breadcrumbs: +- - /developers + - For Developers +- - /developers/how-tos + - How-Tos +page_name: webkit-gardening +title: webkit-gardening +--- + +This page has moved: [Gardening Blink](/blink/sheriffing)
\ No newline at end of file |
.png.sha1?id=8fa0776f1f79e91fc9c0b9c1ba11a0a29c05196b){kind=link}
