nac3_sca/README.md

63 lines
3.0 KiB
Markdown
Raw Normal View History

2022-04-18 15:11:32 +08:00
<div align="center">
![icon](https://git.m-labs.hk/M-Labs/nac3/raw/branch/master/nac3.svg)
2022-04-18 15:11:32 +08:00
</div>
2021-12-13 19:02:13 +08:00
2022-04-18 15:11:32 +08:00
# NAC3
2021-12-13 19:02:13 +08:00
NAC3 is a major, backward-incompatible rewrite of the compiler for the [ARTIQ](https://m-labs.hk/artiq) physics experiment control and data acquisition system. It features greatly improved compilation speeds, a much better type system, and more predictable and transparent operation.
NAC3 has a modular design and its applicability reaches beyond ARTIQ. The ``nac3core`` module does not contain anything specific to ARTIQ, and can be used in any project that requires compiling Python to machine code.
**WARNING: NAC3 is currently experimental software and several important features are not implemented yet.**
## Packaging
NAC3 is packaged using the [Nix](https://nixos.org) Flakes system. Install Nix 2.8+ and enable flakes by adding ``experimental-features = nix-command flakes`` to ``nix.conf`` (e.g. ``~/.config/nix/nix.conf``).
2021-12-13 19:02:13 +08:00
## Try NAC3
2022-01-24 15:54:01 +08:00
### Linux
2022-01-24 11:35:39 +08:00
After setting up Nix as above, use ``nix shell git+https://github.com/m-labs/artiq.git?ref=nac3`` to get a shell with the NAC3 version of ARTIQ. See the ``examples`` directory in ARTIQ (``nac3`` Git branch) for some samples of NAC3 kernel code.
2021-12-13 19:02:13 +08:00
2022-04-05 18:07:38 +08:00
### Windows
2022-01-24 15:54:01 +08:00
Install [MSYS2](https://www.msys2.org/), and open "MSYS2 CLANG64". Edit ``/etc/pacman.conf`` to add:
2022-01-24 15:54:01 +08:00
```
2022-04-05 18:07:38 +08:00
[artiq]
SigLevel = Optional TrustAll
2022-11-03 19:00:44 +08:00
Server = https://msys2.m-labs.hk/artiq-nac3
2022-01-24 15:54:01 +08:00
```
2022-04-05 18:07:38 +08:00
Then run the following commands:
2022-01-24 15:54:01 +08:00
```
2022-04-05 18:07:38 +08:00
pacman -Syu
pacman -S mingw-w64-clang-x86_64-artiq
2022-01-24 15:54:01 +08:00
```
2021-12-13 19:02:13 +08:00
## For developers
2021-06-25 12:28:33 +08:00
This repository contains:
2021-12-13 19:02:13 +08:00
- ``nac3ast``: Python abstract syntax tree definition (based on RustPython).
- ``nac3parser``: Python parser (based on RustPython).
- ``nac3core``: Core compiler library, containing type-checking and code generation.
- ``nac3standalone``: Standalone compiler tool (core language only).
2022-06-06 18:13:21 +08:00
- ``nac3ld``: Minimalist RISC-V and ARM linker.
2021-12-13 19:02:13 +08:00
- ``nac3artiq``: Integration with ARTIQ and implementation of ARTIQ-specific extensions to the core language.
- ``runkernel``: Simple program that runs compiled ARTIQ kernels on the host and displays RTIO operations. Useful for testing without hardware.
Use ``nix develop`` in this repository to enter a development shell.
If you are using a different shell than bash you can use e.g. ``nix develop --command fish``.
Build NAC3 with ``cargo build --release``. See the demonstrations in ``nac3artiq`` and ``nac3standalone``.
### Pre-Commit Hooks
You are strongly recommended to use the provided pre-commit hooks to automatically reformat files and check for non-optimal Rust practices using Clippy. Run `pre-commit install` to install the hook and `pre-commit` will automatically run `cargo fmt` and `cargo clippy` for you.
Several things to note:
- If `cargo fmt` or `cargo clippy` returns an error, the pre-commit hook will fail. You should fix all errors before trying to commit again.
- If `cargo fmt` reformats some files, the pre-commit hook will also fail. You should review the changes and, if satisfied, try to commit again.