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.88 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 crates.io
 14
 15#+BEGIN_SRC sh
 16cargo install orgo
 17#+END_SRC
 18
 19That is the whole thing: cargo builds it and puts =orgo= in =~/.cargo/bin=.
 20
 21* From source
 22
 23#+BEGIN_SRC sh
 24git clone https://github.com/krazywarez/orgo
 25cd orgo
 26cargo build --release
 27#+END_SRC
 28
 29The binary lands at =target/release/orgo=. Copy it somewhere on your =PATH=:
 30
 31#+BEGIN_SRC sh
 32cp target/release/orgo ~/.local/bin/
 33#+END_SRC
 34
 35Or let cargo do it, which puts it in =~/.cargo/bin=:
 36
 37#+BEGIN_SRC sh
 38cargo install --path .
 39#+END_SRC
 40
 41* Running without installing
 42
 43Every command in this documentation works through cargo if you would rather not install
 44anything. Replace =orgo= with =cargo run --= and add =--release= for a fast build:
 45
 46#+BEGIN_SRC sh
 47cargo run --release -- build my-site -o _site
 48#+END_SRC
 49
 50The debug build is fine for small sites and noticeably slower on large ones, because
 51syntax highlighting dominates and is not optimised in a debug profile.
 52
 53* Check that it works
 54
 55#+BEGIN_SRC sh
 56orgo --version
 57orgo init /tmp/orgo-check
 58orgo build /tmp/orgo-check -o /tmp/orgo-check/_site
 59#+END_SRC
 60
 61You should see a line reporting the pages built:
 62
 63#+BEGIN_EXAMPLE
 64built 5 page(s) (5 rendered, 0 cached), copied 0 asset(s) ... (0 unresolved link(s), 0 diagnostic(s))
 65#+END_EXAMPLE
 66
 67Open =/tmp/orgo-check/_site/index.html= in a browser, or serve it properly:
 68
 69#+BEGIN_SRC sh
 70orgo serve /tmp/orgo-check -o /tmp/orgo-check/_site
 71#+END_SRC
 72
 73* Running the test suite
 74
 75#+BEGIN_SRC sh
 76cargo test
 77#+END_SRC
 78
 79152 tests, covering the parser, the renderer, configuration, generated pages, the
 80incremental cache, the watcher and the development server.
 81
 82The oracle suite is part of that run and compares output against Emacs:
 83
 84#+BEGIN_SRC sh
 85cargo test --test oracle
 86#+END_SRC
 87
 88It *skips cleanly* when there is no =emacs= on your =PATH=, so a machine without Emacs
 89still gets a green test run — it simply measures one thing less.
 90
 91* Upgrading
 92
 93orgo stores an incremental cache in =<output>/.orgo-cache.json=, tagged with a
 94format version. A newer binary that changes how output is produced bumps that version,
 95and a version it does not recognise is discarded in favour of a full rebuild. You never
 96need to clear the cache by hand after an upgrade — but if you want to:
 97
 98#+BEGIN_SRC sh
 99orgo clean _site
100#+END_SRC
101
102* Next
103
104[[file:quickstart.org][Quick start]] builds a real site and puts your own writing into it.