vOOice/BUILDING.md

Building VoiceInk

This guide provides detailed instructions for building VoiceInk from source.

Prerequisites

Before you begin, ensure you have:

• macOS 14.0 or later
• Xcode (latest version recommended)
• Swift (latest version recommended)
• Git (for cloning repositories)

Quick Start with Makefile (Recommended)

The easiest way to build VoiceInk is using the included Makefile, which automates the entire build process including building and linking the whisper framework.

Simple Build Commands

# Clone the repository
git clone https://github.com/Beingpax/VoiceInk.git
cd VoiceInk

# Build everything (recommended for first-time setup)
make all

# Or for development (build and run)
make dev

Available Makefile Commands

• make check or make healthcheck - Verify all required tools are installed
• make whisper - Clone and build whisper.cpp XCFramework automatically
• make setup - Prepare the whisper framework for linking
• make build - Build the VoiceInk Xcode project
• make run - Launch the built VoiceInk app
• make dev - Build and run (ideal for development workflow)
• make all - Complete build process (default)
• make clean - Remove build artifacts and dependencies
• make help - Show all available commands

How the Makefile Helps

The Makefile automatically:

1. Manages Dependencies: Creates a dedicated ~/VoiceInk-Dependencies directory for all external frameworks
2. Builds Whisper Framework: Clones whisper.cpp and builds the XCFramework with the correct configuration
3. Handles Framework Linking: Sets up the whisper.xcframework in the proper location for Xcode to find
4. Verifies Prerequisites: Checks that git, xcodebuild, and swift are installed before building
5. Streamlines Development: Provides convenient shortcuts for common development tasks

This approach ensures consistent builds across different machines and eliminates manual framework setup errors.

---

Manual Build Process (Alternative)

If you prefer to build manually or need more control over the build process, follow these steps:

Building whisper.cpp Framework

1. Clone and build whisper.cpp:

git clone https://github.com/ggerganov/whisper.cpp.git
cd whisper.cpp
./build-xcframework.sh

This will create the XCFramework at build-apple/whisper.xcframework.

Building VoiceInk

1. Clone the VoiceInk repository:

git clone https://github.com/Beingpax/VoiceInk.git
cd VoiceInk

2. Add the whisper.xcframework to your project:

   • Drag and drop ../whisper.cpp/build-apple/whisper.xcframework into the project navigator, or
   • Add it manually in the "Frameworks, Libraries, and Embedded Content" section of project settings

3. Build and Run

   • Build the project using Cmd+B or Product > Build
   • Run the project using Cmd+R or Product > Run

Development Setup

1. Xcode Configuration

   • Ensure you have the latest Xcode version
   • Install any required Xcode Command Line Tools

2. Dependencies

   • The project uses whisper.cpp for transcription
   • Ensure the whisper.xcframework is properly linked in your Xcode project
   • Test the whisper.cpp installation independently before proceeding

3. Building for Development

   • Use the Debug configuration for development
   • Enable relevant debugging options in Xcode

4. Testing

   • Run the test suite before making changes
   • Ensure all tests pass after your modifications

Troubleshooting

If you encounter any build issues:

1. Clean the build folder (Cmd+Shift+K)
2. Clean the build cache (Cmd+Shift+K twice)
3. Check Xcode and macOS versions
4. Verify all dependencies are properly installed
5. Make sure whisper.xcframework is properly built and linked

For more help, please check the issues section or create a new issue.