chore: dap fixes and documentation

CHANGELOG.md

@@ -6,6 +6,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.1.2] - 2024-08-02
+
+### Fixed
+
+- DAP: Autoload new configurations in `on_attach` [[#466](https://github.com/mrcjkb/rustaceanvim/issues/466)].
+
 ## [5.1.1] - 2024-07-29
 
 ### Fixed

README.md

@@ -207,7 +207,6 @@ vim.keymap.set(
   You can call them with `require('dap').continue()` or `:DapContinue` once
   they have been loaded. The feature can be disabled by setting
   `vim.g.rustaceanvim.dap.autoload_configurations = false`.
-  It is disabled by default in neovim 0.9, as it can block the UI.
 
   - `:RustLsp debuggables` will only load debug configurations
     created by `rust-analyzer`.

doc/rustaceanvim.txt

@@ -1,14 +1,15 @@
 ==============================================================================
 Table of Contents                                        *rustaceanvim.contents*
 
-Introduction ··························································· |intro|
+Introduction ·············································· |rustaceanvim.intro|
  ································································ |rustaceanvim|
 plugin configuration ····································· |rustaceanvim.config|
 LSP configuration utility ························· |rustaceanvim.config.server|
  ························································ |rustaceanvim.neotest|
+ ···························································· |rustaceanvim.dap|
 
 ==============================================================================
-Introduction                                                             *intro*
+Introduction                                                *rustaceanvim.intro*
 
 This plugin automatically configures the `rust-analyzer` builtin LSP client
 and integrates with other rust tools.
@@ -474,4 +475,31 @@ Note: If you use this adapter, do not add the neotest-rust adapter
 (another plugin).
 
 
+==============================================================================
+                                                              *rustaceanvim.dap*
+
+
+ The DAP integration requires `nvim-dap` https://github.com/mfussenegger/nvim-dap
+ (Please read the plugin's documentation, see |dap-adapter|)
+ and a debug adapter (e.g. `lldb` https://lldb.llvm.org/
+ or `codelldb` https://github.com/vadimcn/codelldb).
+
+ By default, this plugin will silently attempt to autoload |dap-configuration|s
+ when the LSP client attaches.
+ You can call them with `require('dap').continue()` or `:DapContinue` once
+ they have been loaded. The feature can be disabled by setting
+ `vim.g.rustaceanvim.dap.autoload_configurations = false`.
+
+ - `:RustLsp debuggables` will only load debug configurations
+   created by `rust-analyzer`.
+ - `require('dap').continue()` will load all Rust debug configurations,
+   including those specified in a `.vscode/launch.json`
+   (see |dap-launch.json|)
+
+ IMPORTANT: Note that rustaceanvim may only be able to load DAP configurations
+ when rust-analyzer has finished initializing (which may be after
+ the client attaches, in large projects). This means that the
+ DAP configurations may not be loaded immediately upon startup.
+
+
 vim:tw=78:ts=8:noet:ft=help:norl:

flake.nix

@@ -113,6 +113,13 @@
             luacheck.enable = true;
             editorconfig-checker.enable = true;
             markdownlint.enable = true;
+            docgen = {
+              enable = true;
+              name = "docgen";
+              entry = "${docgen}/bin/docgen";
+              files = "\\.(lua)$";
+              pass_filenames = false;
+            };
           };
         };
 
@@ -130,6 +137,7 @@
               luacheck
               editorconfig-checker
               markdownlint-cli
+              docgen
             ]
             ++ oa.buildInputs;
           doCheck = false;

lua/rustaceanvim/config/internal.lua

@@ -297,7 +297,7 @@ local RustaceanDefaultConfig = {
   --- @class rustaceanvim.dap.Config
   dap = {
     --- @type boolean Whether to autoload nvim-dap configurations when rust-analyzer has attached?
-    autoload_configurations = vim.fn.has('nvim-0.10.0') == 1, -- Compiling the debug build cannot be run asynchronously on Neovim < 0.10
+    autoload_configurations = true,
     --- @type rustaceanvim.dap.executable.Config | rustaceanvim.dap.server.Config | rustaceanvim.disable | fun():(rustaceanvim.dap.executable.Config | rustaceanvim.dap.server.Config | rustaceanvim.disable)
     adapter = function()
       --- @type rustaceanvim.dap.executable.Config | rustaceanvim.dap.server.Config | rustaceanvim.disable

lua/rustaceanvim/dap.lua

@@ -1,3 +1,30 @@
+---@mod rustaceanvim.dap
+---@brief [[
+---
+--- The DAP integration requires `nvim-dap` https://github.com/mfussenegger/nvim-dap
+--- (Please read the plugin's documentation, see |dap-adapter|)
+--- and a debug adapter (e.g. `lldb` https://lldb.llvm.org/
+--- or `codelldb` https://github.com/vadimcn/codelldb).
+---
+--- By default, this plugin will silently attempt to autoload |dap-configuration|s
+--- when the LSP client attaches.
+--- You can call them with `require('dap').continue()` or `:DapContinue` once
+--- they have been loaded. The feature can be disabled by setting
+--- `vim.g.rustaceanvim.dap.autoload_configurations = false`.
+---
+--- - `:RustLsp debuggables` will only load debug configurations
+---   created by `rust-analyzer`.
+--- - `require('dap').continue()` will load all Rust debug configurations,
+---   including those specified in a `.vscode/launch.json`
+---   (see |dap-launch.json|)
+---
+--- IMPORTANT: Note that rustaceanvim may only be able to load DAP configurations
+--- when rust-analyzer has finished initializing (which may be after
+--- the client attaches, in large projects). This means that the
+--- DAP configurations may not be loaded immediately upon startup.
+---
+---@brief ]]
+
 local config = require('rustaceanvim.config.internal')
 local shell = require('rustaceanvim.shell')
 local types = require('rustaceanvim.types.internal')
@@ -23,17 +50,6 @@ local dap = require('dap')
 
 local M = {}
 
----@deprecated Use require('rustaceanvim.config').get_codelldb_adapter
-function M.get_codelldb_adapter(...)
-  vim.deprecate(
-    "require('rustaceanvim.dap').get_codelldb_adapter",
-    "require('rustaceanvim.config').get_codelldb_adapter",
-    '4.0.0',
-    'rustaceanvim'
-  )
-  return require('rustaceanvim.config').get_codelldb_adapter(...)
-end
-
 local function get_cargo_args_from_runnables_args(runnable_args)
   local cargo_args = runnable_args.cargoArgs
 
@@ -78,6 +94,7 @@ local function get_rustc_sysroot(callback)
   end)
 end
 
+---@package
 ---@alias rustaceanvim.dap.SourceMap {[string]: string}
 
 ---@param tbl { [string]: string }
@@ -250,6 +267,7 @@ local function handle_configured_options(adapter, args, verbose)
   end
 end
 
+---@package
 ---@param args rustaceanvim.RARunnableArgs
 ---@param verbose? boolean
 ---@param callback? fun(config: rustaceanvim.dap.client.Config)

lua/rustaceanvim/init.lua

@@ -1,6 +1,6 @@
 ---@toc rustaceanvim.contents
 
----@mod intro Introduction
+---@mod rustaceanvim.intro Introduction
 ---@brief [[
 ---This plugin automatically configures the `rust-analyzer` builtin LSP client
 ---and integrates with other rust tools.

lua/rustaceanvim/lsp.lua

@@ -181,6 +181,10 @@ M.start = function(bufnr)
     if type(old_on_attach) == 'function' then
       old_on_attach(...)
     end
+    if config.dap.autoload_configurations then
+      -- When switching projects, there might be new debuggables (#466)
+      require('rustaceanvim.commands.debuggables').add_dap_debuggables()
+    end
   end
 
   local old_on_exit = lsp_start_config.on_exit

nix/docgen.nix

@@ -6,6 +6,6 @@ pkgs.writeShellApplication {
   ];
   text = ''
     mkdir -p doc
-    lemmy-help lua/rustaceanvim/{init,config/init,config/server,neotest/init}.lua > doc/rustaceanvim.txt
+    lemmy-help lua/rustaceanvim/{init,config/init,config/server,neotest/init,dap}.lua > doc/rustaceanvim.txt
   '';
 }