# 🛠️ Rust Project Utility Scripts
This directory contains cross-platform **developer utility scripts** shared across all Rust projects.
They provide unified build checks, quality assurance, and resource verification tools.
> 📦 Intended for use as a private Git submodule, e.g.:
>
> ```bash
> git submodule add git@github.com:umpire274/rust_dev_scripts.git dev_tools
> ```
---
## 🔗 Adding This Repository as a Git Submodule
This utility toolkit is intended to be embedded inside other Rust projects as a **Git submodule**, typically under a
folder such as `dev_tools/`.
Follow the steps below to correctly add, initialize, update, or remove this submodule.
### ➕ Add the submodule to your project
From the root of your target repository:
```bash
git submodule add git@github.com:umpire274/rust_dev_scripts.git dev_tools
git submodule update --init --recursive
```
or using HTTPS:
```bash
git submodule add https://github.com/umpire274/rust_dev_scripts.git dev_tools
git submodule update --init --recursive
```
This will:
* Create the `dev_tools/` directory
* Register the submodule in `.gitmodules`
* Check out the latest commit of the shared scripts
Then commit the changes:
```bash
git add .gitmodules dev_tools/
git commit -m "Add rust_dev_scripts submodule under dev_tools/"
git push
```
---
### 🔄 Initialize or update the submodule
When cloning a repository that already contains this submodule:
```bash
git submodule update --init --recursive
```
To update the submodule to the commit recorded in the main repository:
```bash
git submodule update --recursive
```
To update the submodule to the latest commit on its default branch:
```bash
git submodule update --remote --merge
```
---
### ⬆️ Pulling the latest version of the submodule
If you want your main project to use the latest commit of `rust_dev_scripts`:
```bash
cd dev_tools
git pull origin main
cd ..
git add dev_tools
git commit -m "Update dev_tools submodule"
git push
```
---
### 🗑️ Removing the submodule (clean removal)
To fully remove the submodule from your project:
```bash
git submodule deinit -f dev_tools
git rm -f dev_tools
rm -rf .git/modules/dev_tools
git commit -m "Remove dev_tools submodule"
git push
```
---
## 📁 Recommended Folder Structure
```
your_project/
├─ src/
├─ target/
├─ dev_tools/
│ └─ scripts/
│ ├─ build_check.ps1
│ ├─ build_check.sh
│ ├─ check_icon.ps1
│ ├─ check_icon.sh
│ ├─ generate_ico.ps1
│ ├─ generate_ico.sh
│ ├─ generate_icons.ps1
│ ├─ generate_icons.sh
│ ├─ magick_tools.ps1
│ └─ magick_tools.sh
└─ .gitmodules
```
---
## 🧠 Tip
Always use the shared build-check pipeline before pushing changes:
```bash
./dev_tools/scripts/build_check.sh --release
```
or on Windows:
```powershell
.\dev_tools\scripts\build_check.ps1 --release
```
---
# 📁 Available Scripts
| **build_check.ps1** | Windows (PowerShell) | Full build + QA pipeline for Rust projects |
| **build_check.sh** | Linux / macOS | Full build + QA pipeline (POSIX-compliant) |
| **check_icon.ps1** | Windows | Verifies if an `.exe` file contains embedded icon resources |
| **check_icon.sh** | Linux / macOS | Checks embedded icons in ELF or Mach-O binaries |
| **generate_icons.ps1** | Windows | Generates multi-resolution PNG icons (16 → 1024 px) |
| **generate_icons.sh** | Linux / macOS | Same functionality as the PowerShell version |
| **generate_ico.ps1** | Windows | Builds multi-layer `.ico` files from PNG sources |
| **generate_ico.sh** | Linux / macOS | POSIX version of the ICO generator |
| **magick_tools.ps1** | Windows | ImageMagick wrapper for common operations |
| **magick_tools.sh** | Linux / macOS | POSIX version of the ImageMagick wrapper |
---
# 🚀 Build Pipeline Scripts (`build_check.*`)
These scripts execute a standardized series of Rust project quality checks:
| 🧹 **cargo clean** | Cleans previous build artifacts (optional) |
| 🏗️ **cargo build** | Builds the project in debug or release mode |
| ✨ **cargo fmt (auto-fix)** | Runs `cargo fmt --check`; auto-fixes formatting and re-checks |
| 🔍 **cargo clippy** | Lints the code; warnings are treated as errors |
| 🧪 **cargo test** | Runs all tests (optional) |
---
## ✨ Auto-Fix Formatting
Both build scripts now include enhanced formatting logic:
### 🔄 Automatic correction flow
1. Run `cargo fmt --all -- --check`
2. If formatting is correct → continue
3. If formatting fails → automatically run `cargo fmt --all`
4. Run the check again
5. If formatting is still incorrect → pipeline stops with an error
### ✔️ Advantages
* Ensures consistent formatting across all repos
* Prevents CI failures due to trivial fmt issues
* Reduces friction for contributors
* Keeps code review clean and standardized
---
## 🌐 Common CLI Options
| `--release` | Build and test in release mode |
| `--skip-tests` | Skip running the test suite |
| `--quiet` | Suppress detailed command output |
| `--verbose` | Enable verbose Cargo logging (-vv) |
| `--no-clean` | Skip the initial clean step |
| `--only-build` | Build the project and skip QA steps |
| `--time` | Display total pipeline execution time |
| `--target` | Compile for a custom Rust target triple |
---
## 🧪 Examples
### 🪟 Windows (PowerShell)
```powershell
# Full pipeline
.\build_check.ps1
# Release mode, no clean, skip tests
.\build_check.ps1 --release --skip-tests --no-clean
```
### 🐧 Linux / macOS
```bash
./build_check.sh
./build_check.sh --release --skip-tests --no-clean --quiet
```
---
## 🔢 Exit Codes
| 0 | All steps completed successfully |
| 1 | At least one step failed |
**Note:** The formatting step now performs **automatic fixing**.
It only fails if the code remains incorrectly formatted *after* the auto-fix procedure.
---
# 🖼️ Icon Verification Scripts (`check_icon.*`)
These scripts verify whether a compiled binary includes embedded icon resources.
| check_icon.ps1 | Checks Windows `.exe` metadata for embedded icons |
| check_icon.sh | Uses `file`, `otool`, or `rcedit` to inspect ELF/Mach-O binaries |
---
# 🗂️ ICO Multi-Size Generator (`generate_ico.*`)
Cross-platform scripts for creating Windows `.ico` files with multiple resolutions.
Options and usage examples are identical across platforms (POSIX / PowerShell).
---
# 🖼️ PNG Multi-Size Icon Generator (`generate_icons.*