# 🛠️ 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 tools_private
> ```

---

## 🔗 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

| Script                 | Platform             | Description                                                                                            |
|------------------------|----------------------|--------------------------------------------------------------------------------------------------------|
| **build_check.ps1**    | Windows (PowerShell) | Full build + QA pipeline for Rust projects                                                             |
| **build_check.sh**     | Linux / macOS        | POSIX-compliant version of the same pipeline                                                           |
| **check_icon.ps1**     | Windows (PowerShell) | Verifies if an `.exe` file contains embedded icon resources                                            |
| **check_icon.sh**      | Linux / macOS        | Checks for embedded icons in ELF or Mach-O binaries using `rcedit`, `file`, or `otool` where available |
| **generate_icons.ps1** | Windows (PowerShell) | Generates multi-resolution PNG icons (16 → 1024 px) from a source image. All parameters are mandatory. |
| **generate_icons.sh**  | Linux / macOS        | Same functionality as generate_icons.ps1, implemented in Bash. All parameters are mandatory.           |
| **generate_ico.ps1**   | Windows (PowerShell) | Builds a multi-layer .ico file from a PNG source image. All parameters are mandatory.                  |
| **generate_ico.sh**    | Linux / macOS        | Bash version of the multi-layer .ico generator. All parameters are mandatory.                          |
| **magick_tools.ps1**   | Windows (PowerShell) | ImageMagick utility script for batch image processing tasks                                            |
| **magick_tools.sh**    | Linux / macOS        | POSIX version of the ImageMagick utility script                                                        |

---

## 🚀 Build Pipeline Scripts (`build_check.*`)

These scripts execute a standardized series of Rust project quality checks:

| Step                | Description                                             |
|---------------------|---------------------------------------------------------|
| 🧹 **cargo clean**  | Cleans old build artifacts (optional)                   |
| 🏗️ **cargo build** | Builds the project (debug or release)                   |
| ✨ **cargo fmt**     | Checks code formatting                                  |
| 🔍 **cargo clippy** | Runs linting checks with all warnings treated as errors |
| 🧪 **cargo test**   | Executes the test suite (optional)                      |

### Common CLI Options

| Option         | Description                         |
|----------------|-------------------------------------|
| `--release`    | Build and test in release mode      |
| `--skip-tests` | Skip running the test suite         |
| `--quiet`      | Suppress detailed command output    |
| `--no-clean`   | Skip the initial `cargo clean` step |

### Examples

#### 🪟 Windows (PowerShell or CMD)

```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

| Code | Meaning                          |
|:----:|:---------------------------------|
|  0   | All steps completed successfully |
|  1   | One or more steps failed         |

---

## 🖼️ Icon Verification Scripts (`check_icon.*`)

These scripts verify that a compiled binary includes embedded icon resources (typically used to confirm correct
packaging for Windows .exe or macOS .app bundles).

| Script         | Function                                                            |
|----------------|---------------------------------------------------------------------|
| check_icon.ps1 | Uses PowerShell + Get-Command or rcedit to inspect .exe metadata.   |
| check_icon.sh  | Uses file, otool, or rcedit (if installed) to inspect binary icons. |

### Example

#### 🪟 Windows (PowerShell)

```powershell
# Windows
.\check_icon.ps1 -Path ".\target\release\rbackup.exe"
```

#### 🐧 Linux / macOS

```bash
# Linux / macOS
./check_icon.sh ./target/release/rbackup
```

If the icon is correctly embedded, the script prints a ✅ confirmation message; otherwise, it displays a ⚠️ warning
suggesting to check your .rc or build.rs setup.

---

## 🗂️ ICO Multi-Size Generator (generate_ico.*)

Cross-platform scripts for generating a multi-layer .ico file from a PNG source image. Used to embed application icons
into Windows executables and installers.

| Script           | Function                                       |
|------------------|------------------------------------------------|
| generate_ico.ps1 | PowerShell script for Windows multi-size ICO   |
| generate_ico.sh  | POSIX shell script to build ICO on Linux/macOS |

### ✨ Available Options (all mandatory)

| Option               | Description                              |
|----------------------|------------------------------------------|
| --input-dir <path>   | Directory containing the input PNG       |
| --output-dir <path>  | Directory where the .ico will be written |
| --input-file <name>  | Source PNG file                          |
| --output-file <name> | Output ICO filename                      |
| --sizes <list>       | Comma-separated list of icon sizes       |
| --magick-path <path> | Path to magick.exe or magick binary      |
| --verbose            | Enable verbose logging                   |
| --help               | Display usage instructions               |

### Example Usage

#### 🪟 Windows (PowerShell)

```powershell
pwsh ./dev_tools/generate_ico.ps1 `
    --input-dir "<assets_dir>" `
    --output-dir "<assets_dir>" `
    --input-file "<source_img.png>" `
    --output-file "<dest_img.ico>" `
    --sizes "1024,512,256,128,64,48,32,16" `
    --magick-path "<path\to\ImageMagick_dir>\magick.exe" `
    --verbose
```

#### 🐧 Linux / macOS

```bash
./dev_tools/generate_ico.sh \
    --input-dir <assets_dir> \
    --output-dir <assets_dir> \
    --input-file <source_img.png> \
    --output-file <dest_img.ico> \
    --sizes 1024,512,256,128,64,48,32,16 \
    --magick-path <path/to/ImageMagick_dir_installation>/magick \
    --verbose
```

---

## 🖼️ PNG Multi-Size Icon Generator (generate_icons.*)

Cross-platform scripts for generating multi-resolution PNG icons (16 → 1024 px) from a single source image.

| Script             | Function                                        |
|--------------------|-------------------------------------------------|
| generate_icons.ps1 | PowerShell script for PNG batch size generation |
| generate_icons.sh  | POSIX shell version for Linux / macOS           |

### ✨ Available Options (all mandatory)

| Option               | Description                                      |
|----------------------|--------------------------------------------------|
| --input-dir <path>   | Directory containing the input PNG               |
| --output-dir <path>  | Directory where resized PNGs will be written     |
| --input-file <name>  | Source file name (default: rnetbench.png)        |
| --sizes <list>       | Comma-separated list of sizes (e.g. 1024,512...) |
| --magick-path <path> | Custom path to magick/magick.exe                 |
| --verbose            | Enable verbose logging                           |
| --help               | Show usage example and exit                      |

### Example Usage

#### 🪟 Windows (PowerShell)

```powershell
pwsh ./dev_tools/generate_icons.ps1 `
    --input-dir "<assets_dir>" `
    --output-dir "<assets_dir>" `
    --input-file "<source_img.png>" `
    --sizes "1024,512,256,128,64,48,32,16" `
    --magick-path "<path\to\ImageMagick_dir>\magick.exe" `
    --verbose
```

#### 🐧 Linux / macOS

```bash
./dev_tools/generate_icons.sh \
    --input-dir <assets_dir> \
    --output-dir <assets_dir> \
    --input-file <source_img.png> \
    --sizes 1024,512,256,128,64,48,32,16 \
    --magick-path <path/to/ImageMagick_dir_installation>/magick \
    --verbose
```

---

## 🖼️ ImageMagick Utility Scripts (`magick_tools.*`)

Cross-platform wrapper around ImageMagick 7+ for common asset-processing operations.

| Script           | Function                                     |
|------------------|----------------------------------------------|
| magick_tools.ps1 | PowerShell script for batch image processing |
| magick_tools.sh  | POSIX shell version for Linux / macOS        |

### ✨ Available Actions

| Action    | Description                                                 |
|-----------|-------------------------------------------------------------|
| identify	 | Show image metadata (dimensions, format, channels)          |
| convert   | Convert file between formats (output inferred by extension) |
| resize    | Resize image (--width × --height)                           |
| optimize  | Strip metadata, set interlacing, recompress (quality 85%)   |
| make-ico  | Create multi-size .ico from a single source image           |
| extract   | Extract all icon layers into separate files                 |

### ⚙️ Common Options

| Option            | Description                                        |
|-------------------|----------------------------------------------------|
| --input <path>    | Input file                                         |
| --output <path>   | Output file or directory                           |
| --width, --height | Resize dimensions                                  |
| --sizes <list>    | Comma-separated list of icon sizes (e.g. 16,32,48) |
| --colors <n>      | Palette quantization for ICO generation            |
| --no-dither       | Disable dithering when using --colors              |
| --prefix <name>   | Prefix for extracted layer filenames               |
| --format <ext>    | Output format for extraction (png, jpg, webp)      |
| --magick <path>   | Custom path to magick.exe or magick binary         |
| --verbose         | Enable verbose logging                             |
| --help            | Display usage and exit                             |

### Example Usage

#### 🪟 Windows (PowerShell)

```powershell
# Identify
pwsh magick_tools.ps1 --action identify --input assets/logo.ico

# Convert PNG to WEBP
pwsh magick_tools.ps1 --action convert --input logo.png --output logo.webp

# Resize
pwsh magick_tools.ps1 --action resize --input img.png --output img_256.png --width 256

# Optimize JPEG
pwsh magick_tools.ps1 --action optimize --input photo.jpg --output photo_opt.jpg

# Build multi-size ICO
pwsh magick_tools.ps1 --action make-ico --input logo.png --output favicon.ico --sizes 16,32,48,64 --colors 256 --no-dither

# Extract all icon layers as WEBP
pwsh magick_tools.ps1 --action extract --input favicon.ico --output layers --prefix icon --format webp
```

#### 🐧 Linux / macOS

```bash
# Identify
./magick_tools.sh --action identify --input assets/logo.ico

# Convert PNG to WEBP
./magick_tools.sh --action convert --input logo.png --output logo.webp

# Resize
./magick_tools.sh --action resize --input img.png --output img_256.png --width 256

# Optimize JPEG
./magick_tools.sh --action optimize --input photo.jpg --output photo_opt.jpg

# Build multi-size ICO
./magick_tools.sh --action make-ico --input logo.png --output favicon.ico --sizes 16,32,48,64 --colors 256 --no-dither

# Extract all icon layers as WEBP
./magick_tools.sh --action extract --input favicon.ico --output layers --prefix icon --format webp

```

---

## ⚙️ Cross-Platform Consistency

All scripts follow these conventions:

- UTF-8 encoding with Unicode emoji for visual clarity
- Identical parameter names and behavior across platforms
- Colorless emoji output (safe for legacy terminals)
- Clean exit on first failure (set -e or errorlevel checks)
- Human-readable output suitable for CI logs

---

## 🧠 Recommended Usage

1. Add this submodule under tools_private/scripts/.
2. Run the appropriate script before every commit or CI push:

    ```bash
    ./tools_private/scripts/build_check.sh --release
    ```

3. For Windows projects, verify your icons:

   ```powershell
   .\tools_private\scripts\check_icon.ps1 -Path .\target\release\myapp.exe
   ```

---

## 📜 License & Credits

All scripts © 2025 **Alessandro Maestri**.
Released under the MIT License for educational and private use across personal Rust projects.