build.bat: added upx minify for caesiumclt.exe
This commit is contained in:
@@ -0,0 +1,288 @@
|
||||
# PPTX Image Compressor - Packaging & Distribution Guide
|
||||
|
||||
## Overview
|
||||
|
||||
This project now supports 3 different deployment approaches:
|
||||
1. **Embedded Python** (Current - Development & Local Use)
|
||||
2. **PyInstaller Portable** (Recommended for End Users)
|
||||
3. **Hybrid Approach** (Recommended for Maximum Flexibility)
|
||||
|
||||
---
|
||||
|
||||
## Approach 1: Embedded Python (Development Setup)
|
||||
|
||||
### Use Case
|
||||
- ✅ Development with VS Code
|
||||
- ✅ Debugging with Python Debugger
|
||||
- ✅ Running tests with pytest
|
||||
- ✅ Source code control & modifications
|
||||
|
||||
### What You Have
|
||||
- `install_and_run.bat` - Main launcher
|
||||
- `.venv/` - Virtual environment for development
|
||||
- Source code - Fully editable
|
||||
|
||||
### Usage
|
||||
```bash
|
||||
# Development (with --debug flag to see pip output)
|
||||
.\install_and_run.bat --debug -i "path\to\file.pptx" -o "path\to\output.pptx"
|
||||
|
||||
# With VS Code debugger
|
||||
# Open pptx_image_compress.py and click "Debug" or press F5
|
||||
|
||||
# Run tests
|
||||
.\.venv\Scripts\pytest tests/
|
||||
```
|
||||
|
||||
### Setup Instructions
|
||||
1. Ensure Python 3.9+ is installed on Windows
|
||||
2. Run: `.\install_and_run.bat`
|
||||
3. Virtual environment is created/updated automatically
|
||||
|
||||
### Files
|
||||
- `install_and_run.bat` - Handles Python setup and execution
|
||||
- `requirements.txt` - Python package dependencies for runtime
|
||||
- `requirements-dev.txt` - Development dependencies (pytest, coverage, etc.)
|
||||
|
||||
---
|
||||
|
||||
## Approach 2: PyInstaller Portable (User Distribution)
|
||||
|
||||
### Use Case
|
||||
- ✅ Distribute to end users (No Python installation needed)
|
||||
- ✅ Single-file executable
|
||||
- ✅ Professional appearance
|
||||
- ✅ "Just download and run" experience
|
||||
- ✅ Drag-and-drop support for non-technical users
|
||||
|
||||
### What Gets Generated
|
||||
- `dist/pptx-image-compress.exe` - Standalone executable
|
||||
- `dist/run.bat` - Simple command-line wrapper
|
||||
- `dist/dragdrop.bat` - Drag-and-drop wrapper (easiest for users)
|
||||
|
||||
### Usage by End User
|
||||
```bash
|
||||
# Option 1: Drag-and-drop (Easiest!)
|
||||
# Drag a .pptx file onto dragdrop.bat
|
||||
# Output: filename_compressed.pptx
|
||||
|
||||
# Option 2: Command line
|
||||
.\pptx-image-compress.exe -i "path\to\file.pptx" -o "path\to\output.pptx"
|
||||
|
||||
# Option 3: Wrapper
|
||||
.\run.bat -i "path\to\file.pptx" -o "path\to\output.pptx"
|
||||
|
||||
# Get help
|
||||
.\pptx-image-compress.exe --help
|
||||
```
|
||||
|
||||
### Build Instructions
|
||||
1. Ensure you have the development environment set up (Approach 1)
|
||||
2. Run: `.\build.bat`
|
||||
3. Wait for build to complete (first run takes 2-3 minutes)
|
||||
4. Generated files are in `dist/` folder
|
||||
|
||||
### Build Files
|
||||
- `build.bat` - Automated build script that:
|
||||
- Installs PyInstaller if needed
|
||||
- Compiles Python to standalone executable
|
||||
- Creates wrapper batch file
|
||||
- Prepares distribution package
|
||||
|
||||
### Advantages
|
||||
- No Python installation required on user's machine
|
||||
- Smaller footprint than full Python installation
|
||||
- Professional distribution option
|
||||
- Can be code-signed and digitally stamped
|
||||
|
||||
### Limitations
|
||||
- Larger file size (~80-150 MB) due to bundled Python
|
||||
- First launch slightly slower (unpacking)
|
||||
- Harder to debug if issues occur
|
||||
|
||||
### Distribution Notes
|
||||
- Ensure `caesiumclt.exe` is in the same directory as the .exe
|
||||
- Can optionally add `.venv\Lib\site-packages\svg_polish\*` if svg-polish needs updating
|
||||
- All dependencies are pre-bundled
|
||||
- Users can:
|
||||
1. **Drag-and-drop files** onto `dragdrop.bat` for easy compression
|
||||
2. Use command line for batch operations
|
||||
3. Call `.exe` directly with custom parameters
|
||||
|
||||
### Drag-and-Drop Feature
|
||||
The `dragdrop.bat` wrapper provides the easiest user experience:
|
||||
- Drag a `.pptx` file onto `dragdrop.bat`
|
||||
- Automatically creates `[filename]_compressed.pptx` in the same directory
|
||||
- Shows progress and completion status
|
||||
- No command-line knowledge required
|
||||
|
||||
---
|
||||
|
||||
## Approach 3: Hybrid (Recommended)
|
||||
|
||||
### Use Case
|
||||
- ✅ Flexible development workflow
|
||||
- ✅ Easy distribution to users
|
||||
- ✅ Best of both worlds
|
||||
|
||||
### How It Works
|
||||
**For Developers:**
|
||||
- Use Embedded Python approach (Approach 1)
|
||||
- Edit code, debug, run tests
|
||||
- Keep development lightweight
|
||||
|
||||
**For Users:**
|
||||
- Use PyInstaller Portable (Approach 2)
|
||||
- Download and run .exe
|
||||
- No installation or configuration needed
|
||||
|
||||
### Workflow
|
||||
```
|
||||
Development Phase:
|
||||
├── Edit code
|
||||
├── Test with: .\.venv\Scripts\pytest
|
||||
├── Debug with VS Code
|
||||
└── Use: .\install_and_run.bat --debug -i file.pptx
|
||||
|
||||
Release Phase:
|
||||
├── Run: .\build.bat
|
||||
├── Test the .exe: .\dist\pptx-image-compress.exe -i file.pptx
|
||||
├── Package: Copy dist/* to users
|
||||
└── Users just run: pptx-image-compress.exe
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dependency Management
|
||||
|
||||
### Runtime Dependencies (required for execution)
|
||||
See `requirements.txt`:
|
||||
- `svg-polish==1.0.0` - SVG optimization library (brings defusedxml)
|
||||
|
||||
The core script uses only Python Standard Library modules:
|
||||
- No need for external image libraries
|
||||
- Uses system's `caesiumclt.exe` for image compression
|
||||
- Handles PPTX files using only built-in zipfile module
|
||||
|
||||
### Development Dependencies (for testing/development)
|
||||
See `requirements-dev.txt`:
|
||||
- `pytest==9.0.3` - Testing framework
|
||||
- `pytest-cov==7.1.0` - Coverage reporting
|
||||
- Plus all runtime dependencies
|
||||
|
||||
### Managing Dependencies
|
||||
|
||||
**Update packages:**
|
||||
```bash
|
||||
.\.venv\Scripts\pip install --upgrade -r requirements.txt
|
||||
```
|
||||
|
||||
**Add new package:**
|
||||
```bash
|
||||
.\.venv\Scripts\pip install package_name
|
||||
.\.venv\Scripts\pip freeze > requirements.txt
|
||||
```
|
||||
|
||||
**For development:**
|
||||
```bash
|
||||
.\.venv\Scripts\pip install -r requirements-dev.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Development Setup Issues
|
||||
|
||||
**Problem:** "Python not found"
|
||||
- **Solution:** Run `.\install_and_run.bat` which will download and setup Python
|
||||
|
||||
**Problem:** "svg_polish not found"
|
||||
- **Solution:** Run with `--debug` flag to see installation details
|
||||
- Or manually: `.\.venv\Scripts\pip install svg-polish`
|
||||
|
||||
### PyInstaller Build Issues
|
||||
|
||||
**Problem:** Build takes too long
|
||||
- **Solution:** First build is slower due to PyInstaller analysis. Subsequent builds are faster.
|
||||
|
||||
**Problem:** .exe won't run
|
||||
- **Solution:** Ensure `caesiumclt.exe` is in the same directory or system PATH
|
||||
|
||||
**Problem:** "PyInstaller not installed"
|
||||
- **Solution:** Run `build.bat` again - it will auto-install PyInstaller
|
||||
|
||||
---
|
||||
|
||||
## Technical Comparison
|
||||
|
||||
| Aspect | Embedded Python | PyInstaller | Hybrid |
|
||||
|--------|-----------------|-------------|--------|
|
||||
| **Installation** | Auto (via batch) | None (single .exe) | Mixed |
|
||||
| **Disk Space** | ~50 MB | ~100-150 MB | Both available |
|
||||
| **Execution Speed** | Fast | Fast | Fast |
|
||||
| **Debuggability** | Excellent | Difficult | Excellent (dev) |
|
||||
| **Distribution** | Manual setup | Just .exe | Just .exe (users) |
|
||||
| **Development** | Quick iteration | Requires rebuild | Quick iteration |
|
||||
|
||||
---
|
||||
|
||||
## Recommended Workflow
|
||||
|
||||
### For You (Developer)
|
||||
```
|
||||
1. Daily Development:
|
||||
- Use: .\install_and_run.bat --debug
|
||||
- Edit code in VS Code
|
||||
- Test with pytest
|
||||
- Use debugger with F5
|
||||
|
||||
2. Before Release:
|
||||
- Run: .\build.bat
|
||||
- Test: .\dist\pptx-image-compress.exe
|
||||
- Package and distribute
|
||||
```
|
||||
|
||||
### For End Users
|
||||
```
|
||||
1. First Time:
|
||||
- Download pptx-image-compress.exe
|
||||
- Download run.bat (optional)
|
||||
- Download caesiumclt.exe (if image compression needed)
|
||||
|
||||
2. Usage:
|
||||
- Double-click run.bat
|
||||
- Or: pptx-image-compress.exe -i input.pptx -o output.pptx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Test Embedded Python Setup:**
|
||||
```bash
|
||||
.\install_and_run.bat --debug -i test.pptx -o test_output.pptx
|
||||
```
|
||||
|
||||
2. **Build Portable Distribution:**
|
||||
```bash
|
||||
.\build.bat
|
||||
```
|
||||
|
||||
3. **Test the Executable:**
|
||||
```bash
|
||||
.\dist\pptx-image-compress.exe -h
|
||||
```
|
||||
|
||||
4. **Check Generated Files:**
|
||||
- `dist/pptx-image-compress.exe` - Main executable
|
||||
- `dist/run.bat` - Batch wrapper
|
||||
|
||||
---
|
||||
|
||||
## Support & Maintenance
|
||||
|
||||
- Keep Python version updated for security
|
||||
- Update dependencies: `pip install --upgrade -r requirements.txt`
|
||||
- Rebuild .exe when updating dependencies: `.\build.bat`
|
||||
- Test both approaches before major updates
|
||||
Reference in New Issue
Block a user