diff --git a/.gitignore b/.gitignore index ae01e3d46..72fb97b1f 100644 --- a/.gitignore +++ b/.gitignore @@ -11,7 +11,7 @@ build-*/ .direnv/ result -docs/experimental-documentation/build/* +docs/book/book src/index.js ui.js debugger.js diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..95a5371ea --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,35 @@ + + +## Contributing + +We welcome contributors! + +If you want to fix something smaller, feel free to open an issue or a a PR. + +For bigger changes it's advised to first open an issue/discussion in the relevant Github repo or to discuss it our team in our [Discord chat server](https://discord.gg/aH5WTMnKHT). + +### Contributors guide + +Here are some recommendations, however if you want more info, our docs/contributor guide are hosted [on the CodeTracer site](https://contributors-guide.codetracer.com/) ! + +The guide is written as a set of markdown documents and built using [mdbook](https://rust-lang.github.io/mdBook/) and [mdbook-alerts](https://crates.io/crates/mdbook-alerts) . + +You can contribute to the documentation itself, by editing it in `docs/book` and making a pull request. You can iterate on it locally , by cloning the repo, activating it's nix devshell and running `just serve-docs [hostname port]`: it will serve it locally(by default on http://localhost:3000). + +### Style guide + +For Rust, we are using `cargo fmt` to autoformat our code, and `cargo clippy` with some custom allow/deny rules inside the code. +We have a `cargo clippy` check in our CI, but one can also run it locally. + +For Nim, we still haven't written down a guide or list of rules and principles that we agree on, so this is something that we hope to do. +We might also link to an existing document. + +### Commits/Pull Requests + +We are using [the "Conventional Commits" strategy](https://www.conventionalcommits.org/). + +We use or are ok with using more "types", not only those included by default in their official page: e.g. `cleanup:`, `tooling:`, `examples:` etc. + +We use `git rebase`, not merge and currently use the github pull requests as the main way to add code. Any pull request would need at least one review +from someone from the CodeTracer team. + diff --git a/README.md b/README.md index da13964cb..62744546f 100644 --- 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 ` - Opens the last trace of an application. - `ct replay --id=` - Opens a trace by its trace id. - - `ct replay --trace-folde=` - Opens a trace by its trace folder. + - `ct replay --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/ci/deploy/docs.sh b/ci/deploy/docs.sh index 19b5e906e..fa1990511 100755 --- a/ci/deploy/docs.sh +++ b/ci/deploy/docs.sh @@ -2,10 +2,18 @@ set -e -pushd docs/experimental-documentation +pushd docs/book/ + +# TODO: eventually: a more fine-grained nix shell/env? +# nix-shell --command "mdbook build" + +# for now depending on global project devshell +mdbook build # build output is in the `book` directory + +# TODO: deploy book to codetracer.com ? ask Zahary? echo '###############################################################################' -echo TODO +echo "TODO upload book" echo '###############################################################################' popd diff --git a/docs/experimental-documentation/.htaccess b/docs/book/.htaccess similarity index 100% rename from docs/experimental-documentation/.htaccess rename to docs/book/.htaccess diff --git a/docs/book/book.toml b/docs/book/book.toml new file mode 100644 index 000000000..3dab20c1a --- /dev/null +++ b/docs/book/book.toml @@ -0,0 +1,8 @@ +[book] +authors = ["CodeTracer team"] +language = "en" +multilingual = false +src = "src" +title = "codetracer docs" + +[preprocessor.alerts] diff --git a/docs/experimental-documentation/shell.nix b/docs/book/shell.nix similarity index 66% rename from docs/experimental-documentation/shell.nix rename to docs/book/shell.nix index a9ec1dd9e..b8feb3501 100644 --- a/docs/experimental-documentation/shell.nix +++ b/docs/book/shell.nix @@ -4,14 +4,12 @@ in pkgs.mkShell { buildInputs = with pkgs; [ bash - terser - pandoc - parallel + mdbook + mdbook-alerts ]; nativeBuildInputs = with pkgs; [ bash - terser - pandoc - parallel + mdbook + mdbook-alerts ]; } \ No newline at end of file diff --git a/docs/book/src/CONTRIBUTING.md b/docs/book/src/CONTRIBUTING.md new file mode 100644 index 000000000..95a5371ea --- /dev/null +++ b/docs/book/src/CONTRIBUTING.md @@ -0,0 +1,35 @@ + + +## Contributing + +We welcome contributors! + +If you want to fix something smaller, feel free to open an issue or a a PR. + +For bigger changes it's advised to first open an issue/discussion in the relevant Github repo or to discuss it our team in our [Discord chat server](https://discord.gg/aH5WTMnKHT). + +### Contributors guide + +Here are some recommendations, however if you want more info, our docs/contributor guide are hosted [on the CodeTracer site](https://contributors-guide.codetracer.com/) ! + +The guide is written as a set of markdown documents and built using [mdbook](https://rust-lang.github.io/mdBook/) and [mdbook-alerts](https://crates.io/crates/mdbook-alerts) . + +You can contribute to the documentation itself, by editing it in `docs/book` and making a pull request. You can iterate on it locally , by cloning the repo, activating it's nix devshell and running `just serve-docs [hostname port]`: it will serve it locally(by default on http://localhost:3000). + +### Style guide + +For Rust, we are using `cargo fmt` to autoformat our code, and `cargo clippy` with some custom allow/deny rules inside the code. +We have a `cargo clippy` check in our CI, but one can also run it locally. + +For Nim, we still haven't written down a guide or list of rules and principles that we agree on, so this is something that we hope to do. +We might also link to an existing document. + +### Commits/Pull Requests + +We are using [the "Conventional Commits" strategy](https://www.conventionalcommits.org/). + +We use or are ok with using more "types", not only those included by default in their official page: e.g. `cleanup:`, `tooling:`, `examples:` etc. + +We use `git rebase`, not merge and currently use the github pull requests as the main way to add code. Any pull request would need at least one review +from someone from the CodeTracer team. + diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md new file mode 100644 index 000000000..75051ac24 --- /dev/null +++ b/docs/book/src/SUMMARY.md @@ -0,0 +1,37 @@ +## Summary + +- [Introduction](./introduction.md) +- [Contributing](./CONTRIBUTING.md) + +## Usage guide + +- [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) + +## Backends + +- [DB backend](./backends/db_backend.md) + - [Noir](./backends/db-backend/noir.md) + - [Ruby](./backends/db-backend/ruby.md) + - [Python](./backends/db-backend/py.md) + - [Lua](./backends/db-backend/lua.md) + - [small](./backends/db-backend/small.md) + +- [RR backend](./backends/rr_backend.md) + - [C & C++](./backends/rr-backend/c_and_cpp.md) + - [Rust](./backends/rr-backend/rust.md) + - [Nim](./backends/rr-backend/nim.md) + - [Go](./backends/rr-backend/go.md) + +## Building & packaging + +- [Build systems](./building_and_packaging/build_systems.md) + +### Misc + +- [Troubleshooting](./misc/troubleshooting.md) +- [Environment variables](./misc/environment_variables.md) +- [Building the documentation](./misc/building_docs.md) diff --git a/docs/book/src/backends/db-backend/lua.md b/docs/book/src/backends/db-backend/lua.md new file mode 100644 index 000000000..2f607f28f --- /dev/null +++ b/docs/book/src/backends/db-backend/lua.md @@ -0,0 +1,5 @@ +## Lua + +We still don't have Lua support, however we've had a very minimal proof of concept experiment with supporting Lua (the interpreter, not LuaJIT) with our RR backend years ago. + +We can change that patch to produce traces suitable for the DB backend, or at least publish some kind of basis for that(the RR approach remains possible, but with different tradeoffs) \ No newline at end of file diff --git a/docs/book/src/backends/db-backend/noir.md b/docs/book/src/backends/db-backend/noir.md new file mode 100644 index 000000000..bd7007132 --- /dev/null +++ b/docs/book/src/backends/db-backend/noir.md @@ -0,0 +1,7 @@ +## Noir + +The initial release of CodeTracer has MVP support for the Noir programming language. It has been developed in collaboration with the Blocksense team and currently requires the use of the [Blocksense Noir Compiler](https://github.com/blocksense-network/noir), which is included in the CodeTracer distribution. + +We support many of Noir's features, but not all: e.g. we don't support mutable references currently, we don't serialize struct values and some other cases. + +We are planning on adding support for the missing features. diff --git a/docs/book/src/backends/db-backend/py.md b/docs/book/src/backends/db-backend/py.md new file mode 100644 index 000000000..b5b564a93 --- /dev/null +++ b/docs/book/src/backends/db-backend/py.md @@ -0,0 +1,8 @@ +## Python language + +We currently have started adding support for recording python programs for the DB backend, but the prototype isn't finished yet. + +The recorder is currently hosted in the [codetracer-python-recorder](https://github.com/metacraft-labs/codetracer-python-recorder) repo. + +You can read its README for more details. We are welcoming contributors! + diff --git a/docs/book/src/backends/db-backend/ruby.md b/docs/book/src/backends/db-backend/ruby.md new file mode 100644 index 000000000..e2e4a2ea5 --- /dev/null +++ b/docs/book/src/backends/db-backend/ruby.md @@ -0,0 +1,9 @@ +## Ruby + +We currently have partial support for the Ruby programming language in the DB backend. +We support many cases, you can use it like `ct record []` and `ct replay ` (or directly `ct run []`) + +The recorder for Ruby is currently hosted in the [codetracer-ruby-recorder](https://github.com/metacraft-labs/codetracer-ruby-recorder) repo. + +You can read its README for more details. We welcome contributors! + diff --git a/docs/experimental-documentation/Introduction/Backends/DBBackend/SmallLang.md b/docs/book/src/backends/db-backend/small.md similarity index 53% rename from docs/experimental-documentation/Introduction/Backends/DBBackend/SmallLang.md rename to docs/book/src/backends/db-backend/small.md index 8cfe5d247..b40838554 100644 --- a/docs/experimental-documentation/Introduction/Backends/DBBackend/SmallLang.md +++ b/docs/book/src/backends/db-backend/small.md @@ -1,5 +1,8 @@ -SmallLang is, as the name says, a small, lisp-like language, that's used for general testing of the DB backend. +## small lang + +small lang is, as the name says, a small, lisp-like language, that's used for general dogfooding of new tracing features and testing of the DB backend. It's purely experimental. You can find its source code under `src/small-lang`. There, you can also find multiple files with the `.small` extension, which can be used as examples of the language. + diff --git a/docs/book/src/backends/db_backend.md b/docs/book/src/backends/db_backend.md new file mode 100644 index 000000000..d1e8de779 --- /dev/null +++ b/docs/book/src/backends/db_backend.md @@ -0,0 +1,36 @@ +## DB backend + +### Languages + +The DB backend is currently used for interpreted languages, like scripting and blockchain/zero knowledge languages: + +1. [Noir](./db-backend/noir.md) +1. [Ruby](./db-backend/ruby.md) +1. [Python(prototype not finished yet)](./db-backend/py.md) +1. [Lua(not done: just a plan)](./db-backend/lua.md) +1. [small(a toy interpreter for dogfooding)](./db-backend/small.md) + +If you're interested in db-backend support for those languages or for now ones, you can discuss with us on our [GitHub issue tracker](https://github.com/metacraft-labs/codetracer/issues), +in the [GitHub repo discussions forum](https://github.com/metacraft-labs/codetracer/discussions) or in our [discord chat server](https://discord.gg/aH5WTMnKHT). We welcome contributors! + +### Additional directions + +However we're exploring using this method for emulators(and conversely, for emulating native languages) in the future. + +Also, languages can have both native(AOT) and interpreted implementations: +so we can more easily support e.g. interpreters/VM-s of certain languages with this backend currently. + +### Implementation + +As the name suggests, this backend is implemented as a database. Due to its properties, this backend provides +a more complete feature set - one of the reasons it was ready first. + +For each language, we define a tracer, which instruments or hooks into the interpreter, VM or program and +records all the data, that we need in a trace folder. + +We postprocess and index that trace into a database-like structure. Currently this happens in the beginning of the replay. +For now the data in the database is represented by a runtime-only Rust structure, however +we plan on storing it as a file, which can be memory-mapped and on separating the postprocessing/indexing step as +an optionally independent action. + + diff --git a/docs/book/src/backends/db_backend/noir.md b/docs/book/src/backends/db_backend/noir.md new file mode 100644 index 000000000..63f44f0d4 --- /dev/null +++ b/docs/book/src/backends/db_backend/noir.md @@ -0,0 +1 @@ +# Noir diff --git a/docs/book/src/backends/rr-backend/c_and_cpp.md b/docs/book/src/backends/rr-backend/c_and_cpp.md new file mode 100644 index 000000000..b49988913 --- /dev/null +++ b/docs/book/src/backends/rr-backend/c_and_cpp.md @@ -0,0 +1,6 @@ +## C & C++ + +We have partial support for C and C++ in the RR backend. C generally has good support, though it is less advanced than +the Rust implementation. + +Support for C++ is still experimental, due to missing support for many C++ constructs. diff --git a/docs/experimental-documentation/Introduction/Backends/CoreBackend/Golang.md b/docs/book/src/backends/rr-backend/go.md similarity index 59% rename from docs/experimental-documentation/Introduction/Backends/CoreBackend/Golang.md rename to docs/book/src/backends/rr-backend/go.md index ae6572d35..d9f52104a 100644 --- a/docs/experimental-documentation/Introduction/Backends/CoreBackend/Golang.md +++ b/docs/book/src/backends/rr-backend/go.md @@ -1,2 +1,4 @@ +# Go + We have developed а basic integration that supports small parts of the Golang language in the Core backend. -Development on a more complete revision is scheduled to start soon! \ No newline at end of file +Development of a more complete revision is scheduled to start soon! diff --git a/docs/book/src/backends/rr-backend/nim.md b/docs/book/src/backends/rr-backend/nim.md new file mode 100644 index 000000000..71a664929 --- /dev/null +++ b/docs/book/src/backends/rr-backend/nim.md @@ -0,0 +1,18 @@ +# Nim + +We have partial support for the Nim backend, with it being somewhat behind in features compared to C, but ahead, +compared to C++. + +The Nim backend only supports Nim 1 as of today, but there are plans to add support for Nim 2. + + +Some additional future goals that have been announced in the Nim forum are: + +* First-class support for macro-generated code - macro generated code should be indistinguishable from regular code. You can expand it layer by layer, set breakpoints and tracepoints anywhere within it, and step through it in all the familiar ways. (or at least part of those) +* Precise debug info - you should be able to set breakpoints and tracepoints at the level of individual sub-expressions and you can switch between debugging Nim, C or assembly code at any time. +* Compile-time debugging - with few clicks in your text editor, you should be able to trace the execution of the Nim VM itself. + +> [!NOTE] +> For now we're focused on the beta and initial releases of the RR backend though, and on initial releases for some of the language supports. +> This means the initial support for Nim would be focused on the same features as the other languages: stepping, tracepoints, event log, calltrace, omniscience, state, history. We do hope we'll be able to continue with some of the more advanced goals afterwards. + diff --git a/docs/book/src/backends/rr-backend/rust.md b/docs/book/src/backends/rr-backend/rust.md new file mode 100644 index 000000000..c9558b0f6 --- /dev/null +++ b/docs/book/src/backends/rr-backend/rust.md @@ -0,0 +1,3 @@ +# Rust + +Our backend for Rust is the most developed out of all languages in the RR backend, with it being closest to MVP status(but still non trivial amount of work left). diff --git a/docs/book/src/backends/rr_backend.md b/docs/book/src/backends/rr_backend.md new file mode 100644 index 000000000..2e17509f9 --- /dev/null +++ b/docs/book/src/backends/rr_backend.md @@ -0,0 +1,32 @@ +## RR backend + +The RR backend is used for systems programming languages, like: + +1. [C & C++](./rr-backend/c_and_cpp.md) +1. [Rust](./rr-backend/rust.md) +1. [Nim](./rr-backend/nim.md) +1. [Go](./rr-backend/go.md) + +Under the hood, it uses a patched version of the [RR debugger](https://rr-project.org/), as well as the standard +GDB debugger. + +We are still not distributing it, but we might need to rethink the GDB usage before that. + +The Core backend is based on a dispatcher that maintains a pool of rr replay processes. These processes allow you to jump back and forward in time, while also +preloading information, such as the information, needed for omniscience and calltrace, as well as managing other features, such as tracepoints. This logic is +currently implemented using python code using the gdb API. +(If required, this can be changed to use the lldb API or something more custom, like a dwarf lib-based solution. We are currently using the rust `gimli` DWARF lib for a tool, that helps with recording/metadata in the RR backend). + +These are the main differences, when compared to the DB Backend, based on the way RR works: + +1. Only non-deterministic events are recorded. +1. The program's different states are navigated through re-execution. +1. More practical for recording real-world software(RR was originally created by Mozilla to debug Firefox) +1. Some features of CodeTracer are more challenging to implement, compared to the [DB Backend](./backends/db-backend.md) + +> ![NOTE] +> This backend is in active development, and is yet to be released to the wider public. +> +> It is currently proprietary and it might remain closed source. +> Open sourcing it is also possible, if we find a suitable business model. + diff --git a/docs/experimental-documentation/Introduction/BuildSystem.md b/docs/book/src/building_and_packaging/build_systems.md similarity index 70% rename from docs/experimental-documentation/Introduction/BuildSystem.md rename to docs/book/src/building_and_packaging/build_systems.md index 51dd14703..d0f9ee632 100644 --- a/docs/experimental-documentation/Introduction/BuildSystem.md +++ b/docs/book/src/building_and_packaging/build_systems.md @@ -1,12 +1,18 @@ +## Build systems + Codetracer uses nix, just, tup and direnv as parts of its build system. ## Breakdown of the different components + ### Nix -The Nix package manager/build system deals with managing all dependencies, required by CodeTracer, as well as packaging -it for NixOS, and other operating systems through an AppImage generator utility. + +The [Nix](https://nixos.org/) package manager/build system deals with managing all dependencies, required by CodeTracer, as well as packaging +it for NixOS. It can package for other operating systems through an AppImage generator utility, however currently we are building our +appimages with custom shell scripts in `appimage-scripts`. ### Just -The Just build system is used to trigger build commands. It's semi-analogous to a Makefile. The following commands are + +The [just](https://just.systems/) task runner is used to trigger build commands and various other actions. It's semi-analogous to a Makefile. The following commands are the most widely-used: 1. `just build` - Builds the project with Tup and starts the automatic build process, which is used for active development @@ -21,16 +27,20 @@ the most widely-used: 1. `just reset-config` - Resets the user's configuration if it's incompatible with the latest version of CodeTracer. Further [documentation](https://dev-docs.codetracer.com/Introduction/Configuration) ### Tup -The Tup build system is used for local builds of CodeTracer and deals with calling the actual low-level build instructions. + +The [Tup](https://gittup.org/tup/) build system is used for local builds of CodeTracer and deals with calling the actual low-level build instructions. ### Direnv -The `direnv` utility sets up your local environment for using CodeTracer. +The [direnv](https://direnv.net/) utility sets up your local environment for using CodeTracer. ## Packaging -### Detailed breakdown of the Nix package + +### More detailed breakdown of the Nix package + Coming soon! ### Packaging for non-NixOS distributions + > [!TIP] > If you're a user that wants a package for your distribution contact us. We're currently in the process of creating > packages for popular distributions, such as Debian/Ubuntu, Fedora/RHEL, Arch Linux, Gentoo, Void, etc. @@ -40,7 +50,10 @@ which you can install to `/usr/bin`. Along with it, you should also install our from `resources/` to the needed directories, such as `/usr/share/pixmaps` and `/usr/share/applications`. ### Packaging for Windows(DB-backend only) + Coming soon! ### Packaging for macOS(DB-backend only) + Coming soon! + diff --git a/docs/experimental-documentation/Introduction/Introduction.md b/docs/book/src/introduction.md similarity index 51% rename from docs/experimental-documentation/Introduction/Introduction.md rename to docs/book/src/introduction.md index 5a45e4591..0b3cc9c07 100644 --- a/docs/experimental-documentation/Introduction/Introduction.md +++ b/docs/book/src/introduction.md @@ -1,15 +1,15 @@ +# Introduction + Welcome to the codetracer-desktop wiki. Here you can find information on almost every topic regarding codetracer development and usage. -## What is codetracer -Codetracer is a debugging environment, based on the concept of record and replay, developed as a powerful tool to easily -debug complex applications. - ## Installation + > [!CAUTION] -> Codetracer can only be installed on Linux and macOS. +> Codetracer can only be installed on Linux and macOS currently. ### Prerequisites + On systems that are not NixOS, you need to install `direnv` and `nix`. Nix should not be installed through your distribution's package manager, but from [here](https://nixos.org/download/). @@ -17,6 +17,7 @@ Nix should not be installed through your distribution's package manager, but fro Direnv should be set up in your shell, as shown [here](https://direnv.net/docs/hook.html). ### Installation + 1. Setup SSH with our private GitLab instance: 1. Clone the repository with submodules: `git clone gitlab@gitlab.metacraft-labs.com:codetracer/codetracer-desktop.git --recursive` 1. Enter the created directory @@ -48,38 +49,24 @@ TODO: > 1. Run `direnv allow` ### Building and running the tests -To start running tests do the following: -1. Run `tester build` - Builds tester -1. Run `tester parallel` - Runs the tests +Currently, you can run the db-backend (Rust) tests: -### Enabling `cachix` -> [!NOTE] -> This step is optional - - - -Cachix is a cache for nix that allows you to save time on compiling codetracer and related projects. To enable `cachix` do the following: +```bash +# inside src/db-backend: +cargo test --release --bin db-backend # test most cases: non-ignored +cargo test --release --bin db-backend -- --ignored # test the ignored cases: ignored by default as they're slower +``` -1. Log into [cachix](https://www.cachix.org/) with your personal GitHub account -1. Create an authentication token -1. Run `cachix authtoken --stdin` -1. Paste the token and click enter -1. Press `CTRL + D` to save the token -1. Run `cachix use metacraft-labs-codetracer` -1. Run `direnv allow`, `nix develop`, or `just build-nix` to auto-download cached binaries if available +We are planning on restoring the e2e tests for db-backend: currently they don't work, +as they were created originally with native language test programs in our older repo targetting the rr-backend. +We hope to write a lot more e2e tests, as we haven't covered most features/cases. -### Explicit `cachix` setup -> [!NOTE] -> You have to be an admin for the private cache. Ask an administrator to get added. - -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: +### Enabling `cachix` -1. Go to [this page](https://app.cachix.org/organization/metacraft-labs/cache/metacraft-labs-codetracer/settings/authtokens) -1. Create an auth token with `Read+Write` permissions -1. Locally register it as described in the above heading + + -To push the dev shell to `cachix` use either one of the following commands: +Cachix is a cache for nix that allows you to save time on compiling codetracer and related projects. We'll discuss using a public codetracer cache +for the open sourced parts, however this is available only internally for now. -1. Automatically: `just cachix-push-devshell` -1. Manually: `cachix push metacraft-labs-codetracer "$(nix build --print-out-paths .#devshells.x86_64-linux.default)"` diff --git a/docs/book/src/misc/building_docs.md b/docs/book/src/misc/building_docs.md new file mode 100644 index 000000000..ed372313f --- /dev/null +++ b/docs/book/src/misc/building_docs.md @@ -0,0 +1,8 @@ +## Building the documentation + +The documenation for codetracer is written in Markdown using [mdbook](https://rust-lang.github.io/mdBook/). +We use some extensions from [GitHub Flavoured Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) : specifically alert boxes with [mdbook-alerts](https://crates.io/crates/mdbook-alerts). + +To build the documentation run `just build-docs`. If you want to iterate on the documentation for local development, run `just serve-docs [] []` or by going in the docs directory and running `mdbook serve [--hostname ] [--port ]` and a web server will be started, by default on http://localhost:3000 . + +The built doc files are stored under `docs/experimental-documentation/build`, while the markdown files are under `docs/experimental-documentation` and its child directories. diff --git a/docs/experimental-documentation/Advanced/EnvironmentVariables.md b/docs/book/src/misc/environment_variables.md similarity index 93% rename from docs/experimental-documentation/Advanced/EnvironmentVariables.md rename to docs/book/src/misc/environment_variables.md index ab4e1e851..c0ed4b80d 100644 --- a/docs/experimental-documentation/Advanced/EnvironmentVariables.md +++ b/docs/book/src/misc/environment_variables.md @@ -1,3 +1,5 @@ +## Environment variables + CodeTracer exposes a number of environment variables that you can use to override some of its behaviours: 1. `CODETRACER_ELECTRON_ARGS` - adds arguments for launching Electron. Useful for debugging production builds @@ -16,4 +18,4 @@ These are generally not functional right now, since they affect CodeTracer Shell 1. `CODETRACER_SHELL_RECORDS_OUTPUT` - ? 1. `CODETRACER_SHELL_EXPORT` - ? 1. `CODETRACER_SHELL_CLEANUP_OUTPUT_FOLDER` - ? -1. `CODETRACER_SHELL_SOCKET` and `CODETRACER_SHELL_ADDRESS` - they override the socket location and address respectively \ No newline at end of file +1. `CODETRACER_SHELL_SOCKET` and `CODETRACER_SHELL_ADDRESS` - they override the socket location and address respectively diff --git a/docs/experimental-documentation/Introduction/Troubleshooting.md b/docs/book/src/misc/troubleshooting.md similarity index 58% rename from docs/experimental-documentation/Introduction/Troubleshooting.md rename to docs/book/src/misc/troubleshooting.md index 6842f57ba..c591936ed 100644 --- a/docs/experimental-documentation/Introduction/Troubleshooting.md +++ b/docs/book/src/misc/troubleshooting.md @@ -1,18 +1,26 @@ +## Troubleshooting + CodeTracer is currently in an experimental state, so we expect that there are many bugs that have not been found as of now. If you find any bug, please report it as an issue on GitHub. In the meantime, you can use this page to fix some issues that are somewhat common. -## Fixing outdated configuration/layout files -You can find more information [here](https://dev-docs.codetracer.com/Introduction/Configuration#Layout). +### Fixing outdated configuration/layout files + +You can reset them by deleting your `~/.config/codetracer` folder currently. + +You will be able to find more information in the configuration docs eventually: work in progress. + +### Resetting the local trace database -## Resetting the local trace database There are 2 commands that can be used to completely wipe all traces from your user's data: 1. `just reset-db` - Resets the local user's trace database 1. `just clear-local-traces` - Clears the local user's traces -## Broken local build +### Broken local build + Sometimes your local build might break. In most cases, a simple `direnv reload` and `just build` should be able to fix it. +Otherwise, you can ask for help on our [issues tracker](https://github.com/metacraft-labs/codetracer), or in our [chat server](https://discord.gg/aH5WTMnKHT) diff --git a/docs/experimental-documentation/Introduction/UsageGuide/CLI.md b/docs/book/src/usage_guide/CLI.md similarity index 72% rename from docs/experimental-documentation/Introduction/UsageGuide/CLI.md rename to docs/book/src/usage_guide/CLI.md index 195d977f7..5aff9ebd2 100644 --- a/docs/experimental-documentation/Introduction/UsageGuide/CLI.md +++ b/docs/book/src/usage_guide/CLI.md @@ -1,7 +1,10 @@ -This page details all options, available to you through the `ct` CLI command. +## CLI -## Main actions -The main actions you can execute are as follows: +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: @@ -13,13 +16,13 @@ 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 ` - Opens the last trace of an application. - `ct replay --id=` - Opens a trace by its trace id. - - `ct replay --trace-folde=` - Opens a trace by its trace folder. + - `ct replay --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`, +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/book/src/usage_guide/basic_gui.md b/docs/book/src/usage_guide/basic_gui.md new file mode 100644 index 000000000..498721567 --- /dev/null +++ b/docs/book/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/Introduction/UsageGuide/CodetracerShell.md b/docs/book/src/usage_guide/codetracer_shell.md similarity index 82% rename from docs/experimental-documentation/Introduction/UsageGuide/CodetracerShell.md rename to docs/book/src/usage_guide/codetracer_shell.md index 47935a660..31dd485e2 100644 --- a/docs/experimental-documentation/Introduction/UsageGuide/CodetracerShell.md +++ b/docs/book/src/usage_guide/codetracer_shell.md @@ -1,3 +1,10 @@ +## Codetracer Shell + +> [!NOTE] +> This feature is in its infancy, but in development. The API, implementation approach and feature set/goals may be subject to change! +> +> It's not a part of the public CodeTracer feature set 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. @@ -21,5 +28,3 @@ using the interactive shell, or the following using commands: user $ ct shell -- bash -c "mkdir build && cd build && cmake .. && make" ``` -> [!NOTE] -> This feature is in its infancy, but in active development. API may be subject to change! diff --git a/docs/experimental-documentation/Introduction/CodetracerGuide.md b/docs/book/src/usage_guide/intro_to_usage.md similarity index 83% rename from docs/experimental-documentation/Introduction/CodetracerGuide.md rename to docs/book/src/usage_guide/intro_to_usage.md index 3fe85cb78..1f4c211a2 100644 --- a/docs/experimental-documentation/Introduction/CodetracerGuide.md +++ b/docs/book/src/usage_guide/intro_to_usage.md @@ -1,5 +1,7 @@ +# Intro to usage guide + CodeTracer is a semi-portable piece of technology, so its usage varies, the following subpages explain how you can interact with it through different interfaces, as well as, how to use its signature features: @@ -10,14 +12,15 @@ interact with it through different interfaces, as well as, how to use its signat - [Building C/C++ applications manually](https://dev-docs.codetracer.com/Introduction/UsageGuide/ManualBuilding) ## Frontends + CodeTracer currently only has a GUI frontend, though some interactions, like recording and replaying applications are activated through the CLI. For example, one can launch `ct replay` and the GUI will launch, where you will do all your work after that initial start from the CLI -The GUI frontend is simply a web page. When running as a desktop application, it uses Electron in order to integrate with +The GUI frontend is implemented using web technologies. When running as a desktop application, it uses Electron in order to integrate with your host operating system. You can also use CodeTracer in a web browser. > [!NOTE] > Running CodeTracer in your web browser is not a currently released feature, although we have a working version internally -There are plans for future frontend, such as a REPL or TUI frontend. +There are plans for an additional future frontend, such as a REPL or TUI frontend. diff --git a/docs/experimental-documentation/Introduction/UsageGuide/Tracepoints.md b/docs/book/src/usage_guide/tracepoints.md similarity index 90% rename from docs/experimental-documentation/Introduction/UsageGuide/Tracepoints.md rename to docs/book/src/usage_guide/tracepoints.md index 5fb5f5c4b..de1077c3f 100644 --- a/docs/experimental-documentation/Introduction/UsageGuide/Tracepoints.md +++ b/docs/book/src/usage_guide/tracepoints.md @@ -1,4 +1,5 @@ ## 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. @@ -7,6 +8,7 @@ In CodeTracer, however, they can also unlock a number of strategies for addition of hotspot debugging. ## Tracepoints usage guide + From the GUI: 1. Right-click on a line @@ -21,20 +23,25 @@ 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 be added language-specific features or dialects of the Tracepoint language. +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; @@ -45,7 +52,7 @@ fn test() { | log("I'm in the loop", i) | -------------------------------------------------------------------------------- - -- Output: + // Output: -------------------------------------------------------------------------------- | "I'm in the loop" i=0 | "I'm in the loop" i=1 @@ -56,10 +63,12 @@ fn test() { ### 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 @@ -67,7 +76,7 @@ fn add(a: i32, b: i32) -> i32 { | log(a) | log(b) -------------------------------------------------------------------------------- - -- Output: + // Output: -------------------------------------------------------------------------------- | a=3 b=5 -------------------------------------------------------------------------------- @@ -75,15 +84,19 @@ fn add(a: i32, b: i32) -> i32 { ``` ### 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 | @@ -119,11 +132,12 @@ type, then an Error is raised. ### Arithmetic operations + The supported arithmetic operations are addition (`+`), subtraction (`-`), multiplication (`*`), division (`/`) and -remainder (`%`). They work only on numerical types (Int and Float). +remainder (`%`). They work only with numerical types (Int and Float). -When both arguments are Integer values, then the result is Integer (for `/` the result is rounded toward 0). If at -least one of the arguments is Float, then the result is 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 | @@ -146,10 +160,12 @@ least one of the arguments is Float, then the result is Float. ### Conditional branching (`if`-`else`) + The tracepoint language also supports conditional evaluation and branching. If the condition expression doesn't -evaluate to boolean value, then an error is raised. +evaluate to a boolean value, then an error is raised. #### Example + ```rs fn test() { let mut sum = 0; @@ -166,7 +182,7 @@ fn test() { | log("odd") | } -------------------------------------------------------------------------------- - -- Output: + // Output: -------------------------------------------------------------------------------- | i=0 even | i=1 odd @@ -178,10 +194,11 @@ fn test() { ``` ### Array indexing -If a value is an array, you can index it using the `[]` operators. Indexes are 0 based. -<<<<<<< HEAD +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]; @@ -192,7 +209,7 @@ fn arr(a: i32, b: i32) -> i32 { | log(a[1]) | log(a[4]) -------------------------------------------------------------------------------- - -- Output: + // Output: -------------------------------------------------------------------------------- | a=[1, 2, 3, 4, 5] a[0]=1 a[1]=2 a[4]=5 -------------------------------------------------------------------------------- @@ -200,7 +217,8 @@ fn arr(a: i32, b: i32) -> i32 { ``` ### Errors -When an error occurs, the execution of the tracepoint stops. + +When an error occurs, the evaluation of the tracepoint stops. #### Example ```rs @@ -214,15 +232,13 @@ fn arr(a: i32, b: i32) -> i32 { | } | log(a[2]) // This won't be evaluated -------------------------------------------------------------------------------- - -- Output: + // Output: -------------------------------------------------------------------------------- | a[0]=1 Error=Non-boolean value on conditional jump -------------------------------------------------------------------------------- } ``` -======= ### Rust-specific extensions -We have some language-specific extensions in mind, but they're not ready yet. - +We have some language-specific extensions in mind, but nothing concrete yet. diff --git a/docs/experimental-documentation/404.md b/docs/experimental-documentation/404.md deleted file mode 100644 index 9734535a9..000000000 --- a/docs/experimental-documentation/404.md +++ /dev/null @@ -1,4 +0,0 @@ - -

\(o_o)/

-

Unfortunately this page doesn't exist 😔

-
\ No newline at end of file diff --git a/docs/experimental-documentation/Advanced/CustomPatches.md b/docs/experimental-documentation/Advanced/CustomPatches.md deleted file mode 100644 index 3014a68f0..000000000 --- a/docs/experimental-documentation/Advanced/CustomPatches.md +++ /dev/null @@ -1 +0,0 @@ -Coming soon! \ No newline at end of file diff --git a/docs/experimental-documentation/Advanced/Deprecated.md b/docs/experimental-documentation/Advanced/Deprecated.md deleted file mode 100644 index 3014a68f0..000000000 --- a/docs/experimental-documentation/Advanced/Deprecated.md +++ /dev/null @@ -1 +0,0 @@ -Coming soon! \ No newline at end of file diff --git a/docs/experimental-documentation/Advanced/Dotfiles.md b/docs/experimental-documentation/Advanced/Dotfiles.md deleted file mode 100644 index 3014a68f0..000000000 --- a/docs/experimental-documentation/Advanced/Dotfiles.md +++ /dev/null @@ -1 +0,0 @@ -Coming soon! \ No newline at end of file diff --git a/docs/experimental-documentation/Advanced/Packaging.md b/docs/experimental-documentation/Advanced/Packaging.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/experimental-documentation/Introduction/Backends.md b/docs/experimental-documentation/Introduction/Backends.md deleted file mode 100644 index 99492f665..000000000 --- a/docs/experimental-documentation/Introduction/Backends.md +++ /dev/null @@ -1,4 +0,0 @@ -Codetracer has 2 backends, click the links for additional documentation: - -1. [Core backend](https://dev-docs.codetracer.com/Introduction/Backends/CoreBackend) -1. [DB backend](https://dev-docs.codetracer.com/Introduction/Backends/DBBackend) diff --git a/docs/experimental-documentation/Introduction/Backends/CoreBackend.md b/docs/experimental-documentation/Introduction/Backends/CoreBackend.md deleted file mode 100644 index 35e2e14f6..000000000 --- a/docs/experimental-documentation/Introduction/Backends/CoreBackend.md +++ /dev/null @@ -1,22 +0,0 @@ -The Core backend is used for systems programming languages, like: - -1. [C & C++](https://dev-docs.codetracer.com/Introduction/Backends/CoreBackend/CAndCpp) -1. [Goland](https://dev-docs.codetracer.com/Introduction/Backends/CoreBackend/Golang) -1. [Nim](https://dev-docs.codetracer.com/Introduction/Backends/CoreBackend/Nim) -1. [Rust](https://dev-docs.codetracer.com/Introduction/Bacends/CoreBackend/Rust) - -Under the hood, it uses a patched version of the [rr debugger](https://rr-project.org/), as well as the standard -GDB debugger. - -The Core backend is based on a dispatcher that maintains a pool of rr replay processes. These processes allow you to jump back and forward in time, while also -preloading information, such as the information, needed for omniscience and calltrace, as well as managing other features, such as tracepoints. This logic is -implemented using python code using the gdb API. - -These are the main differences, when compared to the DB Backend: - -1. Only non-deterministic events are recorded -1. The program's different sates are navigated through re-execution -1. Practical for recording real-world software(rr was originally created by Mozilla to debug Firefox) -1. Some features of CodeTracer are more challenging to implement, compared to the [DB Backend](https://dev-docs.codetracer.com/Introduciton/Backends/DBBackend) - -This backend is in active development, and is yet to be released to the wider public. diff --git a/docs/experimental-documentation/Introduction/Backends/CoreBackend/CAndCpp.md b/docs/experimental-documentation/Introduction/Backends/CoreBackend/CAndCpp.md deleted file mode 100644 index dfa7f2ecd..000000000 --- a/docs/experimental-documentation/Introduction/Backends/CoreBackend/CAndCpp.md +++ /dev/null @@ -1,4 +0,0 @@ -We have partial support for C and C++ in the Core backend. C generally has good support, though it is less advanced than -the Rust implementation. - -Support for C++ is still experimental, due to missing support for many C++ constructs. \ No newline at end of file diff --git a/docs/experimental-documentation/Introduction/Backends/CoreBackend/Nim.md b/docs/experimental-documentation/Introduction/Backends/CoreBackend/Nim.md deleted file mode 100644 index bf953cf30..000000000 --- a/docs/experimental-documentation/Introduction/Backends/CoreBackend/Nim.md +++ /dev/null @@ -1,4 +0,0 @@ -We have partial support for the Nim backend, with it being somewhat behind in features compared to C, but ahead, -compared to C++. - -The Nim backend only supports Nim 1 as of today, but there are plans to add support for Nim 2 in the future. \ No newline at end of file diff --git a/docs/experimental-documentation/Introduction/Backends/CoreBackend/Rust.md b/docs/experimental-documentation/Introduction/Backends/CoreBackend/Rust.md deleted file mode 100644 index f59b32e79..000000000 --- a/docs/experimental-documentation/Introduction/Backends/CoreBackend/Rust.md +++ /dev/null @@ -1 +0,0 @@ -Our backend for Rust is the most developed out of all backends, with it being closes to MVP status. \ No newline at end of file diff --git a/docs/experimental-documentation/Introduction/Backends/DBBackend.md b/docs/experimental-documentation/Introduction/Backends/DBBackend.md deleted file mode 100644 index 6fe7b7076..000000000 --- a/docs/experimental-documentation/Introduction/Backends/DBBackend.md +++ /dev/null @@ -1,9 +0,0 @@ -The DB backend is used for interpreted languages, like: - -1. [Noir](https://dev-docs.codetracer.com/Introduction/Backends/DBBackend/Noir) -1. [Ruby](https://dev-docs.codetracer.com/Introduction/Backends/DBBackend/Ruby) -1. [Lua](https://dev-docs.codetracer.com/Introduction/Backends/DBBackend/Lua) -1. [SmallLang](https://dev-docs.codetracer.com/Introduction/Backends/DBBackend/SmallLang) - -As the name suggests, this backend is implemented as a large database. Due to its properties, this backend provides -a more complete feature set - one of the reasons it was open-sourced first. diff --git a/docs/experimental-documentation/Introduction/Backends/DBBackend/Lua.md b/docs/experimental-documentation/Introduction/Backends/DBBackend/Lua.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/experimental-documentation/Introduction/Backends/DBBackend/Noir.md b/docs/experimental-documentation/Introduction/Backends/DBBackend/Noir.md deleted file mode 100644 index 0881501f7..000000000 --- a/docs/experimental-documentation/Introduction/Backends/DBBackend/Noir.md +++ /dev/null @@ -1 +0,0 @@ -We currently have MVP support for the Noir programming language in the DB Backend. \ No newline at end of file diff --git a/docs/experimental-documentation/Introduction/Backends/DBBackend/Ruby.md b/docs/experimental-documentation/Introduction/Backends/DBBackend/Ruby.md deleted file mode 100644 index 9c349f9d3..000000000 --- a/docs/experimental-documentation/Introduction/Backends/DBBackend/Ruby.md +++ /dev/null @@ -1 +0,0 @@ -We currently have partial support for the Ruby programming language in the DB backend. \ No newline at end of file diff --git a/docs/experimental-documentation/Introduction/ClientServerModel.md b/docs/experimental-documentation/Introduction/ClientServerModel.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/experimental-documentation/Introduction/Configuration.md b/docs/experimental-documentation/Introduction/Configuration.md deleted file mode 100644 index d6d3eabf9..000000000 --- a/docs/experimental-documentation/Introduction/Configuration.md +++ /dev/null @@ -1,79 +0,0 @@ -# Main config -## The `default_config.yaml` file -The `default_config.yaml` contains most configuration options for codetracer in YAML format. - -Codetracer stores this file in 2 different places: - -1. In `config` during development, or `/etc/codetracer/` when installed globally -1. In `/.codetracer/` for per-project configuration - -Note that some fields cannot be per-project. Such fields are marked on this page. - -### Codetracer mode -By enabling the `test` field, you can enable test mode. It was previously used -for Nim UI tests, however it should be obsolete by now and should be removed soon. - - - -### Features -You have the ability to enable/disable different features of codetracer to make your debugging environment more customisable. -Here's a list: - -1. `calltrace` -1. `flow` -1. `trace` -1. `events` -1. `history` - Experimental -1. `repl` - -Each of these settings is a dictionary, that looks like this: -```yaml -flow: - enabled: true - ui: parallel -``` -Most features only have the `enabled` field, though some might have additional settings, like flow. - -#### Flow settings -You can modify the following flow settings: - -1. `ui` - Can be either `parallel`, `inline`, or `multiline` - -#### Calltrace settings -You can modify the following calltrace settings: - -1. `callArgs` - whether we should load args/return values for callstack/calltrace - -### Telemetry -The opt-in telemetry enables the sending of anonymised usage statistics and error reports to the CodeTracer team. -This allows us to detect and fix common issues quicker and gain insight into the most important features for our community. - -> [!NOTE] -> This is yet to be implemented - -> [!WARNING] -> This is a global setting - -### Debug -The `debug` field enables/disables debug messages. - -> [!WARNING] -> This is a global setting - -### Layout -The `layout` field sets the default Window management layout file that should be loaded. - -The file is usually `/.codetracer/layout.json`, and is initially created as a copy of -`/etc/codetracer/fallback_layout.json`. - -If your layout is broken, or incompatible with the current version of CodeTracer, the application will try its best to -fix the issue. If the issue is not fixed automatically, run `just reset-layout` in order to hard-reset to the default -layout file. - -### Theme -The `theme` field sets the default theme file that should be loaded. - - - -# Legacy config -Additional legacy config can be found under `config/old`. It's mostly old tmux scripts. diff --git a/docs/experimental-documentation/Introduction/Frontend.md b/docs/experimental-documentation/Introduction/Frontend.md deleted file mode 100644 index 9b3c5a833..000000000 --- a/docs/experimental-documentation/Introduction/Frontend.md +++ /dev/null @@ -1,12 +0,0 @@ -The frontend code can be found under the `src/frontend` directory. It contains the following: - -1. Minimal HTML and Javascript configuration -1. The frontend base, written in Nim using [karax](https://github.com/karaxnim/karax) -1. Tests under the `tests` directory -1. The main frontend services, under `services` -1. UI components, under `ui` - -Due to bad folder ordering, parts of the frontend are located in different folders. For example: - -1. Fonts are under `resources/fonts` -1. Styles are under `src/frontend/styles` \ No newline at end of file diff --git a/docs/experimental-documentation/Introduction/Frontend/Styles.md b/docs/experimental-documentation/Introduction/Frontend/Styles.md deleted file mode 100644 index 10649d32c..000000000 --- a/docs/experimental-documentation/Introduction/Frontend/Styles.md +++ /dev/null @@ -1,16 +0,0 @@ -All styles are located under `src/styles` and are written in the -[stylus CSS preprocessor language](https://stylus-lang.com/). - -The root directory contains different themes for codetracer. When any of those themes is loaded, -it loads `codetracer.styl`, which includes styles for all the UI components. - -Under the `components/` directory, you can find stylus files for each UI component/widget. - -> [!CAUTION] -> Previously, the `components` directory did not exist. Instead, all CSS code was placed in the -> `codetracer.styl` file, which was around 5.6K lines long at the time. -> We did a refactor to separate it into several files, however due `codetracer.styl`'s massive size and -> complicated nature, there may be styles for components/widgets in unrelated files, or a lot of dead code. -> -> Please move suspected dead code to a `legacy.styl` file(this may or may not exist, so create it if needed). -> After that, remove the code and do testing with your colleagues, which maintain the frontend. \ No newline at end of file diff --git a/docs/experimental-documentation/Introduction/RequirementsAndConstraints.md b/docs/experimental-documentation/Introduction/RequirementsAndConstraints.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/experimental-documentation/Introduction/TestApplications.md b/docs/experimental-documentation/Introduction/TestApplications.md deleted file mode 100644 index c95fecc96..000000000 --- a/docs/experimental-documentation/Introduction/TestApplications.md +++ /dev/null @@ -1,122 +0,0 @@ -## Running tests using `tester` -To run standard tests, run the following: - -1. `tester build` - builds the test applications -1. `tester parallel` - runs the tests - -The built test applications can be found under the following folders: - -1. `tests/binaries` -1. `tests/programs` - for scripting languages - -> [!NOTE] -> Most additional options of the `tester` application are experimental, and may, or may not currently work! - -## Real-world testing -CodeTracer is developed as a solution for debugging complex applications, so the simple tests are not enough for testing -in real-world scenarios. - -For this reason, we have a number of highly complex applications real-world applications/libraries that can be used to -test complex usages of CodeTracer. - -> [!NOTE] -> C/C++/Rust examples are for internal use, since the backend for systems programming languages is yet to be released -> publicly. - -> [!TIP] -> Though currently unstable, this backend has been proved to work with these applications without many issues. You can -> check them out yourself as a way to gauge how effective CodeTracer would be in your project. - -> [!NOTE] -> The custom patches to the C/C++ applications are required because CodeTracer Shell is currently not capable of -> bootstrapping complex C/C++ projects. Integrations with most of the popular build tools are coming soon! - -### Noir applications -Coming soon! - -### UntitledDBusUtils(C++) -The [UntitledDBusUtils](https://github.com/MadLadSquad/UntitledDBusUtils) library is a C++ metaprogramming wrapper on -top of the low level [D-Bus](https://en.wikipedia.org/wiki/D-Bus) C API. The code for deserialisation of data has highly -complex control flow that is hard to track with a normal debugger when a bug is introduced. - -Running steps: - -1. Clone the library: `git clone https://github.com/metacraft-labs/UntitledDBusUtils.git --recursive` -1. Enter the cloned folder: - - On NixOS, run `nix-shell` - - On any other distribution, install the following: - - D-Bus - - CMake - - GNU Make - - GCC & G++ - - rr - - GDB - - OpenSSL -1. Copy `/src/native/trace.c` into the root project directory. [Documentation](https://dev-docs.codetracer.com/Introduction/UsageGuide/ManualBulidingCOrCpp) -1. Create a `build` directory and enter it -1. Run `cmake .. -DCMAKE_BUILD_TYPE=DEBUG` -1. Compile with `make -j ` -1. Go to your local copy of `codetracer-desktop`(make sure you're still in the Nix shell if on NixOS) -1. Run `ct record /build/test` -1. Once the process hangs run the following command in another terminal, in order to feed the application data: - ``` - user $ gdbus call --session --dest org.test.Test --object-path /org/test/Test --method org.test.Test.Test --timeout=1 1 2 "test" "(([3,4,5,6],[7,8,9,10]),11,12,([13,14,15,16],[17,18,19,20]))" "test2" - ``` -1. Run `ct replay /build/test` - -### UntitledImGuiFramework/UImGuiDemo(C++) -The [UntitledImGuiFramework](https://github.com/MadLadSquad/UntitledImGuiFramework) is an example of a highly-complex -application that also deals with graphics and constant interactions between it, the user, and the underlying operating -system. - -To test it, we're using the [UImGuiDemo](https://github.com/MadLadSquad/UImGuiDemo) example application. - -Installation instructions: - -1. Clone the framework: `git clone https://github.com/MadLadSquad/UntitledImGuiFramework.git --recursive` -1. Enter the cloned folder: - - If on NixOS, run `nix-shell` - - If on any other distribution, install all dependencies you may need, as listed in the [Installation guide](https://github.com/MadLadSquad/UntitledImGuiFramework/wiki/Install-guide) -1. Run `user $ ./install.sh` -1. Wait for it to finish -1. Add the following line to `Framework/cmake/UImGuiHeader.cmake`: `add_compile_options(-g3 -O0 -finstrument-functions -fcf-protection=none)` -1. Apply changes similar to this patch to `Framework/cmake/CompileProject.cmake`: - ```patch - diff --git a/Framework/cmake/CompileProject.cmake b/Framework/cmake/CompileProject.cmake - index f79592a..db6afb3 100644 - --- a/Framework/cmake/CompileProject.cmake - +++ b/Framework/cmake/CompileProject.cmake - @@ -18,7 +18,7 @@ else() - endif() - add_executable(${APP_TARGET} ${EXECUTABLE_SOURCES}) - endif() - - - +add_library(trace Source/trace.c) - include(SetupTargetSettings) - - # ---------------------------------------------------------------------------------------------------------------------- - @@ -38,9 +38,9 @@ elseif (EMSCRIPTEN) - endforeach() - else () - target_link_libraries(UntitledImGuiFramework ${GLFW_LIBRARIES_T} ${GLEW_LIBRARIES_T} ${OPENGL_LIBRARIES_T} pthread - - ${YAML_CPP_LIBRARIES_T} ${FREETYPE_LIBRARIES} ${VULKAN_LIBRARIES_T} ${X11_LIBRARIES} dl util) - - target_link_libraries(${APP_LIB_TARGET} UntitledImGuiFramework pthread dl ${YAML_CPP_LIBRARIES_T} util) - - target_link_libraries(${APP_TARGET} UntitledImGuiFramework ${APP_LIB_TARGET} ${YAML_CPP_LIBRARIES_T} dl util) - + ${YAML_CPP_LIBRARIES_T} ${FREETYPE_LIBRARIES} ${VULKAN_LIBRARIES_T} ${X11_LIBRARIES} dl util trace) - + target_link_libraries(${APP_LIB_TARGET} UntitledImGuiFramework pthread dl ${YAML_CPP_LIBRARIES_T} util trace) - + target_link_libraries(${APP_TARGET} UntitledImGuiFramework ${APP_LIB_TARGET} ${YAML_CPP_LIBRARIES_T} dl util trace) - - if (APPLE) - target_link_libraries(UntitledImGuiFramework "-framework Cocoa" "-framework IOKit" "-framework CoreFoundation" - ``` -1. Go to the `Projects` directory and clone the demo application: `git clone https://github.com/MadLadSquad/UImGuiDemo` -1. Go to `../UVKBuildTool/build` and run `./UVKBuildTool --generate ../../Projects/UImGuiDemo` -1. Go back to `../../Projecs/UImGuiDemo/` -1. Copy `/src/native/trace.c` to `Source/` -1. Create a `build` folder and enter it -1. Run `cmake .. -DCMAKE_BUILD_TYPE_DEBUG` -1. Run `make -j ` -1. Get the path to the CodeTracer executable. If developing locally go to the CodeTracer source directory and type `which ct` -1. Add the path to the CodeTracer executable to your path -1. Run `ct record ./UImGuiDemo` and close the application after you're done recording -1. Replay using `ct replay ./UImGuiDemo` diff --git a/docs/experimental-documentation/Introduction/UsageGuide/BasicGUI.md b/docs/experimental-documentation/Introduction/UsageGuide/BasicGUI.md deleted file mode 100644 index e811d79ae..000000000 --- a/docs/experimental-documentation/Introduction/UsageGuide/BasicGUI.md +++ /dev/null @@ -1,3 +0,0 @@ -Watch the video below to learn how to use all the features of the CodeTracer GUI: - - \ No newline at end of file diff --git a/docs/experimental-documentation/Introduction/UsageGuide/ManualBuilding.md b/docs/experimental-documentation/Introduction/UsageGuide/ManualBuilding.md deleted file mode 100644 index 3b2675c9c..000000000 --- a/docs/experimental-documentation/Introduction/UsageGuide/ManualBuilding.md +++ /dev/null @@ -1,59 +0,0 @@ -## Manually building applications for Codetracer - -> [!WARNING] -> This only applies to applications that are run through the -> [Core backend](https://dev-docs.codetracer.com/Introduction/Backends/CoreBackend)! - -If your application is more than 1 file long, or if the file has a complex build system, -[Codetracer shell](https://dev-docs.codetracer.com/Introduction/UsageGuide/CodetracerShell) might not be able -to build your project successfully. In this case, you can make a special compile mode for when you want to debug with -Codetracer, and you can add the following compile flags: - -1. `-g3` - optimised debugging support only for GDB -1. `-O0` - no optimisations -1. `-finstrument-functions` - Generates instrumentation calls for entry and exit to functions used for the call graph -1. `-fcf-protection=none` - Turns off instrumentation of control flow transfers - -After that, you also need to link to `src/native/trace.c`, which contains the needed callback functions for Codetracer -to successfully profile and instrument your application for the call graph to work correctly. - -### Example CMake setup -In CMake, you can add the following line to enable the required compile flags in debug mode: -```cmake -option(CODETRACER_DEBUG "Build for debugging with codetracer" OFF) -if (LINUX AND CODETRACER_DEBUG) - add_compile_options(-g3 -O0 -finstrument-functions -fcf-protection=none) -endif() - -# Set up your project further... - -add_library(trace trace.c) # Copy `src/native/trace.c` to your project -target_link_libraries( PUBLIC trace) - -# ... -``` - -### Example Rust setup -In most cases, the manual way of building using `trace.c` is not needed, due to our additional Rust wrapper utilities. -For projects that want to have a more advanced call graph representation, you can try linking to `trace.c` manually -using the following options: - -1. `-Z instrument-functions` -1. `-C passes=ee-instrument` -1. `-C link-arg=${tracePath}` - -It is recommended to use Codetracer's Rust compiler fork. You can use it by setting -`export RUSTC="${codetracer_rust_wrapped_output_dir}/bin/rustc"` - -The `tracePath` variable is calculated in the following way: - -1. It looks for the `CODETRACER_C_TRACE_OBJECT_FILE_PATH` environment variable and uses it if it exists -1. If it does not exist, it uses `${linksPath}/libs/trace.o`, where `linksPath` is calculated in the following way: - - If the links path constant is not empty(when compiling for the Nix package) it is set to the links path constant - - Otherwise, codetracer looks for the `CODETRACER_LINKS_PATH` environment variable and uses it if it exists - - If it does not exist, it uses `${codetracerExeDirDefault}`, which varies in values between the usage of Codetracer - 1. If using as a pure web application, it's set to `${exe.splitFile.dir.parentDir}` - 1. For our Electron backend, it's calculated in the following way: - - If the `NIX_CODETRACER_EXE_DIR` environment variable exists, it's used - - Otherwise, it's calculated using the following function `$(nodePath.dirname(nodePath.dirname(nodeFilename)))`, - where `nodeFilename` is the file name of the node executable we're using diff --git a/docs/experimental-documentation/Misc/BuildingDocs.md b/docs/experimental-documentation/Misc/BuildingDocs.md deleted file mode 100644 index 3d8f2cc69..000000000 --- a/docs/experimental-documentation/Misc/BuildingDocs.md +++ /dev/null @@ -1,7 +0,0 @@ -# Building the documentation -The documenation for codetracer is written in [GitHub Flavoured Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) -that's converted to HTML using [pandoc](https://pandoc.org). This makes the documentation both easy to write, maintain, deploy and build. - -To build the documentation run `just build-docs`. If you want to build the documentation for local development, run `just build-docs localhost` and a web server will be started on port `5000`. - -The built is stored under `docs/experimental-documentation/build`, while the markdown files are under `docs/experimental-documentation` and its child directories. diff --git a/docs/experimental-documentation/Misc/CodetracerUsage.md b/docs/experimental-documentation/Misc/CodetracerUsage.md deleted file mode 100644 index 02d92e10d..000000000 --- a/docs/experimental-documentation/Misc/CodetracerUsage.md +++ /dev/null @@ -1,44 +0,0 @@ -## Applications that use CodeTracer -Here is a list of applications that are known to use CodeTracer during their development process: - -| Type | Name | Developer | Links | -|--------------|--------------|--------------|--------------| -| Coming soon! | Coming soon! | Coming soon! | Coming soon! | - -## Technologies used in CodeTracer -Codetracer currently depends on the following open source projects: - -1. [Python](https://www.python.org/) - The Python programming language -1. [Nim](https://nim-lang.org/) - The Nim programming language -2. [Rust](https://www.rust-lang.org/) - The Rust Programming language -1. [rr](https://rr-project.org/) - Record and replay debugger -1. [gdb](https://www.sourceware.org/gdb/) - GNU debugger -1. [tree-sitter-nim](https://github.com/alaviss/tree-sitter-nim) - Parser for programming languages -1. [karax](https://github.com/karaxnim/karax) - Nim frontend framework with a virtual DOM implementation -1. [Electron](https://www.electronjs.org/) - Client framework -1. [xterm.js](https://xtermjs.org/) - Terminal emulation in the browser -1. [Monaco](https://microsoft.github.io/monaco-editor/) - Text editor widget -1. [stylus](https://stylus-lang.com/) - CSS preprocessor -1. [Chronos](https://github.com/status-im/nim-chronos) - Async library -1. [asynctools](https://github.com/cheatfate/asynctools) - Async utilities -1. [parsetoml](https://github.com/NimParsers/parsetoml) - TOML parser -1. [NimYAML](https://github.com/flyx/NimYAML) - YAML parser -1. [nim-chronicles](https://github.com/status-im/nim-chronicles) - Logging -1. [nim-confutils](https://github.com/status-im/nim-confutils) - Utility library for dealing with CLI options and config files -1. [nim-faststreams](https://github.com/status-im/nim-faststreams) - IO streams for Nim -1. [nim-json-serialization](https://github.com/status-im/nim-json-serialization) - JSON serialisation -1. [nim-serialization](https://github.com/status-im/nim-serialization) - Serialisation framework -1. [nim-prompt](https://github.com/surf1nb1rd/nim-prompt) - Interactive prompts -1. [nim-stew](https://github.com/status-im/nim-stew) - Utility library - -Please add any other libraries or projects we depend on to this list! - -## Inspiration -CodeTracer was largely inspired by the following papers, technologies and pieces of media: - -- : An excellent survey article, listing most of our competitors. -- : A very well-designed IDE for a game engine, featuring a powerful time-travelling debugger. -- : Presenting [pernosco](https://www.pernos.co/), a novel debugging interface developed by the main authors of RR. -- : A classic presentation from Bret Viktor, showcasing the dream of interactive programming. -- : The original [omniscient debugger](https://omniscientdebugger.github.io/) from Bil Lewis that inspired us to start work on CodeTracer. -- [traceGL](https://www.youtube.com/watch?v=4vtKRE9an_I): A little-known JavaScript tracing debugger that has shaped some of the key features of CodeTracer. \ No newline at end of file diff --git a/docs/experimental-documentation/_Home.md b/docs/experimental-documentation/_Home.md deleted file mode 100644 index e1dede829..000000000 --- a/docs/experimental-documentation/_Home.md +++ /dev/null @@ -1,2 +0,0 @@ -Welcome to the codetracer-desktop wiki. Use the sidebar to navigate it. All pages are ordered as a beginner -guide, so it's best you read them sequentially. \ No newline at end of file diff --git a/docs/experimental-documentation/_Sidebar.md b/docs/experimental-documentation/_Sidebar.md deleted file mode 100644 index 4e1584e7c..000000000 --- a/docs/experimental-documentation/_Sidebar.md +++ /dev/null @@ -1,34 +0,0 @@ -- [Home](https://dev-docs.codetracer.com/) -- Beginner topics - - [Introduction](https://dev-docs.codetracer.com/Introduction/Introduction) - - [Usage guide](https://dev-docs.codetracer.com/Introduction/CodetracerGuide) - - [CLI](https://dev-docs.codetracer.com/Introduction/UsageGuide/CLI) - - [GUI](https://dev-docs.codetracer.com/Introduction/UsageGuide/BasicGUI) - - [Tracepoints](https://dev-docs.codetracer.com/Introduction/UsageGuide/Tracepoints) - - [CodeTracer Shell](https://dev-docs.codetracer.com/Introduction/UsageGuide/CodetracerShell) - - [Building C/C++ applications manually](https://dev-docs.codetracer.com/Introduction/UsageGuide/ManualBuilding) - - [Test applications](https://dev-docs.codetracer.com/Introduction/TestApplications) - - Backends - - [CoreBackend](https://dev-docs.codetracer.com/Introduction/Backends/CoreBackend) - - [C & C++](https://dev-docs.codetracer.com/Introduction/Backends/CoreBackend/CAndCpp) - - [Rust](https://dev-docs.codetracer.com/Introduction/Backends/CoreBackend/Rust) - - [Nim](https://dev-docs.codetracer.com/Introduction/Backends/CoreBackend/Nim) - - [Golang](https://dev-docs.codetracer.com/Introduction/Backends/CoreBackend/Golang) - - [DBBackend](https://dev-docs.codetracer.com/Introduction/Backends/DBBackend) - - [Noir](https://dev-docs.codetracer.com/Introduction/Backends/DBBackend/Noir) - - [Ruby](https://dev-docs.codetracer.com/Introduction/Backends/DBBackend/Ruby) - - [SmallLang](https://dev-docs.codetracer.com/Introduction/Backends/DBBackend/SmallLang) - - - Client-server model - - [Building & packaging](https://dev-docs.codetracer.com/Introduction/BuildSystem) - - [Configuration](https://dev-docs.codetracer.com/Introduction/Configuration) - - Limitations - - [Troubleshooting](https://dev-docs.codetracer.com/Introduction/Troubleshooting) -- Advanced topics - - [Environment variables](https://dev-docs.codetracer.com/Advanced/EnvironmentVariables) - - Custom patches - - Dotfiles -- Misc - - [Applications that use CodeTracer](https://dev-docs.codetracer.com/Misc/Dependencies) - - [Building the documentation](https://dev-docs.codetracer.com/Misc/BuildingDocs) diff --git a/docs/experimental-documentation/generate-html.sh b/docs/experimental-documentation/generate-html.sh deleted file mode 100755 index 5800f882c..000000000 --- a/docs/experimental-documentation/generate-html.sh +++ /dev/null @@ -1,40 +0,0 @@ -#!/usr/bin/env bash -mkdir build &> /dev/null || (rm -rf build && mkdir build) || exit -cp ./*.md ./*.css ./*.js Advanced/ Introduction/ Misc/ build/ -r || exit -cd build || exit - -title=$(grep "# " "$1" | head -1 | sed 's/[^ ]* //') -echo "
" > _Sidebar.html || exit -pandoc --from=gfm --standalone --template ../sidebar_template.html -s _Sidebar.md >> _Sidebar.html || exit -echo "
" >> _Sidebar.html || exit -rm _Sidebar.md || exit - -extract() { - title=$(grep "# " "$1" | head -1 | sed 's/[^ ]* //') - out_dir="$(echo "$(dirname "$1")"/"$(basename "$1" md)"html 2> /dev/null)" - - echo -e "\n\n" >> "$1" - cat "_Sidebar.html" >> "$1" - - echo "Processing file: ${out_dir}" - - pandoc --from=gfm --standalone --template ../template.html -s "$1" -o "${out_dir}" --metadata=title:"${title}" 2> /dev/null - - sed -i 's//
/g' "${out_dir}" - sed -i 's/<\/table>/<\/table><\/div>/g' "${out_dir}" - - rm "$(realpath "$1")" || exit -} - -export -f extract - -cpus=$(grep -c processor /proc/cpuinfo) || cpus=$(sysctl -n hw.ncpu) -find ./ -type f -name '*.md' -printf '%p\n' | parallel -j "${cpus}" extract || exit - -mv _Home.html index.html || exit - -if [ "$1" == 'localhost' ]; then - find ./ -type f \( -iname \*.html -o -iname \*.js \) -exec sed -i 's/\.\//http:\/\/0.0.0.0:5000\//g' {} \; - find ./ -type f \( -iname \*.html -o -iname \*.js \) -exec sed -i 's/https:\/\/dev-docs\.codetracer\.com\//http:\/\/0\.0\.0\.0:5000\//g' {} \; - python3 -m http.server 5000 -fi diff --git a/docs/experimental-documentation/index.js b/docs/experimental-documentation/index.js deleted file mode 100644 index 38f13a20b..000000000 --- a/docs/experimental-documentation/index.js +++ /dev/null @@ -1,44 +0,0 @@ -'use strict' - -/** - * Troll jQuery users - * @param x - ID of the element to request - * @returns {HTMLElement|null} Element returned or null - */ -function $(x) -{ - return document.getElementById(x); -} - -/** - * Helper to quickly create an element - * @param { string } tag - HTML element tag type - * @param { string } content - Text content of the element - * @param { string } id - ID of the element - * @param { string } className - Class name of the element - * @param { Array>|null } additionalInfo - Additional key-value pairs to add to the element - * @param { HTMLElement } parent - Parent element to attach to - * @return { HTMLElement } The element in question - */ -function createElement(tag, content, id, className, additionalInfo, parent) -{ - let element = document.createElement(tag); - element.textContent = content; - element.id = id; - element.className = className; - - if (additionalInfo !== null) - for (let info in additionalInfo) - element[additionalInfo[info][0]] = additionalInfo[info][1]; - - parent.appendChild(element); - - return element; -} - -function main() -{ - -} - -main() \ No newline at end of file diff --git a/docs/experimental-documentation/main.css b/docs/experimental-documentation/main.css deleted file mode 100644 index 4c91552e6..000000000 --- a/docs/experimental-documentation/main.css +++ /dev/null @@ -1,269 +0,0 @@ -:root { - --main-background-colour: #f9fbf2; - --main-colour: #00000; - --main-accent-colour: #7776bc; - --main-border-colour: #0e1c36; - --main-code-background-colour: #0e1c36; - - - --note-colour: #2f81f7; - --tip-colour: #3fb950; - --important-colour: #a371f7; - --warning-colour: #d29922; - --caution-colour: #f85149; -} - -html { - margin: 0; - padding: 0; - - background-color: var(--main-background-colour); -} - -main { - display: grid; - grid-template-columns: 4fr 1fr; -} - -@media (orientation: portrait) { - main { - display: block; - } - - #main-text { - border-bottom: 0.1rem solid var(--main-border-colour); - } -} - -main, footer { - max-width: 1920px; - margin-left: auto; - margin-right: auto; -} - -footer { - list-style: none; - overflow: hidden; -} - -footer p, footer select { - padding: 0 0.33rem 0 0.33rem; - font-size: 14px; - color: var(--main-colour); -} - -h1, h2, h3, h4, h5, h6, p, li { - color: var(--main-colour); - font-family: "Ubuntu", sans-serif; -} - -a { - text-decoration: none; - color: var(--main-accent-colour); - font-family: "Ubuntu", sans-serif; -} - -li { - margin-top: 6px; - margin-bottom: 6px; -} - -header { - border-bottom: 1px solid var(--main-border-colour); -} - -header ul { - list-style: none; - padding: 0; - margin: 0; - overflow: hidden; -} - -header ul li { - float: left; - position: relative; - display: flex; - align-items: center; -} - -header ul li a { - display: block; - color: var(--main-accent-colour); - text-align: center; - padding: 0 24px 0 24px; - text-decoration: none; - font-size: 32px; - line-height: 1.5; -} - -select { - padding: 0 0 0 0; - margin: 0 0 0 0; - max-width: max-content; - resize: horizontal; -} - -option { - display: flex; - min-width: 0; - flex-direction: row; - border-color: red; - box-sizing: border-box; -} - -pre > code, code, .sourceCode, .liquid, code .sourceCode span { - width: fit-content; - overflow-x: scroll; - font-family: "JetBrains Mono", monospace; - font-optical-sizing: auto; - font-weight: 400; - font-style: normal; - color: var(--main-background-colour); -} - -code, .sourceCode pre, .liquid pre { - width: fix-content; - overflow-x: scroll; - background-color: var(--main-code-background-colour); - padding: 0.2em; - white-space: pre-wrap; - white-space: -moz-pre-wrap; - white-space: pre-wrap; - white-space: -o-pre-wrap; - word-wrap: break-word; -} - -code:not([class]) { - padding: 0.2em 0.4em; - margin: 0; - font-size: 85%; - white-space: break-spaces; - border-radius: 6px; -} - -.sourceCode code { - color: var(--main-colour); - padding: 0; - display: block; - margin: auto; -} - -figcaption { - display: none; -} - -figure { - margin: 0; - overflow-x: scroll; -} - -table, .table { - display: block; - border-collapse: collapse; - overflow-x: scroll; -} - -th, td { - color: white; - border: 1px solid var(--main-colour); -} - -th { - font-weight: bold; -} - -tr { - text-align: center; -} - -input[type=text]::before, input[type=text]::after, input[type=text] { - box-sizing: border-box; -} - -/* Configure input text fields to follow our style */ -input[type=text] { - color: var(--main-colour); - max-width: 85%; - font-size: 16px; - font-family: inherit; - padding: 2px 2px 2px 2px; - background-color: var(--main-background-colour); - border: 1px solid var(--main-accent-colour); - border-radius: 4px; - margin-bottom: 1rem; -} - -img { - width: 100%; - overflow: scroll; -} - -iframe { - border: 0; -} - -hr { - padding: 0 0 0 0; - margin: 0 0 0 0; - border: 0; - border-top: 0.1rem solid var(--main-border-colour); - background-color: var(--main-border-colour); -} - -#err-404-emoji { - font-size: 14vw; -} - -.centered { - text-align: center; -} - -.vcentered { - margin: auto; -} - -.note, .tip, .important, .warning, .caution { - padding-left: 0.5rem; - border-left-width: 0.25em; - border-left-style: solid; -} - -.note { - border-left-color: var(--note-colour); -} - -.note .title p { - color: var(--note-colour); -} - -.tip { - border-left-color: var(--tip-colour); -} - -.tip .title p { - color: var(--tip-colour); -} - -.important { - border-left-color: var(--important-colour); -} - -.important .title p { - color: var(--important-colour); -} - -.warning { - border-left-color: var(--warning-colour); -} - -.warning .title p { - color: var(--warning-colour); -} - -.caution { - border-left-color: var(--caution-colour); -} - -.caution .title p { - color: var(--caution-colour) -} diff --git a/docs/experimental-documentation/sidebar_template.html b/docs/experimental-documentation/sidebar_template.html deleted file mode 100644 index f37d7c6dc..000000000 --- a/docs/experimental-documentation/sidebar_template.html +++ /dev/null @@ -1 +0,0 @@ -$body$ \ No newline at end of file diff --git a/docs/experimental-documentation/template.html b/docs/experimental-documentation/template.html deleted file mode 100644 index 3ad1e1c6c..000000000 --- a/docs/experimental-documentation/template.html +++ /dev/null @@ -1,49 +0,0 @@ - - - - $title$ - - - - - - - - - - - - - - - - - - - - - -
-
-$body$ -
-
-

- © 2025 Metacraft Labs Ltd. -

-
- - - - - - - - - - - - - - - diff --git a/examples/array.rb b/examples/array.rb index 0f9cdfa0f..8c7bfef87 100644 --- a/examples/array.rb +++ b/examples/array.rb @@ -1,5 +1,7 @@ arr = [42, "Banana", [1, 2]] +puts ARGV + puts arr arr.each do |x| puts x diff --git a/justfile b/justfile index 2893e782f..d2b0e3b4b 100644 --- a/justfile +++ b/justfile @@ -46,10 +46,15 @@ build-once: cd src tup build-debug -build-docs *LOCALHOST: +build-docs: #!/usr/bin/env bash - cd docs/experimental-documentation/ - nix-shell --run "./generate-html.sh {{LOCALHOST}}" + cd docs/book/ + mdbook build + +serve-docs hostname="localhost" port="3000": + #!/usr/bin/env bash + cd docs/book/ + mdbook serve --hostname {{hostname}} --port {{port}} build-deb-package file_sizes_report="false": #!/usr/bin/env bash diff --git a/nix/shells/main.nix b/nix/shells/main.nix index cac7a7e18..e5ec0fbbd 100644 --- a/nix/shells/main.nix +++ b/nix/shells/main.nix @@ -96,6 +96,10 @@ in # a tool to help with binary files hexdump + # docs + mdbook + mdbook-alerts + # cachix support cachix @@ -221,8 +225,8 @@ in # workaround to reuse devshell node_modules for tup build # make sure it's always updated - rm -rf node_modules - ln -s $NIX_NODE_PATH node_modules + rm -rf $ROOT_PATH/node_modules + ln -s $NIX_NODE_PATH $ROOT_PATH/node_modules export NIX_CODETRACER_EXE_DIR=$ROOT_PATH/src/build-debug/ export LINKS_PATH_DIR=$ROOT_PATH/src/build-debug/