nicolas
/
copapy
mirror of https://github.com/Nonannet/copapy.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

readme updated

This commit is contained in:
Nicolas Kruse 2025-10-28 22:09:59 +01:00
parent cd0c2a83d4
commit 98418e5e17
1 changed files with 12 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
README.md
View File

@ -1,40 +1,24 @@
# Copapy # Copapy
Development is in a very early stage. Only very few components are in a working state. Copapy is a python based embedded domain specific language (eDSL) with copy & patch compiler. 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 compiled C code.
The Project targets applications that profit from fast implementation (e.g. prototyping) and require low latency realtime execution as well as minimizing risk of implementation errors not caught during compile time. This applies primarily to applications interfacing hardware, where runtime errors might lead to physical damage - for example in the field of robotics, aerospace, embedded systems and control systems in general.
## Introduction
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.
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.
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.
The language aims to be: The language aims to be:
- Fast to write - Fast to write & easy to read
- Easy to read
- Type safe - Type safe
- Having a predictable runtime - Having a predictable runtime
- Turing-complete only during compile time
- No runtime errors - No runtime errors
- Immutable types
### How it works 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 to improve ergonomics.
### Compilation
The Compilation step starts with the directed graph of variables and operations generated by the python interpreter.
### Tooling
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.
## How it works
The **Compilation** step starts with tracing the python code to generate a acyclic directed graph (DAG) of variables and operations. The DAG can be optimized and gets than linearized to a sequence of operations. Each operation gets mapped to a pre-compiled stencil, which is a piece of machine code with placeholders for memory addresses. The compiler generates patch instructions to fill the placeholders with the correct memory addresses. The binary code build from the stencils, data for constants and the patch instructions are than passed to the Runner for execution. The runner allocates memory for the code and data, applies the patch instructions to correct memory addresses and finally executes the code.
## Developer Guide ## Developer Guide
Contributions are welcome, please open an issue or submit a pull request on GitHub. Contributions are welcome, please open an issue or submit a pull request on GitHub.
To get started with developing the package, follow these steps. To get started with developing the package, first clone the repository to your local machine using Git:
First, clone the repository to your local machine using Git:
```bash ```bash
git clone https://github.com/Nonannet/copapy.git git clone https://github.com/Nonannet/copapy.git
@ -61,18 +45,18 @@ compiler or use the binary from pypi:
pip install copapy[dev] pip install copapy[dev]
``` ```
When using pytest it will run the binary from pypi but the local python code from the repo. When using pytest it will run the binary from pypi but the local python code still from the repo.
For running all tests you need the stencil object files and the compiled runner. 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 yourself. You can download the stencils and binary runner from GitHub or build them with gcc yourself.
For downloading the files run: For downloading the latest binaries from GitHub run:
```bash ```bash
python tools/get_binaries.py python tools/get_binaries.py
``` ```
To build the binaries from source on linux run: To build the binaries from source on Linux run:
```bash ```bash
bash tools/build.sh bash tools/build.sh
@ -85,4 +69,4 @@ pytest
``` ```
## License ## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. This project is licensed under GPL - see the [LICENSE](LICENSE) file for details.