todo: use rustdoc to provide this somewhere.
-Adding shapes
--------------
+
+ADDING SHAPES
+=============
Otter uses SVGs. The sources for the SVGs are all in the otter source
tree, in the library/ directory.
+Unfortunately the mechanisms here are not yet particularly well
+documented.
+
Some of these SVGs were scraped from Wikimedia. The scraper machinery
can perhaps be adapted to scrape SVGs from elsewhere.
Contributions should be via git branch, eg a merge request on Salsa:
https://salsa.debian.org/iwj/otter
+NB that shapes must come with a licence compatible with CC-BY-SA 4.0.
+See LICENCE for more information about copyright status.
BUILDING AND TESTING
====================
+You will need about 5500 megabytes of disk space, and a good internet
+connection. Your computer will be compiling a lot of code.
+
These instructions have been tested on Debian buster.
Setup
-----
-You will need about 6Gby of disk space.
-
1.
- sudo apt install build-essential cpio git curl pkg-config libssl-dev node-typescript
+ sudo apt install build-essential cpio git curl \
+ pkg-config libssl-dev \
+ node-typescript
2. Install Rust. This is most easily done with rustup:
- curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+```
+ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+```
-and then follow the instructions about your PATH. If this rune alarms
-you, see below about Rust privsep.
+ and then follow the instructions about your PATH. If this rune
+ alarms you, see below about Rust privsep.
3. Switch your Rust install to use Rust Nightly and add the WASM
-target:
+ target:
- rustup default nightly
- rustup target add wasm32-unknown-unknown
+```
+ rustup default nightly
+ rustup target add wasm32-unknown-unknown
+```
+
+ Unfortunately, it is possible that the Rust nightly you find when
+ you run this is missing some pieces. The following is known to
+ work (with otter from the time of writing):
+
+ rustup default nightly-2020-11-09
4. Install some build tools:
- cargo install usvg
- cargo install bundle-sources
+```
+ cargo install usvg
+ cargo install bundle-sources
+```
-This will put them in ~/.cargo/bin, which the rustup curl rune above
-will have arranged to put on your PATH.
+ This will put them in `~/.cargo/bin`, which you presumably have on
+ your PATH (or the above `rustup` and `cargo` runes wouldn't work).
-5. Install the version of wasm-pack with the option I need, which
-upstream haven't taken (or refused) the MR for:
+5. Install the version of wasm-pack with the option I need (upstream
+ haven't reviewed my merge request):
- git clone https://github.com/ijackson/wasm-pack.git -b cargo-opts
- cd wasm-pack
- cargo install
+```
+ git clone https://github.com/ijackson/wasm-pack.git -b cargo-opts
+ cd wasm-pack
+ cargo install
+```
-NB that wasm-pack will itself download and install more stuff when it
-is run by the otter Makefile.
+ NB that wasm-pack will itself download and install more stuff when
+ it is run by the otter Makefile.
Build
-----
- git clone https://salsa.debian.org/iwj/otter
- cd otter
- make -j8 all bundled-sources
+```
+ git clone https://salsa.debian.org/iwj/otter
+ cd otter
+ make -j8 all bundled-sources
+```
Test
In one shell:
- target/debug/daemon-otter server-test.toml
+```
+ target/debug/daemon-otter server-test.toml
+```
The server does not daemonise, and the default config there makes it
quite verboxe. So, in another shell:
- target/debug/otter --account server: --config server-test.toml --spec-dir=specs reset --reset-table test server::test demo
+```
+ target/debug/otter \
+ --account server: --config server-test.toml --spec-dir=specs \
+ reset --reset-table test server::test demo
+
+ target/debug/otter \
+ --account server: --config server-test.toml --spec-dir=specs \
+ join-game server::test
+```
+
+The URL printed can then be visited in a local browser.
+
+
+Resetting/restoring things after tests, updating server, etc.
+-------------------------------------------------------------
+
+After the server is updated, you can just ^C and restart it. Games
+are constantly saved (although there is a 1s lag on the most
+frequently udpated game state).
+
+If you want to clear out the server state, delete the files `[ag]-*`
+and `accounts`. NB that you should do this with the server not
+running, because the server has most of that information in memory and
+will like to write it out again.
+
+If you update Typescript (JS code) you will need to rerun make to
+rebuild the JS output.
+
+Apart from that, if you update JS or WASM code or Tera templates, you
+do not need to restart the server - it will pick up changes
+automatically.
+
+When testing, you do not need to `make bundled-sources' more than
+once, at the beginning. So don't, because it's slow. But you
+definitely should run it for every update if you make a deployment for
+other people to use. Otherwise you might be running a privately
+modified server without offering your users its source code. See
+LICENCE.
+
+
+Navigating the otter source code
+--------------------------------
+
+* `src/*.rs`
+
+ The main Rust source code. This is mixture of code used only by the
+ server and code used by the `otter` command line utility; these
+ aren't split up. In Rust terms this is a "library crate".
+
+* `src/bin/*.rs`: The actual executables.
+
+* `wasm/*.rs`: We ship WebAssembly bindings for a few things, mostly
+ to avoid having to write the code twice - once in Rust and once in
+ Typescript.
+
+* `zcoord/*.rs`: Code shared by the host and the WebAssembly.
+ Notably, the Z coordinate handling, but also a
+ string-timestamp-handling function. This is a separate library
+ crate so that we don't have to compile Rocket for WASM...
+
+* templates/script.ts
+
+ The main Typescript (typed Javascript) code. Otter's web
+ targets is earliest browser versions that support WebAssembly.
+
+* `templates/session.tera`, `macros.tera`, etc.
+
+ Tera templates generating the main HTML screen. These templates are
+ filled in from structs in the Rust source code. In the case of
+ `session.tera` and `macros.tera`, the rendering uses an instance of
+ `SessionRenderContext` from `src/session.rs`.
+
+* `library/`
+
+ The shape libraries. The program `./media-scraper` (which is not
+ run by the `Makefile`) reads `library/*.toml` for instructions and
+ generates `files.make` fragments. These fragments arrange to run
+ `./usvg-processor` which launders SVGs through `usvg`.
+ `usvg-processor`.
+
+
+Rust, cargo, curl|bash-ware; privsep
+------------------------------------
+
+If you follow the above instructions you will have downloaded and
+executed - and, therefore, trusted:
+
+ * Various Debian packages - safe
+ * Rustup (the Rust downloader/installer) - this is pretty safe
+ * Rust itself - again, pretty safe
+ * Otter itself - well, I wrote this; up to you.
+ * My branch of wasm-pack - I haven't audited what I started with.
+
+ * 236 transitive dependencies of otter (from crates.io)
+ * 50 transitive dependencies of bundle-sources
+ * the transitive dependencies of resvg
+ * god knows how many transitive dependencies of wasm-pack
+ * whatever wasm-pack downloads at runtime (mostly(?) via cargo)
+
+You will have trusted the integrity of the following:
- target/debug/otter --account server: --config server-test.toml --spec-dir=specs join-game server::test
+ * The Debian archive (via its apt keyring) (very good)
+ * Rustup's and Rust's TLS keyholders (good, I think)
+ * The HTTP TLS cabal (sigh)
+ * github (pretty good in practice)
+ * crates.io (extremely poor traceability)
+ * the project management of hundreds of random crates.io libraries
-The URL printed, something like:
+If this makes you uncomfortable, as it should, you may wish to
+consider running everything in a separate shell account, or a VM or
+container of some kind.
- http://localhost:18056/?KRRUu7FosWe4WxvcyMoTEsgjHJ8p4Qf17aKHUIcApEQj0ialrX2gJJsjvGRBRATz
+(I have a not-properly-released tool called "nailing-cargo" which
+makes it possible to do most things in my main account but run the
+Rust stuff in a separate less-privileged account. There is support
+for this in the Makefile. But if you want to run *everything* in the
+lesser account, you don't need to bother with that.)
-can be visited in a local browser.
+Dependencies - apologia
+-----------------------
+ * Rust Nightly
+ This is needed almost solely because Rocket needs it. Rocket is
+ the web framework I am using. The next version of Rocket (0.5.x),
+ which is in development, will not need Nightly, but it will also be
+ a serious compatibility break. The existing Rocket (0.4.x) will
+ almost certainly never be ported to Stable Rust. Sorry.
-Dependencies
-------------
+ * The many dependencies of Otter
- * Rust Nightly (sorry)
+ These are partly because Rocket is a large piece of software with
+ much functionality. But also because I favoured my own programming
+ convenience and in some cases was experimenting with different
+ approaches. In practice, it seems to me that once I'm using Rocket
+ and WASM utilities and resvg and so on, there is not that much to
+ be gained by trying to prune the dependencies of the otter package
+ itself.
- * `cargo` and a willingness to let it download all the dependencies
- and run them, from crates.io. You can use my `Cargo.lock.example`
- if you like. I use a privsep scheme to avoid running stuff from
- cargo in my main account on my laptop. Using the not properly
- released `nailing-cargo` program.
+ * wasm-pack
- * `tsc`, Microsoft's Typescript compiler. The version in Debian
- buster will do.
+ This is a wrapper a program for manipulating WebAssembly files. It
+ likes to run cargo and do god knows what. I'm not sure it's buying
+ me much over whatever things it runs, so ideally it would be best
+ to replace this with calls to the underlying utilities and
+ libraries. But there are some wrinkles, for example, some version
+ coupling requirements that wasm-pack takes care of. And to be
+ honest, I'm not sure precisely what it does so reproducing that in
+ the Makefile would be nontrivial.
- * `wasm-pack`, a program for manipulating WebAssembly files. This
- too likes to run cargo and do god knows what.
+ * bundle-rust-sources
- * `resvg`, a program for manipulating SVG files.
+ This needs to be properly released.
- * `bundle-rust-sources`, an un-released Rust package for publishing
- source code of Rust projects.
-Weirdnesses:
+Final weirdness
+---------------
* For running on chiark I build with the Rust target
`x86_64-unknown-linux-musl` which on my system is configured to
- produce a completely statically linked bionary:
+ produce a completely statically linked bionary. I have this in my
+ `~/.cargo/config` (in the lesser privsep account):
```
[target.x86_64-unknown-linux-musl]
~ianmdlvl / otter.git / commitdiff