berkus
/
topola
mirror of https://codeberg.org/topola/topola.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

contributing: explain how to enable contracts

This commit is contained in:
Mikolaj Wielgus 2024-06-01 14:18:36 +02:00
parent 765d8495c6
commit 662f959ae5
2 changed files with 106 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
CONTRIBUTING.md
View File

@ -25,14 +25,14 @@ tracker](https://codeberg.org/topola/topola/issues).
Under normal operation, crashes and panics are always considered
reportable bugs.
## Code contribution
## Writing code
We welcome code contributions from anyone regardless of skill or
experience level. We're friendly to newcomers. We will help you with
your contribution if there are any problems.
We welcome code from anyone regardless of skill or experience level.
We're friendly to newcomers. We will help you with your contribution if
there are any problems.
Topola accepts contributions using pull requests. For a step-by-step
guide on how to use these, refer to Codeberg's
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
@ -45,7 +45,8 @@ your changes. Follow the build instructions from the next section.
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.
to be installed on your system. Follow the instructions in above links
to obtain these.
#### Obtaining the source
@ -59,19 +60,15 @@ Change your working directory to your clone of Topola's repository:
cd topola
Topola currently requires nightly Rust to build. Enable it with
rustup override set nightly
#### Egui port
Build the project with
cargo build --features egui --bin topola-egui
cargo build --features "egui,disable_contracts" --bin topola-egui
Finally, run Topola by executing
cargo run --features egui --bin topola-egui
cargo run --features "egui,disable_contracts" --bin topola-egui
##### Running Topola in a Web browser
@ -94,3 +91,46 @@ of the Egui port:
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 --features disable_contracts
#### 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
numerous 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 remove the `disable_contracts` feature from
commands. For example, to build tests with contracts, simply run
cargo test

72
README.md
View File

@ -2,43 +2,77 @@
Work-in-progress interactive topological router in Rust.
The project is funded by the [NLnet Foundation](https://nlnet.nl/) through the [NGI0 Entrust](https://nlnet.nl/entrust/) fund.
The project is funded by the [NLnet Foundation](https://nlnet.nl/) via
the [NGI0 Entrust](https://nlnet.nl/entrust/) fund.
<img src="./assets/ngi0_entrust_banner.svg" alt="NGI0 Entrust banner" width="200"/>
<img src="./assets/nlnet_banner.png" alt="NLnet Foundation banner" width="200"/>
<img src="./assets/ngi0_entrust_banner.svg" alt="NGI0 Entrust banner" width="200"/>
## Chat
Join the official [Matrix chatroom](https://matrix.to/#/%23topola:tchncs.de) or [IRC 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.
Join the official [Matrix
chatroom](https://matrix.to/#/%23topola:tchncs.de) or [IRC
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.
## Contributing
*Anyone* can contribute to Topola, including you. If you want to help us out, please follow
our [Contribution guide](CONTRIBUTING.md).
*Anyone* can contribute to Topola, including you. If you want to help us
out, please follow our [Contribution guide](CONTRIBUTING.md).
Our official repository is on [Codeberg](https://codeberg.org/topola/topola). We also have a
mirror repository on [GitHub](https://github.com/mikwielgus/topola).
Our official repository is on
[Codeberg](https://codeberg.org/topola/topola). We also have a mirror
repository on [GitHub](https://github.com/mikwielgus/topola).
## Licence
Topola is licensed under the [MIT licence](LICENSE).
## Gallery
![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)
![Animation showing a trace, behaving like a rubber band, routed around obstacles step by step. Attempted alternative paths and a guiding mesh are shown.](./assets/mesh_visualization.gif)
![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)
![Animation. There are two upward barriers, with some space between tem, around which four rubberband traces, one over another, are wrapped. Enter mouse cursor. The cursor begins to stretch the left barrier to the right. As it's stretched, the traces cease to be wrapped around the right barrier, becoming "free". The traces and the barrier are two-dimensional and all solid red. The background is black but also very slightly white and blue.](./assets/unwrapping_bends.gif "Unwrapping bends")
![Animation showing a trace, behaving like a rubber band, routed around
obstacles step by step. Attempted alternative paths and a guiding mesh
are shown.](./assets/mesh_visualization.gif)
![This animation shows four traces wrapped around a vertical barrier like rubberbands. Computer
cursor appears and starts dragging the barrier's top end left and right, up and down, elastically
stretching the barrier and having the traces continue being wrapped on the barrier regardless of
its position. The traces and the barrier are all solid red. The background is black but also very
slightly white and blue.](./assets/dragging_with_bends.gif "Dragging with bends")
![Animation. There are two upward barriers, with some space between tem,
around which four rubberband traces, one over another, are wrapped.
Enter mouse cursor. The cursor begins to stretch the left barrier to the
right. As it's stretched, the traces cease to be wrapped around the
right barrier, becoming "free". The traces and the barrier are
two-dimensional and all solid red. The background is black but also very
slightly white and blue.](./assets/unwrapping_bends.gif "Unwrapping
bends")
![Animation. There is an upward barrier in the middle and dots on the left and right of it, four each. A trace is drawn from the leftmost dot on the left to the rightmost dot on the right. Then a trace is drawn from the second leftmost dot on the left to the second rightmost dot on the right, displacing the previous trace so that there's space for the new one. Same happens for the remaining dots. The dots, traces and barrier are all solid red. The background is black but also very slightly white and blue.](./assets/shoving_around.gif "Shoving traces under other traces")
![This animation shows four traces wrapped around a vertical barrier
like rubberbands. Computer cursor appears and starts dragging the
barrier's top end left and right, up and down, elastically stretching
the barrier and having the traces continue being wrapped on the barrier
regardless of its position. The traces and the barrier are all solid
red. The background is black but also very slightly white and
blue.](./assets/dragging_with_bends.gif "Dragging with bends")
![Animation showing three red-colored traces pass around a barrier. Trace bends are not aligned to a grid unlike most PCB layouts these days (this is called "topological routing"). The traces and the barrier are all solid red. The background is black but also very
slightly white and blue.](./assets/stacked_bends.png "Stacking bends")
![Animation. There is an upward barrier in the middle and dots on the
left and right of it, four each. A trace is drawn from the leftmost dot
on the left to the rightmost dot on the right. Then a trace is drawn
from the second leftmost dot on the left to the second rightmost dot on
the right, displacing the previous trace so that there's space for the
new one. Same happens for the remaining dots. The dots, traces and
barrier are all solid red. The background is black but also very
slightly white and blue.](./assets/shoving_around.gif "Shoving traces
under other traces")
![Animation showing a trace zigzagging around two barriers. The trace and the barriers are all solid red. The background is black but also very slightly white and blue.](./assets/zigzag.png "Zigzag")
![Animation showing three red-colored traces pass around a barrier.
Trace bends are not aligned to a grid unlike most PCB layouts these days
(this is called "topological routing"). The traces and the barrier are
all solid red. The background is black but also very slightly white and
blue.](./assets/stacked_bends.png "Stacking bends")
![Animation showing a trace zigzagging around two barriers. The trace
and the barriers are all solid red. The background is black but also
very slightly white and blue.](./assets/zigzag.png "Zigzag")