copapy/README.md

89 lines
3.1 KiB
Markdown
Raw Normal View History

# Copapy
2025-05-25 21:23:02 +00:00
2025-09-29 21:11:54 +00:00
Development is in a very early stage. Only very few components are in a working state.
2025-05-25 21:23:02 +00:00
## Introduction
2025-05-25 21:23:02 +00:00
2025-10-15 20:56:59 +00:00
Copapy is a python based embedded domain specific language (eDSL) with a copy & patch compiler. It compiles to machine code. It uses the python interpreter for compilation. It generates a directed graph of variables and operations. The compiler generates machine code by composing pre-compiled stencils derived from C code with gcc -O3.
2025-05-25 21:23:02 +00:00
2025-10-15 20:56:59 +00:00
For code execution a executable or library receives the composed machine code, data and patch instructions. The patch instructions are used to correct memory address offsets.
2025-05-25 21:23:02 +00:00
2025-10-15 20:56:59 +00:00
The Project targets applications that profit from fast implementation (e.g. prototyping) and require realtime with low latency as well as minimizing risk of implementation errors not cached during compile time. This applies primarily for applications interfacing hardware, where runtime errors might lead to physical damage. For example robotics, embedded systems and control systems.
2025-05-25 21:23:02 +00:00
2025-10-15 20:56:59 +00:00
The language aims to be:
- Fast to write
- Easy to read
- Type safe
- Having a predictable runtime
- Turing-complete only during compile time
- No runtime errors
2025-09-29 21:11:54 +00:00
- Immutable types
2025-05-25 21:23:02 +00:00
### How it works
2025-05-25 21:23:02 +00:00
### Compilation
2025-09-29 21:11:54 +00:00
The Compilation step starts with the directed graph of variables and operations generated by the python interpreter.
2025-05-25 21:23:02 +00:00
### Tooling
2025-09-29 21:11:54 +00:00
Because the language is an embedded language, it can relay heavily on python tooling. While copapy is static typed, it uses Python to derive types during compile time wherever possible. It can get full benefit from python type checkers, to catch type errors even before compilation. Python and Copapy code can be combined seamlessly. Python acts as macro-language for the Copapy program. However, the project is designed in a way that the distinction has typically not to be considered by the programmer.
2025-05-25 21:23:02 +00:00
## Developer Guide
Contributions are welcome, please open an issue or submit a pull request on GitHub.
To get started with developing the package, follow these steps.
First, clone the repository to your local machine using Git:
```bash
git clone https://github.com/Nonannet/copapy.git
cd copapy
```
You may setup a venv:
```bash
python -m venv .venv
source .venv/bin/activate # On Windows use `.venv\Scripts\activate`
```
Build and install the package and dev dependencies:
```bash
pip install .[dev]
```
If this fails because you have no suitable c compiler installed you can either install a
compiler or use the binary from pypi:
```bash
pip install copapy[dev]
```
When using pytest it will run the binary from pypi but the local python code from the repo.
For running all tests you need the stencil object files and the compiled runner.
You can download the stencils and binary runner from GitHub or build them with gcc your self.
For downloading the files run:
```bash
python tools/get_binaries.py
```
To build the binaries from source on linux run:
```bash
bash tools/build.sh
```
Ensure that everything is set up correctly by running the unit tests:
```bash
pytest
```
2025-05-25 21:23:02 +00:00
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.