Visual Studio Code config files

[laurensvalk]

This moves some comments from #10071 for further discussion.

tl;dr

Visual Studio Code allows you to configure the MicroPython source code for more efficient and convenient ways of working. Originally I didn't think configuration files would be accepted upstream, so I submitted #10071 to ignore such files as a workaround. But based on the comments there, it seems like there may be more to it.

And a discussions thread may be a better place to follow up, so here it is.

Original thread

This adds a section to ignore config files for IDEs not used by the core developers. This is helpful for Visual Studio Code users so that their config files don't get in the way of committing fixes.

Signed-off-by: Laurens Valk [email protected]

This isn't to say that we should never have these files in the repo (it could be nice though), but this conveniently keeps them out of the git tree until then.

---

Thanks @laurensvalk -- I think we should merge this just because it avoids a common point of confusion and I guess vscode is popular enough.

I guess the alternative would so be to add a note to the .gitignore to tell users to change their editor's default location, or recommend adding private IDE-specific rules to .git/info/exclude (or user-wide via core.excludesFile).

Originally posted by @jimmo in #10071 (comment)

---

I'm not sure about this. I really think it's up to the user to configure their local IDE settings/gitignore/etc, rather than each project (eg MicroPython) having to do it.

I would rather remove as much as possible from the current .gitignore than add things.

Originally posted by @dpgeorge in #10071 (comment)

---

See #10075 as an alternative/counterpoint.

Originally posted by @dpgeorge in #10071 (comment)

---

I respect that decision, so I suppose we can close this then.

I'll leave some thoughts here in case anyone wants to follow up in the discussions page. This is about committing configuration in general, not this PR. (Hiding them is more of a workaround.)

I really think it's up to the user to configure their local IDE settings/gitignore/etc, rather than each project (eg MicroPython) having to do it.

From the point of view of contributors (especially new ones), it can sometimes be the other way around.

When I first contributed a few years ago (while not being very well-versed in git), I've found myself making clones in different folders (sometimes a whole new clone for one PR). And even now, I still work on multiple PCs so keeping project settings synchronized and updated as the project moves on is useful.

Settings for e.g. vscode can help new contributors by:

• Just press ⏯️ to auto-build and then run their .py file to test their new contribution.
• Providing correct code highlighting for build variants, grey out #ifdefs not used in that build.
• Autoformatting / squiggly lines / comment auto-hardwrap.
• Auto-code completion/intellisense for the C API, e.g. just typing . on a struct type will show its fields.
• Run all tests locally with ⏯️ to see if a contribution will pass CI.

For long-time contributors this is more of a convenience, but for new contributors it can make the difference of figuring out how to do it right.

Configurations of modern IDEs do not add as much bloat as in the past. In case of Visual Studio Code, it's three json files in ./vscode. Even the contents aren't that bloated and to an extent even act as a form of documentation. For example, the tasks.json is just a list of these:

        {
            "label": "build unix coverage debug",
            "type": "shell",
            "command": "make -C ports/unix VARIANT=coverage DEBUG=1 COPT=-O0 -j"
        },

Originally posted by @laurensvalk in #10071 (comment)

---

@laurensvalk thanks for the extra thoughts. Related to this, there was a recent conversation about this in which (I think) @projectgus suggested that we investigate https://editorconfig.org/ which seems like it should be a pretty useful tool for at least setting up sensible default configuration that covers some of your points above, but crucially applies to a wide range of editors and IDEs rather than having to maintain configuration for any one specific tool.

Originally posted by @jimmo in #10071 (comment)

---

@projectgus suggested that we investigate https://editorconfig.org/

Yep, this was me and at some point I will actually get around to submitting a PR for this. Promise! 😁

Unfortunately editorconfig really only goes as far as basic code formatting settings (indent style, etc). The kind of higher level IDE build/lint/etc integration that @laurensvalk describes are outside its scope, AFAIK. I don't know of an "IDE agnostic" setup format of this kind. Although the growing popularity of LSP as an IDE setup "lingua franca" points to the possibility of something existing in the future...

Having at least a docs guide to setting up vscode sounds like it could potentially be useful, as it seems like the most popular fully fledged IDE for embedded C? But it may be the kind of thing that's better as individual blog post(s) from folks in the community, unless someone is really determined to keep an official one up to date and working across all possible permutations of platform/port/etc?

(I am not a lot of help there, all I could document is maybe "how to set up the particular idiosyncratic combination of emacs packages I use, and the quirks that come with that". Audience is likely smaller... 😆 )

Originally posted by @projectgus in #10071 (comment)

---

Configurations of modern IDEs do not add as much bloat as in the past. In case of Visual Studio Code, it's three json files in ./vscode. Even the contents aren't that bloated and to an extent even act as a form of documentation.

I see now. So you have vscode settings specific to MicroPython that enable more efficient development (you can tell I don't use vscode...!). That is conceptually different to .gitignore, eg, for vim to just ignore swp files. I can see how it would be beneficial to have config files for things like vscode stored in this repo, as it is tied to the project.

Anyway, to start with we should simplify .gitignore.

Originally posted by @dpgeorge in #10071 (comment)

---

Anyway, to start with we should simplify .gitignore.

👍

I only submitted this PR as a workaround because I didn't think config files would be accepted, but it sounds like perhaps they might be some day. So yes, keeping the .gitignore simple seems fine to me.

I see now. So you have vscode settings specific to MicroPython that enable more efficient development (you can tell I don't use vscode...!). That is conceptually different to .gitignore, eg, for vim to just ignore swp files. I can see how it would be beneficial to have config files for things like vscode stored in this repo, as it is tied to the project.

Yes. For example, on Move Hub, we have floating point support disabled in mpconfigport.h. On selecting that config, you get this effect:

code-2022-11-28_08.56.51.mp4

Having at least a docs guide to setting up vscode sounds like it could potentially be useful, as it seems like the most popular fully fledged IDE for embedded C? But it may be the kind of thing that's better as individual blog post(s) from folks in the community, unless someone is really determined to keep an official one up to date and working across all possible permutations of platform/port/etc?

Visual Studio Code and its extensions can parse headers like mpconfigport.h, but not make files as far as I know. See settings for above demo.

So in practice this does mean having to maintain a list of include paths to match the INC += .... but there may be better ways now.

Originally posted by @laurensvalk in #10071 (comment)

---

That is a neat demo, I had not seen this kind of subtle "highlight based on macros" syntax highlighting and I like it a lot!

Visual Studio Code and its extensions can parse headers like mpconfigport.h, but not make files as far as I know. See settings for above demo.

My understanding is that there's basically two ways to do this kind of thing for C:

• Top-down. Like shown above, meaning that the compiler/header/etc flags in the JSON have to match the actual build flags. In my experience this works but it is fiddly and error prone, although my recent experience of it is mostly from ESP-IDF which (TBH) turns build fiddliness up to 11... But even in the best scenario there's no "DRY" single-source-of-truth possible, you always have the possibility of a mismatch between the JSON file and the Makefile.
• Bottom-up. This is where an extension like the VSCode C/C++ Extension (I believe) parses the compile_commands.json build output "Clang tooling file" that has the actual command line used to compile each source file, and it generates everything automatically from this information.
  • This is easiest with CMake, if you set export CMAKE_EXPORT_COMPILE_COMMANDS=1 then CMake automatically generates this file in the build directory when it runs. Then configure the VSCode extension to find it in the right place. I use this approach in MicroPython for rp2 and ESP32* builds, which both use CMake (although I use emacs lsp-mode not VSCode). If you only work on one board it's easy, otherwise you have to remember to change the current build directory to pick up the correct settings.
  • When using Make as a build system then you can use a make wrapper tool like Bear to generate compile_commands.json as each build runs. I haven't tried this yet, with MicroPython or any project, but I want to. I think it will always be a little fiddlier because it can only generate the file when you actually do a build, unlike CMake which runs as more like a "configure" step prior to the actual compilation. But I expect it is still less fiddly than the top-down approach of maintaining duplicate settings.

Just my 2c! I am interested if other folks have tried this kind of thing with MP. Alos, we're getting pretty off-topic for the PR, maybe it's worth having a "IDE-Like Experiences With MicroPython Dev" Discussions topic.

Originally posted by @projectgus in #10071 (comment)