Development Setup

Clone, configure signing, and build TablePro in Xcode

Prerequisites

Software	Version	Notes
Xcode	26.0+	Ships the macOS 26 SDK the app builds against. Every CI job pins 26.4.1.
Swift	5.9 language mode	Comes with Xcode, set by SWIFT_VERSION in the project

The app references macOS 26 SDK symbols (NSGlassEffectView in the quick switcher), so an older Xcode cannot compile it. The deployment target stays at macOS 14.0 Sonoma, which is what the built app runs on, not what you build on.

Optional but recommended:

Tool	Install	Purpose
SwiftLint	brew install swiftlint	Linting
SwiftFormat	brew install swiftformat	Code formatting
GitHub CLI	brew install gh	Used by download-libs.sh

Quick Start

1. Clone the repository

   git clone https://github.com/TableProApp/TablePro.git && cd TablePro
   
2. Download native libraries

   scripts/download-libs.sh
   

   This pulls two archives from the libs-v1 GitHub Release into Libs/: the macOS .a files (libmariadb, libpq, libduckdb, libmongoc, and others) and the iOS xcframeworks. About 257 MB downloaded, 620 MB on disk once expanded. Expect a minute or two.

   Skipping this step causes linker errors. The static libraries are not checked into git.

3. Create build config

   touch Secrets.xcconfig
   

   Empty file is fine for development. Production builds use this for API keys.

4. Install tools

   brew install swiftlint swiftformat
   
5. Open in Xcode

   open TablePro.xcodeproj
   
6. Configure signing

   1. Select the TablePro target
   2. Go to Signing & Capabilities, Debug sub-tab
   3. Change Team to your Apple Developer account (a free personal team works)
   4. Change the Bundle Identifier from com.TablePro to something unique, for example com.yourhandle.TablePro

   The Debug configuration signs with TablePro.Debug.entitlements, which drops the iCloud capability, so a free personal team can sign it without a paid Apple Developer Program membership. If another target still shows a team error (a driver plugin or the MCP server), set its Team the same way.

   Do not commit the resulting project.pbxproj changes; they break official Release signing. Hide them locally:

   git update-index --skip-worktree TablePro.xcodeproj/project.pbxproj
   
7. Build and run

   Select the TablePro scheme, set destination to My Mac, press Cmd+R.

   Or from the command line:

   xcodebuild -project TablePro.xcodeproj -scheme TablePro -configuration Debug build -skipPackagePluginValidation
   

   Cmd+R writes the app to DerivedData (~/Library/Developer/Xcode/DerivedData/TablePro-*/Build/Products/Debug). The xcodebuild command above writes to build/Debug/TablePro.app inside the repo instead.

Writing a driver plugin? See Plugin Development to build one and Testing a Custom Plugin to run it in your local build.

Xcode project setup

Project Structure

TablePro

Core

Views

Models

ViewModels

Extensions

Theme

Resources

Plugins

Packages

LocalPackages

Libs

TableProMobile

TableProTests

TableProUITests

docs

scripts

Packages/TableProCore/Sources/TableProPluginKit is a symlink to Plugins/TableProPluginKit. Edit the files under Plugins/ only.

Running Tests

xcodebuild -project TablePro.xcodeproj -scheme TablePro test -skipPackagePluginValidation

Or in Xcode: Cmd+U. To run a single class or method, pass -only-testing:TableProTests/TestClassName or -only-testing:TableProTests/TestClassName/testMethodName.

Linting and Formatting

Before committing:

swiftlint lint --strict
swiftformat .

CI rejects warnings, so plain swiftlint lint is not enough. Full tooling reference: Code Style.

Troubleshooting

Problem	Fix
Linker errors about missing symbols	Run scripts/download-libs.sh
SPM resolution fails	Clean build folder (Cmd+Shift+K), reopen Xcode
Build fails after pulling	Delete derived data: rm -rf ~/Library/Developer/Xcode/DerivedData
Missing Secrets.xcconfig error	Run touch Secrets.xcconfig in project root
Code signing errors	Change Team in Signing & Capabilities

Pass -skipPackagePluginValidation on every xcodebuild invocation so the build does not stop on package plugin validation. scripts/build-release.sh, scripts/build-plugin.sh, scripts/check-pluginkit-abi.sh, and CI all pass it.