diff --git a/INSTALL.md b/INSTALL.md index d9e7695..d7d6fcf 100644 --- a/INSTALL.md +++ b/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