#compiler #moore

moore-common

The common core of the moore compiler framework

15 releases (breaking)

0.14.0 Feb 8, 2022
0.13.2 Nov 11, 2021
0.12.1 Aug 18, 2021
0.12.0 Jan 9, 2021
0.1.0 Feb 27, 2018

#1156 in Development tools

Download history 32/week @ 2022-07-31 33/week @ 2022-08-07 27/week @ 2022-08-14 48/week @ 2022-08-21 17/week @ 2022-08-28 28/week @ 2022-09-04 36/week @ 2022-09-11 20/week @ 2022-09-18 33/week @ 2022-09-25 48/week @ 2022-10-02 19/week @ 2022-10-09 12/week @ 2022-10-16 33/week @ 2022-10-23 37/week @ 2022-10-30 37/week @ 2022-11-06 26/week @ 2022-11-13

134 downloads per month
Used in fewer than 6 crates

Apache-2.0 OR MIT

80KB
2K SLoC

moore

Build Status Released API docs Crates.io Crates.io dependency status

Moore is a compiler for hardware description languages that outputs llhd assembly, with a focus on usability, clear error reporting, and completeness. Its goal is to act as a frontend for hardware design tools such as synthesizers, linters, or logical equivalence checkers.

Usage

Installation

You need a working Rust installation to build Moore. The project also depends on the CIRCT project and transitively on MLIR and LLVM. To get a working binary, you generally want to ensure you have the circt and circt/llvm submodules checked out:

git submodule update --init --recursive

And then follow these steps:

Build LLVM and MLIR

mkdir -p circt/llvm/build
pushd circt/llvm/build
cmake ../llvm \
    -DCMAKE_BUILD_TYPE=Release \
    -DLLVM_BUILD_EXAMPLES=OFF \
    -DLLVM_ENABLE_ASSERTIONS=ON \
    -DLLVM_ENABLE_BINDINGS=OFF \
    -DLLVM_ENABLE_OCAMLDOC=OFF \
    -DLLVM_ENABLE_PROJECTS=mlir \
    -DLLVM_INSTALL_UTILS=ON \
    -DLLVM_OPTIMIZED_TABLEGEN=ON \
    -DLLVM_TARGETS_TO_BUILD="host"
cmake --build .
popd

Build CIRCT

mkdir -p circt/build
pushd circt/build
cmake .. \
    -DCMAKE_BUILD_TYPE=Release \
    -DMLIR_DIR=$PWD/../llvm/build/lib/cmake/mlir \
    -DLLVM_DIR=$PWD/../llvm/build/lib/cmake/llvm \
    -DLLVM_ENABLE_ASSERTIONS=ON
cmake --build .
popd

Build Moore

Set the following environment variables to indicate where your LLVM and CIRCT build is:

export CIRCT_SYS_CIRCT_DIR=$PWD/circt
export CIRCT_SYS_CIRCT_BUILD_DIR=$PWD/circt/build
export CIRCT_SYS_LLVM_DIR=$PWD/circt/llvm
export CIRCT_SYS_LLVM_BUILD_DIR=$PWD/circt/llvm/build

Use cargo to install Moore:

cargo install moore

Note that on Linux systems you are very likely to need libstdc++ version 7 or newer for this to work.

Development

For active development, you'll want to use the usual check, build, run, and test subcommands.

You may also find it useful to point the *_BUILD_DIR environment variables at the actual build directories (usually circt/llvm/build and circt/build), such that you don't need to re-install on every change to CIRCT or LLVM.

Example

Assume the following input file:

// foo.sv
module hello_world;
endmodule

To compile foo.sv and emit the corresponding LLHD assembly to standard output call moore with the file name and the module to elaborate (-e option):

moore foo.sv -e hello_world

You can use llhd-sim to simulate the compiled module:

moore foo.sv -e hello_world > foo.llhd
llhd-sim foo.llhd

Development

Moore is developed in this repository, but is separated into the following crates:

  • moore: Top-level umbrella crate tying everything together
  • moore-common: Common infrastructure used by SystemVerilog and VHDL
  • moore-derive: Procedural macros
  • moore-svlog: SystemVerilog implementation
  • moore-svlog-syntax: SystemVerilog parser and AST implementation
  • moore-vhdl: VHDL implementation
  • moore-vhdl-syntax: VHDL parser and AST implementation
  • moore-circt: Rust wrappers around the CIRCT API
  • moore-circt-sys: Low-level language bindings to CIRCT

Some useful commands when working on moore:

git submodule init
git submodule update
cargo check
cargo test --all
cargo run -- foo.sv -e foo
scripts/test.py --debug -v
scripts/test.py --debug -v <path-to-test-case>
lit test -v

Making a new Release

To create a new release, the individual sub-crates of the project have to be released in the reverse order outlined above. Follow this checklist:

  1. Use scripts/release_status.sh to see an overview of moore/llhd crate versions used throughout the project
  2. Update the version in all Cargo.toml files
  3. Use scripts/release_check.sh to ensure that all crates have the same version as the root
  4. Ensure cargo is happy: cargo check
  5. Update the CHANGELOG.md file
  6. Commit: git commit -am "Bump version to X.Y.Z
  7. Tag: git tag vX.Y.Z
  8. Publish all crates using cargo publish in reverse order

Dependencies

~265–455KB