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

docs(install): remove nonlinearity in reading flow and some copyediting

This commit is contained in:
Mikolaj Wielgus 2025-01-01 17:13:59 +01:00
parent 7f48888c14
commit 2d2ab74bbd
1 changed files with 55 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

114
INSTALL.md
View File

@ -8,22 +8,13 @@ SPDX-License-Identifier: MIT
## Building and installing Topola from source ## Building and installing Topola from source
Note that running any of the below commands that start with `cargo
install` will install a Topola binary on your system. We assume this is
what most people coming here want. If you want to build and run Topola
without installing it, skip these particular commands and follow the
subsections named *Building and running without installing*.
By default, the installed version will have a `release` profile, whereas
without installing the `debug` profile will be used by default.
### Prerequisites ### Prerequisites
Building Topola from source requires Building Topola from source requires
[git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) and [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) and
[cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html) [cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html)
to be installed on your system. Follow the instructions in above links to be installed on your system. Follow the instructions in the above links to
to obtain these. obtain these.
### Obtaining the source ### Obtaining the source
@ -39,22 +30,40 @@ Change your working directory to your clone of Topola's repository:
### Command-line application ### Command-line application
Run the following command to build and install Topola's command-line Topola has a command-line application written the help of the
[clap](https://docs.rs/clap/latest/clap/) library.
(If you do not want to install new software on your system, skip now to the
[Debug build](#debug-build) subsection.)
Run the following command to build and install the Topola's command-line
application: application:
cargo install --locked --path crates/topola-cli cargo install --locked --path crates/topola-cli
The application will now be invokable from your terminal as `topola`. You can then invoke the application from your terminal as `topola`.
#### Debug build
If you do not want to install new software on your system, or are interested in
debugging or developing Topola, you can build a debug executable of the Topola's
command-line application inside your working directory by running
cargo build -p topola-cli
Once built, you can invoke the debug executable by replacing the `topola`
command with `cargo run -p topola-cli -- `.
#### Autorouting example #### Autorouting example
As an example, running the following commands will autoroute a KiCad As an example, running the following commands will autoroute a KiCad
project of a simple THT diode bridge rectifier: project of a simple THT diode bridge rectifier:
``` cd tests/single_layer/tht_diode_bridge_rectifier/
cd tests/single_layer/tht_diode_bridge_rectifier/ topola tht_diode_bridge_rectifier.dsn
topola tht_diode_bridge_rectifier.dsn
``` (Obviously, to use the debug executable, replace the second command with
`cargo run -p topola-cli -- tht_diode_bridge_rectifier.dsn`.)
By default, the output filename is the input filename with extension By default, the output filename is the input filename with extension
changed to `ses`: `tht_diode_bridge_rectifier.ses`. changed to `ses`: `tht_diode_bridge_rectifier.ses`.
@ -64,44 +73,41 @@ changed to `ses`: `tht_diode_bridge_rectifier.ses`.
You can view the results of the autorouting in KiCad if you have it You can view the results of the autorouting in KiCad if you have it
installed. First, open the layout in the KiCad PCB Editor: installed. First, open the layout in the KiCad PCB Editor:
``` pcbnew tht_diode_bridge_rectifier.kicad_pcb
pcbnew tht_diode_bridge_rectifier.kicad_pcb
```
Then choose *File > Import > Specctra Session...* from the menu bar. Then choose *File > Import > Specctra Session...* from the menu bar.
In the newly opened file dialog, choose the file named In the newly opened file dialog, choose the file named
*tht_diode_bridge_rectifier.ses*. This will load the autorouted traces. *tht_diode_bridge_rectifier.ses*. This will load the autorouted traces.
#### Building and running without installing
If you chose not to install the command-line application, you can build
and run it without installing by replacing the `topola` command with
`cargo run -p topola-cli --`. Running the above autorouting example is
then as follows:
```
cd tests/single_layer/tht_diode_bridge_rectifier/
cargo run -p topola-cli -- tht_diode_bridge_rectifier.dsn
```
Viewing the results is obviously the same.
### Egui graphical user interface application ### Egui graphical user interface application
Topola has a graphical user interface (GUI) application written using Topola has a graphical user interface (GUI) application written using the [egui]
the [egui](https://github.com/emilk/egui/) library and its paired (https://github.com/emilk/egui/) library and its paired [eframe](https://
[eframe](https://github.com/emilk/egui/tree/master/crates/eframe) github.com/emilk/egui/tree/master/crates/eframe) framework.
framework.
The following command will build and install Topola's GUI application: (If you do not want to install new software on your system, skip now to the
[Debug build](#debug-build-1) subsection.)
The following command will build and install the Topola's GUI application:
cargo install --locked --path crates/topola-egui cargo install --locked --path crates/topola-egui
You can then invoke the application from your terminal by running You can then start the application from your terminal by running
``` topola-egui
topola-egui
``` #### Debug build
If you do not want to install new software on your system, or are interested in
debugging or developing Topola, you can build a debug executable of the Topola's
GUI application inside your working directory by running
cargo build -p topola-egui
Once built, you can start the application from the debug executable with the
following command:
cargo run -p topola-egui
#### Native run-time dependencies #### Native run-time dependencies
@ -129,21 +135,11 @@ cargo build -p topola-egui --release --no-default-features --features disable_co
This is mostly interesting for people who want to package Topola, and allow exposing features This is mostly interesting for people who want to package Topola, and allow exposing features
(e.g. Gentoo Linux / Portage) (e.g. Gentoo Linux / Portage)
#### Building and running without installing #### Running Topola in Web browser
If you chose not to install the GUI application, you can build and run
it without installing by running
```
cargo run -p topola-egui
```
instead of the above `topola-egui` command.
#### Running Topola in a Web browser
Topola's GUI application can be built to and run in a Web browser using Topola's GUI application can be built to and run in a Web browser using
[Trunk](https://trunkrs.dev/). If you have [cargo-binstall](https://github.com/cargo-bins/cargo-binstall) [Trunk](https://trunkrs.dev/). If you have
[cargo-binstall](https://github.com/cargo-bins/cargo-binstall)
on your system, you can install Trunk from binary with on your system, you can install Trunk from binary with
cargo binstall trunk cargo binstall trunk
@ -170,9 +166,9 @@ Automated tests are run in `debug` profile.
### Contracts ### Contracts
The feature described in this section works only in `debug` profile. If (The feature described in this section is enabled only when using nightly Rust
you are not interested in debugging, you can skip this section and only under `debug` profile. If you are not interested in debugging, you can
altogether. skip this section altogether.)
When trying to locate the source of a bug, it may be helpful to enable 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 [contracts](https://en.wikipedia.org/wiki/Design_by_contract) (yes, this