From: Ian Jackson Date: Sat, 12 Dec 2020 00:59:35 +0000 (+0000) Subject: Tested build instructions and verbiage X-Git-Tag: otter-0.2.0~192 X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=commitdiff_plain;h=fbcd0da72a2df5b0abcf750cfddca08acc7cfdc9;p=otter.git Tested build instructions and verbiage Signed-off-by: Ian Jackson --- diff --git a/README.md b/README.md index 0d7f4804..374b34ec 100644 --- a/README.md +++ b/README.md @@ -69,12 +69,16 @@ src/spec.rs in the Otter source code. 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. @@ -85,59 +89,80 @@ If you copied or adapted an SVG from somewhere, provide details. 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 @@ -145,51 +170,176 @@ 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]