diff options
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 127 |
1 files changed, 127 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..baf5881 --- /dev/null +++ b/README.md | |||
@@ -0,0 +1,127 @@ | |||
1 | # Neovim Tasks | ||
2 | |||
3 | A Neovim 0.7+ plugin that provides a statefull task system focused on integration with build systems. | ||
4 | |||
5 | Tasks in this plugin are provided by modules that implement functionality for a specific build system. Modules can have custom parameters which user can set via `:Task set_module_param` (like current target or build type). Tasks consists of one or more commands and have `args` and `env` parameters to set arguments and environment variable respectively. All this settings are serializable and will be stored in configuration file in your project directory. | ||
6 | |||
7 | ## Dependencies | ||
8 | |||
9 | - Necessary | ||
10 | - [plenary.nvim](https://github.com/nvim-lua/plenary.nvim) for internal helpers. | ||
11 | - Optional | ||
12 | - [nvim-dap](https://github.com/mfussenegger/nvim-dap) - for debugging. | ||
13 | |||
14 | ## Features | ||
15 | |||
16 | - Output directly into quickfix for fast navigation. | ||
17 | - Tasks provided by modules which can have custom parameters. | ||
18 | - Modules are lazy loaded. | ||
19 | - Module for a task name could be determined automatically based on its condition. | ||
20 | - Tasks can run through debugger. | ||
21 | - Tasks can be chained and react on the previous output. | ||
22 | - Task and module parameters are serializable and specific to the current working directly. | ||
23 | - Tasks arguments could be read from parameters and / or extended via additional temporary arguments passed to `:Task` command. | ||
24 | |||
25 | ## Available modules | ||
26 | |||
27 | - [CMake](https://cmake.org) via [cmake-file-api](https://cmake.org/cmake/help/latest/manual/cmake-file-api.7.html#codemodel-version-2). | ||
28 | - [Cargo](https://doc.rust-lang.org/cargo). | ||
29 | |||
30 | You can also write [your own module](#modules-creation-and-configuration). | ||
31 | |||
32 | ## Commands | ||
33 | |||
34 | Use the command `:Task` with one of the following arguments: | ||
35 | |||
36 | | Argument(s) | Description | | ||
37 | | ---------------------------------------- | ---------------------------------------------------------------------------- | | ||
38 | | `start <module> <task>` | Starting a task from a module. | | ||
39 | | `set_module_param <module> <param>` | Set parameter for a module. All parameters are module-specific. | | ||
40 | | `set_task_param <module> <param> <task>` | Set parameter for a task from a module. The parameter can be `arg` or `env`. | | ||
41 | | `cancel` | Cancel currently running task. | | ||
42 | |||
43 | Modules and tasks will be autocompleted. | ||
44 | |||
45 | Module name can be `auto`, in which case the first module that satisfies the condition will be used. | ||
46 | |||
47 | ## Configuration | ||
48 | |||
49 | To configure the plugin, you can call `require('tasks').setup(values)`, where `values` is a dictionary with the parameters you want to override. Here are the defaults: | ||
50 | |||
51 | ```lua | ||
52 | local Path = require('plenary.path') | ||
53 | require('tasks').setup({ | ||
54 | default_params = { -- Default module parameters with which `neovim.json` will be created. | ||
55 | cmake = { | ||
56 | cmd = 'cmake', -- CMake executable to use, can be changed using `:Task set_module_param cmake cmd`. | ||
57 | build_dir = tostring(Path:new('{cwd}', 'build', '{os}-{build_type}')), -- Build directory. The expressions `{cwd}`, `{os}` and `{build_type}` will be expanded with the corresponding text values. Could be a function that return the path to the build directory. | ||
58 | build_type = 'Debug', -- Build type, can be changed using `:Task set_module_param cmake build_type`. | ||
59 | dap_name = 'lldb', -- DAP configuration name from `require('dap').configurations`. If there is no such configuration, a new one with this name as `type` will be created. | ||
60 | args = { -- Task default arguments. | ||
61 | configure = { '-D', 'CMAKE_EXPORT_COMPILE_COMMANDS=1', '-G', 'Ninja' }, | ||
62 | }, | ||
63 | }, | ||
64 | }, | ||
65 | save_before_run = true, -- If true, all files will be saved before executing a task. | ||
66 | params_file = 'neovim.json', -- JSON file to store module and task parameters. | ||
67 | quickfix = { | ||
68 | pos = 'botright', -- Default quickfix position. | ||
69 | height = 12, -- Default height. | ||
70 | }, | ||
71 | dap_open_command = function() return require('dap').repl.open() end, -- Command to run after starting DAP session. You can set it to `false` if you don't want to open anything or `require('dapui').open` if you are using https://github.com/rcarriga/nvim-dap-ui | ||
72 | ``` | ||
73 | |||
74 | ## Usage examples | ||
75 | |||
76 | ### CMake | ||
77 | |||
78 | 1. Open a CMake project. | ||
79 | 2. Run `configuration` task using `:Task start cmake configure`. | ||
80 | 3. Select a target by specifying module parameter with `:Task set_module_param cmake target`. All module parameters are specific to modules. Since CMake can't run targets like Cargo, we introduced a parameter to select the same target for building (appropriate arguments will be passed to CMake automatically) and running. | ||
81 | 4. Optionally set arguments using `:Task set_task_param cmake run`. | ||
82 | 5. Build and run the project via `:Task start cmake run` or build and debug using `:Task start cmake debug`. You can pass additional arguments to these commands, which will be temporarily added to the arguments from the previous step. | ||
83 | |||
84 | ### Cargo | ||
85 | |||
86 | 1. Open a Cargo project. | ||
87 | 2. Optionally set arguments using `:Task set_task_param cargo run`. | ||
88 | 3. Optionally set global cargo arguments using `:Task set_task_param cargo global_cargo_args`. | ||
89 | 4. Build and run the project via `:Task start cargo run` or build and debug using `:Task start cargo debug`. | ||
90 | |||
91 | Cargo module doesn't have a `target` param which specific to CMake because `cargo run` automatically pick the binary. If there is multiple binaries, you can set which one you want to run using `--bin` or `--project` in step 2 as you do in CLI. | ||
92 | |||
93 | ## Modules creation and configuration | ||
94 | |||
95 | To create a module just put a lua file under `lua/tasks/modules` in your configuration or submit your module as a PR. In this module you need to return a table with the following fields: | ||
96 | |||
97 | ```lua | ||
98 | { | ||
99 | params = { | ||
100 | -- A table of parameter names. Possible values: | ||
101 | 'parameter_name1', -- A string parameter, on setting user will be prompted with vim.ui.input. | ||
102 | parameter_name2 = { 'one', 'two' }, -- A table with possible balues, on setting user will be promted with vim.ui.select to pick one of these values. | ||
103 | parameter_name3 = func, -- A function that generates a string or a table. | ||
104 | } | ||
105 | condition = function() return Path:new('file'):exists() end -- A function that returns `true` if this module could be applied to this directory. Used when `auto` is used as module name. | ||
106 | tasks = { | ||
107 | -- A table of module tasks. Possible values: | ||
108 | task_name1 = { | ||
109 | -- Required parameters: | ||
110 | cmd = 'command' -- Command to execute. | ||
111 | -- Optional parameters: | ||
112 | cwd = 'directory' -- Command working directory. Default to current working directory. | ||
113 | after_success = callback -- A callback to execute on success. | ||
114 | dap_name = 'dap_name' -- A debug adapter name. If exists, the task will be launched through the adapter. Usually taken from a module parameter. Implies ignoring all streams below. | ||
115 | -- Disable a stream output to quickfix. If both are disabled, quickfix will not show up. If you want to capture output of a stream in a next task, you need to disable it. | ||
116 | ignore_stdout = true, | ||
117 | ignore_stderr = true, | ||
118 | }, | ||
119 | task_name2 = func1, -- A function that returns a table as above. Accepts configuration for this module and previous job. | ||
120 | task_name3 = { func2, func3 }, -- A list of functions as above. Tasks will be executed in chain. | ||
121 | } | ||
122 | } | ||
123 | ``` | ||
124 | |||
125 | For a more complex example take a look at [cargo.lua](lua/tasks/module/cargo.lua). | ||
126 | |||
127 | You can also edit existing modules in right in your config. Just import a module using `require('tasks.modules.module_name')` and add/remove/modify any fields from the above. | ||