From 2ebd9b411b28d8c57e1a5d1e2ae29f743ad8b802 Mon Sep 17 00:00:00 2001
From: Mikolaj Wielgus <wielgusmikolaj@gmail.com>
Date: Mon, 15 Jul 2024 21:42:20 +0200
Subject: [PATCH] install: explain how to run Topola without installing

---
 INSTALL.md | 70 ++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 58 insertions(+), 12 deletions(-)

diff --git a/INSTALL.md b/INSTALL.md
index 7cc5d2d..9a83e14 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -1,6 +1,15 @@
 # Installing Topola
 
-## 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 people usually 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
 
@@ -33,8 +42,8 @@ The application will now be invokable from your terminal as `topola`.
 
 #### Autorouting example
 
-The following example will autoroute a KiCad project of a simple THT
-diode bridge rectifier:
+As an example, running the following commands will autoroute a KiCad project of a
+simple THT diode bridge rectifier:
 
 ```
 cd tests/single_layer/data/tht_diode_bridge_rectifier/
@@ -54,10 +63,28 @@ 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 --features cli --`. Running the above autorouting example is
+then as follows:
+
+```
+cd tests/single_layer/data/tht_diode_bridge_rectifier/
+cargo run --features cli -- tht_diode_bridge_rectifier.dsn tht_diode_bridge_rectifier.ses autoroute_all.cmd
+```
+
+Viewing the results is obviously the same.
+
 ### Egui GUI application
 
-The following command will build and install Topola's 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.
+
+The following command will build and install Topola's GUI application:
 
     cargo install --locked --path . --features egui --bin egui
 
@@ -67,9 +94,20 @@ You can then invoke the application from your terminal by running
 topola-egui
 ```
 
+#### 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 --features egui --bin topola-egui`
+```
+
+instead of the above `topola-egui` command.
+
 #### Running Topola in a Web browser
 
-Topola's Egui application can be built to 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/), which will be installed with the
 following command:
 
@@ -79,6 +117,9 @@ To build and open Topola in your browser, run
 
     trunk serve
 
+This will work both with and without having the GUI application
+installed.
+
 ### Automated tests
 
 Topola has automated tests to make sure its basic functionalities work.
@@ -86,22 +127,27 @@ To execute these, run
 
     cargo test
 
+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 it 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
 Wikipedia article needs improvement), which are nothing else but
-slightly enchanced assertions.
+somewhat 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
+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
+However, `try` blocks are not present in stable Rust yet, so to use
+these you need to set up your toolchain to use a nightly version of
 Rust.
 
 #### Nightly Rust
@@ -122,7 +168,7 @@ 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,
+Of course, you can enable contracts for any build target. For instance,
 the following command will build the Egui application with debug profile
 and contracts enabled: