Files
daedalus/INSTALL.md
T

161 lines
5.6 KiB
Markdown

# Installing and using daedalus
Python 3.11 or newer. This checkout is an **empty template** (no scripts in
`SCRIPTS` yet). Once you add scripts, the installed `daedalus` command
bundles every registered one and works from any directory.
- [Install](#install)
- [Usage](#usage)
- [Add a script](#add-a-script)
- [Development](#development)
Back to the [script list](./README.md#available-scripts). Repository rules:
[SPEC](./SPEC.md).
## Install
### With pipx (recommended)
[pipx](https://pipx.pypa.io/) installs daedalus into its own environment
and puts the `daedalus` command on `PATH`.
Linux (Debian 12): paste once; open a new shell if `pipx` was just
installed. Run the same block again to refresh from Git (`main`); do **not**
use `pipx upgrade daedalus` for Git installs — it does not pull the repo.
```bash
daedalus_pipx_install() {
r="${1:-git+ssh://git@example.com/your-org/daedalus.git@main}"
command -v pipx >/dev/null || sudo apt install -y pipx
pipx ensurepath 2>/dev/null || pipx ensurepath --force
if pipx list --short 2>/dev/null | grep -qE '^daedalus '; then
pipx install --force "$r"
else
pipx install "$r"
fi
daedalus --version
}; daedalus_pipx_install
```
No SSH key on the Git host: `daedalus_pipx_install git+https://example.com/your-org/daedalus.git`
Windows (PowerShell):
```powershell
python -m pip install --user pipx
python -m pipx ensurepath # once; then open a new terminal
pipx install git+ssh://git@example.com/your-org/daedalus.git
```
Without an SSH key for the Git host, use
`git+https://example.com/your-org/daedalus.git` instead.
### From a checkout
```bash
git clone git@example.com:your-org/daedalus.git
cd daedalus
pipx install . # or, inside a virtual environment: pip install .
```
On Debian 12, `pip install` into the system Python is blocked
(externally managed environment). Use pipx or a virtual environment.
### Without installing
Linux: add to `~/.bashrc`, call `daedalus_checkout` (clone once,
then `git pull --ff-only`).
```bash
daedalus_checkout() {
d="${1:-$HOME/daedalus}"
[[ -d "$d/.git" ]] && git -C "$d" pull --ff-only \
|| git clone git@example.com:your-org/daedalus.git "$d"
export PATH="$d/bin:$PATH"
}; daedalus_checkout
```
Windows: add `<checkout>\bin` to `PATH` (`bin\daedalus.bat`).
### Check, upgrade, remove
```bash
daedalus --version # confirm the install
daedalus_pipx_install # reinstall from Git (same as first paste block)
pipx uninstall daedalus
```
## Usage
```bash
daedalus --help # usage
daedalus [--list] # list the available scripts
daedalus <name> [args...] # run a script; every argument after the name goes to it
daedalus <category> [category...] # list scripts that have every category
daedalus <category> <name> [args...] # run when the script has every category
daedalus --path <name> # print where the script file is
daedalus --version # print the installed version
```
- `daedalus NAME --help` shows the help of the script, not of daedalus.
- The exit code is the script's exit code. daedalus's own errors, such as
an unknown name, exit with 2 and suggest close matches.
- Listings print `Daedalus Version:`, a table of `script`, `type`, and
`categories`, and the wrapped description under each row. Colors follow
`NO_COLOR` / `FORCE_COLOR` and the terminal.
Environment variables:
| Variable | Effect |
| --- | --- |
| `DAEDALUS_PYTHON` | Interpreter for `.py` scripts (default: the interpreter running daedalus) |
| `DAEDALUS_BASH` | Override the bash used for `.sh` scripts |
| `DAEDALUS_LOGLEVEL` | Console log level for Python scripts (default `INFO`) |
| `DAEDALUS_NO_LOGGING` | Non-empty: Python scripts start without the daedalus logging setup |
| `NO_COLOR` / `FORCE_COLOR` | Colors on listings and console logs |
Python scripts run through `daedalus/run_python_script.py`: they get
`REPO_ROOT` on `PYTHONPATH` (so `import daedalus.<folder>` works for
shared code), file and console logging to `~/.daedalus/debug.log`, and
their `sys.argv` and exit code passed through unchanged.
## Add a script
- Put the file in the folder for its type:
| Type | Folder |
| --- | --- |
| Python | `python/src/<name>/<name>.py` |
| bash | `bash/<name>.sh` |
| PowerShell | `powershell/<name>.ps1` |
| Batch | `batch/<name>.bat` (CRLF line endings, Windows only) |
- Register it in `SCRIPTS` in `daedalus/registry.py` (set `categories`
when it belongs to a group such as `media` or `linux`; the default is
`general`).
- Add a row to the [Available scripts](./README.md#available-scripts)
table in `README.md`. A test fails when a registered script is missing
from that table.
- Add tests under `python/tests/` or `bash/tests/`. Python tests import
the script with `from daedalus.<name> import <name>`; a new
`python/src/<folder>/` also needs a matching `daedalus.<folder>`
entry in `pyproject.toml` (SPEC section 9).
- Bump `version` in `pyproject.toml`, then run `daedalus_pipx_install`
(or `pipx install --force` from the Git URL) so pipx picks up the change.
- Run `python autotest.py`.
Details: [SPEC section 6](./SPEC.md#6-adding-a-script).
## Development
```bash
python -m venv .venv
source .venv/bin/activate # Windows: .\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
pip install -e . # daedalus command runs the checkout
python autotest.py # every check; CI runs the same
python autotest.py pytest # only some checks
```
`autotest.py` runs sanity (line endings, private keys, file size),
Python syntax, pycodestyle, shellcheck, JSON, YAML, markdown lint, and
pytest with coverage.