From 7420ce185b83fa8c390ad0309947b324c6f0f284 Mon Sep 17 00:00:00 2001 From: Sebastien Bourdeauducq Date: Mon, 13 Dec 2021 19:02:13 +0800 Subject: [PATCH] README: update --- README.md | 47 ++++++++++++++++++++++++++--------------------- 1 file changed, 26 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 6480476c..412bedd2 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,30 @@ -# NAC3 compiler +# NAC3 + +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.4+ and enable flakes by adding ``experimental-features = nix-command flakes`` to ``nix.conf`` (e.g. ``~/.config/nix/nix.conf``). + +## Try NAC3 + +After setting up Nix as above, use ``nix shell github:m-labs/artiq/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. + +## For developers This repository contains: -- 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). -- 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. +- ``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). +- ``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``. -The core compiler knows nothing about symbol resolution, host variables -etc. nac3artiq and nac3standalone provide (implement) the -symbol resolver to the core compiler for resolving the type and value for -unknown symbols. The core compiler only type checks classes and functions -requested by nac3artiq/nac3standalone (the API should allow the -caller to specify which methods should be compiled). After type checking, the -compiler analyses the set of functions/classes that are used and performs -code generation. - -value could be integer values, boolean values, bytes (for memcpy), function ID -(full name + concrete type) +Build NAC3 with ``cargo build --release``. See the demonstrations in ``nac3artiq`` and ``nac3standalone``.