trixy/README.md

<!--
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.
docs(README): Add 2024-03-27 21:53:08 +00:00			`<!--`
			`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.`

docs(README): Mention the binary 2024-03-27 22:04:14 +00:00			`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.`

docs(README): Add 2024-03-27 21:53:08 +00:00			`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.