Skip to content

Latest commit

 

History

History
127 lines (95 loc) · 4.63 KB

README.md

File metadata and controls

127 lines (95 loc) · 4.63 KB

rCanary -- Rust Leak Checker through Semi-automated Memory Boundary

This is the main source code repository for rCanary. It contains the source code of rlc, cargo-rlc, rust-llvm-heap-analysis-tool (rlc_phase_llvm).

Note: this README is for users rather than contributors.

Quick Start

Installing from Source Code

The build system uses a shell script called install.sh to build all components, which manages the compiling process. It lives in the root of the rlc project.

install_rlc.sh script can be run directly on most unix-like systems, such as mac-os, linux, etc.

Note: before running install_rlc.sh script, you should change current dir to the root of rlc project.

./install_rlc.sh

Building on a Unix-like system

  1. Make sure you have installed the dependencies:

    • clang++ 14.0 or later
    • llvm 14.0 or later
    • python 3.9 or later
    • z3 4.10 or later
    • GNU make 3.81 or later
    • cmake 3.24 or later
    • git
    • rustup 1.25 or later
    • rustc/cargo nightly-2022-08-01
    • cargo components: rust-src, rustc-dev, llvm-tools-preview

  2. Clone the source with git:

git clone https://github.com/Artisan-Lab/rCanary.git
cd rlc
  1. Configure the build settings:

The configuration of rlc building system can be modified in file Cargo.toml and install_rlc.sh. The Rust build system uses a file named Cargo.toml in the root of the source tree to determine various configuration settings for the build. Specifically, Cargo.toml can option the compilation of rlc and cargo-rlc.

install_rlc.sh can option the compilation of rust-llvm-heap-analysis-tool. The binary of this tool named as rlc_phase_llvm will be automated added to your system environment in this script.

#for debug version
cargo install --debug --path "$(dirname "$0")" --force --features backtraces
#for release version
cargo install --path "$(dirname "$0")" --force

If you use bash instead of zsh, you should change in install.sh:

#for zsh
echo $p >> ~/.zshrc
#for bash
echo $p >> ~/.bashrc
  1. Build and install:
./install_rlc.sh

When complete, ./install_rlc.sh install will place several programs into $PREFIX/bin: rlc, the Rust Leakage Checker; cargo-rlc, the specific tool embedded in cargo to call rlc; rlc_phase_llvm, the tool to scan llvm-ir for rust crate and check the usage of heap resource; rlc_solver, the constraint solver for whole rlc system.

Building on Windows

There are two prominent ABIs in use on Windows: the native MSVC ABI used by Visual Studio, and the GNU ABI used by the GCC toolchain.

Currently, the rlc only supports for interop with GNU software built using the MinGW/MSYS2 toolchain use the GNU build.

MSYS2 can be used to easily build Rust on Windows:

  1. Grab the latest MSYS2 installer and go through the installer.

  2. Run mingw64_shell.bat from wherever you installed MSYS2 (i.e. C:\msys64). (As of the latest version of MSYS2 you have to run msys2_shell.cmd -mingw64 from the command line instead)

  3. From this terminal, install the required tools:

# Update package mirrors (may be needed if you have a fresh install of MSYS2)
pacman -Sy pacman-mirrors

# Install build tools needed for Rust. If you're building a 32-bit compiler,
# then replace "x86_64" below with "i686". If you've already got git, python,
# or CMake installed and in PATH you can remove them from this list. Note
# that it is important that you do **not** use the 'python2', 'cmake' and 'ninja'
# packages from the 'msys2' subsystem. The build has historically been known
# to fail with these packages.
pacman -S git \
            make \
            diffutils \
            tar \
            mingw-w64-x86_64-python \
            mingw-w64-x86_64-cmake \
            mingw-w64-clang-x86_64-toolchain
  1. Navigate to rlc source code (or clone it), then build it.

Note: we do not advice the user to use the windows as host platform.

Using RLC

You can directly use rCanary by the command:

cargo rlc

The directory must be the root of a cargo project, and note that our system is not supported virtual workspace.

If you want to check virtual workspace project, you need to go down to the sub folder of this project and check the root of the cargo project.

Including the optional arguments for rCanary, the emitter dir and introduction, and the logging-output system:

"-MIR=V" => show Rust MIR,
"-MIR=VV" => show Rust MIR verbosely,
"-ADT=V" => show the results of ADT-DEF analysis,
"-Z3-GOAL=V" => show the Z3 goal (constraints) of each MIR,
"-ICX-SLICE=V" => show the contexts of each program point for debugging,