docs: copy and adapt more of Stan's usage guide docs

alehander92 · alehander92 · commit 324097b118d5 · 2025-03-11T19:18:57.000+02:00
for now not including the C/C++ manual build docs and the tester docs,
as they seem rr-backend specific
diff --git a/README.md b/README.md
@@ -134,7 +134,7 @@ Run `ct --help` to see the full list of supported subcommands, but the most comm
    - `ct replay` - Opens a simple console-based dialog to choose what recording you want to replay.
    - `ct replay <program-name>` - Opens the last trace of an application.
    - `ct replay --id=<trace-id>` - Opens a trace by its trace id.
-   - `ct replay --trace-folde=<trace-folder>` - Opens a trace by its trace folder.
+   - `ct replay --trace-folder=<trace-folder>` - Opens a trace by its trace folder.
 1. `ct` - Launches the startup screen of the CodeTracer GUI.
 1. `ct help / ct --help` - Gives you a help message.
 1. `ct version` - Returns the current version of CodeTracer.
diff --git a/docs/experimental-documentation/mdbook-ct/src/SUMMARY.md b/docs/experimental-documentation/mdbook-ct/src/SUMMARY.md
@@ -4,4 +4,9 @@
 
 # Usage guide
 
-- [Intro to usage guide](./usage_guide/intro_to_usage.md)
+- [Intro to usage guide](./usage_guide/intro_to_usage.md)
+- [CLI](./usage_guide/CLI.md)
+- [Basic GUI](./usage_guide/basic_gui.md)
+- [Tracepoints](./usage_guide/tracepoints.md)
+- [CodeTracer Shell](./usage_guide/codetracer_shell.md)
+
diff --git a/docs/experimental-documentation/mdbook-ct/src/usage_guide/CLI.md b/docs/experimental-documentation/mdbook-ct/src/usage_guide/CLI.md
@@ -0,0 +1,28 @@
+## CLI
+
+This page details some of the options, available to you through the `ct` CLI command.
+
+### Usage
+
+When you launch the CodeTracer GUI, it will offer you the option to also install the CodeTracer CLI. It provides convenient ways to create and load trace files from the command-line or to integrate CodeTracer with CI processes.
+
+Run `ct --help` to see the full list of supported subcommands, but the most commonly used ones are the following:
+
+`<application>` can be a source file or a project folder (depending on the language):
+
+1. `ct run <application>` - Creates a recording and load it in CodeTracer with a single command.
+1. `ct record <application>` - Creates a trace file that can be loaded later or shared.
+1. `ct replay` - Launches the CodeTracer GUI with a previously recorded trace file. Common usages are:
+   - `ct replay` - Opens a simple console-based dialog to choose what recording you want to replay.
+   - `ct replay <program-name>` - Opens the last trace of an application.
+   - `ct replay --id=<trace-id>` - Opens a trace by its trace id.
+   - `ct replay --trace-folder=<trace-folder>` - Opens a trace by its trace folder.
+1. `ct` - Launches the startup screen of the CodeTracer GUI.
+1. `ct help / ct --help` - Gives you a help message.
+1. `ct version` - Returns the current version of CodeTracer.
+
+Unlike other debuggers, where the debugger is attached to your application process, here you have to launch your application
+through the CodeTracer CLI with commands like `ct run` or `ct record`(or through the user interface, which is documented in the next chapter).
+
+Think of debugging your application with CodeTracer as recording a video and then replaying it in order to find
+the information you need. This is why we use commands like `record` and `replay`.
diff --git a/docs/experimental-documentation/mdbook-ct/src/usage_guide/GUI.md b/docs/experimental-documentation/mdbook-ct/src/usage_guide/GUI.md
@@ -0,0 +1 @@
+# GUI
diff --git a/docs/experimental-documentation/mdbook-ct/src/usage_guide/basic_gui.md b/docs/experimental-documentation/mdbook-ct/src/usage_guide/basic_gui.md
@@ -0,0 +1,20 @@
+## Basic GUI
+
+## Replay interface
+
+Watch the video below to see a demonstration of some of the features of the CodeTracer replay GUI:
+
+[![Video](https://img.youtube.com/vi/xZsJ55JVqmU/maxresdefault.jpg)](https://www.youtube.com/watch?v=xZsJ55JVqmU)
+
+### Startup screen
+
+You can open the startup screen with `ct`.
+
+There you can see a list of the recent traces, and open them directly, or to open them from the filesystem
+using the `Open local trace` dialog. This is the graphical alternative to `ct replay`.
+
+You can graphically record a new trace using the `Record new trace` dialog. 
+This currently works only for noir projects: you should navigate to the root of the noir project folder, with the record dialog,
+select and press `Run`.
+If it is recorded correctly, it should open directly the replay interface.
+
diff --git a/docs/experimental-documentation/mdbook-ct/src/usage_guide/codetracer_shell.md b/docs/experimental-documentation/mdbook-ct/src/usage_guide/codetracer_shell.md
@@ -0,0 +1,30 @@
+## Codetracer Shell
+
+> [!NOTE]
+> This feature is in its infancy, but in development. API may be subject to change!
+>
+> It's not a part of the public CodeTracer features or source code for now.
+
+CodeTracer Shell is a special feature of CodeTracer that creates an environment, and optionally an interactive shell,
+that can be used to build applications with complex, or unorthodox build systems.
+
+CodeTracer requires some additional compile flags and instrumentation functions to be built with your application.
+Because of this, CodeTracer only supports building from a single file. Support for multi-file projects using build systems
+is instead relegated to CodeTracer Shell.
+
+When you execute commands in the CodeTracer Shell's interactive shell, or environment, CodeTracer Shell inserts itself into
+the subprocesses that are launched during the build process of your application, making building and running applications
+with more complex build systems easier.
+
+For example, let's say you want to compile a C/C++ application using CMake. With CodeTracer Shell you can do either:
+```
+user $ ct shell
+(ct shell) user $ mkdir build && cd build
+(ct shell) user $ cmake ..
+(ct shell) user $ make 
+```
+using the interactive shell, or the following using commands:
+```
+user $ ct shell -- bash -c "mkdir build && cd build && cmake .. && make"
+```
+
diff --git a/docs/experimental-documentation/mdbook-ct/src/usage_guide/tracepoints.md b/docs/experimental-documentation/mdbook-ct/src/usage_guide/tracepoints.md
@@ -0,0 +1,244 @@
+## What are tracepoints?
+
+Tracepoints are a type of breakpoint that allows you to run arbitrary code every time this breakpoint is hit. In most
+debuggers that support tracepoints they allow for efficient debugging of complex scenarios, like really deep recursion,
+or complex control flow.
+
+In CodeTracer, however, they can also unlock a number of strategies for additional debugging, specifically in the realm
+of hotspot debugging.
+
+## Tracepoints usage guide
+
+From the GUI:
+
+1. Right-click on a line
+1. Click on "Add tracepoint"
+1. The tracepoints popup should appear
+1. Write your tracepoint code in the text editor in the tracepoints popup
+1. Press "CTRL + Enter" to run the trace
+1. After running the trace, the output of your tracepoint will be listed in the tracepoint popup, and in the event log
+
+From the TUI: Coming soon!
+
+From the REPL: Coming soon!
+
+## Tracepoints language
+
+### Syntax
+
+The syntax of the language is similar to Noir/Rust (and therefore most C-like languages). However it doesn't use semicolons.
+
+In the future it is possible to add language-specific features or dialects of the tracepoint language.
+
+#### Literals
+
+Integer (`1`, `23`, `12`), Float (`1.23`, `.234`, `123.`), Bool (`true`, `false`) and String (`"some text"`) literals
+are supported.
+
+### `log()`
+
+The `log()` statement is used to evaluate the argument expression and add it as output from the current tracepoint.
+The `log()` statement suppors multiple values that are comma-separated: `log(v1, v2, v3)`.
+
+#### Example
+
+```rs
+fn test() {
+  let mut sum = 0;
+
+  for i in 0..3 {
+    sum += i;
+    --------------------------------------------------------------------------------
+    |  log("I'm in the loop", i)
+    |
+    --------------------------------------------------------------------------------
+    // Output:
+    --------------------------------------------------------------------------------
+    |  "I'm in the loop" i=0
+    |  "I'm in the loop" i=1
+    |  "I'm in the loop" i=2
+    --------------------------------------------------------------------------------
+  }
+```
+
+
+### Accessing variables
+
+The tracepoint for has access to all the variables, that are defined when the line on which the tracepoint is added is
+evaluated. You can reference them just by using their names in the expressions.
+
+#### Example
+
+```rs
+fn add(a: i32, b: i32) -> i32 {
+  a + b
+  --------------------------------------------------------------------------------
+  |  log(a)
+  |  log(b)
+  --------------------------------------------------------------------------------
+  // Output:
+  --------------------------------------------------------------------------------
+  |  a=3 b=5
+  --------------------------------------------------------------------------------
+}
+```
+
+### Comparison
+
+#### `==` and `!=`
+
+Two values are considered eqial iff their types are the same and their values are the same. **Exception** to this rule is
+comparing **Int** and **Float**, which are compared by their values, despite them being different type.
+
+#### `<`, `>`, `<=`, `>=`
+
+These operators work **only with numerical values** (e.g Int and Float). If at least one of the values is of non-numerical
+type, then an Error is raised.
+
+#### Example
+
+| Expression | Value |
+| ---------- | ----- |
+| 1 == 1 | true |
+| 1 != 1 | false |
+| 1 == 2 | false |
+| 1 != 2 | true |
+| "banana" == "banana" | true |
+| "banana" != "banana" | false |
+| "banana" == "apple" | false |
+| "banana" != "apple" | true |
+| "banana" == 1 | false |
+| "banana" != 1 | true |
+| | |
+| **1.0 == 1** | **true** |
+| **1.0 != 1** | **false** |
+| **2.0 == 1** | **false** |
+| **2.0 != 1** | **true** |
+| **"1" == 1** | **false** |
+| **"1" != 1** | **true** |
+| | |
+| 1 < 2 | true |
+| 1 <= 2 | true |
+| 1 > 2 | false |
+| 1 >= 2 | false |
+| 1 < 2.2 | true |
+| 1.1 <= 2 | true |
+| 1 > 2.2 | false |
+| 1.1 >= 2 | false |
+| | |
+| **1 < "2"** | **ERROR** |
+| **"0" < 1** | **ERROR** |
+| **"1" >= "2"** | **ERROR** |
+
+
+### Arithmetic operations
+
+The supported arithmetic operations are addition (`+`), subtraction (`-`), multiplication (`*`), division (`/`) and
+remainder (`%`). They work only with numerical types (Int and Float).
+
+When both arguments are Integer values, then the result is an Integer (for `/` the result is rounded toward 0). If at
+least one of the arguments is a Float, then the result is a Float.
+
+#### Example
+| Expression | Value |
+| ---------- | ----- |
+| 2 + 3 | 5 |
+| 2 + 3.0 | 5.0 |
+| 2.2 + 3.3 | 5.5 |
+| 2 - 3 | -1 |
+| 2 - 3.0 | -1.0 |
+| 2.2 - 3.3 | -1.1 |
+| 2 * 3 | 6 |
+| 2 * 3.0 | 6.0 |
+| 2.2 * 3.3 | 7.26 |
+| **7 / 3** | **2** |
+| 7 / 3.0 | 2.3333333 |
+| 7.7 / 3.3 | 2.3333333 |
+| 7 % 3 | 1 |
+| 7 % 3.0 | 1.0 |
+| 7.7 % 3.3 | 1.1 |
+
+
+### Conditional branching (`if`-`else`)
+
+The tracepoint language also supports conditional evaluation and branching. If the condition expression doesn't
+evaluate to a boolean value, then an error is raised.
+
+#### Example
+
+```rs
+fn test() {
+  let mut sum = 0;
+
+  for i in 0..4 {
+    sum += i;
+    --------------------------------------------------------------------------------
+    |  log(i)
+    |  if i % 2 == 0 {
+    |    log("even")
+    |  } else if i % 3 == 0 {
+    |    log("div 3")
+    |  } else {
+    |    log("odd")
+    |  }
+    --------------------------------------------------------------------------------
+    // Output:
+    --------------------------------------------------------------------------------
+    |  i=0 even
+    |  i=1 odd
+    |  i=2 even
+    |  i=3 div 3
+    --------------------------------------------------------------------------------
+  }
+}
+```
+
+### Array indexing
+
+If a value is an array, you can index it using the `[]` operators. Indices are 0-based.
+
+#### Example
+
+```rs
+fn arr(a: i32, b: i32) -> i32 {
+  let a = [1, 2, 3, 4, 5];
+  let b = a[2];
+  --------------------------------------------------------------------------------
+  |  log(a)
+  |  log(a[0])
+  |  log(a[1])
+  |  log(a[4])
+  --------------------------------------------------------------------------------
+  // Output:
+  --------------------------------------------------------------------------------
+  |  a=[1, 2, 3, 4, 5] a[0]=1 a[1]=2 a[4]=5
+  --------------------------------------------------------------------------------
+}
+```
+
+### Errors
+
+When an error occurs, the evaluation of the tracepoint stops.
+
+#### Example
+```rs
+fn arr(a: i32, b: i32) -> i32 {
+  let a = [1, 2, 3, 4, 5];
+  let b = a[2];
+  --------------------------------------------------------------------------------
+  |  log(a[0])
+  |  if a[1] { // This will cause error
+  |    log("banana")
+  |  }
+  |  log(a[2]) // This won't be evaluated
+  --------------------------------------------------------------------------------
+  // Output:
+  --------------------------------------------------------------------------------
+  |  a[0]=1 Error=Non-boolean value on conditional jump
+  --------------------------------------------------------------------------------
+}
+```
+
+### Rust-specific extensions
+
+We have some language-specific extensions in mind, but nothing concrete yet.
