mirror of https://codeberg.org/topola/topola.git
docs(install): remove nonlinearity in reading flow and some copyediting
This commit is contained in:
Mikolaj Wielgus
parent
7f48888c14
commit
2d2ab74bbd
114
INSTALL.md
114
INSTALL.md
|
|
@ -8,22 +8,13 @@ SPDX-License-Identifier: MIT
|
|||
|
||||
## 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
|
||||
|
||||
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.
|
||||
to be installed on your system. Follow the instructions in the above links to
|
||||
obtain these.
|
||||
|
||||
### Obtaining the source
|
||||
|
||||
|
|
@ -39,22 +30,40 @@ Change your working directory to your clone of Topola's repository:
|
|||
|
||||
### 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:
|
||||
|
||||
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
|
||||
|
||||
As an example, running the following commands will autoroute a KiCad
|
||||
project of a simple THT diode bridge rectifier:
|
||||
|
||||
```
|
||||
cd tests/single_layer/tht_diode_bridge_rectifier/
|
||||
topola tht_diode_bridge_rectifier.dsn
|
||||
```
|
||||
cd tests/single_layer/tht_diode_bridge_rectifier/
|
||||
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
|
||||
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
|
||||
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.
|
||||
In the newly opened file dialog, choose the file named
|
||||
*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
|
||||
|
||||
Topola has a graphical user interface (GUI) application written using
|
||||
the [egui](https://github.com/emilk/egui/) library and its paired
|
||||
[eframe](https://github.com/emilk/egui/tree/master/crates/eframe)
|
||||
framework.
|
||||
Topola has a graphical user interface (GUI) application written using the [egui]
|
||||
(https://github.com/emilk/egui/) library and its paired [eframe](https://
|
||||
github.com/emilk/egui/tree/master/crates/eframe) 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
|
||||
|
||||
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
|
||||
|
||||
|
|
@ -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
|
||||
(e.g. Gentoo Linux / Portage)
|
||||
|
||||
#### Building and running without installing
|
||||
|
||||
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
|
||||
#### Running Topola in Web browser
|
||||
|
||||
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
|
||||
|
||||
cargo binstall trunk
|
||||
|
|
@ -170,9 +166,9 @@ Automated tests are run in `debug` profile.
|
|||
|
||||
### Contracts
|
||||
|
||||
The feature described in this section works only in `debug` profile. If
|
||||
you are not interested in debugging, you can skip this section
|
||||
altogether.
|
||||
(The feature described in this section is enabled only when using nightly Rust
|
||||
and only under `debug` profile. If you are not interested in debugging, you can
|
||||
skip this section altogether.)
|
||||
|
||||
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue