cargo_compiler_interrupts/
lib.rs

1//! [![crates.io](https://img.shields.io/crates/v/cargo-compiler-interrupts.svg)][crates.io]
2//! [![docs.rs](https://docs.rs/cargo-compiler-interrupts/badge.svg)][docs.rs]
3//! [![license](https://img.shields.io/crates/l/cargo-compiler-interrupts.svg)][license]
4//!
5//! `cargo-compiler-interrupts` provides you a seamless way to integrate the
6//! [Compiler Interrupts][compiler-interrupts-paper] to any Rust packages.
7//! Check out the Compiler Interrupts [main repository][compiler-interrupts] for more info.
8//!
9//! ## Requirements
10//!
11//! * [Rust 1.45.0 - 1.64.0][rust] and [LLVM 9 - 14][llvm] are required. 
12//! Both must have the same LLVM version.
13//! Later LLVM versions are currently not supported due to the new LLVM pass manager.
14//! * You can check the LLVM version from Rust and LLVM toolchains by running `rustc -vV`
15//! and `llvm-config --version` respectively.
16//! * x86-64 architecture with Linux or macOS is highly recommended.
17//! Other architectures and platforms have not been tested and not guaranteed to work.
18//!
19//! ## Installation
20//!
21//! `cargo-compiler-interrupts` can be installed via `cargo install`.
22//!
23//! ``` sh
24//! cargo install cargo-compiler-interrupts
25//! ```
26//!
27//! You can also fetch the repo and install using `--path`.
28//!
29//! ``` sh
30//! git clone https://github.com/bitslab/cargo-compiler-interrupts
31//! cargo install --path ./cargo-compiler-interrupts
32//! ```
33//!
34//! ## Getting started
35//!
36//! `cargo-compiler-interrupts` provides three binaries:
37//!
38//! ``` sh
39//! cargo-lib-ci install    # install the CI library
40//! cargo-build-ci          # build and integrate CI to the binary
41//! cargo-run-ci            # run the CI-integrated binary
42//! ```
43//!
44//! * `cargo-lib-ci` — manage the Compiler Interrupts library.
45//! * `cargo-build-ci` — build and integrate the Compiler Interrupts to the package.
46//! * `cargo-run-ci` — run the integrated binary.
47//! You can specify which binary to run by passing `--bin <BINARY>`.
48//!
49//! Run `cargo-lib-ci install` to install the Compiler Interrupts library first.
50//! Before running `cargo-build-ci`, add the Compiler Interrupts API package as the dependency for
51//! your Cargo package and registers the Compiler Interrupts handler in your program.
52//! Compiler Interrupts API is provided through the [`compiler-interrupts`][compiler-interrupts-rs]
53//! package.
54//!
55//! ``` rust
56//! fn interrupt_handler(ic: i64) {
57//!     println!("Compiler interrupt called with instruction count: {}", ic);
58//! }
59//!
60//! unsafe {
61//!     compiler_interrupts::register(1000, 1000, interrupt_handler);
62//! }
63//! ```
64//!
65//! For more detailed usages and internals, run the command with `--help` option and
66//! check out the **[documentation]**.
67//!
68//! ## Contribution
69//!
70//! All issue reports, feature requests, pull requests and GitHub stars are welcomed
71//! and much appreciated. Issues relating to the Compiler Interrupts library
72//! should be reported to the [main repository][compiler-interrupts].
73//!
74//! ## Author
75//!
76//! Quan Tran ([@quanshousio][quanshousio])
77//!
78//! ## Acknowledgements
79//!
80//! * My advisor [Jakob Eriksson][jakob] for the enormous support for this project.
81//! * [Nilanjana Basu][nilanjana] for implementing the Compiler Interrupts.
82//!
83//! ## License
84//!
85//! `cargo-compiler-interrupts` is available under the MIT license.
86//! See the [LICENSE][license] file for more info.
87//!
88//! [crates.io]: https://crates.io/crates/cargo-compiler-interrupts
89//! [docs.rs]: https://docs.rs/cargo-compiler-interrupts
90//! [license]: https://github.com/bitslab/cargo-compiler-interrupts/blob/main/LICENSE
91//! [documentation]: https://github.com/bitslab/cargo-compiler-interrupts/blob/main/DOCUMENTATION.md
92//! [compiler-interrupts]: https://github.com/bitslab/CompilerInterrupts
93//! [compiler-interrupts-rs]: https://github.com/bitslab/compiler-interrupts-rs
94//! [compiler-interrupts-paper]: https://dl.acm.org/doi/10.1145/3453483.3454107
95//! [rust]: https://www.rust-lang.org/tools/install
96//! [llvm]: https://releases.llvm.org
97//! [quanshousio]: https://www.quanshousio.com
98//! [jakob]: https://www.linkedin.com/in/erikssonjakob
99//! [nilanjana]: https://www.linkedin.com/in/nilanjana-basu-99027959
100
101#![warn(
102    missing_copy_implementations,
103    missing_debug_implementations,
104    missing_docs,
105    trivial_casts,
106    trivial_numeric_casts,
107    unsafe_code,
108    unstable_features,
109    unused_extern_crates,
110    unused_import_braces,
111    unused_qualifications,
112    clippy::cast_possible_truncation,
113    clippy::cast_possible_wrap,
114    clippy::cast_precision_loss,
115    clippy::cast_sign_loss,
116    clippy::clone_on_ref_ptr,
117    clippy::missing_docs_in_private_items,
118    clippy::mut_mut,
119    clippy::print_stdout,
120    clippy::unseparated_literal_suffix,
121    clippy::unwrap_used
122)]
123
124/// Compiler Interrupts result.
125type CIResult<T> = anyhow::Result<T>;
126
127mod args;
128mod cargo;
129mod config;
130mod error;
131mod llvm;
132pub mod ops;
133mod paths;
134mod util;
135
136/// Name of the cargo-build-ci.
137const BUILD_CI_BIN_NAME: &str = "cargo-build-ci";
138
139/// Name of the cargo-run-ci.
140const RUN_CI_BIN_NAME: &str = "cargo-run-ci";
141
142/// Name of the cargo-lib-ci.
143const LIB_CI_BIN_NAME: &str = "cargo-lib-ci";
cargo_compiler_interrupts/lib.rs

cargo_compiler_interrupts/
lib.rs
