Merge pull request #7 from ahepp/expand_instructions

Expand instructions

README.md

@@ -5,23 +5,63 @@
 
 ### Requirements
 
-    - xargo or cargo xbuild
-    - xtensa-esp32-elf toolchain must be in your `$PATH`
-    - esptool, if targeting the esp32 or esp8266
+#### llvm-xtensa
+Please refer to [Espressif's llvm](https://github.com/espressif/llvm-project) project for authoratative instructions.
 
-First you will need to build `rustc` and `llvm` you can find rough instructions [here](https://gist.github.com/MabezDev/26e175790f84f2f2b0f9bca4e63275d1).
+    $ git clone https://github.com/espressif/llvm-project
+    $ cd llvm-project/llvm
+    $ mkdir build
+    $ cd build
+    $ cmake .. -DLLVM_TARGETS_TO_BUILD="Xtensa;X86" -DCMAKE_BUILD_TYPE=Release -G "Ninja"
+    $ make
 
-## Starting a new project
+Calling make with an appropriate number of threads will speed the process considerably.
 
-`$ cargo generate --git https://github.com/MabezDev/xtensa-rust-quickstart`
+Many use the guideline `n + 1`, where `n` is the number of processor cores on your machine. For example, for a processor with 4 logical cores:
+
+    $ make -j5
 
-Requires cargo generate.
+#### rust-xtensa
+Please refer to the [rust-xtensa](https://github.com/MabezDev/rust-xtensa) project for authoratative instructions.
 
-## Workflow
+Assuming you built llvm in your home directory:
 
-Update `setenv` to use your xtensa enabled rustc, then simply run `source setenv`.
-From then on, you can just call `xargo build` or use the built in `flash` script to build and flash to the esp.
+    $ git clone https://github.com/MabezDev/rust-xtensa
+    $ cd rust-xtensa
+    $ git checkout xtensa-target
+    $ ./configure --llvm-root=$HOME/llvm-project/llvm/build
+    $ ./x.py build
 
+#### xtensa-esp32-elf toolchain
+Instructions can be found [on Espressif's web site](https://docs.espressif.com/projects/esp-idf/en/release-v3.0/get-started/linux-setup.html).
+
+Download the archived toolchain file, and extract it to the directory of your choice. Then add the toolchain's bin/ directory to your `$PATH`. For example:
+
+    $ mkdir ~/esp
+    $ tar -xzf ~/Downloads/xtensa-esp32-elf-linux64-1.22.0-80-g6c4433a-5.2.0.tar.gz -C ~/esp
+    $ PATH="$PATH:$HOME/esp/xtensa-esp32-elf/bin"
+
+#### xargo or cargo xbuild
+    $ cargo install xargo
+
+or
+
+    $ cargo install xbuild
+
+#### esptool
+    $ pip install esptool
+
+### Starting a new project
+    $ git clone https://github.com/MabezDev/xtensa-rust-quickstart
+
+### Workflow
+Update `CUSTOM_RUSTC` in `setenv` to point to the version of rust you compiled earlier. Then load the environment variables with `source setenv`.
+
+If you installed `xbuild` instead of `xargo`, you will need to update `flash` and `flash_release` accordingly.
+
+You should now be able to call xargo (or cargo xbuild) to build the project. You can also run the flash script to both build the project, and flash it to the ESP32
+
+You will need to change the parameter `BLINKY_GPIO` to match your board's LED pin. Unfortunately, this may require adjustments to the chip's IO_MUX peripheral, which will mean consulting the ESP32 Technical Reference Manual. See [this issue](https://github.com/MabezDev/idf2svd/issues/11) for more information.
 
 ## Resources
 
@@ -31,4 +71,4 @@ From then on, you can just call `xargo build` or use the built in `flash` script
 ## FAQ
 
 - `error: intermittent IO error while iterating directory` - try creating that directory
-- `undefined reference to .L` see [this issue](https://github.com/MabezDev/xtensa-rust-quickstart/issues/1)
+- `undefined reference to .L` see [this issue](https://github.com/MabezDev/xtensa-rust-quickstart/issues/1)