diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dba28db..e2ac49d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -31,111 +31,9 @@ We welcome code from anyone regardless of skill or experience level. We are friendly to newcomers. We will help you with your contribution if there are any problems. +To build Topola, follow the build instructions from our [Installation +guide](INSTALL.md). + Topola accepts contributions via pull requests. For a step-by-step guide on how to use these, refer to Codeberg's [documentation](https://docs.codeberg.org/collaborating/pull-requests-and-git-flow/). - -Before you submit a pull request, make sure Topola actually builds with -your changes. Follow the build instructions from the next section. - -### Building - -#### Prerequisites - -Building Topola from source requires -[git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) and -[cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html) -to be installed on your system. Follow the instructions in above links -to obtain these. - -#### Obtaining the source - -Clone the [repository](https://codeberg.org/topola/topola): - - git clone https://codeberg.org/topola/topola.git - -#### Preparing to build - -Change your working directory to your clone of Topola's repository: - - cd topola - -#### Egui port - -Build the project with - - cargo build --features egui --bin topola-egui - -Finally, run Topola by executing - - cargo run --features egui --bin topola-egui - -##### Running Topola in a Web browser - -Topola can be built to run in a Web browser using -[Trunk](https://trunkrs.dev/), which will be installed with the -following command: - - cargo binstall trunk - -To build and open Topola in your browser, run - - trunk serve - -#### SDL2 demo - -Optionally, for shorter build times you may build the SDL2 demo instead -of the Egui port: - - cargo build --features sdl2 --bin topola-sdl2-demo - cargo run --features sdl2 --bin topola-sdl2-demo - -The downside is that the SDL2 demo's user interface is highly incomplete. - -#### Automated tests - -Topola has automated tests to make sure its basic functionalities work. -To execute these, run - - cargo test - -#### Contracts - -When trying to locate the source of a bug, it may be helpful to enable -[contracts](https://en.wikipedia.org/wiki/Design_by_contract) (yes, this -Wikipedia article needs improvement), which are nothing else but -slightly enchanced assertions. - -Unfortunately, the -[contracts](https://docs.rs/contracts/latest/contracts/) library which -we have been using enforces post-conditions via closures, which have -deal-breaking limitations. To bypass these we have forked and modified it -to use `try` blocks instead. The fork is vendored in the -[vendored/contracts/](vendored/contracts/) directory. - -However, `try` blocks aren't present in stable Rust versions yet, so to -use these you need to set up your toolchain to use a nightly version of -Rust. - -##### Nightly Rust - -To use nightly Rust, run the following command: - - rustup override set nightly - -You can go back to stable with - - rustup override unset - -##### Enabling contracts - -To enable contracts, simply add a `--no-default-features` switch. This -switches off a default feature that prevents contracts from executing. -For example, to build tests with contracts, simply run - - cargo test --no-default-features - -Of course, you can enable contracts for any build target. For example, -the following command will build the Egui port with contracts enabled: - - cargo build --features egui --bin topola-egui --no-default-features diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..44dbc62 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,103 @@ +# Installing Topola + +## Building Topola from Source + +### Prerequisites + +Building Topola from source requires +[git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) and +[cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html) +to be installed on your system. Follow the instructions in above links +to obtain these. + +### Obtaining the source + +Clone the [repository](https://codeberg.org/topola/topola): + + git clone https://codeberg.org/topola/topola.git + +### Preparing to build + +Change your working directory to your clone of Topola's repository: + + cd topola + +### Egui port + +Build the project with + + cargo build --features egui --bin topola-egui + +Finally, run Topola by executing + + cargo run --features egui --bin topola-egui + +#### Running Topola in a Web browser + +Topola's Egui port can be built to run in a Web browser using +[Trunk](https://trunkrs.dev/), which will be installed with the +following command: + + cargo binstall trunk + +To build and open Topola in your browser, run + + trunk serve + +### SDL2 demo + +Optionally, for shorter build times you may build the SDL2 demo instead +of the Egui port: + + cargo build --features sdl2 --bin topola-sdl2-demo + cargo run --features sdl2 --bin topola-sdl2-demo + +The downside is that the SDL2 demo's user interface is highly incomplete. + +### Automated tests + +Topola has automated tests to make sure its basic functionalities work. +To execute these, run + + cargo test + +### Contracts + +When trying to locate the source of a bug, it may be helpful to enable +[contracts](https://en.wikipedia.org/wiki/Design_by_contract) (yes, this +Wikipedia article needs improvement), which are nothing else but +slightly enchanced assertions. + +Unfortunately, the +[contracts](https://docs.rs/contracts/latest/contracts/) library which +we have been using enforces post-conditions via closures, which have +deal-breaking limitations. To bypass these we have forked and modified it +to use `try` blocks instead. The fork is vendored in the +[vendored/contracts/](vendored/contracts/) directory. + +However, `try` blocks aren't present in stable Rust versions yet, so to +use these you need to set up your toolchain to use a nightly version of +Rust. + +#### Nightly Rust + +To use nightly Rust, run the following command: + + rustup override set nightly + +You can go back to stable with + + rustup override unset + +#### Enabling contracts + +To enable contracts, simply add a `--no-default-features` switch. This +switches off a default feature that prevents contracts from executing. +For example, to build tests with contracts, simply run + + cargo test --no-default-features + +Of course, you can enable contracts for any build target. For example, +the following command will build the Egui port with contracts enabled: + + cargo build --features egui --bin topola-egui --no-default-features diff --git a/README.md b/README.md index 39eba7a..4be293b 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,10 @@ channel](https://webchat.oftc.net/?channels=#topola) to talk with the developers. Both chatrooms are bridged, so it does not matter which one you join. +## Installation + +To install Topola, follow our [Installation guide](INSTALL.md). + ## Contributing *Anyone* can contribute to Topola, including you. If you want to help us @@ -34,7 +38,7 @@ Topola is licensed under the [MIT licence](LICENSE). ![Animation. There's a rubber band-like trace following cursor, navigating a very simple maze. The maze and the trace are red, the background is solid black but also very slightly white and dark -blue](./assets/interactive_routing.gif) +blue.](./assets/interactive_routing.gif) ![Animation showing a trace, behaving like a rubber band, routed around obstacles step by step. Attempted alternative paths and a guiding mesh