initial commit
Signed-off-by: NotAShelf <raf@notashelf.dev> Change-Id: I6a6a69644236ae18e7b46856fb6d6d6c998f8467
This commit is contained in:
commit
c07b295f71
GPG key ID:
29D95B64378DB4BF
29 changed files with 6780 additions and 0 deletions
109
docs/FORMATS.md
Normal file
109
docs/FORMATS.md
Normal file
|
|
@ -0,0 +1,109 @@
|
|||
# ROM Display Formats
|
||||
|
||||
Unlike prior art, ROM features several different display and legend formats as
|
||||
opposed to NOM's immutable design. This allows for the freedom to mix and match
|
||||
different component styles in the build graph.
|
||||
|
||||
## Display Formats
|
||||
|
||||
ROM supports three display formats controlled by the `--format` flag:
|
||||
|
||||
1. Tree Format (Default)
|
||||
2. Plain Format
|
||||
3. Dashboard Format
|
||||
|
||||
### 1. Tree Format (Default)
|
||||
|
||||
The tree format shows a hierarchical dependency graph with build progress.
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
rom --format tree build nixpkgs#hello
|
||||
# or simply (tree is default)
|
||||
rom build nixpkgs#hello
|
||||
```
|
||||
|
||||
### Examples
|
||||
|
||||
**Tree Format**:
|
||||
|
||||
```plaintext
|
||||
┏━ Dependency Graph:
|
||||
┃ ⏵ hello-2.12.2 (buildPhase) ⏱ 5s
|
||||
┣━━━ Builds
|
||||
┗━ ∑ ⏵ 1 │ ✔ 0 │ ✗ 0 │ ⏸ 4 │ ⏱ 5s
|
||||
```
|
||||
|
||||
**Plain Format**:
|
||||
|
||||
```plaintext
|
||||
━ ⏱ ⏸ 4 planned ↓ 2 downloading ↑ 1 uploading 5.7s
|
||||
↓ breakpad-2024.02.16 1.2 MB/5.0 MB (24%)
|
||||
↓ spirv-tools-1.4.321.0 0 B
|
||||
↑ gcc-13.2.0 250 KB
|
||||
⏵ hello-2.12.2 5s
|
||||
```
|
||||
|
||||
**Dashboard Format**:
|
||||
|
||||
```plaintext
|
||||
BUILD GRAPH: hello-2.12.2
|
||||
────────────────────────────────────────────
|
||||
Host │ localhost
|
||||
Status │ ⏵ building
|
||||
Duration │ 8.1s
|
||||
────────────────────────────────────────────
|
||||
Summary │ jobs=1 ok=1 failed=0 total=8.1s
|
||||
```
|
||||
|
||||
## Legend Styles
|
||||
|
||||
Legend styles control how thee build statistics are displayed at the bottom of
|
||||
the screen. At this moment they only affect the **tree format**.
|
||||
|
||||
1. Table Style
|
||||
2. Compact Style
|
||||
3. Verbose Style
|
||||
|
||||
### Examples
|
||||
|
||||
**Table**:
|
||||
|
||||
```plaintext
|
||||
┏━ Dependency Graph:
|
||||
┃ ⏵ hello-2.12.2 (buildPhase) ⏱ 5s
|
||||
┣━━━ Builds
|
||||
┗━ ∑ ⏵ 1 │ ✔ 0 │ ✗ 0 │ ⏸ 4 │ ⏱ 5s
|
||||
```
|
||||
|
||||
**Compact**:
|
||||
|
||||
```plaintext
|
||||
┏━ Dependency Graph:
|
||||
┃ ⏵ hello-2.12.2 (buildPhase) ⏱ 5s
|
||||
┗━ ⏵ 1 │ ✔ 0 │ ✗ 0 │ ⏸ 4 │ ⏱ 5s
|
||||
```
|
||||
|
||||
**Verbose**:
|
||||
|
||||
```plaintext
|
||||
┏━ Dependency Graph:
|
||||
┃ ⏵ hello-2.12.2 (buildPhase) ⏱ 5s
|
||||
┣━━━ Build Summary:
|
||||
┗━ ⏵ 1 running │ ✔ 0 completed │ ✗ 0 failed │ ⏸ 4 planned │ ⏱ 5s
|
||||
```
|
||||
|
||||
## Icon Legend
|
||||
|
||||
All formats use consistent icons:
|
||||
|
||||
| Icon | Meaning | Color |
|
||||
| ---- | ----------------- | ------ |
|
||||
| ⏵ | Building/Running | Yellow |
|
||||
| ✔ | Completed/Success | Green |
|
||||
| ✗ | Failed/Error | Red |
|
||||
| ⏸ | Planned/Waiting | Grey |
|
||||
| ⏱ | Time/Duration | Grey |
|
||||
| ↓ | Downloading | Blue |
|
||||
| ↑ | Uploading | Green |
|
||||
101
docs/README.md
Normal file
101
docs/README.md
Normal file
|
|
@ -0,0 +1,101 @@
|
|||
# ROM
|
||||
|
||||
A Nix build output monitor for visualizing your Nix builds, with Rust
|
||||
characteristics and DX.
|
||||
|
||||
This project is heavily work in progress. The parser is mostly complete, and
|
||||
located in [`./cognos`](./cognos)
|
||||
|
||||
> [!NOTE]
|
||||
> This project is not yet stable. While it can not harm your projeeect, bugs
|
||||
> must be expected due to its in-dev status. If you end up using ROM, please
|
||||
> make sure to report any bugs :)
|
||||
|
||||
## Usage
|
||||
|
||||
> [!WARNING]
|
||||
> The CLI interface of ROM is not yet stable, and may be subject to change.
|
||||
> Plase consult the `--help` output before reporting a bug.
|
||||
|
||||
```terminal
|
||||
$ rom -h
|
||||
Rust Output Monitor - A Nix build output monitor
|
||||
|
||||
Usage: rom [OPTIONS] [COMMAND]
|
||||
|
||||
Commands:
|
||||
build Run nix build with monitoring
|
||||
shell Run nix shell with monitoring
|
||||
develop Run nix develop with monitoring
|
||||
help Print this message or the help of the given subcommand(s)
|
||||
|
||||
Options:
|
||||
--json Parse JSON output from nix --log-format=internal-json
|
||||
--silent Minimal output
|
||||
--format <FORMAT> Output format: tree, plain [default: tree]
|
||||
--legend <LEGEND> Legend display style: compact, table, verbose [default: table]
|
||||
-h, --help Print help
|
||||
-V, --version Print version
|
||||
```
|
||||
|
||||
ROM is primarily designed to wrap the Nix installation on your system. As such,
|
||||
the _recommended_ interface is using `rom build`, `rom shell` and `rom develop`
|
||||
for their Nix counterparts. The CLI of ROM is similar to NOM, the Haskell
|
||||
utility ROM is designed after. To build a package with Nix, let's say
|
||||
`pkgs.hello`, you can do:
|
||||
|
||||
```terminal
|
||||
$ rom build nixpkgs#hello
|
||||
┏━ Dependency Graph:
|
||||
┃ ⏵ hello-2.12.2 (configurePhase) ⏱ 2s
|
||||
┣━━━ Builds
|
||||
┗━ ∑ ⏵ 1 │ ✔ 0 │ ✗ 0 │ ⏸ 4 │ ⏱ 2s
|
||||
```
|
||||
|
||||
and the dependency tree will appear below.
|
||||
|
||||
### Argument Passthrough
|
||||
|
||||
At times, especially while you're calling ROM as a standalone executable, you
|
||||
might need to pass additional flags to the Nix command being invoked. ROM allows
|
||||
for this behaviour by accepting `--` as a delimiter and passing any arguments
|
||||
that come after to Nix. For example:
|
||||
|
||||
```terminal
|
||||
$ rom develop nixpkgs#hello -- --substituters ""
|
||||
fetching git input 'git+file:///home/notashelf/Dev/notashelf/rom'
|
||||
┗━ ⏵ 0 │ ✔ 2 │ ✗ 0 │ ⏸ 0 │ ⏱ 1s
|
||||
|
||||
|
||||
notashelf@enyo ~/Dev/notashelf/rom [git:(9e83f57...) *]
|
||||
i $ hello
|
||||
Hello, world!
|
||||
```
|
||||
|
||||
## FAQ
|
||||
|
||||
**Q**: If "NOM" is nix-output-monitor, what does "ROM stand for"?
|
||||
|
||||
**A**: It doesn't stand for anything, I named it _rom_ beceuse it sounds like
|
||||
_rum_. I like rum. However you may choose to name it "rusty output monitor" or
|
||||
"raf's output monitor" at your convenience. I don't know, be creative.
|
||||
|
||||
## Attributions
|
||||
|
||||
This project is clearly inspired by the famous
|
||||
<https://github.com/maralorn/nix-output-monitor>. I am a huge fan of NOM's
|
||||
design, but I am a little disappointed by its lack of configurability. This is a
|
||||
more flexible replacement that makes both my life, and displaying build graphs
|
||||
easier.
|
||||
|
||||
The ATerm and internal-json log parser was inspired, and mostly copied from
|
||||
<https://git.atagen.co/atagen/nous> with consolidation, cleaner repo layout, and
|
||||
a better separation of concerns. rom builds on the ideas previously pondered by
|
||||
nous, and provides a subcrate under [`./cognos`](./cognos) for easy parsing.
|
||||
Thank you Atagen for letting me play with the idea.
|
||||
|
||||
## License
|
||||
|
||||
This project is made available under Mozilla Public License (MPL) version 2.0.
|
||||
See [LICENSE](LICENSE) for more details on the exact conditions. An online copy
|
||||
is provided [here](https://www.mozilla.org/en-US/MPL/2.0/).
|
||||
Loading…
Add table
Add a link
Reference in a new issue