Update pico readmes with additional clarity #39
Conversation
|
Resolves Issue #20 |
pico-blink/README.md
Outdated
| - Build and copy the program in the UF2 format to the Mass Storage device to trigger flashing the program into memory (after which the device will reboot and run the firmware): | ||
| ``` console | ||
| $ cd pico-blink | ||
| $ TOOLCHAINS='<toolchain-name>' ./build.sh | ||
| $ TOOLCHAINS='<toolchain-name>' ./build.sh # toolchain-name is typically `swift` |
There was a problem hiding this comment.
I don't think is actually true. I have multiple toolchains installed and if I set TOOLCHAINS=swift, I do not get the latest one chosen.
But point taken that the instructions are not really clear on what the TOOLCHAINS variable should be set to...
There was a problem hiding this comment.
I dont think we want to suggest swift as the toolchain name because when a user has multiple toolchains installed its very very unclear which one is getting used.
There was a problem hiding this comment.
I agree! How would I fix this instruction? It's the only thing that I could find that worked for my situation, but it wasn't clear where I was supposed to source a value from. (I had also tried a path to the toolchain via a ChatGPT suggestion amongst several other attempts, but none of those worked)
There was a problem hiding this comment.
I described the instructions here: https://apple.github.io/swift-matter-examples/tutorials/swiftmatterexamples/setup-macos
But its annoying we keep repeating these instructions across tons of examples/tutorials
There was a problem hiding this comment.
I added a link to those instructions - thoughts on that?
There was a problem hiding this comment.
I also changed toolchain-name to toolchain-identifier since that seems to more accurately reflect what it is and what it's referred to as in the given instructions. (not to mention it would have clarified a lot of my own confusion when I was looking for a name and not an identifier - I think I even glanced into the plist and mentally discarded the id since that's not what was requested)
There was a problem hiding this comment.
I added a link to those instructions - thoughts on that?
It's definitely an option and might be ok for now. @cmcgee1024 do you have thoughts on where we can host more details "how to use a custom toolchain" instructions? I really do not want to maintain this information in every embedded examples repo.
There was a problem hiding this comment.
If you're given freedom to create your own tutorials like the matter one, I think that a tutorial on sourcing, using, identifying, etc on toolchains might be worth it on its own.
There was a problem hiding this comment.
We could certainly create such a tutorial in this repo, but I would prefer we have something hosted on Swift.org
There was a problem hiding this comment.
I just meant in the same style as the matter one, not really intending a specific location for it to go. Wherever the home, links could send people there.
|
@mredig I've rebased and pushed some changes to the approach you had taken. Since we have multiple pico examples and the STM examples also need macholib I've elevated the python instructions to the top level readme. Let me know what you think! |
|
Im gonna merge this as is, feel free to comment and/or open a pr with changes if desired |
Ah I'm sorry! I missed the notification. It all looks good though! :D |
I ran into a few issues that weren't easily googleable and therefore required a decent level of troubleshooting to discover, so I updated the docs to help others overcome these hurdles.