From 41029431042b70424d32727c90a58e9482ebf921 Mon Sep 17 00:00:00 2001 From: h1994st Date: Wed, 21 Jun 2023 22:29:52 -0700 Subject: [PATCH] Update README.md and comments --- README.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++--- src/config.rs | 34 ++++++++++++++++----------------- 2 files changed, 66 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index b5df33c..07bc9fa 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,52 @@ [![rllvm CI](https://github.com/h1994st/rllvm/actions/workflows/ci.yml/badge.svg)](https://github.com/h1994st/rllvm/actions/workflows/ci.yml) -- `rllvm-cc` -- `rllvm-cxx` -- `rllvm-get-bc` +`rllvm` is a Rust port of [`gllvm`](https://github.com/SRI-CSL/gllvm) and provides compiler wrappers to build whole-program LLVM bitcode files for projects with source codes. + +For more details, please refer to [`gllvm`](https://github.com/SRI-CSL/gllvm) or [`wllvm`](https://github.com/SRI-CSL/whole-program-llvm). + +## Installation + +```bash +cargo install rllvm +``` + +## Get Started + +```bash +rllvm-cxx -o hello tests/data/hello.cc +rllvm-get-bc hello # Extract the bitcode file `hello.bc` +llvm-dis hello.bc # Obtain readable `hello.ll` file +``` + +### Configuration + +The default configuration file `~/.rllvm/config.toml` will be automatically created, if it does not exist, with the following entries: + +| Configuration Key | Required? | Notes | +| -------------------------- | --------- | --------------------------------------------------------------------------------------- | +| `llvm_config_filepath` | Yes | The absolute filepath of `llvm-config` | +| `clang_filepath` | Yes | The absolute filepath of `clang` | +| `clangxx_filepath` | Yes | The absolute filepath of `clang++` | +| `llvm_ar_filepath` | Yes | The absolute filepath of `llvm-ar` | +| `llvm_link_filepath` | Yes | The absolute filepath of `llvm-link` | +| `llvm_objcopy_filepath` | Yes | The absolute filepath of `llvm-objcopy` | +| `bitcode_store_path` | No | The absolute path of the directory that stores intermediate bitcode files | +| `llvm_link_flags` | No | Extra user-provided linking flags for `llvm-link` | +| `lto_ldflags` | No | Extra user-provided linking flags for link time optimization | +| `bitcode_generation_flags` | No | Extra user-provided flags for bitcode generation, e.g., "-flto -fwhole-program-vtables" | +| `is_configure_only` | No | The configure only mode, which skips the bitcode generation (Default: false) | +| `log_level` | No | Log level (0: nothing, 1: error, 2: warn, 3: info, 4: debug, 5: trace) | + +Here is an example of the configuration file: + +```toml +llvm_config_filepath = '/usr/local/Cellar/llvm/16.0.4/bin/llvm-config' +clang_filepath = '/usr/local/Cellar/llvm/16.0.4/bin/clang' +clangxx_filepath = '/usr/local/Cellar/llvm/16.0.4/bin/clang++' +llvm_ar_filepath = '/usr/local/Cellar/llvm/16.0.4/bin/llvm-ar' +llvm_link_filepath = '/usr/local/Cellar/llvm/16.0.4/bin/llvm-link' +llvm_objcopy_filepath = '/usr/local/Cellar/llvm/16.0.4/bin/llvm-objcopy' +bitcode_store_path = '/tmp/bitcode_store' +log_level = 3 +``` diff --git a/src/config.rs b/src/config.rs index b7abb79..770cd95 100644 --- a/src/config.rs +++ b/src/config.rs @@ -18,41 +18,41 @@ lazy_static! { #[derive(Serialize, Deserialize, Debug)] pub struct RLLVMConfig { - /// The filepath of `llvm-config` + /// The absolute filepath of `llvm-config` llvm_config_filepath: PathBuf, - /// The filepath of `clang` + /// The absolute filepath of `clang` clang_filepath: PathBuf, - /// The filepath of `clang++` + /// The absolute filepath of `clang++` clangxx_filepath: PathBuf, - /// The filepath of `llvm-ar` + /// The absolute filepath of `llvm-ar` llvm_ar_filepath: PathBuf, - /// The filepath of `llvm-link` + /// The absolute filepath of `llvm-link` llvm_link_filepath: PathBuf, - /// The filepath of `llvm-objcopy` + /// The absolute filepath of `llvm-objcopy` llvm_objcopy_filepath: PathBuf, /// The absolute path of the directory that stores intermediate bitcode files bitcode_store_path: Option, - /// Extra linking flags for `llvm-link` + /// Extra user-provided linking flags for `llvm-link` llvm_link_flags: Option>, - /// Extra linking flags for link time optimization + /// Extra user-provided linking flags for link time optimization lto_ldflags: Option>, - /// Extra flags for bitcode generation, e.g., "-flto -fwhole-program-vtables" + /// Extra user-provided flags for bitcode generation, e.g., "-flto -fwhole-program-vtables" bitcode_generation_flags: Option>, - /// The configure only mode - is_configure_only: bool, + /// The configure only mode, which skips the bitcode generation (Default: false) + is_configure_only: Option, - /// Log level - log_level: u8, + /// Log level (Default: 0, print nothing) + log_level: Option, } impl RLLVMConfig { @@ -97,12 +97,12 @@ impl RLLVMConfig { } pub fn is_configure_only(&self) -> bool { - self.is_configure_only + self.is_configure_only.unwrap_or_default() } pub fn log_level(&self) -> Level { Level::iter() - .nth(self.log_level as usize) + .nth(self.log_level.unwrap_or_default() as usize) .unwrap_or(Level::max()) } } @@ -238,8 +238,8 @@ impl Default for RLLVMConfig { llvm_link_flags: None, lto_ldflags: None, bitcode_generation_flags: None, - is_configure_only: false, - log_level: 0, + is_configure_only: None, + log_level: None, } } }