docs/build.rst

   1 Building
   2 ========
   3
   4 Otter is mostly written in Rust.  The web UI frontend is written in
   5 Typescript.  The shape libraries are SVGs and need SVG manipulation
   6 libraries.  The main documentation is done with Sphinx.
   7
   8 You will need at least 6G of disk space, or more, and a good internet
   9 connection.  Your computer will be compiling a lot of code.
  10
  11 These instructions were once tested on Debian 11 "bullseye" and Debian
  12 10 "buster".  Otter won't build on Debian 9 "stretch" because the
  13 Typescript compiler (tsc) is too old.  tsc 3.3.3333 is known to work.
  14 Ubuntu 20.04LTS "focal" should work.
  15
  16 Setup
  17 -----
  18
  19 1. Install the packaged build dependencies::
  20
  21      sudo apt install build-essential cpio git curl zip        \
  22                       pkg-config libssl-dev                    \
  23                       node-typescript inkscape                 \
  24                       netpbm imagemagick libtoml-parser-perl   \
  25                       potrace libxml-libxml-perl               \
  26                       python3-sphinx python3-recommonmark
  27
  28    And for running the tests (``make check``) you will need::
  29
  30      sudo apt install bubblewrap xvfb moreutils firefox-esr
  31
  32
  33 2. Install Rust.  This is most easily done with rustup_::
  34
  35      curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  36
  37    and then follow the instructions about your ``PATH``.  If this rune
  38    alarms you, see below about Rust privsep.
  39
  40 .. _rustup: https://rustup.rs
  41
  42    Otter is known to work with Rust 1.59.  Probably, many earlier
  43    versions well work.  Current versions of the dependencies quoted in
  44    ``Cargo.toml`` will work, but the minimum versions may be
  45    optimistic - newer versions may be needed than are declared.
  46
  47 3. Add the WASM Rust target::
  48
  49      rustup target add wasm32-unknown-unknown
  50      rustup component add miri # for the tests
  51
  52    **If you just want to run the otter cli client over ssh to an existing server, or edit and preview the shape libraries (ie the piece shapes) you can stop here.**
  53
  54 4. For the tests, install the webdriver binary from Mozilla.  Visit
  55
  56      https://github.com/mozilla/geckodriver/releases/tag/v0.28.0
  57
  58    and just dump the resulting ``geckodriver`` binary on your ``PATH``.
  59
  60 5. The tests also use Nightly Rust because we use Miri to test the
  61    small amount of ``unsafe`` in the Otter codebase::
  62
  63      rustup toolchain add nightly
  64      rustup +nightly component add miri
  65
  66
  67 Full build
  68 ----------
  69
  70 ::
  71
  72      git clone https://salsa.debian.org/iwj/otter
  73      cd otter
  74      make -j8 all bundled-sources && echo it worked
  75
  76 Expect to see ``it worked`` at the end.  If you don't see that, it
  77 failed, and the error message is buried in the scrollback.
  78
  79 Build just the command line game management client `otter`
  80 ..........................................................
  81
  82 ::
  83
  84      cargo build -p otter-cli
  85
  86 and then copy ``target/debug/otter`` onto your path.
  87
  88 Alternatively, you can let ``cargo`` directly install and download the
  89 latest released version:
  90
  91 ::
  92
  93      cargo install otter-cli
  94
  95 Build just the shape library preview
  96 ....................................
  97
  98 ::
  99
 100     make -j8 shapelib
 101
 102 And then open ``./templates/shapelib.html`` in your browser
 103
 104
 105 curl|bash-ware; privsep
 106 -----------------------
 107
 108 **If you are not the kind of person to worry about computer security -
 109 especially your software supply chains - you can skip this part.**
 110
 111 If you follow the above instructions, you will have downloaded and
 112 executed - and, therefore, trusted:
 113
 114  * Various Debian packages - safe
 115  * Rustup (the Rust downloader/installer) - this is pretty safe
 116  * Rust itself - again, pretty safe
 117  * Otter itself - well, I wrote this; up to you.
 118  * 475 transitive dependencies of otter (from crates.io)
 119  * a geckodriver binary directly from mozilla
 120
 121 You will have trusted the integrity of the following:
 122
 123  * The Debian archive (via its apt keyring) (very good)
 124  * Rustup's and Rust's TLS keyholders (good, I think)
 125  * The HTTP TLS cabal (sigh)
 126  * github (pretty good in practice)
 127  * whatever mozilla do to make binaries, in particular geckodriver
 128  * crates.io (extremely poor traceability)
 129  * the project management of hundreds of random crates.io libraries
 130
 131 If this makes you uncomfortable, as it should, you may wish to
 132 consider running everything in a separate shell account, or a VM or
 133 container of some kind.
 134
 135 (I have a not-properly-released tool called "nailing-cargo" which
 136 makes it possible to do most things in my main account but run the
 137 Rust stuff in a separate less-privileged account.  There is support
 138 for this in the Makefile.  But if you want to run *everything* in the
 139 lesser account, you don't need to bother with that.)
 140
 141
 142 Apologia
 143 ........
 144
 145 The many dependencies of Otter
 146 ``````````````````````````````
 147
 148 These are partly because actix is a large piece of software with
 149 much functionality.  But also because I favoured my own programming
 150 convenience and in some cases was experimenting with different
 151 approaches.  In practice, it seems to me that once I'm using Actix
 152 and WASM and resvg and so on, there is not that much to be gained
 153 by trying to prune the dependencies of the otter package itself.
 154
 155 geckodriver (for the automated in-browser tests)
 156 ````````````````````````````````````````````````
 157
 158 This is done with a protocol called "WebDriver" which is a
 159 cross-browser way to puppet a browser.  There is a thing called
 160 "geckodriver" which converts that to a firefox-specific protocol
 161 for the same purpose, called "Marionette".  (In practice all this
 162 seems to have lots of bugs and misfeatures.)
 163
 164 AFAICT the usual approach for using geckodriver is to have it *bind to
 165 a fixed TCP port accessible to all local programs*.  My wrapper
 166 tooling arranges to run this in an ephemeral $HOME and a private
 167 network namespace.
 168
 169 AFAICT the only practical way to get geckodriver is to download the
 170 binary from Mozilla.