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