Skip to content

Commit 063f513

Browse files
author
Alex J Lennon
committed
docs: Update README to show sudo requirement in all examples
- Add sudo to all command examples throughout documentation - Add note about root privilege requirement in setup section - Update all use cases to demonstrate proper sudo usage - Maintain consistency across basic usage, advanced examples, and best practices - Ensure users understand security requirements upfront Makes documentation consistent with script's root privilege requirement.
1 parent 8e0cc76 commit 063f513

File tree

1 file changed

+46
-44
lines changed

1 file changed

+46
-44
lines changed

README.md

Lines changed: 46 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,7 @@ sudo dnf install gzip util-linux parted
104104
#### Getting Started with Unknown WIC Images
105105
```bash
106106
# First, list all partitions to understand the structure
107-
./wic-editor.sh -i unknown-image.wic -p list
107+
sudo ./wic-editor.sh -i unknown-image.wic -p list
108108

109109
# Sample output shows:
110110
# Partition 1: boot (FAT32, 100MB)
@@ -115,86 +115,86 @@ sudo dnf install gzip util-linux parted
115115
#### Basic Usage
116116
```bash
117117
# Auto-detect target partition (works for most images)
118-
./wic-editor.sh -i input.wic -o output.wic
118+
sudo ./wic-editor.sh -i input.wic -o output.wic
119119

120120
# With custom files directory
121-
./wic-editor.sh -i input.wic -o output.wic -d my_custom_files
121+
sudo ./wic-editor.sh -i input.wic -o output.wic -d my_custom_files
122122
```
123123

124124
#### Partition Selection
125125
```bash
126126
# Select specific partition by number
127-
./wic-editor.sh -i input.wic -o output.wic -p 2
127+
sudo ./wic-editor.sh -i input.wic -o output.wic -p 2
128128

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

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

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

138138
# Select largest partition (any filesystem)
139-
./wic-editor.sh -i input.wic -o output.wic -m largest
139+
sudo ./wic-editor.sh -i input.wic -o output.wic -m largest
140140
```
141141

142142
#### File Deletion
143143
```bash
144144
# Delete specific files before adding new ones
145-
./wic-editor.sh -i input.wic -o output.wic -r "/etc/old_config.conf,/var/log/debug.log"
145+
sudo ./wic-editor.sh -i input.wic -o output.wic -r "/etc/old_config.conf,/var/log/debug.log"
146146

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

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

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

157157
#### For NXP i.MX8MM EVK (UUU workflow)
158158
```bash
159159
# Auto-detect (typical usage)
160-
./wic-editor.sh -i imx-image-full-imx8mmevk.wic -o imx-image-full-imx8mmevk-modified.wic
160+
sudo ./wic-editor.sh -i imx-image-full-imx8mmevk.wic -o imx-image-full-imx8mmevk-modified.wic
161161

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

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

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

173173
#### With compressed images
174174
```bash
175175
# Compressed to compressed
176-
./wic-editor.sh -i rootfs.wic.gz -o rootfs_modified.wic.gz -p 2
176+
sudo ./wic-editor.sh -i rootfs.wic.gz -o rootfs_modified.wic.gz -p 2
177177

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

181181
# Uncompressed to compressed with file deletion
182-
./wic-editor.sh -i rootfs.wic -o rootfs_modified.wic.gz -r "/tmp/*"
182+
sudo ./wic-editor.sh -i rootfs.wic -o rootfs_modified.wic.gz -r "/tmp/*"
183183
```
184184

185185
#### File Conflict and Automation
186186
```bash
187187
# Interactive mode (default) - prompts for each file conflict
188-
./wic-editor.sh -i input.wic -o output.wic -p 2
188+
sudo ./wic-editor.sh -i input.wic -o output.wic -p 2
189189

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

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

196196
# Fully automated operation
197-
./wic-editor.sh -i input.wic -o output.wic -p 2 -f -y
197+
sudo ./wic-editor.sh -i input.wic -o output.wic -p 2 -f -y
198198
```
199199

200200
## Setup Instructions
@@ -237,15 +237,17 @@ custom_files/
237237
### 3. Run WIC Editor
238238
```bash
239239
# Interactive mode (default) - prompts for file conflicts
240-
./wic-editor.sh -i your_image.wic -o your_image_modified.wic -d custom_files
240+
sudo ./wic-editor.sh -i your_image.wic -o your_image_modified.wic -d custom_files
241241

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

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

249+
**Note:** WIC Editor requires root privileges to mount filesystems and manage loop devices. Always run with `sudo`.
250+
249251
### 4. Update UUU Script
250252
If using with NXP UUU tool, update your UUU script file (e.g., `uuu.auto-imx8mmevk`):
251253

@@ -369,24 +371,24 @@ File operation summary:
369371
### Exploring Unknown WIC Images
370372
```bash
371373
# First step: understand the partition structure
372-
./wic-editor.sh -i unknown-image.wic -p list
374+
sudo ./wic-editor.sh -i unknown-image.wic -p list
373375

374376
# Once you know the layout, select appropriate partition
375-
./wic-editor.sh -i unknown-image.wic -o modified.wic -p 2
377+
sudo ./wic-editor.sh -i unknown-image.wic -o modified.wic -p 2
376378
```
377379

378380
### System Configuration with Cleanup
379381
```bash
380382
# Remove old configs and add new ones
381-
./wic-editor.sh -i system.wic -o updated.wic \
383+
sudo ./wic-editor.sh -i system.wic -o updated.wic \
382384
-r "/etc/old_config.conf,/etc/deprecated/*" \
383385
-d new_system_configs
384386
```
385387

386388
### Application Deployment
387389
```bash
388390
# Clean deployment: remove old app and install new version
389-
./wic-editor.sh -i base.wic -o deployed.wic \
391+
sudo ./wic-editor.sh -i base.wic -o deployed.wic \
390392
-r "/opt/old_app" \
391393
-d new_app_files \
392394
-m label -p rootfs
@@ -395,10 +397,10 @@ File operation summary:
395397
### Development Workflow
396398
```bash
397399
# Interactive mode for careful development
398-
./wic-editor.sh -i dev-image.wic -o test-image.wic -m manual
400+
sudo ./wic-editor.sh -i dev-image.wic -o test-image.wic -m manual
399401

400402
# Production deployment with automation
401-
./wic-editor.sh -i prod-image.wic -o deployed.wic -p 2 -f -y
403+
sudo ./wic-editor.sh -i prod-image.wic -o deployed.wic -p 2 -f -y
402404
```
403405

404406
### Adding Startup Scripts
@@ -482,10 +484,10 @@ For automated builds where you want to overwrite system files:
482484
bitbake my-image
483485

484486
# Modify the resulting WIC image with force overwrite
485-
./wic-editor.sh -i deploy/images/imx8mmevk/my-image.wic \
486-
-o deploy/images/imx8mmevk/my-image-custom.wic \
487-
-d custom_overlay \
488-
-f -y
487+
sudo ./wic-editor.sh -i deploy/images/imx8mmevk/my-image.wic \
488+
-o deploy/images/imx8mmevk/my-image-custom.wic \
489+
-d custom_overlay \
490+
-f -y
489491

490492
# Flash with UUU
491493
uuu uuu.auto-imx8mmevk-custom
@@ -496,13 +498,13 @@ For complex deployments with multiple file sources:
496498

497499
```bash
498500
# Stage 1: Base system modifications (force overwrite)
499-
./wic-editor.sh -i original.wic -o stage1.wic -d base_system_changes -f
501+
sudo ./wic-editor.sh -i original.wic -o stage1.wic -d base_system_changes -f
500502

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

504506
# Stage 3: Final configuration (non-interactive)
505-
./wic-editor.sh -i stage2.wic -o final.wic -d final_config -y
507+
sudo ./wic-editor.sh -i stage2.wic -o final.wic -d final_config -y
506508
```
507509

508510
### Best Practices for File Conflicts
@@ -511,7 +513,7 @@ For complex deployments with multiple file sources:
511513
When modifying system files like `/etc/hostname`, `/etc/hosts`, `/etc/fstab`:
512514
```bash
513515
# Use interactive mode to review changes
514-
./wic-editor.sh -i input.wic -o output.wic
516+
sudo ./wic-editor.sh -i input.wic -o output.wic
515517

516518
# When prompted, choose option 3 to see differences
517519
# This helps you understand what you're changing
@@ -525,16 +527,16 @@ mkdir -p custom_files/etc/systemd/system
525527
cp my_custom.service custom_files/etc/systemd/system/
526528

527529
# Use interactive mode to review any existing service modifications
528-
./wic-editor.sh -i input.wic -o output.wic
530+
sudo ./wic-editor.sh -i input.wic -o output.wic
529531
```
530532

531533
#### 3. **Development vs Production**
532534
```bash
533535
# Development: Interactive mode for careful review
534-
./wic-editor.sh -i dev_image.wic -o dev_image_modified.wic
536+
sudo ./wic-editor.sh -i dev_image.wic -o dev_image_modified.wic
535537

536538
# Production: Automated mode for consistent deployment
537-
./wic-editor.sh -i prod_image.wic -o prod_image_modified.wic -f -y
539+
sudo ./wic-editor.sh -i prod_image.wic -o prod_image_modified.wic -f -y
538540
```
539541

540542
#### 4. **Backup Strategy**
@@ -544,7 +546,7 @@ mkdir -p backups/$(date +%Y%m%d)
544546
cp important_configs/* backups/$(date +%Y%m%d)/
545547

546548
# Then proceed with modifications
547-
./wic-editor.sh -i input.wic -o output.wic
549+
sudo ./wic-editor.sh -i input.wic -o output.wic
548550
```
549551

550552
## File Size Considerations

0 commit comments

Comments
 (0)