🛠️ 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.:

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:

git submodule add git@github.com:umpire274/rust_dev_scripts.git dev_tools
git submodule update --init --recursive

or using HTTPS:

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:

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:

git submodule update --init --recursive

To update the submodule to the commit recorded in the main repository:

git submodule update --recursive

To update the submodule to the latest commit on its default branch:

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:

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:

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:

./dev_tools/scripts/build_check.sh --release

or on Windows:

.\dev_tools\scripts\build_check.ps1 --release

---

📁 Available Scripts

Script	Platform	Description
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:

Step	Description
🧹 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

Option	Description
--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)

# Full pipeline
.\build_check.ps1

# Release mode, no clean, skip tests
.\build_check.ps1 --release --skip-tests --no-clean

🐧 Linux / macOS

./build_check.sh
./build_check.sh --release --skip-tests --no-clean --quiet

---

🔢 Exit Codes

Code	Meaning
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.

Script	Purpose
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.*