From 92a2f50415b13ffcd3a2c9b7fe0f395a81e662b3 Mon Sep 17 00:00:00 2001
From: Denzel <>
Date: Mon, 30 Mar 2026 18:55:35 +0200
Subject: [PATCH 1/3] chore: update readme

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index f636cdf..2ae3ff0 100644
--- a/README.md
+++ b/README.md
@@ -49,7 +49,7 @@ require("cmake-tools").setup {
                           -- copy:      this will automatically copy compile commands file to target
                           -- lsp:       this will automatically set compile commands file location using lsp
                           -- none:      this will make this option ignored
-    target = vim.loop.cwd() -- path to directory, this is used only if action == "soft_link" or action == "copy"
+    target = vim.loop.cwd, -- path or function returning path to directory, this is used only if action == "soft_link" or action == "copy"
   },
   cmake_kits_path = nil, -- this is used to specify global cmake kits path, see CMakeKits for detailed usage
   cmake_variants_message = {

From d87dd938545f79d7a743c977728ad8b4ca7e86d1 Mon Sep 17 00:00:00 2001
From: Denzel <>
Date: Mon, 30 Mar 2026 20:12:05 +0200
Subject: [PATCH 2/3] chore(init): add annotations

---
 lua/cmake-tools/init.lua | 87 ++++++++++++++++++++++++++++++++++++++--
 1 file changed, 84 insertions(+), 3 deletions(-)

diff --git a/lua/cmake-tools/init.lua b/lua/cmake-tools/init.lua
index 229810a..ff799d2 100644
--- a/lua/cmake-tools/init.lua
+++ b/lua/cmake-tools/init.lua
@@ -23,7 +23,12 @@ local cwd = vim.loop.cwd()
 
 local cmake = {}
 
+---@class cmake.CommandOpts : vim.api.keyset.create_user_command.command_args
+---@field target? string
+---@field args? string[]
+
 --- Setup cmake-tools
+---@param values table
 function cmake.setup(values)
   const = vim.tbl_deep_extend("force", const, values)
   const.cmake_executor.opts = vim.tbl_deep_extend(
@@ -62,6 +67,8 @@ function cmake.setup(values)
   cmake.register_scratch_buffer(config.executor.name, config.runner.name)
 end
 
+---@param callback fun(result: cmake.Result)
+---@return boolean
 local function check_active_job_and_notify(callback)
   if utils.has_active_job(config.runner, config.executor) then
     callback(Result:new_error(Types.ANOTHER_JOB_RUNNING, "Another CMake job already running"))
@@ -70,6 +77,8 @@ local function check_active_job_and_notify(callback)
   return false
 end
 
+---@param callback fun(result: cmake.Result)
+---@return cmake.Result?
 local function get_cmake_configuration_or_notify(callback)
   local result = utils.get_cmake_configuration(config.cwd)
   if not result:is_ok() then
@@ -81,9 +90,8 @@ local function get_cmake_configuration_or_notify(callback)
 end
 
 --- Generate build system for this project, much like the `cmake command`
----@param opt table
----@param callback nil|fun(result: cmake.Result): nil
----@return nil
+---@param opt cmake.CommandOpts
+---@param callback? fun(result: cmake.Result)
 function cmake.generate(opt, callback)
   callback = callback or function() end
   if check_active_job_and_notify(callback) then
@@ -279,6 +287,7 @@ function cmake.generate(opt, callback)
 end
 
 --- Clean targets
+---@param callback? fun(result: cmake.Result)
 function cmake.clean(callback)
   callback = callback or function() end
   if check_active_job_and_notify(callback) then
@@ -311,6 +320,8 @@ end
 
 --- Build this project using the make toolchain of target platform
 --- think it as `cmake --build .`
+---@param opt cmake.CommandOpts
+---@param callback? fun(result: cmake.Result)
 function cmake.build(opt, callback)
   callback = callback or function() end
   if check_active_job_and_notify(callback) then
@@ -419,6 +430,8 @@ function cmake.build(opt, callback)
   return utils.execute(cmd, config.env_script, env, args, config.cwd, config.executor, callback)
 end
 
+---@param opt vim.api.keyset.create_user_command.command_args
+---@param callback? fun(result: cmake.Result)
 function cmake.quick_build(opt, callback)
   callback = callback or function() end
   -- if no target was supplied, query via ui select
@@ -466,6 +479,8 @@ function cmake.stop_runner()
 end
 
 --- CMake install targets
+---@param opt vim.api.keyset.create_user_command.command_args
+---@param callback? fun(result: cmake.Result)
 function cmake.install(opt, callback)
   callback = callback or function() end
   if check_active_job_and_notify(callback) then
@@ -518,6 +533,9 @@ function cmake.open_cache()
   end
 end
 
+---@param path string
+---@param vars table<string, string|number|table>
+---@return string
 function cmake.substitute_path(path, vars)
   for key, value in pairs(vars) do
     if type(value) == "string" or type(value) == "number" then
@@ -537,6 +555,8 @@ function cmake.substitute_path(path, vars)
   return path
 end
 
+---@param target string
+---@return string
 function cmake.get_launch_path(target)
   local model = config:get_code_model_info()[target]
   local result = config:get_launch_target_from_info(model)
@@ -562,6 +582,8 @@ function cmake.get_launch_path(target)
 end
 
 -- Run executable targets
+---@param opt cmake.CommandOpts
+---@param callback? fun(result: cmake.Result)
 function cmake.run(opt, callback)
   callback = callback or function() end
   if check_active_job_and_notify(callback) then
@@ -646,6 +668,8 @@ function cmake.run(opt, callback)
   end
 end
 
+---@param opt vim.api.keyset.create_user_command.command_args
+---@param callback? fun(result: cmake.Result)
 function cmake.quick_run(opt, callback)
   callback = callback or function() end
   -- if no target was supplied, query via ui select
@@ -688,6 +712,7 @@ function cmake.quick_run(opt, callback)
 end
 
 -- Set args for launch target
+---@param opt vim.api.keyset.create_user_command.command_args
 function cmake.launch_args(opt)
   if utils.has_active_job(config.runner, config.executor) then
     return
@@ -702,6 +727,7 @@ function cmake.launch_args(opt)
   end
 end
 
+---@param callback? fun(result: cmake.Result)
 function cmake.select_build_type(callback)
   callback = type(callback) == "function" and callback
     or function(result)
@@ -746,6 +772,7 @@ function cmake.select_build_type(callback)
   )
 end
 
+---@param callback? fun(result: cmake.Result)
 function cmake.select_kit(callback)
   callback = type(callback) == "function" and callback
     or function(result)
@@ -791,6 +818,7 @@ function cmake.select_kit(callback)
   end
 end
 
+---@param callback? fun(result: cmake.Result)
 function cmake.select_configure_preset(callback)
   callback = type(callback) == "function" and callback
     or function(result)
@@ -840,6 +868,7 @@ function cmake.select_configure_preset(callback)
   end
 end
 
+---@param callback? fun(result: cmake.Result)
 function cmake.select_test_preset(callback)
   callback = type(callback) == "function" and callback
     or function(result)
@@ -888,6 +917,7 @@ function cmake.select_test_preset(callback)
   end
 end
 
+---@param callback? fun(result: cmake.Result)
 function cmake.select_build_preset(callback)
   callback = type(callback) == "function" and callback
     or function(result)
@@ -955,6 +985,8 @@ function cmake.select_build_preset(callback)
   end
 end
 
+---@param regenerate boolean
+---@param callback? fun(result: cmake.Result)
 function cmake.select_build_target(regenerate, callback)
   callback = type(callback) == "function" and callback or function(_) end
   if not (config:has_build_directory()) then
@@ -1000,6 +1032,7 @@ function cmake.select_build_target(regenerate, callback)
   )
 end
 
+---@param callback? fun(result: cmake.Result)
 function cmake.get_cmake_launch_targets(callback)
   callback = callback or function() end
   if not (config:has_build_directory()) then
@@ -1016,6 +1049,8 @@ function cmake.get_cmake_launch_targets(callback)
   callback(config:launch_targets())
 end
 
+---@param regenerate boolean
+---@param callback? fun(result: cmake.Result)
 function cmake.select_launch_target(regenerate, callback)
   callback = callback or function() end
   if not (config:has_build_directory()) then
@@ -1060,7 +1095,9 @@ function cmake.select_launch_target(regenerate, callback)
   )
 end
 
+---@return cmake.BaseVars
 function cmake.get_base_vars()
+  ---@class cmake.BaseVars
   local vars = { dir = {} }
 
   vars.dir.build = config:build_directory_path() .. "/"
@@ -1068,6 +1105,9 @@ function cmake.get_base_vars()
   return vars
 end
 
+---@param str string
+---@return boolean ok
+---@return table? value
 local function convert_to_table(str)
   -- do a roundtrip. this should remove unsupported stuff like function() which vim.inspect cannot convert
   local fn = loadstring(str)
@@ -1090,6 +1130,8 @@ local function convert_to_table(str)
   end
 end
 
+---@param target string
+---@return cmake.BaseVars?
 function cmake.get_target_vars(target)
   local vars = cmake.get_base_vars()
 
@@ -1148,6 +1190,7 @@ function cmake.settings()
   end
 end
 
+---@param opt vim.api.keyset.create_user_command.command_args
 function cmake.target_settings(opt)
   if utils.has_active_job(config.runner, config.executor) then
     return
@@ -1197,6 +1240,8 @@ function cmake.target_settings(opt)
   end
 end
 
+---@param opt vim.api.keyset.create_user_command.command_args
+---@param callback? fun(result: cmake.Result)
 function cmake.run_test(opt, callback)
   callback = callback or function() end
   if utils.has_active_job(config.runner, config.executor) then
@@ -1299,6 +1344,7 @@ function cmake.run_test(opt, callback)
   end)
 end
 
+---@param opt vim.api.keyset.create_user_command.command_args
 function cmake.run_current_file(opt)
   local targets = {}
   local display_targets = {}
@@ -1330,6 +1376,7 @@ function cmake.run_current_file(opt)
   end
 end
 
+---@param opt vim.api.keyset.create_user_command.command_args
 function cmake.build_current_file(opt)
   local targets = {}
   local display_targets = {}
@@ -1361,34 +1408,41 @@ function cmake.build_current_file(opt)
 end
 
 --[[ Getters ]]
+---@return Config
 function cmake.get_config()
   return config
 end
 
+---@return string[]?
 function cmake.get_build_target()
   return config.build_target
 end
 
+---@return string?
 function cmake.get_build_target_path()
   local result = config:get_build_target()
   local target_path = result.data
   return target_path
 end
 
+---@return string?
 function cmake.get_launch_target()
   return config.launch_target
 end
 
+---@return string?
 function cmake.get_launch_target_path()
   local result = config:get_launch_target()
   local target_path = result.data
   return target_path
 end
 
+---@return table?
 function cmake.get_model_info()
   return config:get_code_model_info()
 end
 
+---@return string[]
 function cmake.get_launch_args()
   if cmake.get_launch_target() == nil then
     return {}
@@ -1403,10 +1457,13 @@ function cmake.get_launch_args()
   return {}
 end
 
+---@return table<string, string>
 function cmake.get_build_environment()
   return environment.get_build_environment_table(config)
 end
 
+---@param target? string
+---@return table<string, string>
 function cmake.get_run_environment(target)
   return environment.get_run_environment_table(
     config,
@@ -1414,51 +1471,63 @@ function cmake.get_run_environment(target)
   )
 end
 
+---@return string?
 function cmake.get_build_type()
   return config.build_type
 end
 
+---@return string?
 function cmake.get_kit()
   return config.kit
 end
 
+---@return string?
 function cmake.get_configure_preset()
   return config.configure_preset
 end
 
+---@return string?
 function cmake.get_build_preset()
   return config.build_preset
 end
 
+---@return string?
 function cmake.get_test_preset()
   return config.test_preset
 end
 
+---@return Path?
 function cmake.get_build_directory()
   return config.build_directory
 end
 
+---@return boolean
 function cmake.is_cmake_project()
   local result = utils.get_cmake_configuration(config.cwd)
   return result.code == Types.SUCCESS
 end
 
+---@return boolean
 function cmake.has_cmake_preset()
   return Presets.exists(config.cwd)
 end
 
+---@return cmake.Result
 function cmake.get_build_targets()
   return config:build_targets()
 end
 
+---@return cmake.Result
 function cmake.get_launch_targets()
   return config:launch_targets()
 end
 
+---@return string[]
 function cmake.get_generate_options()
   return config:generate_options()
 end
 
+---@return string[]
 function cmake.get_build_options()
   return config:build_options()
 end
@@ -1521,6 +1590,7 @@ function cmake.compile_commands_from_lsp()
   vim.api.nvim_set_current_buf(buf)
 end
 
+---@param new_config table
 function cmake.clangd_on_new_config(new_config)
   const.lsp_type = "clangd"
 
@@ -1533,12 +1603,14 @@ function cmake.clangd_on_new_config(new_config)
   table.insert(new_config.cmd, arg)
 end
 
+---@param new_config table
 function cmake.ccls_on_new_config(new_config)
   const.lsp_type = "ccls"
 
   new_config.init_options.compilationDatabaseDirectory = config:build_directory_path()
 end
 
+---@param cwd_path vim.api.keyset.create_user_command.command_args
 function cmake.select_cwd(cwd_path)
   if cwd_path.args == "" then
     vim.ui.input(
@@ -1570,6 +1642,7 @@ function cmake.select_cwd(cwd_path)
   end
 end
 
+---@param cwd_path vim.api.keyset.create_user_command.command_args|{ args: string }
 function cmake.select_build_dir(cwd_path)
   if cwd_path.args == "" then
     vim.ui.input(
@@ -1757,6 +1830,8 @@ function cmake.register_autocmd_provided_by_users()
   end
 end
 
+---@param executor string
+---@param runner string
 function cmake.register_scratch_buffer(executor, runner)
   if cmake.is_cmake_project() and const.cmake_use_scratch_buffer then
     vim.schedule(function()
@@ -1769,6 +1844,8 @@ function cmake.register_dap_function()
   local has_nvim_dap, dap = pcall(require, "dap")
   if has_nvim_dap then
     -- Debug execuable targets
+    ---@param opt cmake.CommandOpts
+    ---@param callback? fun(result: cmake.Result)
     function cmake.debug(opt, callback)
       if utils.has_active_job(config.runner, config.executor) then
         return
@@ -1875,6 +1952,8 @@ function cmake.register_dap_function()
       end
     end
 
+    ---@param opt vim.api.keyset.create_user_command.command_args
+    ---@param callback? fun(result: cmake.Result)
     function cmake.quick_debug(opt, callback)
       -- if no target was supplied, query via ui select
       if opt.fargs[1] == nil then
@@ -1908,6 +1987,7 @@ function cmake.register_dap_function()
       end
     end
 
+    ---@param opt vim.api.keyset.create_user_command.command_args
     function cmake.debug_current_file(opt)
       local targets = {}
       local display_targets = {}
@@ -1972,6 +2052,7 @@ function cmake.register_telescope_function()
   if has_telescope then
     telescope.load_extension("cmake_tools")
 
+    ---@param opt vim.api.keyset.create_user_command.command_args
     function cmake.show_target_files(opt)
       -- if no target was supplied, query via ui select
       if opt.fargs[1] == nil then

From a9efa3c04b374d229f31ff824ce9ddc846b5e9da Mon Sep 17 00:00:00 2001
From: Denzel <>
Date: Mon, 30 Mar 2026 20:12:31 +0200
Subject: [PATCH 3/3] fix(init): only run debug when build succeeded

---
 lua/cmake-tools/init.lua | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/lua/cmake-tools/init.lua b/lua/cmake-tools/init.lua
index ff799d2..08a1cb9 100644
--- a/lua/cmake-tools/init.lua
+++ b/lua/cmake-tools/init.lua
@@ -1890,7 +1890,10 @@ function cmake.register_dap_function()
 
       if opt.target then
         -- explicit target requested. use that instead of the configured one
-        return cmake.build({ target = opt.target }, function()
+        return cmake.build({ target = opt.target }, function(build_result)
+          if not build_result:is_ok() then
+            return
+          end
           local model = config:get_code_model_info()[opt.target]
           local result = config:get_launch_target_from_info(model)
           local dap_config = {
@@ -1932,7 +1935,10 @@ function cmake.register_dap_function()
           -- Build select launch target every time
           return cmake.build(
             { target = config.launch_target, fargs = utils.deepcopy(opt.fargs) },
-            function()
+            function(build_result)
+              if not build_result:is_ok() then
+                return
+              end
               result = config:get_launch_target()
               local target_path = result.data
               local dap_config = {