Fix `initCommands` behavior

[andy9a9]

The current behavior described in documentation is misleading: commands sent before attaching to inferior. The commands are sent after the GDB is attached, which is too late, especially if you wanted to set e.g. the baudrate. The preRunCommands section should be used instead.

[jreineckearm]

I am keen to hear others' opinions (@jonahgraham , @asimgunes), but I believe changing this will break a lot of existing setups:
I agree that implementation and documentation diverge in this case. But based on the current behavior, people debugging embedded systems may have used it to configure the (remote) target system after connecting to the GDB server but before loading any program files. This sometimes is necessary to unlock a device or to setup memories, clocks, etc.

To keep the disrupt for users low I'd suggest to rather fix the documentation and add another set of initialization commands executed before connection (maybe preConnectCommands ?).

[cwalther]

No opinion from my side, I am only using connectCommands at this time – and if that ever changes, I can still adapt as we haven’t released anything yet.

[jonahgraham]

I agree with @jreineckearm's conclusion.

The documentation (readme.md) has over simplified things a little as initCommands is documented here for local and here for target debugging. Both entries say:

List of GDB commands sent before attaching to inferior.

But in the package.json documented them differently for local and target debugging:

Local, launch: List of GDB commands sent before starting inferior.
Local, attach: List of GDB commands sent before attaching to inferior.
Target, launch: List of GDB commands sent after attaching to target before loading image on target.
Target, attach: List of GDB commands sent after attaching to target before loading image on target.

[jreineckearm]

@andy9a9 , would you be OK with a solution where we don't touch when initCommands is called but rather introduce a new setting preConnectCommands? I think your PR #431 could be easily adjusted to that.

Just may need adding of the new option here: https://github.com/eclipse-cdt-cloud/cdt-gdb-adapter/blob/main/src/types/session.ts
And a PR for https://github.com/eclipse-cdt-cloud/cdt-gdb-vscode to add it to the package.json and the docs.

I took the liberty of fixing the docs for initCommands for gdbtarget here: eclipse-cdt-cloud/cdt-gdb-vscode#178

[andy9a9]

@andy9a9 , would you be OK with a solution where we don't touch when initCommands is called but rather introduce a new setting preConnectCommands? I think your PR #431 could be easily adjusted to that.

Yes, that makes sense to me. But then the documentation needs some polishing where the options will be clearly described.

[jreineckearm]

@andy9a9 , apologies for the long silence.
I have updated the documentation for the current behavior with yesterday's release.

Would you be interested in reusing your PR to introduce the new preConnectCommands setting? Depending on how urgent the change is for you, this may help to accelerate it getting included.

[andy9a9]

Yes, you can re-use it without any problems. And no, it's not so urgent.