install.html
82 lines · 8595 bytes
1<!DOCTYPE html>
2<html lang="en">
3<head>
4<meta charset="utf-8">
5<meta name="viewport" content="width=device-width, initial-scale=1">
6<title>Install · orgo</title>
7<meta name="description" content="Build orgo from source, put it on your PATH, and check that it works.">
8<link rel="icon" href="favicon.svg" type="image/svg+xml">
9<link rel="stylesheet" href="theme.css">
10<link rel="stylesheet" href="syntax.css">
11<link rel="stylesheet" href="style.css">
12</head>
13<body>
14<header class="site">
15<a class="site-title" href="index.html">orgo</a>
16<nav>
17<a href="#">Install</a>
18<a href="quickstart.html">Quick start</a>
19<a href="guide/index.html">Guide</a>
20</nav>
21</header>
22<main>
23<h1>Install</h1>
24<p class="lede">One Rust toolchain, one command, no runtime dependencies.</p>
25<nav class="toc" aria-label="On this page">
26<h2>On this page</h2>
27<ul>
28<li><a href="#requirements">Requirements</a></li>
29<li><a href="#from-crates-io">From crates.io</a></li>
30<li><a href="#from-source">From source</a></li>
31<li><a href="#running-without-installing">Running without installing</a></li>
32<li><a href="#check-that-it-works">Check that it works</a></li>
33<li><a href="#running-the-test-suite">Running the test suite</a></li>
34<li><a href="#upgrading">Upgrading</a></li>
35<li><a href="#next">Next</a></li>
36</ul>
37</nav>
38<h2 id="requirements">Requirements</h2>
39<ul>
40<li><strong>Rust 1.88 or newer.</strong> Install from <a href="https://rustup.rs">rustup.rs</a> if you do not have it. There is no other runtime requirement: the binary is self-contained, with syntax definitions and highlighting themes compiled in.</li>
41<li><strong>Emacs (optional).</strong> Only the differential test suite uses it, to compare output against org's own exporter. Nothing about building a site needs Emacs.</li>
42</ul>
43<h2 id="from-crates-io">From crates.io</h2>
44<pre><code class="language-sh highlight"><span class="source shell bash"><span class="meta function-call shell"><span class="variable function shell">cargo</span></span><span class="meta function-call arguments shell"> install orgo</span></span></code></pre>
45<p>That is the whole thing: cargo builds it and puts <code class="verbatim">orgo</code> in <code class="verbatim">~/.cargo/bin</code>.</p>
46<h2 id="from-source">From source</h2>
47<pre><code class="language-sh highlight"><span class="source shell bash"><span class="meta function-call shell"><span class="variable function shell">git</span></span><span class="meta function-call arguments shell"> clone https://gitbay.org/krz/orgo</span>
48<span class="meta function-call shell"><span class="support function cd shell">cd</span></span><span class="meta function-call arguments shell"> orgo</span>
49<span class="meta function-call shell"><span class="variable function shell">cargo</span></span><span class="meta function-call arguments shell"> build<span class="variable parameter option shell"><span class="punctuation definition parameter shell"> --</span>release</span></span></span></code></pre>
50<p>The binary lands at <code class="verbatim">target/release/orgo</code>. Copy it somewhere on your <code class="verbatim">PATH</code>:</p>
51<pre><code class="language-sh highlight"><span class="source shell bash"><span class="meta function-call shell"><span class="variable function shell">cp</span></span><span class="meta function-call arguments shell"> target/release/orgo <span class="meta group expansion tilde"><span class="variable language tilde shell">~</span></span>/.local/bin/</span></span></code></pre>
52<p>Or let cargo do it, which puts it in <code class="verbatim">~/.cargo/bin</code>:</p>
53<pre><code class="language-sh highlight"><span class="source shell bash"><span class="meta function-call shell"><span class="variable function shell">cargo</span></span><span class="meta function-call arguments shell"> install<span class="variable parameter option shell"><span class="punctuation definition parameter shell"> --</span>path</span> .</span></span></code></pre>
54<h2 id="running-without-installing">Running without installing</h2>
55<p>Every command in this documentation works through cargo if you would rather not install anything. Replace <code class="verbatim">orgo</code> with <code class="verbatim">cargo run --</code> and add <code class="verbatim">--release</code> for a fast build:</p>
56<pre><code class="language-sh highlight"><span class="source shell bash"><span class="meta function-call shell"><span class="variable function shell">cargo</span></span><span class="meta function-call arguments shell"> run<span class="variable parameter option shell"><span class="punctuation definition parameter shell"> --</span>release</span><span class="keyword operator end-of-options shell"> --</span></span><span class="meta function-call arguments shell"> build my-site -o _site</span></span></code></pre>
57<p>The debug build is fine for small sites and noticeably slower on large ones, because syntax highlighting dominates and is not optimised in a debug profile.</p>
58<h2 id="check-that-it-works">Check that it works</h2>
59<pre><code class="language-sh highlight"><span class="source shell bash"><span class="meta function-call shell"><span class="variable function shell">orgo</span></span><span class="meta function-call arguments shell"><span class="variable parameter option shell"><span class="punctuation definition parameter shell"> --</span>version</span></span>
60<span class="meta function-call shell"><span class="variable function shell">orgo</span></span><span class="meta function-call arguments shell"> init /tmp/orgo-check</span>
61<span class="meta function-call shell"><span class="variable function shell">orgo</span></span><span class="meta function-call arguments shell"> build /tmp/orgo-check<span class="variable parameter option shell"><span class="punctuation definition parameter shell"> -</span>o</span> /tmp/orgo-check/_site</span></span></code></pre>
62<p>You should see a line reporting the pages built:</p>
63<pre>built 5 page(s) (5 rendered, 0 cached), copied 0 asset(s) ... (0 unresolved link(s), 0 diagnostic(s))</pre>
64<p>Open <code class="verbatim">/tmp/orgo-check/_site/index.html</code> in a browser, or serve it properly:</p>
65<pre><code class="language-sh highlight"><span class="source shell bash"><span class="meta function-call shell"><span class="variable function shell">orgo</span></span><span class="meta function-call arguments shell"> serve /tmp/orgo-check<span class="variable parameter option shell"><span class="punctuation definition parameter shell"> -</span>o</span> /tmp/orgo-check/_site</span></span></code></pre>
66<h2 id="running-the-test-suite">Running the test suite</h2>
67<pre><code class="language-sh highlight"><span class="source shell bash"><span class="meta function-call shell"><span class="variable function shell">cargo</span></span><span class="meta function-call arguments shell"> test</span></span></code></pre>
68<p>152 tests, covering the parser, the renderer, configuration, generated pages, the incremental cache, the watcher and the development server.</p>
69<p>The oracle suite is part of that run and compares output against Emacs:</p>
70<pre><code class="language-sh highlight"><span class="source shell bash"><span class="meta function-call shell"><span class="variable function shell">cargo</span></span><span class="meta function-call arguments shell"> test<span class="variable parameter option shell"><span class="punctuation definition parameter shell"> --</span>test</span> oracle</span></span></code></pre>
71<p>It <strong>skips cleanly</strong> when there is no <code class="verbatim">emacs</code> on your <code class="verbatim">PATH</code>, so a machine without Emacs still gets a green test run — it simply measures one thing less.</p>
72<h2 id="upgrading">Upgrading</h2>
73<p>orgo stores an incremental cache in <code class="verbatim"><output>/.orgo-cache.json</code>, tagged with a format version. A newer binary that changes how output is produced bumps that version, and a version it does not recognise is discarded in favour of a full rebuild. You never need to clear the cache by hand after an upgrade — but if you want to:</p>
74<pre><code class="language-sh highlight"><span class="source shell bash"><span class="meta function-call shell"><span class="variable function shell">orgo</span></span><span class="meta function-call arguments shell"> clean _site</span></span></code></pre>
75<h2 id="next">Next</h2>
76<p><a href="quickstart.html">Quick start</a> builds a real site and puts your own writing into it.</p>
77</main>
78<footer class="site">
79Built with orgo — these docs are an orgo site.
80</footer>
81</body>
82</html>