kevin/neovim
1
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2024-12-23 12:45:17 -07:00
Code Issues Packages Projects Releases Wiki Activity

doc (#9288)

Browse Source 
- misc
- doc: `:help config`. closes #9329
- cleanup test/README.md
This commit is contained in:
Justin M. Keyes 2018-12-09 01:31:34 +01:00 committed by GitHub
parent f1eb25f0c4
commit 857a7312d0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 109 additions and 130 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@ -86,7 +86,7 @@ Project layout
├─ ci/ build automation
├─ cmake/ build scripts
├─ runtime/ user plugins/docs
├─ src/ application source code (see src/nvim/README.md)
├─ src/nvim/ application source code (see src/nvim/README.md)
│ ├─ api/ API subsystem
│ ├─ eval/ VimL subsystem
│ ├─ event/ event-loop subsystem

28
runtime/doc/api.txt
View File

@ -1138,7 +1138,7 @@ nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line},
which returns a namespace id. Pass it in to this function as
`ns_id` to add highlights to the namespace. All highlights in
the same namespace can then be cleared with single call to
|nvim_buf_clear_highlight|. If the highlight never will be
|nvim_buf_clear_namespace|. If the highlight never will be
deleted by an API call, pass `ns_id = -1`.
As a shorthand, `ns_id = 0` can be used to create a new
@ -1162,20 +1162,21 @@ nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line},
Return: ~
The ns_id that was used
*nvim_buf_clear_highlight()*
nvim_buf_clear_highlight({buffer}, {ns_id}, {line_start}, {line_end})
Clears highlights and virtual text from a given source id and
range of lines
*nvim_buf_clear_namespace()*
nvim_buf_clear_namespace({buffer}, {ns_id}, {line_start}, {line_end})
Clears namespaced objects, highlights and virtual text, from a
line range
To clear a source group in the entire buffer, pass in 0 and -1
To clear the namespace in the entire buffer, pass in 0 and -1
to line_start and line_end respectively.
Parameters: ~
{buffer} Buffer handle
{ns_id} Namespace to clear, or -1 to clear all.
{ns_id} Namespace to clear, or -1 to clear all
namespaces.
{line_start} Start of range of lines to clear
{line_end} End of range of lines to clear (exclusive)
or -1 to clear to end of file.
or -1 to clear to end of buffer.
*nvim_buf_set_virtual_text()*
nvim_buf_set_virtual_text({buffer}, {ns_id}, {line}, {chunks}, {opts})
@ -1184,18 +1185,17 @@ nvim_buf_set_virtual_text({buffer}, {ns_id}, {line}, {chunks}, {opts})
By default (and currently the only option) the text will be
placed after the buffer text. Virtual text will never cause
reflow, rather virtual text will be truncated at the end of
the screen line. The virtual text will begin after one cell to
the right of the ordinary text, this will contain the |lcs-
eol| char if set, otherwise just be a space.
the screen line. The virtual text will begin one cell (|lcs-
eol| or space) after the ordinary text.
Namespaces are used to support batch deletion/updating of
virtual text. To create a namespace, use
|nvim_create_namespace|. Virtual text is cleared using
|nvim_buf_clear_highlight|. The same `ns_id` can be used for
|nvim_buf_clear_namespace|. The same `ns_id` can be used for
both virtual text and highlights added by
|nvim_buf_add_highlight|, both can then be cleared with a
single call to |nvim_buf_clear_highlight|. If the virtual text
never will be cleared by an API call, pass `src_id = -1`.
single call to |nvim_buf_clear_namespace|. If the virtual text
never will be cleared by an API call, pass `ns_id = -1`.
As a shorthand, `ns_id = 0` can be used to create a new
namespace for the virtual text, the allocated id is then

23
runtime/doc/starting.txt
View File

@ -410,20 +410,17 @@ accordingly. Vim proceeds in this order:
3. Execute Ex commands, from environment variables and/or files
An environment variable is read as one Ex command line, where multiple
commands must be separated with '|' or "<NL>".
*init.vim* *vimrc* *exrc*
A file that contains initialization commands is called a "vimrc" file.
Each line in a vimrc file is executed as an Ex command line. It is
sometimes also referred to as "exrc" file. They are the same type of
file, but "exrc" is what Vi always used, "vimrc" is a Vim specific
name, "init.vim" is Neovim specific location for vimrc file. Also see
|vimrc-intro|.
commands must be separated with '|' or <NL>.
*config* *init.vim* *vimrc* *exrc*
A file that contains initialization commands is generically called
a "vimrc" or config file. Each line in a vimrc file is executed as an
Ex command line. See also |vimrc-intro| and |base-directories|.
Places for your personal initializations (see |base-directories|):
Unix $XDG_CONFIG_HOME/nvim/init.vim
(default for $XDG_CONFIG_HOME is ~/.config)
Windows $XDG_CONFIG_HOME/nvim/init.vim
(default for $XDG_CONFIG_HOME is ~/AppData/Local)
The Nvim config file is named "init.vim", located at:
Unix ~/.config/nvim/init.vim
Windows ~/AppData/Local/nvim/init.vim
Or if |$XDG_CONFIG_HOME| is defined:
$XDG_CONFIG_HOME/nvim/init.vim
RECOMMENDATION: Put all your Vim configuration stuff in the
$HOME/.config/nvim/ directory. That makes it easy to copy it to

3
src/nvim/api/buffer.c
View File

@ -1027,8 +1027,7 @@ void nvim_buf_clear_highlight(Buffer buffer,
/// By default (and currently the only option) the text will be placed after
/// the buffer text. Virtual text will never cause reflow, rather virtual
/// text will be truncated at the end of the screen line. The virtual text will
/// begin after one cell to the right of the ordinary text, this will contain
/// the |lcs-eol| char if set, otherwise just be a space.
/// begin one cell (|lcs-eol| or space) after the ordinary text.
///
/// Namespaces are used to support batch deletion/updating of virtual text.
/// To create a namespace, use |nvim_create_namespace|. Virtual text is

183
test/README.md
View File

@ -1,27 +1,63 @@
Tests
=====
Tests are run by `/cmake/RunTests.cmake` file, using `busted`.
Tests are broadly divided into *unit tests* ([test/unit](https://github.com/neovim/neovim/tree/master/test/unit/)),
*functional tests* ([test/functional](https://github.com/neovim/neovim/tree/master/test/functional/)),
and *old tests* ([src/nvim/testdir/](https://github.com/neovim/neovim/tree/master/src/nvim/testdir/)).
For some failures, `.nvimlog` (or `$NVIM_LOG_FILE`) may provide insight.
- _Unit_ testing is achieved by compiling the tests as a shared library which is
loaded and called by [LuaJit FFI](http://luajit.org/ext_ffi.html).
- _Functional_ tests are driven by RPC, so they do not require LuaJit (as
opposed to Lua).
You can learn the [key concepts of Lua in 15 minutes](http://learnxinyminutes.com/docs/lua/).
Use any existing test as a template to start writing new tests.
Tests are run by `/cmake/RunTests.cmake` file, using `busted` (a Lua test-runner).
For some failures, `.nvimlog` (or `$NVIM_LOG_FILE`) may provide insight.
Depending on the presence of binaries (e.g., `xclip`) some tests will be
ignored. You must compile with libintl to prevent `E319: The command is not
available in this version` errors.
Depending on the presence of binaries (e.g., `xclip`) some tests will be ignored. You must compile with libintl to prevent `E319: The command is not available in this version` errors.
---
- [Running tests](#running-tests)
- [Unit tests](#unit-tests)
- [Writing tests](#writing-tests)
- [Lint](#lint)
- [Environment variables](#environment-variables)
---
Layout
======
- `/test/benchmark` : benchmarks
- `/test/functional` : functional tests
- `/test/unit` : unit tests
- `/test/config` : contains `*.in` files which are transformed into `*.lua`
files using `configure_file` CMake command: this is for acessing CMake
variables in lua tests.
- `/test/includes` : include-files for use by luajit `ffi.cdef` C definitions
parser: normally used to make macros not accessible via this mechanism
accessible the other way.
- `/test/*/preload.lua` : modules preloaded by busted `--helper` option
- `/test/**/helpers.lua` : common utility functions for test code
- `/test/*/**/*_spec.lua` : actual tests. Files that do not end with
`_spec.lua` are libraries like `/test/**/helpers.lua`, except that they have
some common topic.
- `/src/nvim/testdir` : old tests (from Vim)
Running tests
-------------
=============
## Executing Tests
Executing Tests
---------------
To run all _non-legacy_ (unit + functional) tests:
To run all tests (except "old" tests):
make test
@ -33,9 +69,32 @@ To run only _functional_ tests:
make functionaltest
---
## Filter Tests
Legacy tests
------------
To run all legacy Vim tests:
make oldtest
To run a *single* legacy test set `TEST_FILE`, for example:
TEST_FILE=test_syntax.res make oldtest
- The `.res` extension (instead of `.vim`) is required.
- Specify only the test file name, not the full path.
Debugging tests
---------------
You can set `$GDB` to [run tests under gdbserver](https://github.com/neovim/neovim/pull/1527).
And if `$VALGRIND` is set it will pass `--vgdb=yes` to valgrind instead of
starting gdbserver directly.
Filtering Tests
---------------
### Filter by name
@ -85,58 +144,20 @@ To run only the tagged tests:
TEST_TAG=foo make functionaltest
**NOTES**:
**NOTE:**
* Tags are mainly used for testing issues (ex: `#1234`), so use the following
method.
* `TEST_FILE` is not a pattern string like `TEST_TAG` or `TEST_FILTER`. The
given value to `TEST_FILE` must be a path to an existing file.
* Both `TEST_TAG` and `TEST_FILTER` filter tests by the strings from either
`it()` or `describe()` functions.
* Both `TEST_TAG` and `TEST_FILTER` filter tests by the string descriptions
found in `it()` and `describe()`.
---
### Legacy
Writing tests
=============
To run all legacy (Vim) integration tests:
make oldtest
To run a *single* legacy test, run `make` with `TEST_FILE=test_name.res`. E.g.
to run `test_syntax.vim`:
TEST_FILE=test_syntax.res make oldtest
- The `.res` extension (instead of `.vim`) is required.
- Specify only the test file name, not the full path.
### Functional tests
`$GDB` can be set to [run tests under
gdbserver](https://github.com/neovim/neovim/pull/1527). If `$VALGRIND` is also
set, it will add the `--vgdb=yes` option to valgrind instead of
starting gdbserver directly.
Unit tests
Guidelines
----------
Tests are broadly divided into *unit tests*
([test/unit](https://github.com/neovim/neovim/tree/master/test/unit) directory)
and *functional tests*
([test/functional](https://github.com/neovim/neovim/tree/master/test/functional)
directory). Use any of the existing tests as a template to start writing new
tests.
- _Unit_ testing is achieved by compiling the tests as a shared library which is
loaded and called by LuaJit [FFI](http://luajit.org/ext_ffi.html).
- _Functional_ tests are driven by RPC, so they do not require LuaJit (as
opposed to Lua).
You can learn the [key concepts of Lua in 15
minutes](http://learnxinyminutes.com/docs/lua/).
## Guidelines for writing tests
- Consider [BDD](http://en.wikipedia.org/wiki/Behavior-driven_development)
guidelines for organization and readability of tests. Describe what you're
testing (and the environment if applicable) and create specs that assert its
@ -174,8 +195,14 @@ minutes](http://learnxinyminutes.com/docs/lua/).
([example](https://github.com/neovim/neovim/commit/5c1dc0fbe7388528875aff9d7b5055ad718014de#diff-bf80b24c724b0004e8418102f68b0679R18)).
- Use `make testlint` for using the shipped luacheck program ([supported by syntastic](https://github.com/scrooloose/syntastic/blob/d6b96c079be137c83009827b543a83aa113cc011/doc/syntastic-checkers.txt#L3546))
to lint all tests.
- Really long `source([=[...]=])` blocks may break syntax highlighting. Try
`:syntax sync fromstart` to fix it.
### Where tests go
Where tests go
--------------
Tests in `/test/unit` and `/test/functional` are divided into groups
by the semantic component they are testing.
- _Unit tests_
([test/unit](https://github.com/neovim/neovim/tree/master/test/unit)) should
@ -189,33 +216,9 @@ minutes](http://learnxinyminutes.com/docs/lua/).
- Try to find an existing `test/functional/*/*_spec.lua` group that makes
sense, before creating a new one.
## Checklist for migrating legacy tests
**Note:** Only "old style" (`src/nvim/testdir/*.in`) legacy tests should be
converted. Please _do not_ convert "new style" Vim tests
(`src/nvim/testdir/*.vim`).
The "new style" Vim tests are faster than the old ones, and converting them
takes time and effort better spent elsewhere.
- Remove the associated `test.in`, `test.out`, and `test.ok` files from
`src/nvim/testdir/`.
- Make sure the lua test ends in `_spec.lua`.
- Make sure the test count increases accordingly in the build log.
- Make sure the new test contains the same control characters (`^]`, ...) as the
old test.
- Instead of the actual control characters, use an equivalent textual
representation (e.g. `<esc>` instead of `^]`). The
`scripts/legacy2luatest.pl` script does some of these conversions
automatically.
## Tips
- Really long `source([=[...]=])` blocks may break syntax highlighting. Try
`:syntax sync fromstart` to fix it.
Lint
----
====
`make lint` (and `make testlint`) runs [luacheck](https://github.com/mpeterv/luacheck)
on the test code.
@ -229,29 +232,9 @@ http://luacheck.readthedocs.io/en/stable/warnings.html
Ignore the smallest applicable scope (e.g. inside a function, not at the top of
the file).
Layout
------
- `/test/benchmark` : benchmarks
- `/test/functional` : functional tests
- `/test/unit` : unit tests
- `/test/config` : contains `*.in` files which are transformed into `*.lua`
files using `configure_file` CMake command: this is for acessing CMake
variables in lua tests.
- `/test/includes` : include-files for use by luajit `ffi.cdef` C definitions
parser: normally used to make macros not accessible via this mechanism
accessible the other way.
- `/test/*/preload.lua` : modules preloaded by busted `--helper` option
- `/test/**/helpers.lua` : common utility functions for test code
- `/test/*/**/*_spec.lua` : actual tests. Files that do not end with
`_spec.lua` are libraries like `/test/**/helpers.lua`, except that they have
some common topic.
Tests in `/test/unit` and `/test/functional` are normally divided into groups
by the semantic component they are testing.
Environment variables
---------------------
=====================
Test behaviour is affected by environment variables. Currently supported
(Functional, Unit, Benchmarks) (when Defined; when set to _1_; when defined,