Contributing
This page is aimed to developers of vsql.
Building from Source
make bin/vsql # macOS and linux
make bin/vsql.exe # windows
Debugging
Termination signals often don’t give much context, you can get more information
by using the lldb debugger:
v examples/memory.v && lldb -o run examples/memory
Documentation
Documentation is built and published automatically at vsql.readthedocs.com.
You can generate the documentation locally with:
make docs
If you receive an error, you might be missing some dependencies:
pip3 install sphinx sphinx_rtd_theme
cd docs && python3 -m pip install -r requirements.txt
make docs will only regenerate the parts that it thinks have changed. To
rebuild the entire docs you can use:
make clean-docs docs
Parser & SQL Grammar
To make changes to the SQL grammar you will need to modify the grammar.bnf
file. These rules are partial or complete BNF rules from the
2016 SQL standard.
Within grammar.bnf you will see that some of the rules have a parser
function which is a name after ->. The actual parser function will have
parse_ prefix added. You can find all the existing parse functions in the
parse.v file.
If a rule does not have a parse function (no ->) then the value will be
passed up the chain which is the desired behavior in most cases. However, be
careful if there are multiple terms, you will need to provide a parse function
to return the correct term.
Each of the rules can have an optional type described in /* */ before
::=. Rules that do not have a type will be ignored as parameters for parse
functions. Otherwise, these types are used in the generated code to make sure
the correct types are passed into the parse functions.
After making changes to grammar.bnf you will need to run:
make grammar
Now, when running v test . you may receive errors for missing parse_
functions, you should implement those now.
Testing
vsql is tested exclusively with SQL test files. See Testing.