Added IDE section to BUILDING.md

BUILDING.md

@@ -1,3 +1,9 @@
+# Table of contents
+- [Building Retro-Go](#prerequisites)
+- [Porting Retro-Go](#porting-retro-go)
+- [IDE Support](#ide-support)
+
+
 # Building Retro-Go
 
 ## Prerequisites
@@ -13,7 +19,6 @@ Patching esp-idf may be required for full functionality. Patches are located in
 
 ## Obtaining the code
 
-
 Using git is the preferred method but you can also download a zip from the project's front page and extract it if you want, Retro-Go has no external dependencies.
 
 There are generally two active git branches on retro-go:
@@ -23,35 +28,27 @@ There are generally two active git branches on retro-go:
 `git clone -b <branch> https://github.com/ducalex/retro-go/`
 
 
-# rg_tool
-ESP-IDF doesn't support managing multiple apps in one environment (launcher, prboom-go, etc). `rg_tool.py` is used instead, which passes correct arguments to `idf.py` and other tools.
+## rg_tool.py
+ESP-IDF's `idf.py` isn't capable of managing multiple applications in one project by itself (building a multi-app image, flashing to the correct partition, single build command, etc). `rg_tool.py` must be used instead, which passes correct arguments to `idf.py` and other tools.
 
+For brevity, all the commands listed in this document omit additional flags that you will likely need, such as `--target` and `--port`. Those two flags can also be specified in the environment as `RG_TOOL_TARGET` and `RG_TOOL_PORT`, respectively.
+
+Run `python rg_tool.py --help` to see all available flags and commands.
 
-To get started, run
-```
-./rg_tool.py
-```
-or 
-```
-python rg_tool.py
-```
 
 ## Build everything and generate a firmware image:
-- Generate a .fw file to be installed with odroid-go-firmware (SD Card):\
-   `python rg_tool.py build-fw` or `python rg_tool.py release` (clean build)
+- Generate a .fw file to be installed with odroid-go-firmware or odroid-go-multi-firmware from SD Card:\
+    `python rg_tool.py build-fw` or `python rg_tool.py release` (clean build)
 - Generate a .img to be flashed with esptool.py (Serial):\
-   `python rg_tool.py build-img` or `python rg_tool.py release` (clean build)
-
+    `python rg_tool.py build-img` or `python rg_tool.py release` (clean build)
 
 For a smaller build you can also specify which apps you want, for example the launcher + DOOM only:
 1. `python rg_tool.py build-fw launcher prboom-go`
 
-
 Note that the app named `retro-core` contains the following emulators: NES, PCE, G&W, Lynx, and SMS/GG/COL. As such, these emulators cannot be selected individually. The reason for the bundling is simply size, together they account for a mere 700KB instead of almost 3MB when they were built separately.
 
 
 ## Flashing an image for the first time
-
 Once we have successfully built an image file (`.img` or `.fw`), it must be flashed to the device.
 
 To flash a `.img` file with `rg_tool.py`, run:
@@ -64,41 +61,61 @@ To flash a `.img` file with `esptool.py`, run:
 esptool.py write_flash --flash_size detect 0x0 retro-go_*.img
 ```
 
-To flash a `.fw` file: 
+To flash a `.fw` file:
 
 Instructions depend on your device, refer to [README.md](README.md#installation).
 
-## Build, flash, and monitor individual apps for faster development:
 
+## Build, flash, and monitor individual apps for faster development:
 A full Retro-Go image must be flashed at least once (refer to previous section), but, after that, it is possible to flash and monitor individual apps for faster development time.
 
 1. Flash: `python rg_tool.py --port=COM3 flash prboom-go`
 2. Monitor: `python rg_tool.py --port=COM3 monitor prboom-go`
 3. Flash then monitor: `python rg_tool.py --port=COM3 run prboom-go`
 
-## Environment variables
-rg_tool.py supports a few environment variables if you want to avoid passing flags all the time:
-- `RG_TOOL_TARGET` represents --target
-- `RG_TOOL_BAUD` represents --baud
-- `RG_TOOL_PORT` represents --port
+
+## Windows
+Running `./rg_tool.py ...` on Windows might invoke the wrong Python interpreter (causing the build to fail)
+or even do nothing at all. In such cases you should use `python rg_tool.py ...` instead.
+
 
 ## Changing the launcher's images
 All images used by the launcher (headers, logos) are located in `launcher/main/images`. If you edit them you must run the `launcher/main/gen_images.py` script to regenerate `images.c`. Magenta (rgb(255, 0, 255) / 0xF81F) is used as the transparency color.
 
+
 ## Capturing crash logs
 When a panic occurs, Retro-Go has the ability to save debugging information to `/sd/crash.log`. This provides users with a simple way of recovering a backtrace (and often more) without having to install drivers and serial console software. A weak hook is installed into esp-idf panic's putchar, allowing us to save each chars in RTC RAM. Then, after the system resets, we can move that data to the sd card. You will find a small esp-idf patch to enable this feature in tools/patches.
 
-
 To resolve the backtrace you will need the application's elf file. If lost, you can recreate it by building the app again **using the same esp-idf and retro-go versions**. Then you can run `xtensa-esp32-elf-addr2line -ifCe app-name/build/app-name.elf`.
 
-## Porting
-Instructions to port to new ESP32 devices can be found in [PORTING.md](PORTING.md).
 
 
+# Porting Retro-Go
+
+## ESP32
+Instructions to port to new ESP32 devices can be found in [PORTING.md](PORTING.md).
+
+## Other architectures
 I don't want to maintain non-ESP32 ports in this repository, but let me know if I can make small changes to make your own port easier! The absolute minimum requirements for Retro-Go are roughly:
 - Processor: 200Mhz 32bit little-endian
 - Memory: 2MB
 - Compiler: C99 (and C++03 for handy-go)
 
 Whilst all applications were heavily modified or even redesigned for our constrained needs, special care is taken to keep
 Retro-Go and ESP32-specific code exclusively in their port file (main.c). This makes reusing them in your own codebase very easy!
+
+
+
+# IDE Support
+
+## VS Code
+Retro-Go comes with a VS Code workspace file that contains configuration for the C/C++ extension.
+
+To get intellisense working properly you have to define some paths in your *global* configuration file:
+
+````json
+    "retro-go.sdk-path": "C:/espressif/frameworks/esp-idf-v5.0.4",
+    "retro-go.tools-path": "C:/espressif/tools/xtensa-esp32-elf/esp-2021r2-patch3-8.4.0/xtensa-esp32-elf",
+````
+
+Clangd is not supported at this time because I have not found a way to make it work well in our multi-folder workspace.

PORTING.md

@@ -1,6 +1,5 @@
-# Patching Retro-Go
-Adjust retro-go to use your drivers and hardware
-
+# Porting Retro-Go
+This document describes the process of adding support for a new ESP32 device (what retro-go calls a *target*).
 
 
 
@@ -13,10 +12,10 @@ Before using your own patch of retro-go, make a clean build of retro go using ba
 ./rg_tool.py build-img launcher --target esp32s3-devkit-c
 ```
 
-Since we aren't using other setups, like ODROID-GO, we will be building `/img` files, not `.fw`. Use `./rg_tool.py build-img` to build imgs.
+Since we aren't using other setups, like ODROID-GO, we will be building `.img` files, not `.fw`. Use `./rg_tool.py build-img` to build imgs.
 
 
-**Make sure a basic setup is working before continuing to patch the code for your setup** 
+**Make sure a basic setup is working before continuing to patch the code for your setup**
 
 If it doesn't, refer to [BUILDING.md](BUILDING.md). Also check your `esp-idf` installation and make sure you have it set up in your environment (run `idf.py --version` to check)
 ```