69 lines
2.6 KiB
Markdown
69 lines
2.6 KiB
Markdown
<!--
|
|
Copyright (C) 2023 - 2024:
|
|
The Trinitrix Project <soispha@vhack.eu, antifallobst@systemausfall.org>
|
|
SPDX-License-Identifier: LGPL-3.0-or-later
|
|
|
|
This file is part of the Trixy crate for Trinitrix.
|
|
|
|
Trixy is free software: you can redistribute it and/or modify
|
|
it under the terms of the Lesser GNU General Public License as
|
|
published by the Free Software Foundation, either version 3 of
|
|
the License, or (at your option) any later version.
|
|
|
|
This program is distributed in the hope that it will be useful,
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
GNU General Public License for more details.
|
|
|
|
You should have received a copy of the GNU General Public License
|
|
and the Lesser GNU General Public License along with this program.
|
|
If not, see <https://www.gnu.org/licenses/>.
|
|
-->
|
|
|
|
# Trixy
|
|
|
|
A crate to generate a multi-language foreign function interface.
|
|
|
|
## Features
|
|
|
|
- Support for custom types, derived from a set of [primitive types](./src/types/mod.rs).
|
|
- Support for callbacks, thought c function pointers.
|
|
- Support for error handling, when checking a functions arguments (NULL pointer and such things).
|
|
|
|
## Supported languages:
|
|
|
|
- c
|
|
|
|
## Dependencies
|
|
|
|
Trixy only needs:
|
|
|
|
- `clang-format` to format the generated c header files.
|
|
|
|
## The Trixy Language
|
|
|
|
The API to generate is specified in a Trixy file. The language of these files is an subset
|
|
of rust and should thus be easy to learn and pick up.
|
|
|
|
A grammar file is provided [here](./docs/grammar.ebnf) encoded in [Extended Backus-Naur Form](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form).
|
|
The grammar file is rendered as railroad diagrams in PDF [here](./docs/grammar.pdf), run [`./docs/generate_docs`](./docs/generate_docs.sh) to regenerate the PDF file.
|
|
|
|
## Testing
|
|
|
|
Trixy contains integration tests in the `./tests` directory. These are maintained with the
|
|
`./scripts/tests.sh` script. Take a look at it's `--help` output for further usage
|
|
information.
|
|
|
|
This crate also contains a binary, which can help with manual testing and inspecting of the
|
|
generated AST. The `cargo run --features 'build-binary' -- --help` output should provide
|
|
all required information.
|
|
|
|
Tests are (as of now) only positive, i.e. they can only test successful situations.
|
|
Failing test will probably be supported in the future.
|
|
|
|
## Contributing
|
|
|
|
We have a [nix flake](./flake.nix), which provides the required dependencies to work with Trixy and the associated scripts in the `./scripts` directory.
|
|
|
|
Please also make sure to run the `./scripts/renew_copyright_header.sh` after you added a new file, to ensure that every file contains a license header.
|