README.md

THIS REPO IS NOT MAINTAINED ANYMORE

If you're willing to contribute please do on this repo

Report a Bug - Request a Feature - Ask a Question

Table of Contents

• Report a Bug
• Request a Feature
• Report a bug
• Request a feature
• About
  • Built With
• Architecture
• Getting Started
  • Prerequisites
    • Rust
    • LLVM
  • Installation
    • shenlongup
    • Environment variables
• Usage
  • Command line interface
    • Compile Sierra to LLVM IR
• Performance
  • Benchmarks
• Roadmap
• Support
• Project assistance
• Contributing
• Authors & contributors
• Security
• License
• Acknowledgements
• Contributors ✨

---

Report a bug

If you find a bug, please open a GitHub issue!

Request a feature

To request a new feature, please open an issue following this template.

About

Shenlong is a blazingly fast ⚡ tool to generate LLVM IR from Cairo, written in Rust 🦀

Built With

• Rust
• inkwell
• cairo

Architecture

               +--------------+
               |   Cairo code |
               +-------+------+
                       | Compile with Cairo compiler
                       |
               +-------v------+
               |   Sierra     |
               +-------+------+
                       | Compile with Shenlong
                       |
               +-------v------+
               |   LLVM IR    |
      +--------+-------+------+---------+
      | lli            |clang           | clang
      |                |                |
+-----v-------+  +-----v-----+  +-------v----+
|    JIT      |  |  Binary   |  |    WASM    |
+-------------+  +-----------+  +------------+

Getting Started

Prerequisites

Rust

The project requires nightly, which the rust-toolchain.toml file on the repository takes care of.

LLVM

In order to build the project, you need to have LLVM 16+ installed on your system.

On debian/ubuntu:

You can use the follow repository (make sure to install LLVM 16): https://apt.llvm.org/

And then export the following env var:

export LLVM_SYS_150_PREFIX=/usr/lib/llvm-16
export LLI_PATH=/usr/lib/llvm-16/bin/lli # used for testing

On macos:

While the oficial brew repo doesn't have LLVM 16 right now, you can use this custom tap:

brew install -s edg-l/tap/llvm@16

Example of .zshenv file:

export LLVM_SYS_150_PREFIX=$(/opt/homebrew/bin/brew --prefix llvm@16)
export LLI_PATH=$(/opt/homebrew/bin/brew --prefix llvm@16)/bin/lli # used for testing

Installation

shenlongup

To install with shenlongup run (shenlongup requires nightly rustup):

curl -sL https://raw.githubusercontent.com/keep-starknet-strange/shenlong/main/shenlongup | sh

Environment variables

Copy the .env.example file to a .env file and populate each variable:

cp examples/.env.example .env

Build from source:

cargo build --all --release

The binaries will be located in target/release/. Specifically, the binary for the CLI is target/release/shenlong.

Usage

Command line interface

Shenlong, make me a LLVM compiler!
Shenlong is a blazingly fast ⚡ tool to generate LLVM IR from Cairo, written in Rust 🦀

Usage: shenlong [CONFIG] <COMMAND>

Commands:
  sierra  Sierra related subcommands
  help    Print this message or the help of the given subcommand(s)

Arguments:
  [CONFIG]

Options:
  -h, --help     Print help information
  -V, --version  Print version information

Compile Sierra to LLVM IR

shenlong sierra compile-to-llvm \
--program-path examples/sierra/add.sierra \
--output-path target/llvm/add.ir

Performance

Benchmarks

Run the benchmarks with:

cargo bench

Result on a MacBook Pro Apple M1 Max 2021 with 64GB of RAM:

     Running benches/sierra_2_llvm_benchmark.rs (target/release/deps/sierra_2_llvm_benchmark-b2798c19234aee25)
Benchmarking sierra-2-llvm-simple-test: Collecting 100 samples in estimated 5.6913 s (10k iterasierra-2-llvm-simple-test
                        time:   [556.84 µs 559.02 µs 562.34 µs]
                        change: [-3.0928% -1.3163% +0.1790%] (p = 0.13 > 0.05)
                        No change in performance detected.

This benchmark is the compilation of the resources/bench/sierra/simple_test.sierra file. This file is a simple program that do some additions, here is the Cairo code:

func main(a: felt) -> felt  {
    let d = 70;
    let b = a + 1;
    let c = b + d;
    c
}

Roadmap

See the open issues for a list of proposed features (and known issues).

• Top Feature Requests (Add your votes using the 👍 reaction)
• Top Bugs (Add your votes using the 👍 reaction)
• Newest Bugs

Support

Reach out to the maintainer at one of the following places:

• GitHub Discussions
• Contact options listed on this GitHub profile

Project assistance

If you want to say thank you or/and support active development of shenlong:

• Add a GitHub Star to the project.
• Tweet about the shenlong.
• Write interesting articles about the project on Dev.to, Medium or your personal blog.

Together, we can make shenlong better!

Contributing

First off, thanks for taking the time to contribute! Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make will benefit everybody else and are greatly appreciated.

Please read our contribution guidelines, and thank you for being involved!

Authors & contributors

For a full list of all authors and contributors, see the contributors page.

Security

shenlong follows good practices of security, but 100% security cannot be assured. shenlong is provided "as is" without any warranty. Use at your own risk.

For more information and to report security issues, please refer to our security documentation.

License

This project is licensed under the MIT license.

See LICENSE for more information.

Acknowledgements

• Shout out to StarkWare for the amazing Cairo compiler and the Cairo language itself, specifically to the compiler team for their help and support and for the primitives on which shenlong is built.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Abdel @ StarkWare 💻	Lucas @ StarkWare 💻
Add your contributions

This project follows the all-contributors specification. Contributions of any kind welcome!