Skip to content

Latest commit

 

History

History
113 lines (83 loc) · 4.65 KB

CONTRIBUTING.md

File metadata and controls

113 lines (83 loc) · 4.65 KB
Raw

Contributing

The following are all welcome:

  • code reviews
  • issues/feature requests. Note that feature requests should be limited to extensions or better error handling, the compiler will not break backwards compatibility with C.
  • test cases

Contributing Code

Bugfixes and minor features (e.g. better error messages) are welcome, please submit a pull request.

If you would like to work on a larger feature, either comment on an existing issue, make a new issue, or discuss it in the discord to make sure you know how to get started.

If you do submit a patch, please write at least one or two test cases. You can either write unit tests or runner tests, described below.

Patches will not be merged unless they pass all current tests, including clippy and rustfmt. You can run these with tests/pre-commit.sh; I suggest sym-linking it to .git/hooks/pre-commit like this: ln -s ../../tests/pre-commit.sh .git/hooks/pre-commit.

Note that new dependencies are frowned upon because each new library increases the build time, making the compiler incrementally more frustrating to work on.

Unit tests

Rust convention for unit tests is to put them in a tests module with #[test] in front of the function, which makes them automatically run with cargo test. See the end of src/lex.rs for an example.

Runner tests

Writing unit tests for nested types can get tedious very quickly. Writing unit tests for codegen is not really possible, since we want to see how the program behaves at runtime, and running arbitrary C code in-process is a recipe for disaster.

Instead, saltwater uses 'Runner tests', which are C files in tests/runner-tests that are compiled and run by tests/runner.rs. You can control the expected output using a comment at the top of the file (usually something like // succeeds or code: 1). See runner.rs:run_one for a full list of options. See tests/runner-tests for examples of existing tests.

Input minimizer

In minimizer/ is a script wrapping DustMite which can be used to minimize any C file using some simple conditions. You can read more about how to use it in minimizer/README.md. The minimizer can be used in combination with fuzzing, bug replication and of course bug reporting.

Contributing Bug Reports

If you contribute a lot of bug reports, you may find the .github/report-issue.sh script useful. It's used like so:

usage: ./report-issue.sh <issue type> <file> [-f]

<issue type> is the name of one of the issue templates, currently:

./report-issue.sh a README.md
unrecognized issue type (options are panic, codegen, parse), aborting

<file> is the path to the file with the relevant C source code. report-issue will open your editor with a partially-filled out template, including a backtrace if appropriate. After you close your editor, report-issue will open your browser to a 'new issue' GitHub page with the contents of the now-complete template. You can still edit the issue browser if you like.

If you don't like this behavior of opening the browser, you can instead run the script with BROWSER=echo and it will print the URL instead. Be aware that the URL contains the entire contents of the issue, so it will be very long.

If you want to run the script non-interactively, use EDITOR=true.

Reference

You may find the following references useful.

Other projects

Documentation for codegen

Code of Conduct

There is not currently a code of conduct. Please do not do anything that would require me to make one.