Need help with inkwell?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

TheDan64
976 Stars 102 Forks Apache License 2.0 954 Commits 61 Opened issues

Description

It's a New Kind of Wrapper for Exposing LLVM (Safely)

Services available

!
?

Need anything else?

Contributors list

Inkwell(s)

Crates.io Build Status codecov lines of code Join the chat at https://gitter.im/inkwell-rs/Lobby Minimum rustc 1.42

It's a New Kind of Wrapper for Exposing LLVM (Safely)

Inkwell aims to help you pen your own programming languages by safely wrapping llvm-sys. It provides a more strongly typed interface than the underlying LLVM C API so that certain types of errors can be caught at compile time instead of at LLVM's runtime. This means we are trying to replicate LLVM IR's strong typing as closely as possible. The ultimate goal is to make LLVM safer from the rust end and a bit easier to learn (via documentation) and use.

Requirements

  • Rust 1.42+
  • Rust Stable, Beta, or Nightly
  • LLVM 3.6, 3.7, 3.8, 3.9, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0, or 13.0

Usage

You'll need to point your Cargo.toml to an existing preview crate on crates.io or the master branch with a corresponding LLVM feature flag:

[dependencies]
inkwell = { git = "https://github.com/TheDan64/inkwell", branch = "master", features = ["llvm12-0"] }

Supported versions:

| LLVM Version | Cargo Feature Flag | | :----------: | :-----------: | | 3.6.x | llvm3-6 | | 3.7.x | llvm3-7 | | 3.8.x | llvm3-8 | | 3.9.x | llvm3-9 | | 4.0.x | llvm4-0 | | 5.0.x | llvm5-0 | | 6.0.x | llvm6-0 | | 7.0.x | llvm7-0 | | 8.0.x | llvm8-0 | | 9.0.x | llvm9-0 | | 10.0.x | llvm10-0 | | 11.0.x | llvm11-0 | | 12.0.x | llvm12-0 | | 13.0.x | llvm13-0 |

Please be aware that we may make breaking changes on master from time to time since we are pre-v1.0.0, in compliance with semver. Please prefer a crates.io release whenever possible!

Documentation

Documentation is automatically deployed here based on master. These docs are not yet 100% complete and only show the latest supported LLVM version due to a rustdoc issue. See #2 for more info.

Examples

Tari's llvm-sys example written in safe code1 with Inkwell:

use inkwell::OptimizationLevel;
use inkwell::builder::Builder;
use inkwell::context::Context;
use inkwell::execution_engine::{ExecutionEngine, JitFunction};
use inkwell::module::Module;
use inkwell::targets::{InitializationConfig, Target};
use std::error::Error;

/// Convenience type alias for the sum function. /// /// Calling this is innately unsafe because there's no guarantee it doesn't /// do unsafe operations internally. type SumFunc = unsafe extern "C" fn(u64, u64, u64) -> u64;

struct CodeGen { context: &'ctx Context, module: Module, builder: Builder, execution_engine: ExecutionEngine, }

impl CodeGen { fn jit_compile_sum(&self) -> Option> { let i64_type = self.context.i64_type(); let fn_type = i64_type.fn_type(&[i64_type.into(), i64_type.into(), i64_type.into()], false); let function = self.module.add_function("sum", fn_type, None); let basic_block = self.context.append_basic_block(function, "entry");

    self.builder.position_at_end(basic_block);

    let x = function.get_nth_param(0)?.into_int_value();
    let y = function.get_nth_param(1)?.into_int_value();
    let z = function.get_nth_param(2)?.into_int_value();

    let sum = self.builder.build_int_add(x, y, "sum");
    let sum = self.builder.build_int_add(sum, z, "sum");

    self.builder.build_return(Some(&sum));

    unsafe { self.execution_engine.get_function("sum").ok() }
}

}

fn main() -> Result> { let context = Context::create(); let module = context.create_module("sum"); let execution_engine = module.create_jit_execution_engine(OptimizationLevel::None)?; let codegen = CodeGen { context: &context, module, builder: context.create_builder(), execution_engine, };

let sum = codegen.jit_compile_sum().ok_or("Unable to JIT compile `sum`")?;

let x = 1u64;
let y = 2u64;
let z = 3u64;

unsafe {
    println!("{} + {} + {} = {}", x, y, z, sum.call(x, y, z));
    assert_eq!(sum.call(x, y, z), x + y + z);
}

Ok(())

}

1 There are two uses of

unsafe
in this example because the actual act of compiling and executing code on the fly is innately
unsafe
. For one, there is no way of verifying we are calling
get_function()
with the right function signature. It is also
unsafe
to call the function we get because there's no guarantee the code itself doesn't do
unsafe
things internally (the same reason you need
unsafe
when calling into C).

LLVM's Kaleidoscope Tutorial

Can be found in the examples directory.

Alternative Crate(s)

Contributing

Check out our Contributing Guide

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.