mirror of https://codeberg.org/topola/topola.git
contributing: move installation instructions to INSTALL.md
This commit is contained in:
Mikolaj Wielgus
parent
925e3d5266
commit
1e21a501d8
108
CONTRIBUTING.md
108
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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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).
|
|||
|
||||
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue