114 lines
3.8 KiB
Markdown
114 lines
3.8 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
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](https://github.com/ggerganov/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](https://github.com/Beingpax/VoiceInk/issues) section or create a new issue. |