Merge pull request #55 from UnionCompilerDesign/dev

Dev

Author: CalebLItalien

.cargo/config.toml

@@ -0,0 +1,2 @@
+[build]
+rustflags = ["-W", "unused-imports", "-W", "missing-docs", "-W", "unused-variables", "-W", "dead-code"]

.github/ISSUE_TEMPLATE/issue.md

@@ -0,0 +1,14 @@
+### Details
+
+### Issue Type
+- [ ] Feature
+- [ ] Bugfix
+- [ ] Documentation
+- [ ] Refactoring
+- [ ] Other:
+
+### Requirements
+
+### Dependencies
+
+### Notes

.github/README_TEMPLATE/README.md

@@ -0,0 +1,26 @@
+# [Module Name]
+
+## Overview
+This document provides details about the [Module Name] in the SafeLLVM project. The [Module Name] module is designed to [briefly describe the purpose and functionality]. 
+
+## Features
+List the main features of the module:
+- **Feature 1**:
+- **Feature 2**;
+
+## Usage
+Explain how to use the module with examples:
+
+```
+    use safe_llvm::module_name::{function1, function2};
+
+    function1();  // Example usage of function1
+    function2();  // Example usage of function2
+```
+
+Provide any necessary warnings or special instructions for using the module correctly.
+
+## FAQ
+
+## Further Information
+For further information or questions regarding the use of `[Module Name]`, feel free to contact the main contributors or raise an issue on the GitHub repository.

.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: SafeLLVM
+
+on:
+  push:
+    branches:
+      - main
+      - dev
+  pull_request:
+    branches:
+      - main
+      - dev
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v2
+
+    - name: Install Dependencies
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y ca-certificates wget curl gnupg software-properties-common build-essential cmake libfreetype6-dev libfontconfig1-dev xclip valgrind libzstd-dev
+        wget -qO - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -
+        sudo apt-add-repository "deb http://apt.llvm.org/focal/ llvm-toolchain-focal-17 main"
+        sudo apt-get update
+        sudo apt-get install -y clang-17 llvm-17 llvm-17-dev llvm-17-tools libpolly-17-dev
+
+    - name: Install Rust
+      uses: actions-rs/toolchain@v1
+      with:
+        toolchain: stable
+        profile: minimal
+        components: rustfmt, clippy
+        override: true
+
+    - name: Set Environment Variables
+      run: |
+        echo "LLVM_SYS_170_PREFIX=/usr/lib/llvm-17" >> $GITHUB_ENV
+        echo "PATH=$PATH:/root/.cargo/bin:/usr/lib/llvm-17/bin" >> $GITHUB_ENV
+
+    - name: Build Project
+      uses: actions-rs/cargo@v1
+      with:
+        command: build
+        args: --all --verbose
+
+    - name: Run Tests
+      uses: actions-rs/cargo@v1
+      with:
+        command: test
+        args: --all --verbose

.gitignore

@@ -1,7 +1,11 @@
 /Cargo.lock
 /target/
-/Dockerfile
 /app.log
 /dev_toolchain/target/
 /dev_toolchain/app.log
 /dev_toolchain/Cargo.lock
+/.vscode/
+/jit/target/
+/jit/app.log
+/ir/target/
+/ir/app.log

CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing to SafeLLVM
+
+Welcome to the SafeLLVM project! We appreciate your interest in contributing to SafeLLVM, a wrapper around **[llvm-sys](https://github.com/tari/llvm-sys.rs)** designed to serve as the backend for the Simple Instructional C99 Compiler (SICC).
+
+## Getting Started
+
+Before contributing, please make sure to familiarize yourself with the project structure and the goals of both SafeLLVM and SICC. This understanding will help you make meaningful contributions that align with the project's objectives.
+
+### Setting Up Your Development Environment
+
+1. **Install the prerequisites found in README.md**
+
+2. **Fork and clone the repository:**
+    Start by cloning the SafeLLVM repository to your local machine.
+    ```
+    git clone [email protected]:UnionCompilerDesign/safe_llvm.git
+    ```
+
+3. **Build and test the project:**
+    ```
+    cd safe_llvm
+    cargo build --all
+    cargo test --all
+    ```
+
+## Making Contributions
+
+### Reporting Bugs
+
+If you find a bug, please report it by opening a new issue on GitHub. Include as much detail as possible and please use the template found in `safe_llvm/.github/ISSUE_TEMPLATE`.
+
+### Suggesting Enhancements
+
+We welcome suggestions for improvements! If you have an idea to enhance SafeLLVM, please create an issue to discuss so we can discuss it.
+
+### Pull Requests
+
+We actively welcome your pull requests:
+
+1. Fork the repo and create your branch from `main`.
+2. If you've added code that should be tested, add tests.
+3. Ensure your code lints (use `cargo clippy`).
+4. Issue the pull request!
+
+### Coding Guidelines
+
+- Follow the [Rust style guide](https://doc.rust-lang.org/1.0.0/style/README.html).
+- Write clean, readable code and include comments where necessary.
+- Ensure that all tests pass before you make a pull request.
+
+## Recognition
+
+Contributors who make significant improvements will be recognized as "Contributors" in the project README.
+
+Thank you for your interest in contributing to SafeLLVM! We look forward to your contributions and are excited to see how the project grows and evolves with your help.

Cargo.toml

@@ -5,16 +5,32 @@ edition = "2021"
 
 [dependencies]
 llvm-sys = "170"
-mockall = "0.10.2"
 slog = "2.7"
 slog-async = "2.6"
 slog-term = "2.8"
 slog-json = "2.4"
 
+ir = { path = "./ir" }
+analysis = { path = "./analysis" }
+common = { path = "./common" }
+jit = { path = "./jit" }
+logging = { path = "./logging" }
+
 [dev-dependencies]
 llvm-sys = "170"
-mockall = "0.10.2"
 slog = "2.7"
 slog-async = "2.6"
 slog-term = "2.8"
-slog-json = "2.4"
+slog-json = "2.4"
+
+[workspace]
+members = [
+    "./ir",
+    "./analysis",
+    "./common",
+    "./jit",
+    "./logging",
+]
+
+[build-dependencies]
+pkg-config = "0.3"

Dockerfile

@@ -0,0 +1,37 @@
+FROM ubuntu:20.04
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+WORKDIR /usr/src/safe_llvm
+
+RUN apt-get update && \
+    apt-get install -y \
+    ca-certificates \
+    wget \
+    curl \
+    gnupg \
+    software-properties-common \
+    build-essential \
+    cmake \
+    libfreetype6-dev \
+    libfontconfig1-dev \
+    xclip \
+    valgrind \
+    libzstd-dev && \
+    wget -qO - https://apt.llvm.org/llvm-snapshot.gpg.key | apt-key add - && \
+    apt-add-repository "deb http://apt.llvm.org/focal/ llvm-toolchain-focal-17 main" && \
+    apt-get update && \
+    apt-get install -y clang-17 llvm-17 llvm-17-dev llvm-17-tools libpolly-17-dev && \
+    rm -rf /var/lib/apt/lists/*
+
+RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
+
+ENV PATH="/root/.cargo/bin:/usr/lib/llvm-17/bin:$PATH"
+
+ENV LLVM_SYS_170_PREFIX="/usr/lib/llvm-17"
+
+COPY . .
+
+RUN cargo build --verbose
+
+CMD ["bash"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2024] Caleb L'Italien
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,47 @@
+# Safe LLVM
+
+## Contributors
+Caleb L'Italien, John Daly
+
+## Overview
+SafeLLVM is a Rust-based library designed to provide a safe and user-friendly interface to llvm-sys. It is developed specifically for the Simple Instructional C99 Compiler (SICC). The library aims to encapsulate the complexity of LLVM’s API, making it accessible for undergraduate work.
+
+## Disclaimer
+
+SafeLLVM is designed for educational purposes and is not intended for production use. If you are looking for a production-level LLVM crate for Rust projects, consider using the following crates:
+
+- **[Inkwell](https://github.com/TheDan64/inkwell)**
+- **[llvm-ir](https://github.com/cdisselkoen/llvm-ir)**
+
+## Project Structure
+- `analysis/`: Tools for performing various analyses on LLVM IR.
+- `common/`: Common utilities and helper functions shared across the project.
+- `ir/`: Manages the creation of LLVM Intermediate Representation (IR).
+- `jit/`: Implements an ExecutionEngine for execution of pre-compiled LLVM modules.
+- `logging/`: Handles logging functionalities for debugging.
+
+## Getting Started
+
+### Usage
+To use SafeLLVM in your Rust projects, you can include it directly via Cargo by adding it as a dependency in your `Cargo.toml` file using its GitHub repository URL. Here's how to do it:
+
+1. **Add SafeLLVM as a dependency in your `Cargo.toml`:**
+    ```toml
+    [dependencies]
+    safe_llvm = { git = "[email protected]:UnionCompilerDesign/safe_llvm.git", branch = "main" }
+    ```
+
+2. **Refer to specific `README`s in each directory:**
+For more specific usage details, please refer to the READMEs located in each directory. These documents provide further instructions and examples on how to use the components within SafeLLVM.
+
+### How to Contribute
+Contributions are welcome! Please refer to the `CONTRIBUTING` file for guidelines on how to contribute.
+
+### License
+Distributed under the MIT License. See the `LICENSE` file for more details.
+
+### Acknowledgements
+Special thanks to Professor Aaron Cass of Union College for his guidance and expertise throughout the development of this project.
+
+### Contact
+For any inquiries, contact Caleb L'Italien at [email protected].

analysis/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "analysis"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+name = "analysis"
+path = "src/lib.rs"
+
+[dependencies]
+llvm-sys = "170"
+common = { path = "../common" }

analysis/README.md

@@ -0,0 +1,31 @@
+# Analysis Tools for SafeLLVM
+
+## Overview
+The Analysis module is a component of the SafeLLVM project for checking the correctness of LLVM modules and functions.
+
+## Features
+- **Module Validator**: Determines if an LLVM module is well-formed.
+- **Function Validator**: Determines if an LLVM function is well-formed.
+
+## Usage
+1. Initialize the Validator with a module: Create a Validator instance by passing a protected reference to the LLVM module you wish to validate.
+2. Validate Functions or Modules: 
+   - To validate an LLVM module, call the is_valid_module() method on your Validator instance:
+        ```
+        let validator = Validator::new(module_pointer);
+        let is_module_valid = validator.is_valid_module();
+        eprintln!("Module is valid: ", is_module_valid);
+        ```
+   - Similarly, to validate a specific function within a module, provide a protected reference to the LLVM function to the is_valid_function() method:
+        ```
+        let validator = Validator::new(module_pointer);
+        let is_function_valid = validator.is_valid_function(function_pointer);
+        eprintln!("Function is valid: ", is_function_valid);
+        ```
+
+Provide any necessary warnings or special instructions for using the module correctly, such as ensuring that pointers are correctly managed and threads are safely handled due to the use of Arc and RwLock.
+
+## FAQ
+
+## Further Information
+For further information or questions regarding the use of the analysis tools, feel free to contact the main contributors or raise an issue on the GitHub repository.

analysis/src/lib.rs

@@ -0,0 +1,3 @@
+//! Analysis Toolchain.
+
+pub mod validator;