loveuer/uskey
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1e8b79585f9d2da00f26714a456f9a4916b65396
uskey/BUILD.md
loveuer 1e8b79585f Initial commit: uskey - macOS keyboard remapper 
Features:
- Menu bar GUI with enable/disable toggle
- JSON-based configuration system
- File-based logging with debug support
- CGEventTap-based key remapping
- Custom app icon support
- DMG installer packaging

Core Components:
- AppDelegate: Application lifecycle and initialization
- EventTapManager: Event tap creation and management with proper pointer lifetime
- KeyMapper: Key mapping logic and configuration loading
- StatusBarController: Menu bar UI and user interactions
- Logger: File and console logging with configurable levels
- Config: JSON configuration parser with default creation

Build System:
- build-app.sh: Creates macOS .app bundle with icon
- build-dmg.sh: Generates distributable DMG installer
- create-icon.sh: Converts PNG to .icns format

Documentation:
- README.md: User guide and troubleshooting
- BUILD.md: Build instructions and packaging
- DEBUG.md: Debugging guide with log access

🤖 Generated with [Qoder](https://qoder.com)
2025-12-02 17:51:56 +08:00

1.8 KiB
Raw Blame History

Build Scripts

This directory contains scripts to build and package uskey for distribution.

Creating the App Icon

If you have a custom icon, place a 1024x1024 PNG file at static/uskey.png, then run:

./create-icon.sh

This will:

  1. Create multiple icon sizes (16px to 1024px) for different display contexts
  2. Generate a proper .icns file for macOS
  3. Output to static/uskey.icns

The build script will automatically use this icon when building the app.

Building the App Bundle

To create a macOS .app bundle:

./build-app.sh

This will:

  1. Build the release binary using Swift Package Manager
  2. Create a proper .app bundle structure
  3. Add the Info.plist with app metadata
  4. Copy the app icon to the bundle
  5. Set the app to run as a menu bar utility (LSUIElement)

The resulting app will be at .build/release/uskey.app

Creating a DMG Installer

To create a distributable DMG file:

./build-dmg.sh

This will:

  1. Create a disk image with the app and Applications folder link
  2. Configure the DMG appearance (icon layout)
  3. Compress the DMG for distribution

The resulting DMG will be at .build/release/uskey-1.0.0.dmg

One-Step Build

To build both the app and DMG:

./build-app.sh && ./build-dmg.sh

Distribution

After building the DMG, you can distribute uskey-1.0.0.dmg to users. They can:

  1. Open the DMG file
  2. Drag uskey.app to the Applications folder
  3. Launch from Applications or Spotlight
  4. Grant Accessibility permissions when prompted

Notes

  • The app is built with LSUIElement set to true, so it runs as a menu bar-only app (no Dock icon)
  • Minimum macOS version is set to 13.0
  • Bundle identifier is com.uskey.app
  • Icon is automatically included if static/uskey.icns exists