Document how to use logging in WebKit

twilco · webkit-commit-queue · commit a9126ba522c3 · 2021-04-06T02:46:54.000Z
https://bugs.webkit.org/show_bug.cgi?id=224152 Patch by Tyler Wilcock <twilco.o@protonmail.com> on 2021-04-05 Reviewed by Simon Fraser. Add documentation about how to use logging in WebKit. * Introduction.md: Canonical link: https://commits.webkit.org/236140@main git-svn-id: https://svn.webkit.org/repository/webkit/trunk@275482 268f45cc-cd09-0410-ab3c-d52691b4dbfc
diff --git a/ChangeLog b/ChangeLog
@@ -1,3 +1,14 @@
+2021-04-05  Tyler Wilcock  <twilco.o@protonmail.com>
+
+        Document how to use logging in WebKit
+        https://bugs.webkit.org/show_bug.cgi?id=224152
+
+        Reviewed by Simon Fraser.
+
+        Add documentation about how to use logging in WebKit.
+
+        * Introduction.md:
+
 2021-03-28  David Kilzer  <ddkilzer@apple.com>
 
         Compile WebKit with UBSan
diff --git a/Introduction.md b/Introduction.md
@@ -1344,5 +1344,49 @@ FIXME: Talk about how to debug API tests.
 
 # Logging in WebKit
 
-FIXME: Write this.
+Some places in WebKit use a macro called `LOG_WITH_STREAM`. Here's an example invocation:
+
+```
+LOG_WITH_STREAM(Scrolling, stream << "ScrollingTree::commitTreeState - removing unvisited node " << nodeID);
+```
+
+The first argument is the _log channel_ and the second is the _log content_. By default, this logging is enabled in
+debug builds and disabled in release builds (see definition of `LOG_DISABLED`).
+
+The only logs that will be printed are those whose channels you have enabled. You can specify the channels you want to
+enable by constructing a comma-separated list with the following syntax:
+
+* `ChannelName` to enable logging for this channel
+* `all` to enable logging for all channels
+* `-ChannelName` to disable logging for this channel
+
+Where you specify this list depends on the platform you are running WebKit on.
+
+### Linux
+
+Set the `WEBKIT_DEBUG` environment variable.
+
+```
+WEBKIT_DEBUG=Scrolling Tools/Scripts/run-minibrowser --gtk --debug
+```
+
+### Mac
+
+Set a value for the `WebCoreLogging` key in [standardUserDefaults](https://developer.apple.com/documentation/foundation/nsuserdefaults/1416603-standarduserdefaults).
+
+You may also pass this key and value as an argument:
+
+```
+Tools/Scripts/run-minibrowser --debug -WebCoreLogging Scrolling
+```
+
+or set the key and value on the [NSGlobalDomain](https://developer.apple.com/documentation/foundation/nsglobaldomain).
+
+```
+defaults write NSGlobalDomain  WebCoreLogging -string Scrolling
+Tools/Scripts/run-minibrowser --debug
+```
+
+### Windows
 
+Set the `WebCoreLogging` environment variable.
