Skip to content

Commit 144dec8

Browse files
alehander92alehander92
committed
docs: start moving Stan's docs book to mdbook
work from several days ago
1 parent 094f88a commit 144dec8

File tree

8 files changed

+135
-2
lines changed

8 files changed

+135
-2
lines changed

‎docs/experimental-documentation/Introduction/CodetracerGuide.md

+3-2
Original file line numberDiff line numberDiff line change
@@ -10,14 +10,15 @@ interact with it through different interfaces, as well as, how to use its signat
1010
- [Building C/C++ applications manually](https://dev-docs.codetracer.com/Introduction/UsageGuide/ManualBuilding)
1111

1212
## Frontends
13+
1314
CodeTracer currently only has a GUI frontend, though some interactions, like recording and replaying applications are
1415
activated through the CLI. For example, one can launch `ct replay` and the GUI will launch, where you will do all your
1516
work after that initial start from the CLI
1617

17-
The GUI frontend is simply a web page. When running as a desktop application, it uses Electron in order to integrate with
18+
The GUI frontend is implemented using web technologies. When running as a desktop application, it uses Electron in order to integrate with
1819
your host operating system. You can also use CodeTracer in a web browser.
1920

2021
> [!NOTE]
2122
> Running CodeTracer in your web browser is not a currently released feature, although we have a working version internally
2223
23-
There are plans for future frontend, such as a REPL or TUI frontend.
24+
There are plans for an additional future frontend, such as a REPL or TUI frontend.

‎docs/experimental-documentation/Introduction/Troubleshooting.md

+1
Original file line numberDiff line numberDiff line change
@@ -14,5 +14,6 @@ There are 2 commands that can be used to completely wipe all traces from your us
1414

1515
## Broken local build
1616
Sometimes your local build might break. In most cases, a simple `direnv reload` and `just build` should be able to fix it.
17+
Otherwise, you can ask for help on our [issues tracker](github.com/metacraft-labs/codetracer), or in our [chat server](https://discord.gg/aH5WTMnKHT)
1718

1819
<!-- TODO: Add more info here -->

‎docs/experimental-documentation/mdbook-ct/.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
book

‎docs/experimental-documentation/mdbook-ct/book.toml

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
[book]
2+
authors = ["Stanislav Vasilev"]
3+
language = "en"
4+
multilingual = false
5+
src = "src"
6+
title = "codetracer docs"
7+
8+
[preprocessor.alerts]

‎docs/experimental-documentation/mdbook-ct/src/SUMMARY.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Summary
2+
3+
- [Introduction](./chapter_1.md)
4+
5+
# Usage guide
6+
7+
- [Intro to usage guide](./usage_guide/intro_to_usage.md)

‎docs/experimental-documentation/mdbook-ct/src/chapter_1.md

+88
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Introduction
2+
3+
Welcome to the codetracer-desktop wiki. Here you can find information on almost every topic
4+
regarding codetracer development and usage.
5+
6+
## What is codetracer
7+
Codetracer is a debugging environment, based on the concept of record and replay, developed as a powerful tool to easily
8+
debug complex applications.
9+
10+
## Installation
11+
> [!CAUTION]
12+
> Codetracer can only be installed on Linux and macOS.
13+
14+
### Prerequisites
15+
On systems that are not NixOS, you need to install `direnv` and `nix`.
16+
17+
Nix should not be installed through your distribution's package manager, but from [here](https://nixos.org/download/).
18+
19+
Direnv should be set up in your shell, as shown [here](https://direnv.net/docs/hook.html).
20+
21+
### Installation
22+
1. Setup SSH with our private GitLab instance: <https://gitlab.metacraft-labs.com>
23+
1. Clone the repository with submodules: `git clone [email protected]:codetracer/codetracer-desktop.git --recursive`
24+
1. Enter the created directory
25+
1. For first-time setup:
26+
- Create a PAT from [here](https://gitlab.metacraft-labs.com/-/user_settings/personal_access_tokens)
27+
- Create a new token with at least `read_api` and `read_repository` access
28+
- Add the following text to `~/.config/nix/nix.conf`
29+
```
30+
access-tokens = gitlab.metacraft-labs.com=PAT:<token>
31+
experimental-features = nix-command flakes
32+
```
33+
- And replace `<token>` with your PAT
34+
1. Run `nix develop`
35+
1. Run `direnv allow`
36+
1. To build codetracer simply run `just build`
37+
1. Now every time you enter the `codetracer-desktop` directory your environment should be updated
38+
39+
<!-- Question: Is an access token required for GitHub right now? It might be needed if we use the GitHub API more than a couple of times a second
40+
TODO:
41+
1. Change repository URL
42+
1. Remove references to GitLab
43+
-->
44+
45+
46+
> [!TIP]
47+
> Users of Visual Studio Code might encounter issues when using `code .`. To fix them do the following:
48+
> 1. Run `direnv deny`
49+
> 1. Run `code .`
50+
> 1. Run `direnv allow`
51+
52+
### Building and running the tests
53+
To start running tests do the following:
54+
55+
1. Run `tester build` - Builds tester
56+
1. Run `tester parallel` - Runs the tests
57+
58+
### Enabling `cachix`
59+
> [!NOTE]
60+
> This step is optional
61+
62+
<!-- TODO: Scrap or completely rewrite the cachix instructions for end users. Alternatively, make this an internal developer guide -->
63+
64+
Cachix is a cache for nix that allows you to save time on compiling codetracer and related projects. To enable `cachix` do the following:
65+
66+
1. Log into [cachix](https://www.cachix.org/) with your personal GitHub account
67+
1. Create an authentication token
68+
1. Run `cachix authtoken --stdin`
69+
1. Paste the token and click enter
70+
1. Press `CTRL + D` to save the token
71+
1. Run `cachix use metacraft-labs-codetracer`
72+
1. Run `direnv allow`, `nix develop`, or `just build-nix` to auto-download cached binaries if available
73+
74+
### Explicit `cachix` setup
75+
> [!NOTE]
76+
> You have to be an admin for the private cache. Ask an administrator to get added.
77+
78+
Our current `cachix` setup pushes binaries from CI, but if you want to manually push to `cachix` as well, or want to know how pushing works, you can do the following:
79+
80+
1. Go to [this page](https://app.cachix.org/organization/metacraft-labs/cache/metacraft-labs-codetracer/settings/authtokens)
81+
1. Create an auth token with `Read+Write` permissions
82+
1. Locally register it as described in the above heading
83+
84+
To push the dev shell to `cachix` use either one of the following commands:
85+
86+
1. Automatically: `just cachix-push-devshell`
87+
1. Manually: `cachix push metacraft-labs-codetracer "$(nix build --print-out-paths .#devshells.x86_64-linux.default)"`
88+

‎docs/experimental-documentation/mdbook-ct/src/usage_guide/into_to_usage.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Intro to usage guide

‎docs/experimental-documentation/mdbook-ct/src/usage_guide/intro_to_usage.md

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
<!-- This page's structure feels really off, please help me rewrite it -->
2+
3+
# Intro to usage guide
4+
5+
CodeTracer is a semi-portable piece of technology, so its usage varies, the following subpages explain how you can
6+
interact with it through different interfaces, as well as, how to use its signature features:
7+
8+
- [CLI](https://dev-docs.codetracer.com/Introduction/UsageGuide/CLI)
9+
- [GUI](https://dev-docs.codetracer.com/Introduction/UsageGuide/BasicGUI)
10+
- [Tracepoints](https://dev-docs.codetracer.com/Introduction/UsageGuide/Tracepoints)
11+
- [CodeTracer Shell](https://dev-docs.codetracer.com/Introduction/UsageGuide/CodetracerShell)
12+
- [Building C/C++ applications manually](https://dev-docs.codetracer.com/Introduction/UsageGuide/ManualBuilding)
13+
14+
## Frontends
15+
16+
CodeTracer currently only has a GUI frontend, though some interactions, like recording and replaying applications are
17+
activated through the CLI. For example, one can launch `ct replay` and the GUI will launch, where you will do all your
18+
work after that initial start from the CLI
19+
20+
The GUI frontend is implemented using web technologies. When running as a desktop application, it uses Electron in order to integrate with
21+
your host operating system. You can also use CodeTracer in a web browser.
22+
23+
> [!NOTE]
24+
> Running CodeTracer in your web browser is not a currently released feature, although we have a working version internally
25+
26+
There are plans for an additional future frontend, such as a REPL or TUI frontend.

0 commit comments

Comments
 (0)