Documenting all the configuration keywords

[bertulli]

Hi! Thank you for the very interesting package.

I am trying to figure out how to use it, and right now I'm trying to launch a simple C++ project that produces a single executable. I want to pass to that executable some CLI arguments, like ./a.out test123. It's not clear to me how should I do it.

Both the docstrings for dape and dape-configs couldn't help me, as not all the keywords are documented, but I guess this is because some of them are specific not to dape, but to the debugger protocol, which I don't know. But it got me wonder, could it be possible to add in the README a tutorial, or a reference to where to get this information? Like, what's the meaning of :args? Is that the keyword I should use? How can I modify the debug sessions every time, so to test different CLI arguments? If I understood correctly, this is done in VSCode/dap-mode using launch.json configuration files, while in dape this is discouraged and instead I should use dir-locals. But how?

If it can help in some way I could try to write down a tutorial if given the complete information, in case this turned out to be too much work.

Thank you again!

[svaante]

Hi! Documentation could definitely be improved and as you pointed out one of the issue is that DAP spec defines zero parameters, so it's up to each adapter to define it's parameters. Dape could make an effort of documenting parameters, I am unsure if it's a good idea as it will add a stronger dependency on the adapters. But I can be conviced

Thrown together some type of poc for how it could be displayed (it's just the docs part that has been added, the larger minibuffer with all key values are on master branch):

I don't know if you have elpa distributed or from master but strategy has changed some and should minimize the need for storing configurations as modifying them directly in the minibuffer should be a better experience.

The current workflow would be something like the following:

If you have a project specific configuration that you dont care to type out each time:

• add-dir-local-variable c++-mode dape-command
• (codelldb-cc command-cwd "~/my-project/" :program "build/bin" :args ["MY_ARG"] compile "make all")

Then after invoking dape the minibuffer will contain codelldb-cc command-cwd "~/my-project/" :program "build/bin" :args ["MY_ARG"] compile "make all" where ex :args vector can be removed or extended based on the use case.

If it's a one time thing dape tries to have sane defaults for all adapters then add or remove flags in the minibuffer with completion for both files and arguments.

The workflow tries to be as close to working with compile command.

[bertulli]

First of all, thanks!

The key for me was that :args is a vector, and not a space separated string. Typing the correct debug configuration in the minibuffer worked for me.

However, I have troubles in setting the .dir-locals.el. It seems to me that the variable dape-command does not exist. Since I'm on ELPA though (0.3.0), IIUC the example workflow you described is in the git version?

Lastly, I can try playing around with the DAP spec, but if I get you right the specification doesn't describe where the arguments need to be passed? That sucks, but I guess it's possible that a de-facto standard will arise.

---

EDIT: it seems that the runInTerminal request has an args parameter: isn't that standard?

[svaante]

dape-command was introduced after latest version bump, but it's time to bump versions.

It has an args thats correct but it's not related to args. runInTerminal is something that is sent from adapter to client (dape) and :args as an vector is something that most adapters (not all, I believe jdtls takes an string) are able to receive as part of an "launch" request.

80% of the properties of launch.json that vscode uses to configure adapters are sent as an "launch" or "attach" request to the adapters including "request" even if it's the way that vscodeand dape figures out if it should be a "launch" or "attach" request.

[bertulli]

Thanks a lot! Using the git version works. If you plan to add this kind of information on the README and you need an hand, please let me know.

Shame the protocol doesn't support this by specification, I'll probably open an issue on that side, maybe it helps.