tblgen

This crate provides raw bindings and a safe wrapper for TableGen, a domain-specific language used by the LLVM project.

The goal of this crate is to enable users to develop custom TableGen backends in Rust. Hence the primary use case of this crate are procedural macros that generate Rust code from TableGen description files.

Documentation

Read the documentation at https://danacus.gitlab.io/tblgen-rs/tblgen/.

Supported LLVM Versions

An installation of LLVM is required to use this crate. This crate only aims to support the latest version of LLVM. The version of LLVM currently supported is 17.x.x.

The 1TABLEGEN_170_PREFIX` environment variable can be used to specify a custom directory of the LLVM installation.

lib.rs:

This crate provides raw bindings and a safe wrapper for TableGen, a domain-specific language used by the LLVM project.

The goal of this crate is to enable users to develop custom TableGen backends in Rust. Hence the primary use case of this crate are procedural macros that generate Rust code from TableGen description files.

Safety

This crate aims to be completely safe.

Supported LLVM Versions

An installation of LLVM is required to use this crate. The versions of LLVM currently supported are 16.x.x (default) and 17.x.x. Different LLVM version can be selected using features flags (llvm16-0 or llvm17-0).

The TABLEGEN_<version>_PREFIX environment variable can be used to specify a custom directory of the LLVM installation.

Examples

The following example parse simple TableGen code provided as a &str and iterates over classes and defs defined in this file.

use tblgen::{TableGenParser, RecordKeeper};

let keeper: RecordKeeper = TableGenParser::new()
    .add_source(
        r#"
        class A;
        def D: A;
        "#,
    )?
    .parse()?;
assert_eq!(keeper.classes().next().unwrap().0, Ok("A"));
assert_eq!(keeper.defs().next().unwrap().0, Ok("D"));
assert_eq!(keeper.all_derived_definitions("A").next().unwrap().name(), Ok("D"));

By adding include paths, external TableGen files can be included.

use tblgen::{TableGenParser, RecordKeeper};
use std::path::Path;

let keeper: RecordKeeper = TableGenParser::new()
    .add_source(r#"include "mlir/IR/OpBase.td""#)?
    .add_include_path(&format!("{}/include", std::env::var("TABLEGEN_170_PREFIX")?))
    .parse()?;
let i32_def = keeper.def("I32").expect("has I32 def");
assert!(i32_def.subclass_of("I"));
assert_eq!(i32_def.int_value("bitwidth"), Ok(32));

API Stability

LLVM does not provide a stable C API for TableGen, and the C API provided by this crate is not stable. Furthermore, the safe wrapper does not provide a stable interface either, since this crate is still in early development.