diff options
| -rw-r--r-- | CONTRIBUTING.md | 104 | ||||
| -rw-r--r-- | runtime/autoload/python3complete.vim | 2 | ||||
| -rw-r--r-- | runtime/autoload/pythoncomplete.vim | 2 | ||||
| -rw-r--r-- | runtime/doc/eval.txt | 19 | ||||
| -rw-r--r-- | runtime/doc/nvim_terminal_emulator.txt | 2 | ||||
| -rw-r--r-- | runtime/doc/options.txt | 2 | ||||
| -rw-r--r-- | runtime/doc/provider.txt | 12 | ||||
| -rwxr-xr-x | src/clint.py | 17 | ||||
| -rw-r--r-- | src/nvim/eval.c | 8 | ||||
| -rw-r--r-- | test/README.md | 137 |
10 files changed, 171 insertions, 134 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 630324e289..607f1aae83 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,5 @@ -# Contributing to Neovim +Contributing to Neovim +====================== Getting started --------------- @@ -11,6 +12,18 @@ low-risk/isolated tasks: - Fix bugs found by [Clang](#clang-scan-build), [PVS](#pvs-studio) or [Coverity](#coverity). +Reporting problems +------------------ + +- [Check the FAQ][wiki-faq]. +- [Search existing issues][github-issues] (including closed!) +- Update Neovim to the latest version to see if your problem persists. +- Disable plugins incrementally, to narrow down the cause of the issue. +- When reporting a crash, [include a stacktrace](https://github.com/neovim/neovim/wiki/FAQ#backtrace-linux). +- [Bisect][git-bisect] to the cause of a regression, if you are able. This is _extremely_ helpful. +- Check `$NVIM_LOG_FILE`, if it exists. +- Include `cmake --system-information` for build-related issues. + Developer guidelines -------------------- @@ -24,18 +37,6 @@ Developer guidelines make # Nvim build system uses ninja automatically, if available. ``` -Reporting problems ------------------- - -- [Check the FAQ][wiki-faq]. -- [Search existing issues][github-issues] (including closed!) -- Update Neovim to the latest version to see if your problem persists. -- Disable plugins incrementally, to narrow down the cause of the issue. -- When reporting a crash, [include a stacktrace](https://github.com/neovim/neovim/wiki/Development-tips#backtrace-linux). -- [Bisect][git-bisect] to the cause of a regression, if you are able. This is _extremely_ helpful. -- Check `$NVIM_LOG_FILE`, if it exists. -- Include `cmake --system-information` for build-related issues. - Pull requests (PRs) --------------------- @@ -64,20 +65,10 @@ Pull requests (PRs) Pull requests have three stages: `[WIP]` (Work In Progress), `[RFC]` (Request For Comment) and `[RDY]` (Ready). -- Untagged PRs are assumed to be `[RFC]`, i.e. you are requesting a review. -- Prepend `[WIP]` to the PR title if you are _not_ requesting feedback and the - work is still in flux. -- Prepend `[RDY]` to the PR title if you are _done_ with the PR and are only - waiting on it to be merged. - -For example, a typical workflow is: - -1. You open a `[WIP]` PR where the work is _not_ ready for feedback, you just want to - let others know what you are doing. -2. Once the PR is ready for review, you replace `[WIP]` in the title with `[RFC]`. - You may add fix up commits to address issues that come up during review. -3. Once the PR is ready for merging, you rebase/squash your work appropriately and - then replace `[RFC]` in the title with `[RDY]`. +- `[RFC]` is assumed by default, i.e. you are requesting a review. +- Add `[WIP]` to the PR title if you are _not_ requesting feedback and the work + is still in flux. +- Add `[RDY]` if you are _done_ and only waiting on merge. ### Commit messages @@ -106,19 +97,18 @@ and [AppVeyor]. - CI runs [ASan] and other analyzers. - To run valgrind locally: `VALGRIND=1 make test` - To run Clang ASan/UBSan locally: `CC=clang make CMAKE_FLAGS="-DCLANG_ASAN_UBSAN=ON"` -- The `lint` build ([#3174][3174]) checks modified lines _and their immediate - neighbors_. This is to encourage incrementally updating the legacy style to - meet our style guidelines. +- The [lint](#lint) build checks modified lines _and their immediate + neighbors_, to encourage incrementally updating the legacy style to meet our + [style](#style). (See [#3174][3174] for background.) - [How to investigate QuickBuild failures](https://github.com/neovim/neovim/pull/4718#issuecomment-217631350) - -QuickBuild uses this invocation: - - mkdir -p build/${params.get("buildType")} \ - && cd build/${params.get("buildType")} \ - && cmake -G "Unix Makefiles" -DBUSTED_OUTPUT_TYPE=TAP -DCMAKE_BUILD_TYPE=${params.get("buildType")} - -DTRAVIS_CI_BUILD=ON ../.. && ${node.getAttribute("make", "make")} - VERBOSE=1 nvim unittest-prereqs functionaltest-prereqs - + - QuickBuild uses this invocation: + ``` + mkdir -p build/${params.get("buildType")} \ + && cd build/${params.get("buildType")} \ + && cmake -G "Unix Makefiles" -DBUSTED_OUTPUT_TYPE=TAP -DCMAKE_BUILD_TYPE=${params.get("buildType")} + -DTRAVIS_CI_BUILD=ON ../.. && ${node.getAttribute("make", "make")} + VERBOSE=1 nvim unittest-prereqs functionaltest-prereqs + ``` ### Clang scan-build @@ -165,6 +155,41 @@ master build. To view the defects, just request access; you will be approved. git log --oneline --no-merges --grep coverity ``` + +Coding +------ + +### Lint + +You can run the linter locally by: + + make lint + +The lint step downloads the [master error list] and excludes them, so only lint +errors related to the local changes are reported. + +You can lint a single file (but this will _not_ exclude legacy errors): + + ./src/clint.py src/nvim/ops.c + +### Style + +The repo includes a `.clang-format` config file which (mostly) matches the +[style-guide]. You can use `clang-format` to format code with the `gq` +operator in Nvim: + + if !empty(findfile('.clang-format', ';')) + setlocal formatprg=clang-format\ -style=file + endif + +### Navigate + +- Use **[universal-ctags](https://github.com/universal-ctags/ctags).** + ("Exuberant ctags", the typical `ctags` binary provided by your distro, is + unmaintained and won't recognize many function signatures in Neovim source.) +- Explore the source code [on the web](https://sourcegraph.com/github.com/neovim/neovim). + + Reviewing --------- @@ -203,3 +228,4 @@ as context, use the `-W` argument as well. [Merge a Vim patch]: https://github.com/neovim/neovim/wiki/Merging-patches-from-upstream-Vim [Clang report]: https://neovim.io/doc/reports/clang/ [complexity:low]: https://github.com/neovim/neovim/issues?q=is%3Aopen+is%3Aissue+label%3Acomplexity%3Alow +[master error list]: https://raw.githubusercontent.com/neovim/doc/gh-pages/reports/clint/errors.json diff --git a/runtime/autoload/python3complete.vim b/runtime/autoload/python3complete.vim index f0f3aaddb3..a3b057d4d0 100644 --- a/runtime/autoload/python3complete.vim +++ b/runtime/autoload/python3complete.vim @@ -44,7 +44,7 @@ " if !has('python3') - echo "Error: Required vim compiled with +python3" + echo 'Error: Requires python3 + pynvim. :help provider-python' finish endif diff --git a/runtime/autoload/pythoncomplete.vim b/runtime/autoload/pythoncomplete.vim index ecc36646d9..9cc0ae0d79 100644 --- a/runtime/autoload/pythoncomplete.vim +++ b/runtime/autoload/pythoncomplete.vim @@ -42,7 +42,7 @@ " if !has('python') - echo "Error: Required vim compiled with +python" + echo 'Error: Requires python + pynvim. :help provider-python' finish endif diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index 06af04bf63..01bd2a0c65 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -5351,10 +5351,11 @@ jobwait({ids}[, {timeout}]) *jobwait()* Wait for a set of jobs to complete. {ids} is a list of |job-id|s to wait for. - {timeout} is the maximum number of milliseconds to wait. + {timeout} is the maximum waiting time in milliseconds, -1 + means forever. - Use zero {timeout} to check the status of a job: > - let exited = jobwait([{job-id}], 0)[0] >= 0 + Timeout of 0 can be used to check the status of a job: > + let running = jobwait([{job-id}], 0)[0] == -1 < During jobwait() callbacks for jobs not in the {ids} list may be invoked. The screen will not redraw unless |:redraw| is @@ -8572,13 +8573,10 @@ timer_start({time}, {callback} [, {options}]) waiting for input. {options} is a dictionary. Supported entries: - "repeat" Number of times to repeat calling the - callback. -1 means forever. When not present - the callback will be called once. + "repeat" Number of times to repeat the callback. + -1 means forever. Default is 1. If the timer causes an error three times in a - row the repeat is cancelled. This avoids that - Vim becomes unusable because of all the error - messages. + row the repeat is cancelled. Example: > func MyHandler(timer) @@ -8586,8 +8584,7 @@ timer_start({time}, {callback} [, {options}]) endfunc let timer = timer_start(500, 'MyHandler', \ {'repeat': 3}) -< This will invoke MyHandler() three times at 500 msec - intervals. +< This invokes MyHandler() three times at 500 msec intervals. timer_stop({timer}) *timer_stop()* Stop a timer. The timer callback will no longer be invoked. diff --git a/runtime/doc/nvim_terminal_emulator.txt b/runtime/doc/nvim_terminal_emulator.txt index 983d04b3bf..d1831a8de6 100644 --- a/runtime/doc/nvim_terminal_emulator.txt +++ b/runtime/doc/nvim_terminal_emulator.txt @@ -129,7 +129,7 @@ Example: > input to the terminal. Use |jobwait()| to check if the terminal job has finished: > - let exited = jobwait([&channel], 0)[0] >= 0 + let running = jobwait([&channel], 0)[0] == -1 ============================================================================== :Termdebug plugin *terminal-debug* diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index 8fc8a04df3..84e08ae04b 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -3210,7 +3210,7 @@ A jump table for the options with a short description can be found at |Q_op|. so far, matches. The matched string is highlighted. If the pattern is invalid or not found, nothing is shown. The screen will be updated often, this is only useful on fast terminals. -< Note that the match will be shown, but the cursor will return to its + Note that the match will be shown, but the cursor will return to its original position when no match is found and when pressing <Esc>. You still need to finish the search command with <Enter> to move the cursor to the match. diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt index 364fbac351..594c9602f4 100644 --- a/runtime/doc/provider.txt +++ b/runtime/doc/provider.txt @@ -57,14 +57,14 @@ If you run into problems, uninstall _both_ then install "pynvim" again: > PYTHON PROVIDER CONFIGURATION ~ *g:python_host_prog* -Path to Python 2 interpreter. Setting this makes startup faster. Also useful -for working with virtualenvs. > - let g:python_host_prog = '/path/to/python' " Python 2 +Command to start Python 2 (executable, not directory). Setting this makes +startup faster. Useful for working with virtualenvs. > + let g:python_host_prog = '/path/to/python' < *g:python3_host_prog* -Path to Python 3 interpreter. Setting this makes startup faster. Also useful -for working with virtualenvs. > - let g:python3_host_prog = '/path/to/python3' " Python 3 +Command to start Python 3 (executable, not directory). Setting this makes +startup faster. Useful for working with virtualenvs. > + let g:python3_host_prog = '/path/to/python3' < *g:loaded_python_provider* To disable Python 2 support: > diff --git a/src/clint.py b/src/clint.py index 862fdbc06b..719142d523 100755 --- a/src/clint.py +++ b/src/clint.py @@ -7,15 +7,14 @@ # modification, are permitted provided that the following conditions are # met: # -# * Redistributions of source code must retain the above copyright -# notice, this list of conditions and the following disclaimer. -# * Redistributions in binary form must reproduce the above -# copyright notice, this list of conditions and the following disclaimer -# in the documentation and/or other materials provided with the -# distribution. -# * Neither the name of Google Inc. nor the names of its -# contributors may be used to endorse or promote products derived from -# this software without specific prior written permission. +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright +# notice, this list of conditions and the following disclaimer in the +# documentation and/or other materials provided with the distribution. +# * Neither the name of Google Inc. nor the names of its contributors may be +# used to endorse or promote products derived from this software without +# specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT diff --git a/src/nvim/eval.c b/src/nvim/eval.c index 2dc6a287a1..aa79d4ce5f 100644 --- a/src/nvim/eval.c +++ b/src/nvim/eval.c @@ -12076,6 +12076,14 @@ static void f_jobresize(typval_T *argvars, typval_T *rettv, FunPtr fptr) rettv->vval.v_number = 1; } +/// Builds a process argument vector from a VimL object (typval_T). +/// +/// @param[in] cmd_tv VimL object +/// @param[out] cmd Returns the command or executable name. +/// @param[out] executable Returns `false` if argv[0] is not executable. +/// +/// @returns Result of `shell_build_argv()` if `cmd_tv` is a String. +/// Else, string values of `cmd_tv` copied to a (char **) list. static char **tv_to_argv(typval_T *cmd_tv, const char **cmd, bool *executable) { if (cmd_tv->v_type == VAR_STRING) { diff --git a/test/README.md b/test/README.md index 903e93e495..73d51c995c 100644 --- a/test/README.md +++ b/test/README.md @@ -26,7 +26,7 @@ available in this version` errors. - [Running tests](#running-tests) - [Writing tests](#writing-tests) - [Lint](#lint) -- [Environment variables](#environment-variables) +- [Configuration](#configuration) --- @@ -246,95 +246,102 @@ Ignore the smallest applicable scope (e.g. inside a function, not at the top of the file). -Environment variables -===================== +Configuration +============= + +busted (luassert) by default does not print the full result of deeply-nested +tables. But sometimes it's useful while debugging a test. + + assert:set_parameter('TableFormatLevel', 1000000) Test behaviour is affected by environment variables. Currently supported (Functional, Unit, Benchmarks) (when Defined; when set to _1_; when defined, treated as Integer; when defined, treated as String; when defined, treated as Number; !must be defined to function properly): -`GDB` (F) (D): makes nvim instances to be run under `gdbserver`. It will be -accessible on `localhost:7777`: use `gdb build/bin/nvim`, type `target remote -:7777` inside. +- `GDB` (F) (D): makes nvim instances to be run under `gdbserver`. It will be + accessible on `localhost:7777`: use `gdb build/bin/nvim`, type `target remote + :7777` inside. -`GDBSERVER_PORT` (F) (I): overrides port used for `GDB`. +- `GDBSERVER_PORT` (F) (I): overrides port used for `GDB`. -`VALGRIND` (F) (D): makes nvim instances to be run under `valgrind`. Log files -are named `valgrind-%p.log` in this case. Note that non-empty valgrind log may -fail tests. Valgrind arguments may be seen in `/test/functional/helpers.lua`. -May be used in conjunction with `GDB`. +- `VALGRIND` (F) (D): makes nvim instances to be run under `valgrind`. Log + files are named `valgrind-%p.log` in this case. Note that non-empty valgrind + log may fail tests. Valgrind arguments may be seen in + `/test/functional/helpers.lua`. May be used in conjunction with `GDB`. -`VALGRIND_LOG` (F) (S): overrides valgrind log file name used for `VALGRIND`. +- `VALGRIND_LOG` (F) (S): overrides valgrind log file name used for `VALGRIND`. -`TEST_SKIP_FRAGILE` (F) (D): makes test suite skip some fragile tests. +- `TEST_SKIP_FRAGILE` (F) (D): makes test suite skip some fragile tests. -`NVIM_PROG`, `NVIM_PRG` (F) (S): override path to Neovim executable (default to -`build/bin/nvim`). +- `NVIM_PROG`, `NVIM_PRG` (F) (S): override path to Neovim executable (default + to `build/bin/nvim`). -`CC` (U) (S): specifies which C compiler to use to preprocess files. Currently -only compilers with gcc-compatible arguments are supported. +- `CC` (U) (S): specifies which C compiler to use to preprocess files. + Currently only compilers with gcc-compatible arguments are supported. -`NVIM_TEST_MAIN_CDEFS` (U) (1): makes `ffi.cdef` run in main process. This -raises a possibility of bugs due to conflicts in header definitions, despite the -counters, but greatly speeds up unit tests by not requiring `ffi.cdef` to do -parsing of big strings with C definitions. +- `NVIM_TEST_MAIN_CDEFS` (U) (1): makes `ffi.cdef` run in main process. This + raises a possibility of bugs due to conflicts in header definitions, despite + the counters, but greatly speeds up unit tests by not requiring `ffi.cdef` to + do parsing of big strings with C definitions. -`NVIM_TEST_PRINT_I` (U) (1): makes `cimport` print preprocessed, but not yet -filtered through `formatc` headers. Used to debug `formatc`. Printing is done -with the line numbers. +- `NVIM_TEST_PRINT_I` (U) (1): makes `cimport` print preprocessed, but not yet + filtered through `formatc` headers. Used to debug `formatc`. Printing is done + with the line numbers. -`NVIM_TEST_PRINT_CDEF` (U) (1): makes `cimport` print final lines which will be -then passed to `ffi.cdef`. Used to debug errors `ffi.cdef` happens to throw -sometimes. +- `NVIM_TEST_PRINT_CDEF` (U) (1): makes `cimport` print final lines which will + be then passed to `ffi.cdef`. Used to debug errors `ffi.cdef` happens to + throw sometimes. -`NVIM_TEST_PRINT_SYSCALLS` (U) (1): makes it print to stderr when syscall -wrappers are called and what they returned. Used to debug code which makes unit -tests be executed in separate processes. +- `NVIM_TEST_PRINT_SYSCALLS` (U) (1): makes it print to stderr when syscall + wrappers are called and what they returned. Used to debug code which makes + unit tests be executed in separate processes. -`NVIM_TEST_RUN_FAILING_TESTS` (U) (1): makes `itp` run tests which are known to -fail (marked by setting third argument to `true`). +- `NVIM_TEST_RUN_FAILING_TESTS` (U) (1): makes `itp` run tests which are known + to fail (marked by setting third argument to `true`). -`LOG_DIR` (FU) (S!): specifies where to seek for valgrind and ASAN log files. +- `LOG_DIR` (FU) (S!): specifies where to seek for valgrind and ASAN log files. -`NVIM_TEST_CORE_*` (FU) (S): a set of environment variables which specify where -to search for core files. Are supposed to be defined all at once. +- `NVIM_TEST_CORE_*` (FU) (S): a set of environment variables which specify + where to search for core files. Are supposed to be defined all at once. -`NVIM_TEST_CORE_GLOB_DIRECTORY` (FU) (S): directory where core files are -located. May be `.`. This directory is then recursively searched for core files. -Note: this variable must be defined for any of the following to have any effect. +- `NVIM_TEST_CORE_GLOB_DIRECTORY` (FU) (S): directory where core files are + located. May be `.`. This directory is then recursively searched for core + files. Note: this variable must be defined for any of the following to have + any effect. -`NVIM_TEST_CORE_GLOB_RE` (FU) (S): regular expression which must be matched by -core files. E.g. `/core[^/]*$`. May be absent, in which case any file is -considered to be matched. +- `NVIM_TEST_CORE_GLOB_RE` (FU) (S): regular expression which must be matched + by core files. E.g. `/core[^/]*$`. May be absent, in which case any file is + considered to be matched. -`NVIM_TEST_CORE_EXC_RE` (FU) (S): regular expression which excludes certain -directories from searching for core files inside. E.g. use `^/%.deps$` to not -search inside `/.deps`. If absent, nothing is excluded. +- `NVIM_TEST_CORE_EXC_RE` (FU) (S): regular expression which excludes certain + directories from searching for core files inside. E.g. use `^/%.deps$` to not + search inside `/.deps`. If absent, nothing is excluded. -`NVIM_TEST_CORE_DB_CMD` (FU) (S): command to get backtrace out of the debugger. -E.g. `gdb -n -batch -ex "thread apply all bt full" "$_NVIM_TEST_APP" -c -"$_NVIM_TEST_CORE"`. Defaults to the example command. This debug command may use -environment variables `_NVIM_TEST_APP` (path to application which is being -debugged: normally either nvim or luajit) and `_NVIM_TEST_CORE` (core file to -get backtrace from). +- `NVIM_TEST_CORE_DB_CMD` (FU) (S): command to get backtrace out of the + debugger. E.g. `gdb -n -batch -ex "thread apply all bt full" + "$_NVIM_TEST_APP" -c "$_NVIM_TEST_CORE"`. Defaults to the example command. + This debug command may use environment variables `_NVIM_TEST_APP` (path to + application which is being debugged: normally either nvim or luajit) and + `_NVIM_TEST_CORE` (core file to get backtrace from). -`NVIM_TEST_CORE_RANDOM_SKIP` (FU) (D): makes `check_cores` not check cores after -approximately 90% of the tests. Should be used when finding cores is too hard -for some reason. Normally (on OS X or when `NVIM_TEST_CORE_GLOB_DIRECTORY` is -defined and this variable is not) cores are checked for after each test. +- `NVIM_TEST_CORE_RANDOM_SKIP` (FU) (D): makes `check_cores` not check cores + after approximately 90% of the tests. Should be used when finding cores is + too hard for some reason. Normally (on OS X or when + `NVIM_TEST_CORE_GLOB_DIRECTORY` is defined and this variable is not) cores + are checked for after each test. -`NVIM_TEST_RUN_TESTTEST` (U) (1): allows running `test/unit/testtest_spec.lua` -used to check how testing infrastructure works. +- `NVIM_TEST_RUN_TESTTEST` (U) (1): allows running + `test/unit/testtest_spec.lua` used to check how testing infrastructure works. -`NVIM_TEST_TRACE_LEVEL` (U) (N): specifies unit tests tracing level: `0` -disables tracing (the fastest, but you get no data if tests crash and there was -no core dump generated), `1` or empty/undefined leaves only C function cals and -returns in the trace (faster then recording everything), `2` records all -function calls, returns and lua source lines exuecuted. +- `NVIM_TEST_TRACE_LEVEL` (U) (N): specifies unit tests tracing level: `0` + disables tracing (the fastest, but you get no data if tests crash and there + was no core dump generated), `1` or empty/undefined leaves only C function + cals and returns in the trace (faster then recording everything), `2` records + all function calls, returns and lua source lines exuecuted. -`NVIM_TEST_TRACE_ON_ERROR` (U) (1): makes unit tests yield trace on error in -addition to regular error message. +- `NVIM_TEST_TRACE_ON_ERROR` (U) (1): makes unit tests yield trace on error in + addition to regular error message. -`NVIM_TEST_MAXTRACE` (U) (N): specifies maximum number of trace lines to keep. -Default is 1024. +- `NVIM_TEST_MAXTRACE` (U) (N): specifies maximum number of trace lines to + keep. Default is 1024. |