doc [ci skip] #10383

- test/README.md: document luassert `TableFormatLevel`
- CONTRIBUTING.md: absorb parts of the old "Development tips" wiki page
This commit is contained in:
Justin M. Keyes 2019-07-19 21:32:04 +02:00 gecommit door GitHub
bovenliggende d5f7099be2
commit afef973262
Geen bekende sleutel gevonden voor deze handtekening in de database
GPG sleutel-ID: 4AEE18F83AFDEB23
10 gewijzigde bestanden met toevoegingen van 171 en 134 verwijderingen

Bestand weergeven

@ -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

Bestand weergeven

@ -44,7 +44,7 @@
"
if !has('python3')
echo "Error: Required vim compiled with +python3"
echo 'Error: Requires python3 + pynvim. :help provider-python'
finish
endif

Bestand weergeven

@ -42,7 +42,7 @@
"
if !has('python')
echo "Error: Required vim compiled with +python"
echo 'Error: Requires python + pynvim. :help provider-python'
finish
endif

Bestand weergeven

@ -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.

Bestand weergeven

@ -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*

Bestand weergeven

@ -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.

Bestand weergeven

@ -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: >

Bestand weergeven

@ -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

Bestand weergeven

@ -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) {

Bestand weergeven

@ -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.