krz/orgo

 1#+TITLE: Install
 2#+DESCRIPTION: Build orgo from source, put it on your PATH, and check that it works.
 3#+LEDE: One Rust toolchain, one command, no runtime dependencies.
 4
 5* Requirements
 6
 7- *Rust 1.82 or newer.* Install from [[https://rustup.rs][rustup.rs]] if you do not have it. There is no other
 8  runtime requirement: the binary is self-contained, with syntax definitions and
 9  highlighting themes compiled in.
10- *Emacs (optional).* Only the differential test suite uses it, to compare output against
11  org's own exporter. Nothing about building a site needs Emacs.
12
13* From source
14
15#+BEGIN_SRC sh
16git clone <repository-url> orgo
17cd orgo
18cargo build --release
19#+END_SRC
20
21The binary lands at =target/release/orgo=. Copy it somewhere on your =PATH=:
22
23#+BEGIN_SRC sh
24cp target/release/orgo ~/.local/bin/
25#+END_SRC
26
27Or let cargo do it, which puts it in =~/.cargo/bin=:
28
29#+BEGIN_SRC sh
30cargo install --path .
31#+END_SRC
32
33* Running without installing
34
35Every command in this documentation works through cargo if you would rather not install
36anything. Replace =orgo= with =cargo run --= and add =--release= for a fast build:
37
38#+BEGIN_SRC sh
39cargo run --release -- build my-site -o _site
40#+END_SRC
41
42The debug build is fine for small sites and noticeably slower on large ones, because
43syntax highlighting dominates and is not optimised in a debug profile.
44
45* Check that it works
46
47#+BEGIN_SRC sh
48orgo --version
49orgo init /tmp/orgo-check
50orgo build /tmp/orgo-check -o /tmp/orgo-check/_site
51#+END_SRC
52
53You should see a line reporting the pages built:
54
55#+BEGIN_EXAMPLE
56built 5 page(s) (5 rendered, 0 cached), copied 0 asset(s) ... (0 unresolved link(s), 0 diagnostic(s))
57#+END_EXAMPLE
58
59Open =/tmp/orgo-check/_site/index.html= in a browser, or serve it properly:
60
61#+BEGIN_SRC sh
62orgo serve /tmp/orgo-check -o /tmp/orgo-check/_site
63#+END_SRC
64
65* Running the test suite
66
67#+BEGIN_SRC sh
68cargo test
69#+END_SRC
70
71152 tests, covering the parser, the renderer, configuration, generated pages, the
72incremental cache, the watcher and the development server.
73
74The oracle suite is part of that run and compares output against Emacs:
75
76#+BEGIN_SRC sh
77cargo test --test oracle
78#+END_SRC
79
80It *skips cleanly* when there is no =emacs= on your =PATH=, so a machine without Emacs
81still gets a green test run — it simply measures one thing less.
82
83* Upgrading
84
85orgo stores an incremental cache in =<output>/.orgo-cache.json=, tagged with a
86format version. A newer binary that changes how output is produced bumps that version,
87and a version it does not recognise is discarded in favour of a full rebuild. You never
88need to clear the cache by hand after an upgrade — but if you want to:
89
90#+BEGIN_SRC sh
91orgo clean _site
92#+END_SRC
93
94* Next
95
96[[file:quickstart.org][Quick start]] builds a real site and puts your own writing into it.