Skip to content

BUILD.md

Latest commit

 

History

History
251 lines (197 loc) · 5.99 KB

BUILD.md

File metadata and controls

251 lines (197 loc) · 5.99 KB
Raw

Build Instructions

Guide for building Photo Size Reducer as standalone executables for macOS and Windows.

Prerequisites

  • Python 3.8+
  • pip
  • PyInstaller (pip install pyinstaller)

Building for macOS

Create .app Bundle

# Run the build script
./build_macos.sh

# The app will be in: dist/Photo Size Reducer.app

Create DMG for Distribution

# After building the .app, create a DMG
hdiutil create -volname "Photo Size Reducer" \
    -srcfolder "dist/Photo Size Reducer.app" \
    -ov -format UDZO \
    PhotoSizeReducer-macOS.dmg

Manual Build (without script)

pyinstaller --clean \
    --onefile \
    --windowed \
    --name "Photo Size Reducer" \
    --osx-bundle-identifier "com.nsozturk.photosizereducer" \
    photo_reducer.py

Building for Windows

Create .exe

# Run the build script
build_windows.bat

# The exe will be in: dist\PhotoSizeReducer.exe

Manual Build (without script)

pyinstaller --clean ^
    --onefile ^
    --windowed ^
    --name "PhotoSizeReducer" ^
    photo_reducer.py

Adding an Icon (Optional)

macOS (.icns)

  1. Create or download a 1024x1024 PNG icon
  2. Convert to .icns: 
    mkdir icon.iconset
sips -z 16 16     icon.png --out icon.iconset/icon_16x16.png
sips -z 32 32     icon.png --out icon.iconset/icon_16x16@2x.png
sips -z 32 32     icon.png --out icon.iconset/icon_32x32.png
sips -z 64 64     icon.png --out icon.iconset/icon_32x32@2x.png
sips -z 128 128   icon.png --out icon.iconset/icon_128x128.png
sips -z 256 256   icon.png --out icon.iconset/icon_128x128@2x.png
sips -z 256 256   icon.png --out icon.iconset/icon_256x256.png
sips -z 512 512   icon.png --out icon.iconset/icon_256x256@2x.png
sips -z 512 512   icon.png --out icon.iconset/icon_512x512.png
sips -z 1024 1024 icon.png --out icon.iconset/icon_512x512@2x.png
iconutil -c icns icon.iconset

Windows (.ico)

  1. Create or download a 256x256 PNG icon
  2. Convert to .ico using an online tool or software
  3. Save as icon.ico in the project root

Creating GitHub Releases

1. Build Executables

Build on each platform:

  • On macOS: Run ./build_macos.sh to create the .app
  • On Windows: Run build_windows.bat to create the .exe

2. Create Release Archives

macOS:

# Create DMG (recommended)
hdiutil create -volname "Photo Size Reducer" \
    -srcfolder "dist/Photo Size Reducer.app" \
    -ov -format UDZO \
    PhotoSizeReducer-v1.0.0-macOS.dmg

# OR create ZIP
cd dist
zip -r ../PhotoSizeReducer-v1.0.0-macOS.zip "Photo Size Reducer.app"
cd ..

Windows:

# Create ZIP
cd dist
powershell Compress-Archive PhotoSizeReducer.exe ..\PhotoSizeReducer-v1.0.0-Windows.zip
cd ..

3. Create GitHub Release

  1. Go to your repository on GitHub
  2. Click "Releases" → "Create a new release"
  3. Tag version: v1.0.0
  4. Release title: Photo Size Reducer v1.0.0
  5. Description: 
    ## What's New
- Initial release
- Drag & drop support
- Batch processing
- Live preview
- Compression and resize options
- Support for JPEG, PNG, WebP

## Downloads
- **macOS**: Download the .dmg file
- **Windows**: Download the .zip file and extract

## Installation
**macOS**: Open the DMG and drag the app to Applications folder
**Windows**: Extract the ZIP and run PhotoSizeReducer.exe
  6. Upload the built files:
    • PhotoSizeReducer-v1.0.0-macOS.dmg (or .zip)
    • PhotoSizeReducer-v1.0.0-Windows.zip
  7. Click "Publish release"

4. Using GitHub Actions (Automated - Advanced)

Create .github/workflows/build.yml for automated builds on every release:

name: Build Executables

on:
  release:
    types: [created]

jobs:
  build-macos:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - run: pip install -r requirements.txt pyinstaller
      - run: ./build_macos.sh
      - uses: actions/upload-release-asset@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          upload_url: ${{ github.event.release.upload_url }}
          asset_path: ./dist/Photo Size Reducer.app
          asset_name: PhotoSizeReducer-macOS.app
          asset_content_type: application/zip

  build-windows:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - run: pip install -r requirements.txt pyinstaller
      - run: build_windows.bat
      - uses: actions/upload-release-asset@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          upload_url: ${{ github.event.release.upload_url }}
          asset_path: ./dist/PhotoSizeReducer.exe
          asset_name: PhotoSizeReducer-Windows.exe
          asset_content_type: application/octet-stream

Troubleshooting

macOS: "App is damaged and can't be opened"

Remove the quarantine attribute:

xattr -cr "Photo Size Reducer.app"

Windows: Antivirus False Positive

Some antivirus software may flag PyInstaller executables. This is a known issue. Users can:

  • Add an exception for the file
  • Download and run from source instead

Missing Dependencies

If the built app crashes due to missing modules:

# Add hidden imports to the build command
pyinstaller --hidden-import=PIL._imagingtk ...

File Size Optimization

To reduce executable size:

# Use UPX compression (install UPX first)
pyinstaller --upx-dir=/usr/local/bin ...

# Exclude unnecessary modules
pyinstaller --exclude-module matplotlib ...

Code Signing (Production)

macOS

# Sign the app
codesign --deep --force --sign "Developer ID Application: Your Name" "dist/Photo Size Reducer.app"

# Verify
codesign --verify --deep --strict --verbose=2 "dist/Photo Size Reducer.app"

Windows

Use a code signing certificate from a trusted CA.

Author: Enes Ozturk GitHub: @nsozturk