466 lines
21 KiB
Text
466 lines
21 KiB
Text
*ale-development.txt* For Vim version 8.0.
|
|
*ale-dev*
|
|
*ale-development*
|
|
|
|
ALE Development Documentation
|
|
|
|
===============================================================================
|
|
CONTENTS *ale-development-contents*
|
|
|
|
1. Introduction.........................|ale-development-introduction|
|
|
2. Design Goals.........................|ale-design-goals|
|
|
3. Coding Standards.....................|ale-coding-standards|
|
|
4. Testing ALE..........................|ale-development-tests|
|
|
4.1. Writing Linter Tests.............|ale-development-linter-tests|
|
|
4.2. Writing Fixer Tests..............|ale-development-fixer-tests|
|
|
4.3. Running Tests in a Windows VM....|ale-development-windows-tests|
|
|
5. Contributing.........................|ale-development-contributing|
|
|
|
|
===============================================================================
|
|
1. Introduction *ale-development-introduction*
|
|
|
|
This document contains helpful information for ALE developers, including
|
|
design goals, information on how to run the tests, coding standards, and so
|
|
on. You should read this document if you want to get involved with ALE
|
|
development.
|
|
|
|
===============================================================================
|
|
2. Design Goals *ale-design-goals*
|
|
|
|
This section lists design goals for ALE, in no particular order. They are as
|
|
follows.
|
|
|
|
ALE code should be almost 100% VimL. This makes the plugin as portable as
|
|
possible.
|
|
|
|
ALE should run without needing any other plugins to be installed, to make
|
|
installation simple. ALE can integrate with other plugins for more advanced
|
|
functionality, non-essential functionality, or improving on basic first party
|
|
functionality.
|
|
|
|
ALE should check files with as many tools as possible by default, except where
|
|
they cause security issues or make excessive use of resources on modern
|
|
machines.
|
|
|
|
ALE should be free of breaking changes to the public API, which is comprised of
|
|
documented functions and options, until a major version is planned. Breaking
|
|
changes should be preceded by a deprecation phase complete with warnings.
|
|
Changes required for security may be an exception.
|
|
|
|
ALE supports Vim 8 and above, and NeoVim 0.2.0 or newer. These are the
|
|
earliest versions of Vim and NeoVim which support |job|, |timer|, |closure|,
|
|
and |lambda| features. All ALE code should be written so it is compatible with
|
|
these versions of Vim, or with version checks so particular features can
|
|
degrade or fail gracefully.
|
|
|
|
Just about everything should be documented and covered with tests.
|
|
|
|
By and large, people shouldn't pay for the functionality they don't use. Care
|
|
should be taken when adding new features, so supporting new features doesn't
|
|
degrade the general performance of anything ALE does.
|
|
|
|
LSP support will become more important as time goes on. ALE should provide
|
|
better support for LSP features as time goes on.
|
|
|
|
When merging pull requests, you should respond with `Cheers! :beers:`, purely
|
|
for comedy value.
|
|
|
|
===============================================================================
|
|
3. Coding Standards *ale-coding-standards*
|
|
|
|
The following general coding standards should be adhered to for Vim code.
|
|
|
|
* Check your Vim code with `Vint` and do everything it says. ALE will check
|
|
your Vim code with Vint automatically. See: https://github.com/Kuniwak/vint
|
|
Read ALE's `Dockerfile` to see which version of `Vint` it uses.
|
|
* Try to write descriptive and concise names for variables and functions.
|
|
Names shouldn't be too short or too long. Think about others reading your
|
|
code later on.
|
|
* Use `snake_case` names for variables and arguments, and `PascalCase` names
|
|
for functions. Prefix every variable name with its scope. (`l:`, `g:`, etc.)
|
|
* Try to keep lines no longer than 80 characters, but this isn't an absolute
|
|
requirement.
|
|
* Use 4 spaces for every level of indentation in Vim code.
|
|
* Add a blank line before every `function`, `if`, `for`, `while`, or `return`,
|
|
which doesn't start a new level of indentation. This makes the logic in
|
|
your code easier to follow.
|
|
* End every file with a trailing newline character, but not with extra blank
|
|
lines. Remove trailing whitespace from the ends of lines.
|
|
* Write the full names of commands instead of abbreviations. For example, write
|
|
`function` instead of `func`, and `endif` instead of `end`.
|
|
* Write functions with `!`, so files can be reloaded. Use the |abort| keyword
|
|
for all functions, so functions exit on the first error.
|
|
* Make sure to credit yourself in files you have authored with `Author:`
|
|
and `Description:` comments.
|
|
|
|
In addition to the above general guidelines for the style of your code, you
|
|
should also follow some additional rules designed to prevent mistakes. Some of
|
|
these are reported with ALE's `custom-linting-rules` script. See
|
|
|ale-development-tests|.
|
|
|
|
* Don't leave stray `:echo` lines in code. Write `" no-custom-checks` above
|
|
the line if you must echo something.
|
|
* For strings use |is#| instead of |==#|, `is?` instead of `==?`, `isnot#`
|
|
instead of `!=#`, and `isnot?` instead of `!=?`. This is because `'x' ==# 0`
|
|
returns 1, while `'x' is# 0` returns 0, so you will experience fewer issues
|
|
when numbers are compared with strings. `is` and `isnot` also do not throw
|
|
errors when other objects like List or Dictionaries are compared with
|
|
strings.
|
|
* Don't use the `getcwd()` function in the ALE codebase. Most of ALE's code
|
|
runs from asynchronous callback functions, and these functions can execute
|
|
from essentially random buffers. Therefore, the `getcwd()` output is
|
|
useless. Use `expand('#' . a:buffer . ':p:h')` instead. Don't use
|
|
`expand('%...')` for the same reason.
|
|
* Don't use the `simplify()` function. It doesn't simplify paths enough. Use
|
|
`ale#path#Simplify()` instead.
|
|
* Don't use the `shellescape()` function. It doesn't escape arguments properly
|
|
on Windows. Use `ale#Escape()` instead, which will avoid escaping where it
|
|
isn't needed, and generally escape arguments better on Windows.
|
|
* Don't use the `tempname()` function. It doesn't work when `$TMPDIR` isn't
|
|
set. Use `ale#util#Tempname()` instead, which temporarily sets `$TMPDIR`
|
|
appropriately where needed.
|
|
* Use `snake_case` names for linter names, so they can be used as part of
|
|
variable names. You can define `aliases` for linters, for other names people
|
|
might try to configure linters with.
|
|
* Use |v:t_TYPE| variables instead of `type()`, which are more readable.
|
|
|
|
Apply the following guidelines when writing Vader test files.
|
|
|
|
* Use 2 spaces for Vader test files, instead of the 4 spaces for Vim files.
|
|
* If you write `Before` and `After` blocks, you should typically write them at
|
|
the top of the file, so they run for all tests. There may be some tests
|
|
where it make sense to modify the `Before` and `After` code part of the way
|
|
through the file.
|
|
* If you modify any settings or global variables, reset them in `After`
|
|
blocks. The Vader `Save` and `Restore` commands can be useful for this
|
|
purpose.
|
|
* If you load or define linters in tests, write `call ale#linter#Reset()` in
|
|
an `After` block.
|
|
* Just write `Execute` blocks for Vader tests, and don't bother writing `Then`
|
|
blocks. `Then` blocks execute after `After` blocks in older versions, and
|
|
that can be confusing.
|
|
|
|
Apply the following rules when writing Bash scripts.
|
|
|
|
* Run `shellcheck`, and do everything it says.
|
|
See: https://github.com/koalaman/shellcheck
|
|
* Try to write scripts so they will run on Linux, BSD, or Mac OSX.
|
|
|
|
===============================================================================
|
|
4. Testing ALE *ale-development-tests* *ale-dev-tests* *ale-tests*
|
|
|
|
ALE is tested with a suite of tests executed via GitHub Actions and AppVeyor.
|
|
ALE runs tests with the following versions of Vim in the following
|
|
environments.
|
|
|
|
1. Vim 8.0.0027 on Linux via GitHub Actions.
|
|
2. Vim 8.2.4693 on Linux via GitHub Actions.
|
|
3. NeoVim 0.2.0 on Linux via GitHub Actions.
|
|
4. NeoVim 0.7.0 on Linux via GitHub Actions.
|
|
6. Vim 8 (stable builds) on Windows via AppVeyor.
|
|
|
|
If you are developing ALE code on Linux, Mac OSX, or BSD, you can run ALEs
|
|
tests by installing Docker and running the `run-tests` script. Follow the
|
|
instructions on the Docker site for installing Docker.
|
|
See: https://docs.docker.com/install/
|
|
|
|
NOTE: Don't forget to add your user to the `docker` group on Linux, or Docker
|
|
just won't work. See: https://docs.docker.com/install/linux/linux-postinstall/
|
|
|
|
If you run simply `./run-tests` from the ALE repository root directory, the
|
|
latest Docker image for tests will be downloaded if needed, and the script
|
|
will run all of the tests in Vader, Vint checks, and several Bash scripts for
|
|
finding extra issues. Run `./run-tests --help` to see all of the options the
|
|
script supports. Note that the script supports selecting particular test files.
|
|
|
|
Once you get used to dealing with Vim and NeoVim compatibility issues, you
|
|
probably want to use `./run-tests --fast -q` for running tests with only the
|
|
fastest available Vim version, and with success messages from tests
|
|
suppressed.
|
|
|
|
Generally write tests for any changes you make. The following types of tests
|
|
are recommended for the following types of code.
|
|
|
|
* New/edited error handler callbacks -> Write tests in `test/handler`
|
|
* New/edited linter definition -> Write tests in `test/linter`
|
|
* New/edited fixer functions -> Write tests in `test/fixers`
|
|
|
|
Look at existing tests in the codebase for examples of how to write tests.
|
|
Refer to the Vader documentation for general information on how to write Vader
|
|
tests: https://github.com/junegunn/vader.vim
|
|
|
|
If you need to add any supporting files for tests, such as empty files present
|
|
to test searching upwards through paths for configuration files, they can be
|
|
added to the `test/test-files` directory.
|
|
|
|
See |ale-development-linter-tests| for more information on how to write linter
|
|
tests.
|
|
|
|
When you add new linters or fixers, make sure to add them into the tables in
|
|
supported-tools.md and |ale-supported-languages-and-tools.txt|. If you forget to
|
|
keep them both in sync, you should see an error like the following in the
|
|
builds run for GitHub Actions.
|
|
>
|
|
========================================
|
|
diff supported-tools.md and doc/ale-supported-languages-and-tools.txt tables
|
|
========================================
|
|
Differences follow:
|
|
|
|
--- /tmp/readme.qLjNhJdB 2018-07-01 16:29:55.590331972 +0100
|
|
+++ /tmp/doc.dAi8zfVE 2018-07-01 16:29:55.582331877 +0100
|
|
@@ -1 +1 @@
|
|
- ASM: gcc, foobar
|
|
+ ASM: gcc
|
|
<
|
|
Make sure to list documentation entries for linters and fixers in individual
|
|
help files in the table of contents, and to align help tags to the right
|
|
margin. For example, if you add a heading for an `aardvark` tool to
|
|
`ale-python.txt` with a badly aligned doc tag, you will see errors like so. >
|
|
|
|
========================================
|
|
Look for badly aligned doc tags
|
|
========================================
|
|
Badly aligned tags follow:
|
|
|
|
doc/ale-python.txt:aardvark ...
|
|
========================================
|
|
Look for table of contents issues
|
|
========================================
|
|
|
|
Check for bad ToC sorting:
|
|
|
|
Check for mismatched ToC and headings:
|
|
|
|
--- /tmp/table-of-contents.mwCFOgSI 2018-07-01 16:33:25.068811878 +0100
|
|
+++ /tmp/headings.L4WU0hsO 2018-07-01 16:33:25.076811973 +0100
|
|
@@ -168,6 +168,7 @@
|
|
pyrex (cython), ale-pyrex-options
|
|
cython, ale-pyrex-cython
|
|
python, ale-python-options
|
|
+ aardvark, ale-python-aardvark
|
|
autopep8, ale-python-autopep8
|
|
black, ale-python-black
|
|
flake8, ale-python-flake8
|
|
<
|
|
Make sure to make the table of contents match the headings, and to keep the
|
|
doc tags on the right margin.
|
|
|
|
===============================================================================
|
|
4.1 Writing Linter Tests *ale-development-linter-tests*
|
|
|
|
Tests for ALE linters take two forms.
|
|
|
|
1. Tests for handling the output of commands.
|
|
2. Tests for checking which commands are run, or connections are made.
|
|
|
|
Tests of the first form should go in the `test/handler` directory, and should
|
|
be written like so. >
|
|
|
|
Before:
|
|
" Load the file which defines the linter.
|
|
runtime ale_linters/filetype/linter_name_here.vim
|
|
|
|
After:
|
|
" Unload all linters again.
|
|
call ale#linter#Reset()
|
|
|
|
Execute(The output should be correct):
|
|
|
|
" Test that the right loclist items are parsed from the handler.
|
|
AssertEqual
|
|
\ [
|
|
\ {
|
|
\ 'lnum': 1,
|
|
\ 'type': 'E',
|
|
\ 'text': 'Something went wrong',
|
|
\ },
|
|
\ ],
|
|
\ ale_linters#filetype#linter_name#Handle(bufnr(''), [
|
|
\ '1:Something went wrong',
|
|
\ ]
|
|
<
|
|
Tests for what ALE runs should go in the `test/linter` directory, and should
|
|
be written like so. >
|
|
|
|
Before:
|
|
" Load the linter and set up a series of commands, reset linter variables,
|
|
" clear caches, etc.
|
|
"
|
|
" Vader's 'Save' command will be called here for linter variables.
|
|
call ale#assert#SetUpLinterTest('filetype', 'linter_name')
|
|
|
|
After:
|
|
" Reset linters, variables, etc.
|
|
"
|
|
" Vader's 'Restore' command will be called here.
|
|
call ale#assert#TearDownLinterTest()
|
|
|
|
Execute(The default command should be correct):
|
|
" AssertLinter checks the executable and command.
|
|
" Pass expected_executable, expected_command
|
|
AssertLinter 'some-command', ale#Escape('some-command') . ' --foo'
|
|
|
|
Execute(Check chained commands):
|
|
" GivenCommandOutput can be called with 1 or more list for passing output
|
|
" to chained commands. The output for each callback defaults to an empty
|
|
" list.
|
|
GivenCommandOutput ['v2.1.2']
|
|
" Given a List of commands, check all of them.
|
|
" Given a String, only the last command in the chain will be checked.
|
|
AssertLinter 'some-command', [
|
|
\ ale#Escape('some-command') . ' --version',
|
|
\ ale#Escape('some-command') . ' --foo',
|
|
\]
|
|
<
|
|
The full list of commands that will be temporarily defined for linter tests
|
|
given the above setup are as follows.
|
|
|
|
`GivenCommandOutput [...]` - Define output for ale#command#Run.
|
|
`AssertLinterCwd cwd` - Check the `cwd` for the linter.
|
|
`AssertLinter executable, command` - Check the executable and command.
|
|
`AssertLinterNotExecuted` - Check that linters will not be executed.
|
|
`AssertLSPLanguage language` - Check the language given to an LSP server.
|
|
`AssertLSPOptions options_dict` - Check the options given to an LSP server.
|
|
`AssertLSPConfig config_dict` - Check the config given to an LSP server.
|
|
`AssertLSPProject project_root` - Check the root given to an LSP server.
|
|
`AssertLSPAddress address` - Check the address to an LSP server.
|
|
|
|
|
|
===============================================================================
|
|
4.2 Writing Fixer Tests *ale-development-fixer-tests*
|
|
|
|
Tests for ALE fixers should go in the `test/fixers` directory, and should
|
|
be written like so. >
|
|
|
|
Before:
|
|
" Load the fixer and set up a series of commands, reset fixer variables,
|
|
" clear caches, etc.
|
|
"
|
|
" Vader's 'Save' command will be called here for fixer variables.
|
|
call ale#assert#SetUpFixerTest('filetype', 'fixer_name')
|
|
|
|
After:
|
|
" Reset fixers, variables, etc.
|
|
"
|
|
" Vader's 'Restore' command will be called here.
|
|
call ale#assert#TearDownFixerTest()
|
|
|
|
Execute(The default command should be correct):
|
|
" AssertFixer checks the result of the loaded fixer function.
|
|
AssertFixer {'command': ale#Escape('some-command') . ' --foo'}
|
|
|
|
Execute(Check chained commands):
|
|
" Same as above for linter tests.
|
|
GivenCommandOutput ['v2.1.2']
|
|
" Given a List of commands, check all of them.
|
|
" Given anything else, only the last result will be checked.
|
|
AssertFixer [
|
|
\ ale#Escape('some-command') . ' --version',
|
|
\ {'command': ale#Escape('some-command') . ' --foo'}
|
|
\]
|
|
<
|
|
The full list of commands that will be temporarily defined for fixer tests
|
|
given the above setup are as follows.
|
|
|
|
`GivenCommandOutput [...]` - Define output for ale#command#Run.
|
|
`AssertFixerCwd cwd` - Check the `cwd` for the fixer.
|
|
`AssertFixer results` - Check the fixer results
|
|
`AssertFixerNotExecuted` - Check that fixers will not be executed.
|
|
|
|
|
|
===============================================================================
|
|
4.3 Running Tests in a Windows VM *ale-development-windows-tests*
|
|
|
|
Tests are run for ALE in a build of Vim 8 for Windows via AppVeyor. These
|
|
tests can frequently break due to minor differences in paths and how escaping
|
|
is done for commands on Windows. If you are a Linux or Mac user, running these
|
|
tests locally can be difficult. Here is a process that will make that easier.
|
|
|
|
First, you want to install a Windows image with VirtualBox. Install VirtualBox
|
|
and grab a VirtualBox image for Windows such as from here:
|
|
https://developer.microsoft.com/en-us/microsoft-edge/tools/vms/
|
|
|
|
NOTE: If you need to enter a password for the virtual machine at any point,
|
|
the password is "Passw0rd!" without the double quotes.
|
|
|
|
NOTE: If your trial period for Windows runs out, run the commands like the
|
|
wallpaper tells you to.
|
|
|
|
Your virtual machine will need to have PowerShell installed. Before you go any
|
|
further, confirm that PowerShell is installed in your Windows virtual machine.
|
|
|
|
Consult the VirtualBox documentation on how to install "Guest Additions."
|
|
You probably want to install "Guest Additions" for most things to work
|
|
properly.
|
|
|
|
After you've loaded your virtual machine image, go into "Settings" for your
|
|
virtual machine, and "Shared Folders." Add a shared folder with the name
|
|
"ale", and set the "Folder Path" to the path to your ALE repository, for
|
|
example: "/home/w0rp/ale"
|
|
|
|
Find out which drive letter "ale" has been mounted as in Windows. We'll use
|
|
"E:" as the drive letter, for example. Open the command prompt as an
|
|
administrator by typing in `cmd` in the start menu, right clicking on the
|
|
command prompt application, and clicking "Run as administrator." Click "Yes"
|
|
when prompted to ask if you're sure you want to run the command prompt. You
|
|
should type in the following command to mount the "ale" directory for testing,
|
|
where "E:" is replaced with your drive letter. >
|
|
|
|
mklink /D C:\testplugin E:
|
|
<
|
|
Close the administrator Command Prompt, and try running the command
|
|
`type C:\testplugin\LICENSE` in a new Command Prompt which you are NOT running
|
|
as administrator. You should see the license for ALE in your terminal. After
|
|
you have confirmed that you have mounted ALE on your machine, search in the
|
|
Start Menu for "power shell," run PowerShell as an administrator, and issue
|
|
the following commands to install the correct Vim and Vader versions for
|
|
running tests. >
|
|
|
|
Add-Type -A System.IO.Compression.FileSystem
|
|
|
|
Invoke-WebRequest ftp://ftp.vim.org/pub/vim/pc/vim80-586w32.zip -OutFile C:\vim.zip
|
|
[IO.Compression.ZipFile]::ExtractToDirectory('C:\vim.zip', 'C:\vim')
|
|
rm C:\vim.zip
|
|
|
|
Invoke-WebRequest ftp://ftp.vim.org/pub/vim/pc/vim80-586rt.zip -OutFile C:\rt.zip
|
|
[IO.Compression.ZipFile]::ExtractToDirectory('C:\rt.zip', 'C:\vim')
|
|
rm C:\rt.zip
|
|
|
|
Invoke-WebRequest https://github.com/junegunn/vader.vim/archive/c6243dd81c98350df4dec608fa972df98fa2a3af.zip -OutFile C:\vader.zip
|
|
[IO.Compression.ZipFile]::ExtractToDirectory('C:\vader.zip', 'C:\')
|
|
mv C:\vader.vim-c6243dd81c98350df4dec608fa972df98fa2a3af C:\vader
|
|
rm C:\vader.zip
|
|
<
|
|
After you have finished installing everything, you can run all of the tests
|
|
in Windows by opening a Command Prompt NOT as an administrator by navigating
|
|
to the directory where you've mounted the ALE code, which must be named
|
|
`C:\testplugin`, and by running the `run-tests.bat` batch file. >
|
|
|
|
cd C:\testplugin
|
|
run-tests
|
|
<
|
|
It will probably take several minutes for all of the tests to run. Be patient.
|
|
You can run a specific test by passing the filename as an argument to the
|
|
batch file, for example: `run-tests test/test_c_flag_parsing.vader` . This will
|
|
give you results much more quickly.
|
|
|
|
===============================================================================
|
|
5. Contributing *ale-development-contributing*
|
|
|
|
All integration of new code into ALE is done through GitHub pull requests.
|
|
Using that tool streamlines the process and minimizes the time and effort
|
|
required to e.g. ensure test suites are run for every change.
|
|
|
|
As for any project hosted by GitHub, the choice of platform demands every
|
|
contributor to take care to setup an account and configure it accordingly.
|
|
|
|
Due to details of our process, a difference to many other GitHub hosted
|
|
projects is that contributors who wish to keep the author fields for their
|
|
commits unaltered need to configure a public email address in their account
|
|
and profile settings. See: https://docs.github.com/en/account-and-profile/
|
|
|
|
Unless configuring GitHub to expose contact details, commits will be rewritten
|
|
to appear by `USERNAME <RANDOM_NUMBER+USERNAME@users.noreply.github.com>` .
|
|
|
|
===============================================================================
|
|
vim:tw=78:ts=2:sts=2:sw=2:ft=help:norl:
|