WIC Editor

Repository: https://github.com/DynamicDevices/wic-editor

A powerful tool for modifying WIC (OpenEmbedded Image Creator) images used in embedded Linux development. Originally designed for NXP i.MX8MM EVK boards using Yocto Project builds, but compatible with any WIC-based embedded Linux system.

About WIC Images: The name "WIC" is derived from OpenEmbedded Image Creator (oeic). WIC is a standalone utility that provides flexible partitioning functionality for OpenEmbedded build artifacts, based on Redhat kickstart syntax.

Overview

This script allows you to unpack a WIC image (compressed or uncompressed), add custom files to the root filesystem, and repackage it for flashing with tools like UUU (Universal Update Utility).

Features

Flexible input/output: Handles both compressed (.wic.gz) and uncompressed (.wic) images
Advanced partition detection: Multiple methods to identify and select target partitions
Intelligent file conflict handling: Detects and manages file overwrites with multiple resolution options
File deletion capabilities: Remove unwanted files before adding new ones
Safe operation: Uses loop devices for safe image manipulation
Permission preservation: Maintains file permissions and directory structure
Interactive and automated modes: Supports both manual review and automated deployment
Comprehensive partition analysis: Detailed information about all partitions in WIC images
Error handling: Comprehensive error checking and automatic cleanup
UUU integration: Optimised for NXP UUU flashing workflow
Detailed reporting: Shows exactly what files were added, modified, or deleted

Requirements

System Requirements

Linux-based operating system
sudo privileges (required for mounting filesystems)
Sufficient disk space (approximately 3x the size of your WIC image)

Required Tools

The following tools must be installed on your system:

gunzip / gzip (usually part of gzip package)
losetup (usually part of util-linux package)
parted (disk partitioning tool)
mount / umount (filesystem mounting tools)
blkid (block device identification tool)

Installation on Ubuntu/Debian

sudo apt-get update
sudo apt-get install gzip util-linux parted mount

Installation on CentOS/RHEL/Fedora

# CentOS/RHEL
sudo yum install gzip util-linux parted

# Fedora
sudo dnf install gzip util-linux parted

Usage

Basic Syntax

./wic-editor.sh -i <input_wic[.gz]> -o <output_wic[.gz]> [-d <custom_files_dir>] [-p <partition>] [-m <mode>] [-r <files_to_delete>] [-f] [-y]

Options

-i: Input WIC image file (compressed .wic.gz or uncompressed .wic)
-o: Output WIC image file (compressed .wic.gz or uncompressed .wic)
-d: Directory containing custom files to add (default: custom_files)
-p: Target partition (number, label, or 'list' to show available partitions)
-m: Partition selection mode: auto, manual, largest, label, filesystem
-r: Comma-separated list of files/directories to delete from target partition
-f: Force overwrite existing files without prompting
-y: Answer 'yes' to all prompts (non-interactive mode)
-h: Show help message

Partition Selection Modes

auto (default): Find largest ext4 partition
manual: Interactively select partition
largest: Select largest partition regardless of filesystem
label: Select partition by label (use with -p)
filesystem: Select partition by filesystem type (use with -p)

Examples

Getting Started with Unknown WIC Images

# First, list all partitions to understand the structure
sudo ./wic-editor.sh -i unknown-image.wic -p list

# Sample output shows:
# Partition 1: boot (FAT32, 100MB)
# Partition 2: rootfs (ext4, 2GB) 
# Partition 3: data (ext4, 1GB)

Basic Usage

# Auto-detect target partition (works for most images)
sudo ./wic-editor.sh -i input.wic -o output.wic

# With custom files directory
sudo ./wic-editor.sh -i input.wic -o output.wic -d my_custom_files

Partition Selection

# Select specific partition by number
sudo ./wic-editor.sh -i input.wic -o output.wic -p 2

# Interactive partition selection
sudo ./wic-editor.sh -i input.wic -o output.wic -m manual

# Select by partition label
sudo ./wic-editor.sh -i input.wic -o output.wic -m label -p rootfs

# Select by filesystem type
sudo ./wic-editor.sh -i input.wic -o output.wic -m filesystem -p ext4

# Select largest partition (any filesystem)
sudo ./wic-editor.sh -i input.wic -o output.wic -m largest

File Deletion

# Delete specific files before adding new ones
sudo ./wic-editor.sh -i input.wic -o output.wic -r "/etc/old_config.conf,/var/log/debug.log"

# Delete with wildcards
sudo ./wic-editor.sh -i input.wic -o output.wic -r "/tmp/*,/var/cache/*"

# Delete directories
sudo ./wic-editor.sh -i input.wic -o output.wic -r "/opt/old_app"

# Combined deletion and addition
sudo ./wic-editor.sh -i input.wic -o output.wic -r "/etc/hostname,/var/log/*" -d new_files

For NXP i.MX8MM EVK (UUU workflow)

# Auto-detect (typical usage)
sudo ./wic-editor.sh -i imx-image-full-imx8mmevk.wic -o imx-image-full-imx8mmevk-modified.wic

# List partitions first to understand structure
sudo ./wic-editor.sh -i imx-image-full-imx8mmevk.wic -p list

# Select specific partition
sudo ./wic-editor.sh -i imx-image-full-imx8mmevk.wic -o imx-image-full-imx8mmevk-modified.wic -p 2

# Clean up old files and add new ones
sudo ./wic-editor.sh -i imx-image-full-imx8mmevk.wic -o imx-image-full-imx8mmevk-modified.wic \
  -r "/etc/hostname,/var/log/*" -d my_custom_files -f

With compressed images

# Compressed to compressed
sudo ./wic-editor.sh -i rootfs.wic.gz -o rootfs_modified.wic.gz -p 2

# Compressed to uncompressed with partition selection
sudo ./wic-editor.sh -i rootfs.wic.gz -o rootfs_modified.wic -m manual

# Uncompressed to compressed with file deletion
sudo ./wic-editor.sh -i rootfs.wic -o rootfs_modified.wic.gz -r "/tmp/*"

File Conflict and Automation

# Interactive mode (default) - prompts for each file conflict
sudo ./wic-editor.sh -i input.wic -o output.wic -p 2

# Force overwrite all conflicting files
sudo ./wic-editor.sh -i input.wic -o output.wic -p 2 -f

# Non-interactive mode - automatically overwrites conflicting files
sudo ./wic-editor.sh -i input.wic -o output.wic -p 2 -y

# Fully automated operation
sudo ./wic-editor.sh -i input.wic -o output.wic -p 2 -f -y

Setup Instructions

1. Download and Setup Script

# Make the script executable
chmod +x wic_modify.sh

2. Prepare Custom Files

Create a directory structure that mirrors where you want files to be placed in the root filesystem:

mkdir custom_files

Example directory structure:

custom_files/
├── etc/
│   ├── my_config.conf
│   └── systemd/
│       └── system/
│           └── my_service.service
├── usr/
│   └── local/
│       └── bin/
│           └── my_script.sh
├── home/
│   └── root/
│       └── my_file.txt
└── opt/
    └── my_application/
        ├── app_binary
        └── config/
            └── app.conf

3. Run WIC Editor

# Interactive mode (default) - prompts for file conflicts
sudo ./wic-editor.sh -i your_image.wic -o your_image_modified.wic -d custom_files

# Automated mode - overwrites all conflicts
sudo ./wic-editor.sh -i your_image.wic -o your_image_modified.wic -d custom_files -f -y

# Force overwrite mode - overwrites conflicts but still shows progress
sudo ./wic-editor.sh -i your_image.wic -o your_image_modified.wic -d custom_files -f

Note: WIC Editor requires root privileges to mount filesystems and manage loop devices. Always run with sudo.

4. Update UUU Script

If using with NXP UUU tool, update your UUU script file (e.g., uuu.auto-imx8mmevk):

# Change this line:
FB: flash -raw2sparse all imx-image-full-imx8mmevk.wic

# To:
FB: flash -raw2sparse all imx-image-full-imx8mmevk-modified.wic

Script Workflow

Input validation: Checks if input files exist and required tools are available
Image preparation: Decompresses input if needed, creates working copy
Partition analysis: Uses parted to examine WIC image structure
Loop device setup: Creates loop device for safe image manipulation
Partition detection/selection: Automatically finds or interactively selects target partition
Filesystem mounting: Mounts target partition for file operations
File deletion: Removes specified files/directories if requested
File conflict detection: Scans for existing files that would be overwritten
File addition: Copies custom files with conflict resolution options
Cleanup and packaging: Unmounts filesystem, detaches loop device, creates output image
Compression: Applies compression if output filename ends with .gz

Partition Detection and Selection

WIC Editor provides multiple ways to identify and select the target partition for modification:

Automatic Detection (Default)

Scans all partitions in the WIC image
Finds the largest ext4 partition
Assumes this is the root filesystem
Works for 90% of embedded Linux images

Interactive Selection

Shows detailed information about all partitions
Displays partition number, size, filesystem type, and label
Allows you to choose the appropriate partition
Confirms selection before proceeding

Specific Selection Methods

By number: Direct partition number specification
By label: Searches for partition with specific label
By filesystem: Finds first partition with specified filesystem type
Largest: Selects largest partition regardless of filesystem

Partition Information Display

When listing partitions, you'll see:

Partition 1:
  Device: /dev/loop0p1
  Size: 100MB
  Filesystem: vfat
  Label: boot
  UUID: 1234-5678

Partition 2:
  Device: /dev/loop0p2
  Size: 2GB
  Filesystem: ext4
  Label: rootfs
  UUID: abcd-ef12-3456-7890

File Conflict Handling

The script intelligently handles file conflicts when custom files would overwrite existing files in the WIC image:

Interactive Mode (Default)

When a file conflict is detected, the script will:

Show information about both files (existing and new)
Present options:
- Overwrite existing file: Replace with your custom file
- Keep existing file: Skip copying your custom file
- Show file differences: Display diff between files (if available)
- Abort operation: Stop the entire process

Non-Interactive Modes

Force mode (-f): Automatically overwrites all conflicting files
Non-interactive mode (-y): Automatically answers 'yes' to all prompts
Combined (-f -y): Fully automated operation

Conflict Resolution Examples

Interactive Session

File conflict detected: etc/hostname
  Existing file: /mnt/wic_mount/etc/hostname
  New file: ../custom_files/etc/hostname
  Existing file info:
    -rw-r--r-- 1 root root 12 Jan 15 10:30 /mnt/wic_mount/etc/hostname
  New file info:
    -rw-r--r-- 1 user user 15 Jan 20 14:45 ../custom_files/etc/hostname
  Options:
    1) Overwrite existing file
    2) Keep existing file (skip)
    3) Show file differences
    4) Abort operation
  Choose option [1-4]: 3
  File differences:
    --- /mnt/wic_mount/etc/hostname
    +++ ../custom_files/etc/hostname
    @@ -1 +1 @@
    -imx8mmevk
    +my-custom-hostname
  Choose option [1-4]: 1
  Action: Overwriting existing file

Summary Report

At the end of the operation, you'll see a summary:

File operation summary:
  Files copied: 15
  Files skipped: 2

Common Use Cases

Exploring Unknown WIC Images

# First step: understand the partition structure
sudo ./wic-editor.sh -i unknown-image.wic -p list

# Once you know the layout, select appropriate partition
sudo ./wic-editor.sh -i unknown-image.wic -o modified.wic -p 2

System Configuration with Cleanup

# Remove old configs and add new ones
sudo ./wic-editor.sh -i system.wic -o updated.wic \
  -r "/etc/old_config.conf,/etc/deprecated/*" \
  -d new_system_configs

Application Deployment

# Clean deployment: remove old app and install new version
sudo ./wic-editor.sh -i base.wic -o deployed.wic \
  -r "/opt/old_app" \
  -d new_app_files \
  -m label -p rootfs

Development Workflow

# Interactive mode for careful development
sudo ./wic-editor.sh -i dev-image.wic -o test-image.wic -m manual

# Production deployment with automation
sudo ./wic-editor.sh -i prod-image.wic -o deployed.wic -p 2 -f -y

Adding Startup Scripts

# Add systemd service
mkdir -p custom_files/etc/systemd/system
cp my_service.service custom_files/etc/systemd/system/

Adding User Files

# Add files to root user's home directory
mkdir -p custom_files/home/root
cp my_files/* custom_files/home/root/

Troubleshooting

Permission Errors

Ensure you have sudo privileges
The script needs root access to mount filesystems

No Root Partition Found

Check that your WIC image contains an ext4 partition
Verify the image isn't corrupted by testing with parted -s your_image.wic print

Insufficient Disk Space

Ensure you have at least 3x the size of your WIC image available
Clean up temporary files in case of previous failed runs

Custom Files Not Appearing

Verify the directory structure in your custom files directory
Check file permissions in the custom files directory
Ensure the custom files directory exists and contains files
Check the file operation summary for skipped files
Verify you're targeting the correct partition

Wrong Partition Selected

Use -p list to see all available partitions
Use -m manual for interactive selection
Check partition labels with -m label -p <label_name>
Verify filesystem type before proceeding

Partition Not Found Errors

Ensure partition number exists (use -p list)
Check partition label spelling for label-based selection
Verify filesystem type for filesystem-based selection

File Deletion Issues

Use absolute paths starting with / for file deletion
Check file paths exist before deletion
Use interactive mode to confirm deletions
Wildcards require proper shell escaping

File Conflicts Not Being Detected

Ensure you're using the correct relative paths in your custom files directory
Check that the script has permission to read both source and destination files
Verify that the filesystem is properly mounted

Unwanted File Overwrites

Use interactive mode (default) to review each conflict
Check the file operation summary to see what was overwritten
Use the -f flag cautiously - it overwrites all conflicting files

Loop Device Issues

If script fails with loop device errors, manually clean up:
```
sudo losetup -D  # Detach all loop devices
```

Advanced Usage

Automated Build Integration

For automated builds where you want to overwrite system files:

#!/bin/bash
# Build script example

# Build your Yocto image
bitbake my-image

# Modify the resulting WIC image with force overwrite
sudo ./wic-editor.sh -i deploy/images/imx8mmevk/my-image.wic \
                     -o deploy/images/imx8mmevk/my-image-custom.wic \
                     -d custom_overlay \
                     -f -y

# Flash with UUU
uuu uuu.auto-imx8mmevk-custom

Staged File Deployment

For complex deployments with multiple file sources:

# Stage 1: Base system modifications (force overwrite)
sudo ./wic-editor.sh -i original.wic -o stage1.wic -d base_system_changes -f

# Stage 2: Application files (interactive to review conflicts)
sudo ./wic-editor.sh -i stage1.wic -o stage2.wic -d application_files

# Stage 3: Final configuration (non-interactive)
sudo ./wic-editor.sh -i stage2.wic -o final.wic -d final_config -y

Best Practices for File Conflicts

1. System Configuration Files

When modifying system files like /etc/hostname, /etc/hosts, /etc/fstab:

# Use interactive mode to review changes
sudo ./wic-editor.sh -i input.wic -o output.wic

# When prompted, choose option 3 to see differences
# This helps you understand what you're changing

2. Service Files and Scripts

For systemd services, init scripts, or configuration files:

# Prepare your custom files
mkdir -p custom_files/etc/systemd/system
cp my_custom.service custom_files/etc/systemd/system/

# Use interactive mode to review any existing service modifications
sudo ./wic-editor.sh -i input.wic -o output.wic

3. Development vs Production

# Development: Interactive mode for careful review
sudo ./wic-editor.sh -i dev_image.wic -o dev_image_modified.wic

# Production: Automated mode for consistent deployment
sudo ./wic-editor.sh -i prod_image.wic -o prod_image_modified.wic -f -y

4. Backup Strategy

# Always keep backups of critical configurations
mkdir -p backups/$(date +%Y%m%d)
cp important_configs/* backups/$(date +%Y%m%d)/

# Then proceed with modifications
sudo ./wic-editor.sh -i input.wic -o output.wic

File Size Considerations

The script will display file size comparisons after completion:

Original file size
Modified file size
The difference helps you understand the impact of your additions

Security Considerations

The script requires sudo privileges for mounting filesystems
Files are copied with their original permissions
File overwrites: In interactive mode, you can review each file before overwriting
Automated modes: Use -f and -y flags cautiously as they can overwrite system files
Ensure custom files don't contain sensitive information unless intended
Validate custom files before adding them to the root filesystem
Backup recommendation: Always keep a backup of your original WIC image

Contributing

We welcome contributions to WIC Editor! Here's how you can help:

Reporting Issues

Use the GitHub Issues page
Include your system information and WIC image details
Provide steps to reproduce the problem

Contributing Code

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Test thoroughly on your target hardware
Ensure compatibility with different WIC image formats
Add error handling for edge cases
Update documentation as needed
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Follow existing code style and patterns
Add comprehensive error handling
Include appropriate comments
Test on multiple WIC image types
Update the README for new features

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Copyright

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Support

Documentation: This README and inline help (./wic-editor.sh -h)
Issues: Report bugs and request features via GitHub Issues
Community: Join discussions in the repository's Discussions section

Acknowledgments

Originally developed for NXP i.MX8MM EVK workflows
Inspired by the need for safer WIC image modification
Built for the embedded Linux and Yocto Project communities

Version History

v1.0: Initial release with basic WIC modification support
v1.1: Added support for both compressed and uncompressed images
v1.2: Improved error handling and cleanup procedures
v1.3: Enhanced UUU integration and documentation
v1.4: Added intelligent file conflict detection and resolution
v1.5: Implemented interactive and automated modes for file handling
v1.6: Added detailed file operation reporting and diff capabilities
v1.7: Advanced partition detection with multiple selection modes
v1.8: File deletion capabilities and comprehensive partition analysis

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
.github		.github
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
wic-editor.sh		wic-editor.sh

License

DynamicDevices/wic-editor

Folders and files

Latest commit

History

Repository files navigation

WIC Editor

Table of Contents

Overview

Features

Requirements

System Requirements

Required Tools

Installation on Ubuntu/Debian

Installation on CentOS/RHEL/Fedora

Usage

Basic Syntax

Options

Partition Selection Modes

Examples

Examples

Getting Started with Unknown WIC Images

Basic Usage

Partition Selection

File Deletion

For NXP i.MX8MM EVK (UUU workflow)

With compressed images

File Conflict and Automation

Setup Instructions

1. Download and Setup Script

2. Prepare Custom Files

Example directory structure:

3. Run WIC Editor

4. Update UUU Script

Script Workflow

Partition Detection and Selection

Automatic Detection (Default)

Interactive Selection

Specific Selection Methods

Partition Information Display

File Conflict Handling

Interactive Mode (Default)

Non-Interactive Modes

Conflict Resolution Examples

Interactive Session

Summary Report

Common Use Cases

Exploring Unknown WIC Images

System Configuration with Cleanup

Application Deployment

Development Workflow

Adding Startup Scripts

Adding User Files

Troubleshooting

Permission Errors

No Root Partition Found

Insufficient Disk Space

Custom Files Not Appearing

Wrong Partition Selected

Partition Not Found Errors

File Deletion Issues

File Conflicts Not Being Detected

Unwanted File Overwrites

Loop Device Issues

Advanced Usage

Automated Build Integration

Staged File Deployment

Best Practices for File Conflicts

1. System Configuration Files

2. Service Files and Scripts

3. Development vs Production

4. Backup Strategy

File Size Considerations

Security Considerations

Contributing

Reporting Issues

Contributing Code

Development Guidelines

License

Copyright

Packages