Espressif build environment confusing setup docs

[samblenny]

CircuitPython version

n/a

Code/REPL

n/a

Behavior

n/a

Description

I'm trying to set up an Espressif build environment from scratch, and I hit a couple documentation snags.

1. Looking at the main CircuitPython README, I had a hard time locating where I should start looking for build documentation. Eventually I realized there's a BUILDING.md file, which was helpful, but that file is hard to notice amidst many other top level files. Before that, I found the CONTRIBUTING.md file, but initially missed its link to the Building CircuitPython learn guide. The link text to the guide that I overlooked was just the word "here", so I didn't realize what it was until I went back and did a text search on the Markdown source code. It would be handy if there was a more prominent link to Dan's guide with link text along the lines of, "Building CircuitPython Learn Guide".

2. The Building CircuitPython learn guide instructions on the Install Build Tools on Ubuntu section of the Linux Setup page links to the Espressif Builds page. The Espressif Builds page starts with a request to go read ports/espressif/README.md. So, at that point, you have to choose between jumping to the README or continuing with the Learn guide. If you take the README route first, under the Building and Flashing subheading, it says to do,

   cd ports/espressif
   ./esp-idf/install.sh
   

   But, that doesn't work unless you've first followed the Learn Guide instructions to fetch submodules with

   cd ports/espressif
   make fetch-port-submodules
   

   For a freshly cloned adafruit/circuitpython repo, the ports/espressif/esp-idf directory is empty, so the install script doesn't exist. If the espressif/ports/README.md file mentioned the need to run make fetch-port-submodules, it would be less confusing.

Additional information

No response

[dhalbert]

Did you look at https://learn.adafruit.com/building-circuitpython ? We don't really try to keep the README's up to date, and should probably remvoe most of them.

[dhalbert]

Especially https://learn.adafruit.com/building-circuitpython/espressif-build

[samblenny]

Yes, I eventually found your guide and have been working through its instructions. That's where I ran into the order of operations trouble with fetching submodules relative to installing the esp-idf with install.sh.

[samblenny]

If it would be helpful, I could make a PR with some edits (maybe CONTRIBUTING.md and ports/espressif/README.md). Not sure which branch the PR should be made against though.

[dhalbert]

Thanks - I would like to have the info in the guide, rather than in the README's, because it's easier to maintain. But I know this goes against the grain of having build info in the source code. Nevertheless, the build setup is complicated enough that I'd rather just cross-reference to the guide.

It can go against main.

[bablokb]

@samblenny: You should also have a look at the Readme and scripts in .devcontainer. These scripts (start with install_build_env.sh) are tailored to run on a Github codespace, but changing REPO_ROOT and setting CP_TOOLCHAIN="esp-idf" and CP_PORT=espressif should make them run on a PC too.

[dhalbert]

@samblenny Would you say this issue is fixed now, by #9554, or would you like some additions to the Building CircuitPython guide?

[samblenny]

For this issue, from my perspective, yeah it's fixed.

There might be some opportunity to revise the guide by arranging things into a more linear sequence, with less need to follow cross-reference links. But, I don't feel like I have enough experience with the build system to say much about that. I'm sure there are lots of edge cases to consider.