From 9ec167813377326e3003939987dec97f5e7a5497 Mon Sep 17 00:00:00 2001
From: Delan Azabani <dazabani@igalia.com>
Date: Fri, 13 Sep 2024 15:57:41 +0800
Subject: [PATCH 1/2] Profiling: update recommended build instructions

---
 src/hacking/profiling.md | 14 +++++---------
 1 file changed, 5 insertions(+), 9 deletions(-)

diff --git a/src/hacking/profiling.md b/src/hacking/profiling.md
index 3824d3a..a2a077c 100644
--- a/src/hacking/profiling.md
+++ b/src/hacking/profiling.md
@@ -2,18 +2,14 @@
 
 # Profiling
 
-First, ensure that you are building Servo in release (optimized) mode with optimal debugging symbols:
-In Cargo.toml:
+When profiling Servo or troubleshooting performance issues, make sure your build is optimised while still allowing for accurate profiling data.
 
-```
-[profile.release]
-debug = true
-lto = false
+```sh
+$ ./mach build --profile profiling --with-frame-pointer
 ```
 
-```
- ./mach build --release --with-frame-pointers
-```
+- **--profile profiling** builds Servo with [our profiling configuration](building-servo.md#build-profiles)
+- **--with-frame-pointer** builds Servo with stack frame pointers on all platforms
 
 Several ways to get profiling information about Servo's runs:
 * [Interval Profiling](#interval-profiling)

From 4f9680c129f1161698041d4ebb09cf854421c0d1 Mon Sep 17 00:00:00 2001
From: Delan Azabani <dazabani@igalia.com>
Date: Fri, 20 Sep 2024 17:31:36 +0800
Subject: [PATCH 2/2] Building Servo: update production; add -stripped and
 profiling

---
 src/hacking/building-servo.md | 50 ++++++++++++++++++++++++++++++-----
 1 file changed, 43 insertions(+), 7 deletions(-)

diff --git a/src/hacking/building-servo.md b/src/hacking/building-servo.md
index 354a3b2..8c972c1 100644
--- a/src/hacking/building-servo.md
+++ b/src/hacking/building-servo.md
@@ -52,22 +52,58 @@ There are three main build profiles, which you can build and use independently o
         <th>mach option
         <td><code>-d</code>
         <td><code>-r</code>
-        <td><code>--profile production</code>
+        <td><code>--prod</code>
     <tr>
         <th>optimised?
-        <td>no<td>yes<td>yes
+        <td><a href="https://doc.rust-lang.org/cargo/reference/profiles.html#dev">no</a>
+        <td><a href="https://github.com/servo/servo/blob/457d37d94ee6966cad377c373d333a00c637e1ae/Cargo.toml#L153">yes</a>
+        <td>yes, <a href="https://github.com/servo/servo/blob/457d37d94ee6966cad377c373d333a00c637e1ae/Cargo.toml#L159-L160">more</a> <a href="https://github.com/servo/servo/blob/457d37d94ee6966cad377c373d333a00c637e1ae/Cargo.toml#L170-L171">than</a> in <strong>release</strong>
     <tr>
-        <th>debug info?
-        <td>yes<td>no<td>no
+        <th>maximum RUST_LOG level
+        <td><code>trace</code>
+        <td><code>info</code>
+        <td><code>info</code>
     <tr>
         <th>debug assertions?
         <td>yes<td>yes(!)<td>no
     <tr>
-        <th>maximum RUST_LOG level
-        <td><code>trace</code><td><code>info</code><td><code>info</code>
+        <th>debug info?
+        <td>yes<td>no<td>no
+    <tr>
+        <th>symbols?
+        <td>yes<td>no<td>yes
+    <tr>
+        <th>finds resources in<br>current working dir?
+        <td>yes<td>yes<td>no(!)
+</table>
+
+There are also two special variants of production builds for performance-related use cases:
+
+- `production-stripped` builds are ideal for benchmarking Servo over time, with debug symbols stripped for faster initial startup
+- `profiling` builds are ideal for [profiling](profiling.md) and troubleshooting performance issues; they behave like a debug or release build, but have the same performance as a production build
+
+<table>
+<thead>
+    <tr>
+        <th>
+        <th>production
+        <th>production-stripped
+        <th>profiling
+<tbody>
+    <tr>
+        <th>mach <code>--profile</code>
+        <td><code>production</code>
+        <td><code>production-stripped</code>
+        <td><code>profiling</code>
+    <tr>
+        <th>debug info?
+        <td>no<td>no<td>yes
+    <tr>
+        <th>symbols?
+        <td>yes<td>no<td>yes
     <tr>
         <th>finds resources in<br>current working dir?
-        <td>yes<td>yes<td>no
+        <td>no<td>no<td>yes(!)
 </table>
 
 You can change these settings in a servobuild file (see [servobuild.example](https://github.com/servo/servo/blob/b79e2a0b6575364de01b1f89021aba0ec3fcf399/servobuild.example)) or in the root [Cargo.toml](https://github.com/servo/servo/blob/b79e2a0b6575364de01b1f89021aba0ec3fcf399/Cargo.toml).