.nornir/for-idiots.md · nordisk/nornir

For idiots

Class: idiot. Every step spelled out, nothing assumed. Goal: go from a cold shell to nornir watching one workspace and answering questions about it — the whole thing, once, end to end. If you already know your way around a terminal, read guide.md instead; it says the same in a tenth of the words. Each function has its own idiot guide (*-for-idiots.md) that zooms in on one step.

What you need first

A terminal. That is the black (or white) window where you type a line and press Enter.
The nornir program installed. Check it is there — type this and press Enter:

nornir --version

If you see a version number (like nornir 0.5.1), you are ready. If instead it says "command not found", nornir is not installed yet — do the offline install first: airgap-for-idiots.md.

What we are about to do

nornir remembers everything about a set of Rust crates: their code, their tests, their releases. To make it do that we do five small things in order. Each one hands its result to the next through one shared memory called the warehouse. You do not have to understand the warehouse — just do the steps.

Step 1 — go to your project

Type this, replacing the path with where your Rust project lives, and press Enter:

cd /path/to/your/project

This is a Rust project if there is a file named Cargo.toml in it. Check by typing:

ls Cargo.toml

If it prints Cargo.toml, good. If it says "No such file", you are in the wrong folder — cd somewhere else and try again.

Step 2 — appoint the workspace

Tell nornir "these crates are one set I care about". Type and press Enter:

nornir workspace register myproject --descriptor nornir-workspace.toml

Replace myproject with any short name you like. nornir now remembers this set. The full, every-keystroke version of this step (including making the descriptor file) is in workspace-for-idiots.md.

Step 3 — let nornir read the code

Type and press Enter:

nornir docs render myproject

This makes nornir walk through all the code and write down what it found. It may take a minute. Dots or lines will scroll past — that is normal. When you get your prompt back (the $ or >), it is done.

Step 4 — run the tests

Type and press Enter:

nornir test myproject

This runs every kind of check — does it build, do the tests pass, is it formatted — and writes the answers down too. A table appears at the end. Green/OK is good. Every step of this is spelled out in test-for-idiots.md.

Step 5 — ask nornir a question

Now nornir remembers things. Ask it something. Type and press Enter:

nornir warehouse query "SELECT COUNT(*) FROM dep_graph_edges"

It prints a number: how many dependency edges it found. You just queried a database that nornir built for you.

Don't know what you can ask about? See the list of things nornir remembers:

nornir warehouse tables

That prints every table you can query. To see what's inside one, name it:

nornir warehouse tables dep_graph_edges

It lists that table's columns — the words you can put after SELECT. Try other questions in sql-guide.md.

If nornir eats too much memory

The server keeps some of what it read in memory so your questions answer fast. It stops itself at 4 GB of that cache (and says so in its log when it throws something out). On a small computer you can make it smaller before starting it:

NORNIR_WORKING_SET_MAX_BYTES=1g nornir-server

That is the whole loop

You appointed a workspace, nornir read it, tested it, and now answers questions about it. Everything else nornir does is a variation on those five steps:

to cut a release to crates.io → release-for-idiots.md
to make the pretty PDF manual → nornir docs book myproject → docbook-guide.md
to watch it all happen in a window → type nornir viz
to do all of this with no internet → airgap-for-idiots.md

If a command ever prints a red error, read the last line — nornir tries to tell you exactly what to fix (a missing file, a crate not checked out). It almost never means you broke something.