changed file structure and added run.sh to run CI

Author: vikashsiwach

.gitignore

@@ -1,14 +1,34 @@
-# Generated by Cargo
-# will have compiled files and executables
-debug/
+# ==============================
+# Rust (global)
+# ==============================
+
+# Compiled files
 target/
+debug/
 
-# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
-# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
+# Cargo lock (keep ignored for libraries)
 Cargo.lock
 
-# These are backup files generated by rustfmt
+# Rustfmt backups
 **/*.rs.bk
 
-# MSVC Windows builds of rustc generate these, which store debugging information
+# Windows debug symbols
 *.pdb
+
+# ==============================
+# Example-specific (IMPORTANT)
+# ==============================
+
+# C++ compiled binary
+example
+
+# Any compiled outputs
+*.out
+*.exe
+*.o
+
+# Rust build inside subfolder
+examples/incompatible_allocators/rust/target/
+
+# macOS junk files
+.DS_Store

examples/build-tool-template/main.cpp

@@ -0,0 +1,14 @@
+// A C++ program that prints a message to the terminal, from C++ and Rust
+
+#include <iostream>
+
+// Declare the Rust function so C++ can call it
+extern "C" void print_rust_message(void);
+
+// Prints a run message to the terminal, from C++ and Rust
+int main(void) {
+    // Replace this with your C++ code
+    std::cout << "C++ code ran while running the build-tool-template example" << std::endl;
+    print_rust_message();
+    return 0;
+}

examples/build-tool-template/run.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# ^ support bash that's not in the standard `/bin` path
+
+# A script that builds, tests, and runs the build-tool-template example
+
+# This file needs to be executable:
+# - on Linux or macOS, use `chmod +x run.sh` then `git add run.sh`
+# - on Windows, use `git add --chmod=+x run.sh` or `git update-index --chmod=+x run.sh`
+
+# bash "strict mode": fail the script if any command fails, or any variable is unset when used
+set -euo pipefail
+
+# Replace unset `$CXX` variable with the empty string
+if [ -z "${CXX:-}" ]; then
+  echo "CXX environment variable is empty or unset, using the default 'c++' compiler"
+  CXX=c++
+fi
+
+# If the script is run outside the example directory, change to the expected location
+cd "$(dirname "$0")"
+
+# Replace the lines below with your build tool command
+echo "Shell script ran while running the build-tool-template example"
+# Build the Rust library
+pushd rust-library
+cargo build
+popd
+# Build and run the C++ and Rust binary
+# This order is important, dependencies must be later than code that depends on them
+$CXX main.cpp rust-library/target/debug/librust_library.a -o main
+./main

examples/build-tool-template/rust-library/Cargo.lock

@@ -0,0 +1,11 @@
+[package]
+name = "rust-library"
+version = "0.1.0"
+edition = "2024"
+
+# Build a static C/C++ library
+[lib]
+crate-type = ["staticlib"]
+
+# Add Rust dependencies here
+[dependencies]

examples/build-tool-template/rust-library/Cargo.toml

@@ -0,0 +1,34 @@
+//! A Rust library that prints a message to the terminal
+
+/// Prints a Rust run message to the terminal
+///
+/// # Safety
+///
+/// The entire binary must only have one function with this un-mangled name.
+/// Callers must use the C calling convention to call this function.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn print_rust_message() {
+    // Replace this with your Rust code
+    println!("Rust code ran while running the build-tool-template example");
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io::Write;
+
+    // Optional: Replace this with your Rust tests, if you need any
+    //
+    /// Test printing a Rust message to the terminal
+    #[test]
+    fn test_rust_message() {
+        // Rust tests hide test output, here's one way to print it anyway
+        writeln!(
+            &mut std::io::stderr(),
+            "Rust code ran while testing the build-tool-template example",
+        )
+        .expect("failed to write to stderr");
+
+        unsafe { print_rust_message() };
+    }
+}