Skip to main content

​
Prerequisites

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:

​
Quick Start

1

Clone the repository

2

Download native libraries

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

Install tools

4

Generate the Xcode project

TablePro.xcodeproj and TableProMobile/TableProMobile.xcodeproj are generated from project.yml and are not in git. Run this again after changing project.yml or Configs/, and after adding, moving, or deleting a source file: XcodeGen collects sources at generation time, so a new file is not in the project until you regenerate.
5

Open in Xcode

6

Configure signing

Set your own team and a unique bundle identifier:
A free personal team works. The Debug configuration signs with TablePro.Debug.entitlements, which drops the iCloud capability, so no paid Apple Developer Program membership is needed. Plugin bundles and the MCP server sign ad-hoc, so they need no team at all.Configs/Secrets.xcconfig is gitignored, so these settings cannot reach a commit, and they survive regenerating the project. Do not change signing in the Xcode UI: the project is generated, and the next scripts/generate-project.sh discards the edit.
7

Build and run

Select the TablePro scheme, set destination to My Mac, press Cmd+R.Or from the command line:
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 setup

Xcode project setup

​
Project Structure

TablePro
Models
ViewModels
Extensions
Theme
Resources
TableProTests
TableProUITests
Packages/TableProCore/Sources/TableProPluginKit is a symlink to Plugins/TableProPluginKit. Edit the files under Plugins/ only.

​
Running Tests

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:
CI rejects warnings, so plain swiftlint lint is not enough. Full tooling reference: Code Style.

​
Troubleshooting

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.