Add support for envFile/dotEnv/.env files

[seppestas]

Many launch configurations providers, e.g cppdbg, nodejs and Python, have an option to provide an envFile that contains a list of environmental variables.

This feature is very handy to transfer information between build tasks and the launch configuration since vscode is currently lacking a decent built-in feature that allows this. Please consider supporting this in cortex-debug launch configurations. It would be especially handy if this feature could be used to set things like the debugger server, device, and the executable.

My use-case is a project with many build configurations and targets. Currently a very big (15k lines and growing) launch configuration is used, which is quickly getting unmaintainable.

[haneefdm]

Well, how would that be used in an embedded processor? It has no concept of an env. The env in those other debuggers are for the program being launched./debugged

How else are the variables that go into the env file used? Are they used to expand env vars referred to in the tasks/launch.json? As far as I know, they aren't used by anyone except the program being debugged.

You can already use env variables in your launch.json (not coming from the envFile though). Please note that we do not interpret the launch.json for variable substitutions. VSCode does that and the source of the variables can be your env, workspace, input, a task, etc.

https://code.visualstudio.com/docs/editor/variables-reference
https://code.visualstudio.com/docs/cpp/launch-json-reference#_environment-variable-definitions-file

Can you show me an example of how the envFile is used to make launch.json easier in these other debuggers? What triggers the substitutions? For a normal env. variable for instance, VSCode uses the syntax like ${env:USERNAME}

https://code.visualstudio.com/docs/editor/variables-reference#_environment-variables

[seppestas]

I admit it is a bit of a hack. The problem with ${env:} variables is that they only show VSCode's environment at the time of launch, they can't be altered by e.g tasks. The only way to change it is to launch VSCode with a different environment. Really what is missing is a decent project variable concept in VSCode, see microsoft/vscode#154802.

I thought the plugin might be able to load variables from a .env file and substitute the ${env:} or $, but looking at the source this is indeed probably not possible because VSCode handles the expansion.

Maybe having pre-defined env vars set some of the configuration of cortex-debug would work?

E.g a .env file with

CORTEX_DEBUG_SERVERTYPE=jlink
CORTEX_DEBUG_EXCECUTABLE=some/executable.elf

could be used with a launch configuration like:

{
    "name": "Debug with JLink",
    "type": "cortex-debug",
    "request": "launch",
    "envFile": ".env"
}

This way, the build task can output an env file with the correct debugger and executable path.

[haneefdm]

And, that is not how other debuggers I know work, AFAIK. It is not us, but VSCode who will parse the whole thing and interpret what is in it before giving it to us. There is OS-specific stuff as well that VSCode handles and filters. What you are asking for is not an evnFile but an alternate to launch.json and perhaps in a different format.

For instance, in the example the preLaunchTask is something that VSCode deals with. We never get to see that aspect.

What I can see is to have the full launch.json there and allow substitutions on top of what VSCode has already done. But what you seem to want is to literally concatenate whats in launch.json with what is in envFile. I can't envision that. The same can also be passed to all tools we launch but that might have unintended consequences. So, I would not call those env. variables.

Why not regenerate the entire launch.json at the end of your build? VSCode is pretty good at monitoring any change in launch.json

Another thing I noticed is that CMake tools integrated into VSCode do some magic on launch.json and replace many build-related variables referred to in launcj.json. They probably use Command variables and they can do that because they are a plugin.

https://code.visualstudio.com/docs/editor/variables-reference#_command-variables

[seppestas]

AFAIK. It is not us, but VSCode who will parse the whole thing and interpret what is in it before giving it to us

Sure, this is how it is now. I would like to bypass that in a way, because VSCode does a pretty bad job at it IMO.

Why not regenerate the entire launch.json at the end of your build? VSCode is pretty good at monitoring any change in launch.json

Not a bad idea, thanks. I ended up coming to the same conclusion, I'm closing this issue because indeed env variables might not be the most logical solution. Again, my reasoning for using "env vars" is because vscode lacks any form of "project variables", env vars being the closest thing to it.

Another thing I noticed is that CMake tools integrated into VSCode do some magic on launch.json and replace many build-related variables referred to in launcj.json. They probably use Command variables and they can do that because they are a plugin.

This only works if you build custom commands. There is a run task command, but sadly it does not allow to return values from the task.

My goal is to get a minimal viable setup without any extra custom plugins to maintain. The project I'm working on is used by a lot of different people across different teams, so I would prefer not having to document a combination of plugins being required.

[daltonv]

I still think this issue is needed if you are getting your compiler or debugger executables from a package manager like Conan. Conan downloads the package into a special folder in your home directory. It is not feasible to know the name of this directory ahead of time, however conan generates a shell script that appends this directory to your PATH. It could easily be modified to generate a .env file too.

[haneefdm]

Why don't you wrap gdb in any script of your own? I am still not open to this. You have a dozen different ways to customize.

[seppestas]

It's not that this feature is required, it would just make things easier. Basically, it's a work around the lack of a proper project variables in VS Code, see microsoft/vscode#154802. My hope was that adding a workaround in cortex-debug would be easier to get accepted than for MS to consider adding a missing feature.

A GDB script would not easily fix the problem, which is to get variables that can be easily changed into the launch config. Though a GDB script parsing something like a .env file is may be not a bad idea.

E.g. when I created this issue, I had a lot of configuration of software (different radio chipsets and software built on different RTOSes) that I wanted to run on multiple targets. My goal was to:

• Allow to quickly and easily change aspects of the the software being built (OS, feature set, ...), which could result in different Jlink / GDB options
• Allow to quickly and easily change what specific device to program and/or debug

See also leighmcculloch/vscode-extension-status-bar-env-var#1

I'm currently experimenting with KConfig (as in making VS Code alter the KConfig) for the first requirement. Generating the launch.json was good enough for the second requirement.

Loading in something like a .env file would make things a lot simpler though, and it is what a lot of other VSCode launch plugins seem to do. NB. that "environmental variable" here refers to the "launch" environment, and it would include things like e.g the IP of the JLink server, not runtime variables in the device.

[haneefdm]

What other debuggers do is for the target. Those are not embedded targets. But even those, you can do with a gdb-script that you can specify as debuggerArgs in launch.json

https://sourceware.org/gdb/current/onlinedocs/gdb.html/Environment.html

I just don't want to deal with env-vars across all platforms (local & remote) that have not already been set before you start VSCode. You can even wrap vscode in a script and have your team use that.

We launch so many programs as part of starting a debug session. How do these things affect each of those programs?

[SonnyDinnetz]

I've made a PR which adds support for "envFile" and "environment" as properties in the launch.json.

#1117