improve documentation

fix some formatting issues

recommend use of more descriptive build directory names:
* `./build_rp2040`
* `./build_rp2350`

_Note: Github actions currently continue to simply build in `./build`, as they build only one architecture per task, and thus do not have cross-architecture pollution concerns._

hacks/build_server.md

@@ -43,15 +43,15 @@ source /etc/profile.d/pico-sdk.sh
 ```
 sudo git clone https://github.com/DangerousPrototypes/BusPirate5-firmware.git bp5-main
 cd bp5-main
-mkdir build
-mkdir build6
 
-pushd build 
-cmake ..
+mkdir build-rp2040
+pushd build-rp2040
+cmake .. -DPICO_SDK_FETCH_FROM_GIT=TRUE
 make
 popd
 
-pushd build6
+mkdir build-rp2350
+pushd build-rp2350
 cmake .. -DPICO_SDK_FETCH_FROM_GIT=TRUE -DBP_PICO_PLATFORM=rp2350
 make
 popd

hacks/build_server_condensed.md

@@ -23,9 +23,9 @@ echo 'export PICO_SDK_PATH=/opt/pico-sdk' | sudo tee -a /etc/profile.d/pico-sdk.
 source /etc/profile.d/pico-sdk.sh
 ```
 
-# Install BP5
+# Install BP5 (RP2040)
 ```
-sudo git clone https://github.com/DangerousPrototypes/BusPirate5-firmware.git bp5-main && cd bp5-main &&mkdir build && cd build  && cmake .. && make
+sudo git clone https://github.com/DangerousPrototypes/BusPirate5-firmware.git bp5-main && cd bp5-main && mkdir build_rp2040 && pushd build_rp2040  && cmake .. -DPICO_SDK_FETCH_FROM_GIT=TRUE && make && popd && mkdir build_rp2350 && pushd build_rp2350 && cmake .. -DPICO_SDK_FETCH_FROM_GIT=TRUE -DBP_PICO_PLATFORM=rp2350 && make && popd
 ```
 
 # Install build script and webhook

readme.md

@@ -38,8 +38,10 @@ Bus Pirate 5 is the universal serial interface tool designed by hackers, for hac
 
 This project uses `cmake` as the build system, so building the project only takes 2 steps:
 1. project configuration (needs to be ran once, or when you want to change configuration).  
-    `cmake -S . -B build  -DPICO_SDK_FETCH_FROM_GIT=TRUE`
-    `cmake -S . -B build6 -DPICO_SDK_FETCH_FROM_GIT=TRUE -DBP_PICO_PLATFORM=rp2350`
+    ```
+    cmake -S . -B build_rp2040 -DPICO_SDK_FETCH_FROM_GIT=TRUE
+    cmake -S . -B build_rp2350 -DPICO_SDK_FETCH_FROM_GIT=TRUE -DBP_PICO_PLATFORM=rp2350
+    ```
     you may want to add the flags `-DPICO_SDK_PATH=/path/to/pico-sdk -DPICO_SDK_FETCH_FROM_GIT=FALSE` if you want to use pico-sdk that is in your local path.  
     > NOTE: WINDOWS users: for some reason the automatic fetch fails because of git submodule, so you will need to clone pico-sdk your self, and then
     > apply the following commands inside the pico-sdk repo:  
@@ -48,21 +50,44 @@ This project uses `cmake` as the build system, so building the project only take
     > git submodule update
     > ```
     
-2. project build  
-    `cmake --build ./build`
-    `cmake --build ./build6`
-    you may add a specific target, such as:
-    `cmake --build ./build --target bus_pirate5_rev8`
-    `cmake --build ./build --target bus_pirate5_rev10`
-    `cmake --build ./build6 --target bus_pirate5_xl`
-    `cmake --build ./build6 --target bus_pirate6`
-    you can manually clean via:
-    `cmake --build ./build --target clean`
-    `cmake --build ./build6 --target clean`
-    Finally, you can force a clean prior to building by adding `--clean-first`.
+2. project build
+    ```bash
+    cmake --build ./build_rp2040 --target all
+    cmake --build ./build_rp2350 --target all
+    # you may add a specific target, such as:
+    cmake --build ./build_rp2040 --target bus_pirate5_rev8
+    cmake --build ./build_rp2040 --target bus_pirate5_rev10
+    cmake --build ./build_rp2350 --target bus_pirate5_xl
+    cmake --build ./build_rp2350 --target bus_pirate6
+    ```
+    You can also manually clean using `--target clean`, or
+    force a clean prior to building by using `--clean-first`.
+
+### Build using Github Actions
+
+Having difficulty setting up a build environment?  Here's a
+workaround that, while it takes longer to build than a local build,
+can be done with just a web browser and a GitHub account.
+
+<details><summary>Click to expand / show workaround...</summary><P/>
+
+Example:
+1. Presume you've forked the repository into your GitHub account, and have a local branch you've named `fix_branch` with your changes.
+1. Next, click on the `Actions` tab (near top of the UI, to the right of `<> Code` and `Pull Requests`
+1. If this is the first time you've done this, you may need to authorize the github actions to run on your fork.  This is a one-time operation.
+1. Otherwise, click on the `CMake` workflow listed on the left.
+1. Note that the page will say, `This workflow has a workflow_run event trigger.`  That means you can run the action manually on a branch of your choice.
+1. Click the `Run workflow` button, select the branch you created (e.g., `fix_branch`), and click the `Run workflow` button.
+1. Wait a few seconds, then refresh the page, and you should see the workflow running.  It may take a few minutes to complete (e.g., **4-7 minutes** is normal.)
+1. Once the workflow completes (shows green checkmark), click on the job to see details.  At the bottom of the page should be the generated artifacts, with download links.
+1. Download the artifact of interest. BP5 firmware can be found in `firmware-rp2040-*`, while the BP5XL and BP6 firmwares can be found in `firmware-rp2350-*`.
+
+That's it!  You now have a firmware build without having to have installed a local build environment.
+
+</details>
 
-    
 ### build using docker
+
 Instructions on the forum provide additional details; however, this repo provides a docker compose image for you to just get running quickly in the event you want to try patching/hacking.
 To run a build, perform the following actions on linux: