Fix and clean up BUILD.md

BUILD.md

@@ -11,72 +11,115 @@ This is a guide to how to build Rerun.
 * [`RELEASES.md`](RELEASES.md)
 
 
-## Getting started with the repository.
-* Install the Rust toolchain: <https://rustup.rs/>
-* `git clone [email protected]:rerun-io/rerun.git && cd rerun`
-* Run `./scripts/setup_dev.sh`.
-* Make sure `cargo --version` prints `1.69.0` once you are done
+## Getting started with the repository
 
-All Rust examples are separate executable projections. Meaning to run them you specify the package, e.g. `cargo run -p dna`.
+First, install the Rust toolchain using the installer from <https://rustup.rs/>.
 
-You can type `cargo rerun` to compile and run the `rerun` binary with most features enabled, thanks to a shortcut in `.cargo/config.toml`.
+Then, clone the repository:
+```sh
+git clone [email protected]:rerun-io/rerun.git
+cd rerun
+```
+
+Finally, run the following script to install the dependencies and CLI tools needed for Rerun's build environment:
+
+```sh
+./scripts/setup_dev.sh
+```
 
-### Apple-silicon Macs
+Make sure `cargo --version` prints `1.69.0` once you are done.
 
 If you are using an Apple-silicon Mac (M1, M2), make sure `rustc -vV` outputs `host: aarch64-apple-darwin`. If not, this should fix it:
 
 ```sh
 rustup set default-host aarch64-apple-darwin && rustup install 1.69.0
 ```
 
-## Building the docs
+## Building and running the viewer
 
-High-level documentation for rerun can be found at [http://rerun.io/docs](http://rerun.io/docs). It is built from the separate repository [rerun-docs](https://github.com/rerun-io/rerun-docs).
+Use this command for building and running the viewer:
 
-Python API docs can be found at <https://ref.rerun.io/docs/python> and are built via `mkdocs` and hosted on GitHub. For details on the python doc-system, see [Writing Docs](https://github.com/rerun-io/rerun/blob/main/rerun_py/docs/writing_docs.md).
+```sh
+cargo rerun
+```
 
-Rust documentation is hosted on <https://docs.rs/rerun/>. You can build them locally with: `cargo doc --all-features --no-deps --open`
+This custom cargo command is enabled by an alias located in `.cargo/config.toml`.
+
+
+## Running the Rust examples
+
+All Rust examples are set up as separate executables, so they can be run by specifying the corresponding package, for example:
+
+```sh
+cargo run -p dna
+```
+
+
+## Building and installing the Rerun Python SDK
+
+Rerun is available as a package on PyPi and can be installed with `pip install rerun-sdk`.
+
+Additionally, prebuilt dev wheels from head of main are available at <https://github.com/rerun-io/rerun/releases/tag/prerelease>.
 
-## Build and install the Rerun Python SDK
-Rerun is available as a package on PyPi and can be installed with `pip install rerun-sdk`
+If you want to build from source, use the following instructions.
 
-Additionally, prebuilt dev wheels from head of main are available at <https://github.com/rerun-io/rerun/releases/tag/latest>.
+### Mac/Linux
 
-However, if you want to build from source you can follow the instructions below.
+First, a local virtual environment must be created and the necessary dependencies installed (this needs to be done only once):
 
-### Set up virtualenv
+```sh
+just py-dev-env
+```
 
-Mac/Linux:
+Then, the SDK can be compiled and installed in the virtual environment using the following command:
+
+```sh
+just py-build
+```
+
+This needs to be repeated each time the Rust source code is updated, for example after updating your clone using `git pull`.
+
+Finally, the virtual environment must be activated to run Python examples:
 
 ```sh
-python3 -m venv venv  # Rerun supports Python version >= 3.7
 source venv/bin/activate
-python -m pip install --upgrade pip  # We need pip version >=21.3
+python examples/python/car/main.py
 ```
 
-Windows (powershell):
+### Windows (PowerShell)
+
+The `justfile` currently doesn't support Windows, so each step must be run manually.
+
+First, create and activate a local virtual environment and install the required dependencies using the following commands:
 
 ```ps1
 python -m venv venv
 .\venv\Scripts\Activate.ps1
 python -m pip install --upgrade pip
+python -m pip install -r scripts/requirements-dev.txt
 ```
 
-From here on out, we assume you have this virtualenv activated.
+Then build and install the Rerun SDK with:
 
-### Build and install
-
-You need to setup your build environment once with
-```sh
-./scripts/setup.sh
+```ps1
+maturin develop \
+    --manifest-path rerun_py/Cargo.toml \
+    --extras="tests"
 ```
 
-Then install the Rerun SDK with:
-```
-pip install ./rerun_py
+You can then run the example using the following command:
+
+```ps1
+python examples/python/car/main.py
 ```
 
-> Note: If you are unable to upgrade pip to version `>=21.3`, you need to pass `--use-feature=in-tree-build` to the `pip install` command.
+## Building the docs
+
+High-level documentation for rerun can be found at [http://rerun.io/docs](http://rerun.io/docs). It is built from the separate repository [rerun-docs](https://github.com/rerun-io/rerun-docs).
+
+Python API docs can be found at <https://ref.rerun.io/docs/python> and are built via `mkdocs` and hosted on GitHub. For details on the python doc-system, see [Writing Docs](https://github.com/rerun-io/rerun/blob/main/rerun_py/docs/writing_docs.md).
+
+Rust documentation is hosted on <https://docs.rs/rerun/>. You can build them locally with: `cargo doc --all-features --no-deps --open`
 
 
 ## Building for the Web
@@ -95,7 +138,7 @@ cargo run -p re_build_web_viewer -- --release
 
 ### Building with WebGPU support
 
-By default all web builds are using WebGL for rendering.
+By default, all web builds are using WebGL for rendering.
 However, Rerun can also build with experimental WebGPU support!
 Note that currently we can't build wasm files that support both WebGPU and WebGL.
 
@@ -114,7 +157,7 @@ cargo run -p re_build_web_viewer -- --release --webgpu
 
 As of today, we link everything statically in both debug and release builds, which makes custom linkers and split debuginfo the two most impactful tools we have at our disposal in order to improve compile times.
 
-These tools can configured through your `Cargo` configuration, available at `$HOME/.cargo/config.toml`.
+These tools can be configured through your `Cargo` configuration, available at `$HOME/.cargo/config.toml`.
 
 ### macOS