This repository has been archived on 2024-05-26. You can view files and clone it, but cannot push or open issues or pull requests.
trixy/README.md

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.