From c1e09e39273b87006bbbae1782fdb269d5f49e0e Mon Sep 17 00:00:00 2001
From: David Lenfesty <lenfesty@ualberta.ca>
Date: Fri, 16 Jun 2023 14:34:54 -0600
Subject: [PATCH] update some documentation about the Dockerfile

---
 BUILDING.md | 36 +++++++++++++++++++++++++++++++++++-
 Dockerfile  |  2 ++
 2 files changed, 37 insertions(+), 1 deletion(-)

diff --git a/BUILDING.md b/BUILDING.md
index daa7eda..2292070 100644
--- a/BUILDING.md
+++ b/BUILDING.md
@@ -3,7 +3,41 @@
 All of this is assumed to be on a linux system. Eventually I'll probably make or
 use some dockerfile or nix flake that has all this installed already.
 
-## Toolchain Installation
+The recommended dev flow if you want to make changes is to use VSCode with remote containers,
+it's the easiest way to get the toolchain up and running, and to fix the issues encountered
+with migen.
+
+*Note: I currently do not know how to run the dev container with --privileged, so you'll need
+to flash by manually running it*
+
+Recommended extensions:
+
+- Pylance
+- rust-analyzer
+
+## Building with docker
+
+Easiest way is to build and use the docker container:
+
+```
+docker build -r arvp_sonar:latest ./
+# Privileged lets you access USB devices inside the container
+docker run --privileged --rm -it -v /path/to/repository:/code arvp_sonar:latest
+
+# These commands are run inside the container
+cd /code/gateware
+python3 litex_main.py --build # Build the bitstream
+
+# To write to the flash storage
+# TODO not sure how to use this command
+ecpdap write
+# To program the FPGA once
+ecpdap program build/sonar/gateware/sonar.bit --freq 10M
+```
+
+This will generate a bitstream in `gateware/build/sonar
+
+## Toolchain Manual Installation
 
 ### Trellis and FPGA toolchain
 
diff --git a/Dockerfile b/Dockerfile
index 20d8e1e..13e8afa 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -33,6 +33,8 @@ COPY migen.patch /litex/migen/migen.patch
 RUN cd /litex/migen && git apply /litex/migen/migen.patch
 RUN pip install --editable /litex/migen
 
+# TODO remove unnecessary tools
+
 # Delete package cache to keep size small
 RUN apt-get clean