From 7827873e16c3900c8492871e141780bafccb638d Mon Sep 17 00:00:00 2001 From: jacqueline Date: Wed, 20 Sep 2023 14:28:06 +1000 Subject: Freshed up building instructions, move to a better-named file. --- BUILDING.md | 103 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 103 ------------------------------------------------------------ 2 files changed, 103 insertions(+), 103 deletions(-) create mode 100644 BUILDING.md delete mode 100644 README.md diff --git a/BUILDING.md b/BUILDING.md new file mode 100644 index 00000000..8e4427ab --- /dev/null +++ b/BUILDING.md @@ -0,0 +1,103 @@ + + +# Building and flashing + +1. Make sure you've got all of the submodules in this repo correctly initialised: + +``` +git submodule update --init --recursive +``` + +2. If this is your first time setting up the repo, then you will need to install +the ESP-IDF tools. You can consult the [ESP-IDF docs](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-macos-setup.html) +for more detailed instructions, but the TL;DR is that you'll want to run +something like this: + +``` +./lib/esp-idf/install.sh esp32 +``` + +3. As a final piece of setup, you will need to source the env file in this repo +to correctly set up your environment for building. + +``` +. ./.env +``` + +There is also a `.env.fish` for fish users. + +4. You can now build the project using `idf.py build`. Or to flash the project +onto your board, something like: + +``` +idf.py -p /dev/ttyUSB0 -b 115200 flash +``` + +(give or take the correct serial port) + +# Running tests + +Tests are implemented as a separate application build, located in the `test` +directory. We use Catch2 as our test framework. + +To run them, navigate to the test directory, then build and flash as normal. +Connect to your device via UART, and you will be presented with a terminal +prompt that you may run tests from. + +To add new tests to a components, you must: + 1. Create a `test` subcomponent within that component. See `drivers/test` for + an example of this. + 2. Include the component in the test build and list of testable components, in + `test/CMakeLists.txt`. + + +# VSCode setup + +When using the Espressif IDF extension, you may want to set the following in your settings.json file: +``` + "idf.espIdfPath": "${workspaceFolder}/lib/esp-idf", + "idf.espIdfPathWin": "${workspaceFolder}/lib/esp-idf" +``` + +# LSP (clangd) setup + +A regular build will generate `build/compile_commands.json`, which clangd will +automatically pick up. However, there are a couple of additional steps to get +everything to play nicely. + +First, you will need to download the xtensa clang toolchain. You can do this +via ESP-IDF by running `idf_tools.py install xtensa-clang` + +This will install their prebuild clang into a path like `~/.espressif/tools/xtensa-clang/VERSION/xtensa-esp32-elf-clang/` + +Next, you will need to configure clangd to use this version of clang, plus +forcible remove a couple of GCC-specific build flags. Do this by creating +`.clangd` in the root directory of your project, with contents like so: + +``` +CompileFlags: + Add: [ + -ferror-limit=0, + -I/Users/YOU/.espressif/tools/xtensa-esp32-elf/esp-2021r2-patch5-8.4.0/xtensa-esp32-elf/include, + -I/Users/YOU/.espressif/tools/xtensa-esp32-elf/esp-2021r2-patch5-8.4.0/xtensa-esp32-elf/xtensa-esp32-elf/include, + -I/Users/YOU/.espressif/tools/xtensa-esp32-elf/esp-2021r2-patch5-8.4.0/xtensa-esp32-elf/xtensa-esp32-elf/include/c++/8.4.0, + -I/Users/YOU/.espressif/tools/xtensa-esp32-elf/esp-2021r2-patch5-8.4.0/xtensa-esp32-elf/xtensa-esp32-elf/include/c++/8.4.0/xtensa-esp32-elf, + -isysroot=/Users/YOU/.espressif/tools/xtensa-esp32-elf/esp-2021r2-patch5-8.4.0/xtensa-esp32-elf/xtensa-esp32-elf, + ] + Remove: [ + -Wduplicated-cond, + -Wduplicated-branches, + -Wlogical-op, + -fno-tree-switch-conversion, + -mtext-section-literals, + -mlongcalls, + -fstrict-volatile-bitfields, + ] + Compiler: /Users/YOU/.espressif/tools/xtensa-clang/esp-clang/bin/clang++ +``` + +You should then get proper LSP integration via clangd. diff --git a/README.md b/README.md deleted file mode 100644 index f5100e16..00000000 --- a/README.md +++ /dev/null @@ -1,103 +0,0 @@ - - -# Building and flashing - -1. Make sure you've got all of the submodules in this repo correctly initialised; -``` -git submodule update --init --recursive -``` - -2. If this is your first time setting up the repo, then you will need to install -the ESP-IDF tools. You can consult the [ESP-IDF docs](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-macos-setup.html) -for more detailed instructions, but the TL;DR is that you'll want to run -something like this: -``` -./lib/esp-adf/esp-idf/install.sh esp32 -``` - -3. As a final piece of setup, you will need to source the env file in this repo -to correctly set up your environment for building. -``` -. ./.env -``` -**For VSCode:** - -When using the Espressif IDF extension, you may want to set the following in your settings.json file: -``` - "idf.espAdfPath": "${workspaceFolder}/lib/esp-adf", - "idf.espAdfPathWin": "${workspaceFolder}/lib/esp-adf", - "idf.espIdfPath": "${workspaceFolder}/lib/esp-adf/esp-idf", - "idf.espIdfPathWin": "${workspaceFolder}/lib/esp-adf/esp-idf" -``` - -4. You can now build the project using `idf.py build`. Or to flash the project -onto your board, something like: -``` -idf.py -p /dev/ttyUSB0 -b 115200 flash -``` -(give or take the correct serial port) - -Remember that you will need to boot your ESP32 into software download mode -before you will be able to flash. - -# Running tests - -Tests are implemented as a separate application build, located in the `test` -directory. We use Catch2 as our test framework. - -To run them, navigate to the test directory, then build and flash as normal. -Connect to your device via UART, and you will be presented with a terminal -prompt that you may run tests from. - -To add new tests to a components, you must: - 1. Create a `test` subcomponent within that component. See `drivers/test` for - an example of this. - 2. Include the component in the test build and list of testable components, in - `test/CMakeLists.txt`. - -# clangd setup - -A regular build will generate `build/compile_commands.json`, which clangd will -automatically pick up. However, there are a couple of additional steps to get -everything to place nicely. - -First, you will need to download the xtensa clang toolchain. You can do this -via ESP-IDF by running `idf_tools.py install xtensa-clang` - -This will install their prebuild clang into a path like `~/.espressif/tools/xtensa-clang/VERSION/xtensa-esp32-elf-clang/` - -Next, you will need to configure clangd to use this version of clang, plus -forcible remove a couple of GCC-specific build flags. Do this by creating -`.clangd` in the root directory of your project, with contents like so: - -``` -CompileFlags: - Add: [ - -ferror-limit=0, - -I/Users/YOU/.espressif/tools/xtensa-esp32-elf/esp-2021r2-patch5-8.4.0/xtensa-esp32-elf/include, - -I/Users/YOU/.espressif/tools/xtensa-esp32-elf/esp-2021r2-patch5-8.4.0/xtensa-esp32-elf/xtensa-esp32-elf/include, - -I/Users/YOU/.espressif/tools/xtensa-esp32-elf/esp-2021r2-patch5-8.4.0/xtensa-esp32-elf/xtensa-esp32-elf/include/c++/8.4.0, - -I/Users/YOU/.espressif/tools/xtensa-esp32-elf/esp-2021r2-patch5-8.4.0/xtensa-esp32-elf/xtensa-esp32-elf/include/c++/8.4.0/xtensa-esp32-elf, - -isysroot=/Users/YOU/.espressif/tools/xtensa-esp32-elf/esp-2021r2-patch5-8.4.0/xtensa-esp32-elf/xtensa-esp32-elf, - ] - Remove: [ - -Wduplicated-cond, - -Wduplicated-branches, - -Wlogical-op, - -fno-tree-switch-conversion, - -mtext-section-literals, - -mlongcalls, - -fstrict-volatile-bitfields, - ] - Compiler: /Users/YOU/.espressif/tools/xtensa-clang/esp-clang/bin/clang++ -``` - -You should then get proper LSP integration via clangd, give or take a couple of -oddities (e.g. for some reason, my install still can't see `stdio.h`. NBD tho.) - -Expect this integration to improve sometime in the near future, per [this forum -thread](https://esp32.com/viewtopic.php?f=13&t=29563). -- cgit v1.2.3