328 lines
11 KiB
Markdown
328 lines
11 KiB
Markdown
# GREX
|
|
|
|
**A graphical editor for Rex projects.**
|
|
|
|
AGPL-3.0 | Written by Chris Punches | [SILO GROUP](https://www.silogroup.org)
|
|
|
|
---
|
|
|
|
## What is GREX?
|
|
|
|
GREX is a desktop application for creating and managing
|
|
[Rex](https://git.silogroup.org/SILO-GROUP/rex) project files. Rex is SILO
|
|
GROUP's JSON-driven workflow execution system — it runs scripts and executables
|
|
in a predetermined order with logging, error handling, and self-healing
|
|
capabilities. Rex was originally built to drive the creation of
|
|
[Dark Horse Linux](https://www.darkhorselinux.org) but is designed for any
|
|
automation use case.
|
|
|
|
Rex projects are configured entirely through JSON files: configs, plans, unit
|
|
definitions, and shell definitions. GREX provides a visual interface for
|
|
managing all of these, replacing the need to hand-edit JSON. GREX edits Rex
|
|
project files — it does not execute them. Rex remains the runtime.
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
### Prerequisites
|
|
|
|
- A C++17-capable compiler (GCC 8+ or Clang 7+)
|
|
- CMake 3.10 or later
|
|
- GTK4 development libraries
|
|
- pkg-config
|
|
|
|
The nlohmann/json library is vendored and does not require separate
|
|
installation.
|
|
|
|
### Building
|
|
|
|
```bash
|
|
cmake -B build
|
|
cmake --build build
|
|
```
|
|
|
|
The resulting binary is `build/grex`.
|
|
|
|
### Distribution Packages
|
|
|
|
Distribution-specific packages are not yet available. To install system-wide,
|
|
place the `grex` binary in a location on your `PATH` (e.g.,
|
|
`/usr/local/bin`).
|
|
|
|
---
|
|
|
|
## Getting Started
|
|
|
|
Launch GREX with no arguments to start with an empty session:
|
|
|
|
```bash
|
|
grex
|
|
```
|
|
|
|
Or open directly into a Rex project by passing a config file:
|
|
|
|
```bash
|
|
grex -c /path/to/rex.config
|
|
```
|
|
|
|
When you launch without a config, the first thing to do is open or create one
|
|
on the **Rex Config** tab. Once a config is loaded and its paths resolve
|
|
correctly, the **Plans**, **Units**, and **Shells** tabs become active.
|
|
|
|
On first launch, GREX creates its own settings file at
|
|
`~/.config/grex/grex.ini` with default values.
|
|
|
|
A status bar at the bottom of the window reports the results of load, save, and
|
|
error operations as you work.
|
|
|
|
---
|
|
|
|
## Working with Rex Configs
|
|
|
|
The **Rex Config** tab is where you load and manage your project's
|
|
configuration file.
|
|
|
|
### Opening and Creating Configs
|
|
|
|
- **Open Config** — Browse to an existing `rex.config` file.
|
|
- **Create Config** — Choose a location and filename to create a new, empty
|
|
config.
|
|
- **Close Config** — Unload the current config. The other tabs will be
|
|
disabled until a new config is loaded.
|
|
|
|
### Editing Configuration Values
|
|
|
|
Once a config is loaded, its key-value pairs are displayed as editable fields.
|
|
The standard keys are:
|
|
|
|
- `project_root` — The root directory of your Rex project.
|
|
- `units_path` — Path to the directory containing `.units` files (relative to
|
|
project root).
|
|
- `shells_path` — Path to the shells definition file (relative to project
|
|
root).
|
|
|
|
You can also define custom keys for your own use.
|
|
|
|
### Variables
|
|
|
|
Configuration values can contain variable references using `${VAR}` syntax.
|
|
For example:
|
|
|
|
```
|
|
project_root = ${HOME}/my-rex-project
|
|
```
|
|
|
|
GREX resolves these variables from your environment. If a variable is not set
|
|
in your environment, the **Variables** section will show it as unresolved and
|
|
let you provide an override value manually.
|
|
|
|
### Resolved Paths
|
|
|
|
The **Resolved Paths** section shows the fully-expanded values of
|
|
`project_root`, `units_dir`, and `shells_path` after variable substitution.
|
|
Check this section to confirm that your paths are pointing where you expect
|
|
before moving on to the other tabs.
|
|
|
|
### Saving
|
|
|
|
Click **Save** to write the config back to disk. The save button turns blue
|
|
when there are unsaved changes.
|
|
|
|
---
|
|
|
|
## Working with Plans
|
|
|
|
The **Plans** tab is where you create and manage execution plans — the ordered
|
|
sequences of tasks that Rex runs.
|
|
|
|
### Opening and Creating Plans
|
|
|
|
- **Open Plan** — Browse to an existing plan file.
|
|
- **Create Plan** — Choose a location and filename for a new, empty plan.
|
|
- **Close Plan** — Unload the current plan.
|
|
|
|
The current plan filename is shown in the header.
|
|
|
|
### Managing Tasks
|
|
|
|
The left panel lists the tasks in the current plan. Tasks are executed by Rex
|
|
in the order they appear.
|
|
|
|
- **Add** — Append a new empty task to the plan.
|
|
- **Delete** — Remove the selected task.
|
|
- **Move Up / Move Down** — Reorder the selected task.
|
|
|
|
### Editing a Task
|
|
|
|
Select a task in the list to view its properties in the right panel:
|
|
|
|
- **Name** — The name of the unit this task will execute (read-only display;
|
|
change it with the unit picker below).
|
|
- **Comment** — An optional note describing what this task does or why it
|
|
exists.
|
|
- **Change/Select Unit...** — Opens a picker dialog listing all units across
|
|
your loaded unit files. Select one to assign it to this task.
|
|
- **Edit Unit...** — Opens a modal dialog to edit the properties of the unit
|
|
assigned to this task.
|
|
- **Save Unit** — Writes changes to the unit's file on disk. Turns blue when
|
|
the unit has unsaved changes.
|
|
|
|
### Saving the Plan
|
|
|
|
Click **Save Plan** to write the plan file to disk. The button turns blue when
|
|
there are unsaved changes. If you switch tabs with unsaved changes, GREX will
|
|
prompt you to save or revert.
|
|
|
|
---
|
|
|
|
## Working with Units
|
|
|
|
The **Units** tab is where you manage unit definitions — the building blocks
|
|
that Rex executes.
|
|
|
|
### Browsing Unit Files
|
|
|
|
The left panel lists all `.units` files found in your project's units
|
|
directory. Select a file to see its units in the right panel.
|
|
|
|
### Managing Unit Files
|
|
|
|
- **New File** — Create a new `.units` file in your units directory.
|
|
- **Delete File** — Remove the selected file from the project (the file is not
|
|
deleted from disk).
|
|
|
|
### Managing Units Within a File
|
|
|
|
The right panel lists the units in the selected file, in the order they appear
|
|
in the file.
|
|
|
|
- **New Unit** — Add a new unit to the current file. You will be prompted for
|
|
a name. Unit names must be unique across all unit files in the project.
|
|
- **Delete Unit** — Remove the selected unit.
|
|
- **Edit Unit...** — Open a modal dialog to edit the selected unit's
|
|
properties.
|
|
- **Move Up / Move Down** — Reorder the selected unit within the file.
|
|
- **Rename** — Double-click a unit to rename it inline. Press Enter to confirm
|
|
or click elsewhere to cancel.
|
|
|
|
### Unit Properties
|
|
|
|
When you open the unit properties dialog (from either the Units or Plans tab),
|
|
you can configure:
|
|
|
|
- **Target** — The script or command that Rex will execute.
|
|
- **Shell Definition** — Which shell interpreter to use (selected from your
|
|
project's shell definitions).
|
|
- **Shell Command** — Whether the target is a shell command (interpreted by the
|
|
shell) or a direct path to an executable.
|
|
- **Force PTY** — Allocate a pseudo-terminal for execution.
|
|
- **Rectify / Rectifier** — Enable self-healing behavior. If the target fails
|
|
and rectification is enabled, Rex runs the rectifier script before
|
|
continuing. This is one of Rex's most powerful features — it allows
|
|
verification-and-fix patterns and preventive error recovery.
|
|
- **Active** — Whether Rex will include this unit when executing a plan. Inactive
|
|
units are skipped.
|
|
- **Required** — Whether failure of this unit should halt plan execution. If a
|
|
non-required unit fails (and rectification doesn't resolve it), Rex
|
|
continues to the next task.
|
|
- **User / Group** — Run the target under a specific user and group identity.
|
|
- **Working Directory** — Set a custom working directory for execution.
|
|
- **Environment** — Path to an environment file to source before execution.
|
|
|
|
You can also browse for file paths and open or create files in your configured
|
|
editor directly from the dialog.
|
|
|
|
### Saving
|
|
|
|
Click **Save Unit File** to write changes to disk. The button turns blue when
|
|
there are unsaved changes. Switching to a different unit file with unsaved
|
|
changes will prompt you to save or revert.
|
|
|
|
---
|
|
|
|
## Working with Shells
|
|
|
|
The **Shells** tab is where you manage shell definitions — the interpreters
|
|
that Rex uses to run unit targets.
|
|
|
|
### Managing Shell Definitions
|
|
|
|
The left panel lists all defined shells. Select one to edit its properties in
|
|
the right panel.
|
|
|
|
- **Add** — Create a new shell definition.
|
|
- **Delete** — Remove the selected shell definition.
|
|
|
|
### Shell Properties
|
|
|
|
Each shell definition has four fields:
|
|
|
|
- **Name** — An identifier for the shell (e.g., `bash`, `zsh`, `python3`).
|
|
This is the name referenced by units' shell definition setting.
|
|
- **Path** — The full filesystem path to the interpreter binary (e.g.,
|
|
`/bin/bash`).
|
|
- **Execution Arg** — The argument used to pass a command string for execution
|
|
(e.g., `-c`).
|
|
- **Source Cmd** — The command used to source environment files (e.g.,
|
|
`source` for bash, `.` for POSIX sh).
|
|
|
|
### Saving
|
|
|
|
Click **Save Shells** to write the shells file to disk.
|
|
|
|
---
|
|
|
|
## GREX Settings
|
|
|
|
Click the **Grex Config** button in the header bar to open GREX's own settings
|
|
dialog.
|
|
|
|
Currently, the only setting is:
|
|
|
|
- **File Editor** — The command GREX uses to open files for external editing.
|
|
The default is `xterm -e vim`. Change this to your preferred terminal editor
|
|
command (e.g., `alacritty -e nano`, `gnome-terminal -- vim`,
|
|
`xdg-open`).
|
|
|
|
GREX stores its settings at `~/.config/grex/grex.ini` (or under
|
|
`$XDG_CONFIG_HOME/grex/` if that variable is set). The format is simple
|
|
key-value:
|
|
|
|
```ini
|
|
file_editor=xterm -e vim
|
|
```
|
|
|
|
---
|
|
|
|
## Rex Concepts Quick Reference
|
|
|
|
| Concept | Meaning |
|
|
|---|---|
|
|
| **Project** | A Rex workspace anchored by a `rex.config` file. All paths are resolved relative to the project root. |
|
|
| **Config** | The `rex.config` file. Defines the project root, where to find units and shells, and any custom key-value settings. |
|
|
| **Plan** | An ordered list of tasks for Rex to execute sequentially. |
|
|
| **Task** | A single entry in a plan. Each task references a unit by name and optionally carries a comment. |
|
|
| **Unit** | A definition of something Rex can execute — a script, command, or binary — along with its execution context and error handling behavior. |
|
|
| **Shell** | An interpreter definition (name, binary path, execution argument, source command) that Rex uses to run shell-command units. |
|
|
| **Variable** | A `${VAR}` pattern in a config value, resolved from environment variables or manual overrides. Enables portable configs across machines. |
|
|
| **Rectification** | Rex's self-healing mechanism. When a unit's target fails and rectification is enabled, Rex runs the rectifier script. Used for verification-and-fix or preventive recovery patterns. |
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
GREX is licensed under the
|
|
[GNU Affero General Public License v3.0](https://www.gnu.org/licenses/agpl-3.0.html)
|
|
(AGPL-3.0).
|
|
|
|
Copyright (C) 2025, SILO GROUP LLC. Written by Chris Punches.
|
|
|
|
---
|
|
|
|
## Links
|
|
|
|
- [Rex](https://git.silogroup.org/SILO-GROUP/rex) — The Rex execution engine
|
|
- [SILO GROUP](https://www.silogroup.org) — Distributed systems and consulting
|
|
- [Dark Horse Linux](https://www.darkhorselinux.org) — The Linux distribution Rex was originally built for
|
