> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/LadybirdBrowser/ladybird/llms.txt
> Use this file to discover all available pages before exploring further.

# Build profiling

> Instructions for profiling and analyzing Ladybird browser build times

There are three ways you can get information about compile times:

1. Using `time ninja install` instead of `ninja install` to time it overall
2. Reading ninja's log files to get a per-file compile time
3. Enabling GCC or Clang flags to get a more detailed per-file breakdown of times for compiler passes within a file

***

## Ninja log files

Ninja produces a handy log file that includes a per-cpp-file compilation time. This is useful for discovering which files take the most time, and so are good targets for speeding up the overall build time.

A python3 script named `ninjatracing` converts the ninja log file into a JSON format that's readable by several profile viewers.

### Prerequisites

`ninjatracing` is available on [GitHub](https://github.com/nico/ninjatracing/blob/master/ninjatracing).

It requires `python3`, available at `python`. You can either create the symlink yourself, or just modify the ninjatracing file to say `python3` instead of `python`.

<Info>
  You also need to make sure `ninjatracing` is marked as executable, and available from your PATH (or somewhere convenient where you can manually call it from).
</Info>

### Usage

<Steps>
  <Step title="Clean the build">
    First, we need to clean the build (and `ccache` if present) to make sure every file gets compiled and gives a meaningful time reading.

    ```bash theme={null}
    ninja clean
    ccache --clear
    ```
  </Step>

  <Step title="Execute ninja">
    ```bash theme={null}
    ninja
    ```

    The log will be written to `.ninja_log` in the current directory by default.
  </Step>

  <Step title="Convert the log to JSON">
    Call `ninjatracing` from the directory you called ninja from:

    ```bash theme={null}
    ninjatracing .ninja_log > trace.json
    ```
  </Step>

  <Step title="Visualize the results">
    You can then drag-and-drop the file onto [Speedscope](https://www.speedscope.app/) or any other compatible flamegraph visualizer.
  </Step>
</Steps>

<Tip>
  The resulting flamegraph will help you identify which files take the longest to compile, making them prime targets for optimization.
</Tip>

***

## GCC/Clang compiler flags

Adding the `-ftime-report` flag to GCC will cause it to output a breakdown for each file it compiles.

### Example output

<details>
  <summary>GCC -ftime-report output</summary>

  ```
  Time variable                                   usr           sys          wall           GGC
   phase setup                        :   0.00 (  0%)   0.00 (  0%)   0.01 (  0%)  1326k (  2%)
   phase parsing                      :   0.57 ( 61%)   0.19 ( 83%)   1.63 ( 65%)    59M ( 74%)
   phase lang. deferred               :   0.10 ( 11%)   0.03 ( 13%)   0.30 ( 12%)  8761k ( 11%)
   phase opt and generate             :   0.23 ( 25%)   0.01 (  4%)   0.48 ( 19%)    10M ( 13%)
   phase last asm                     :   0.03 (  3%)   0.00 (  0%)   0.08 (  3%)   539k (  1%)
   |name lookup                       :   0.11 ( 12%)   0.01 (  4%)   0.25 ( 10%)  2004k (  2%)
   |overload resolution               :   0.08 (  9%)   0.00 (  0%)   0.26 ( 10%)  7900k ( 10%)
   dump files                         :   0.02 (  2%)   0.00 (  0%)   0.00 (  0%)     0  (  0%)
   callgraph construction             :   0.04 (  4%)   0.00 (  0%)   0.06 (  2%)  2677k (  3%)
   callgraph optimization             :   0.00 (  0%)   0.00 (  0%)   0.01 (  0%)  4752  (  0%)
   callgraph functions expansion      :   0.15 ( 16%)   0.00 (  0%)   0.32 ( 13%)  6267k (  8%)
   callgraph ipa passes               :   0.03 (  3%)   0.01 (  4%)   0.08 (  3%)  1413k (  2%)
   template instantiation             :   0.27 ( 29%)   0.08 ( 35%)   0.89 ( 36%)    25M ( 32%)
   TOTAL                              :   0.93          0.23          2.50           79M
  ```
</details>

<Note>
  Depending on whether you understand the internals of the compiler, this may or may not be helpful to you! Generally, this is not recommended unless you're doing deep compiler optimization work.
</Note>

Clang also supports `-ftime-report`, but the output format may differ.

### How to enable

To add the flag, edit the `CMakeLists.txt` in the ladybird root directory, and add `add_compile_options(-ftime-report)` to the list of compile options that start around line 220.

Additionally, you can add `-ftime-report-details` for even more detailed output.

<Warning>
  Enabling these flags will produce a lot of output and may significantly slow down the compilation process. Use sparingly and only when profiling specific compilation issues.
</Warning>