Skip to main content

​
Development Setup

​
Prerequisites

SoftwareVersionNotes
macOS14.0+ (Sonoma)Target platform
Xcode15.0+Includes Swift 5.9
Optional but recommended:
ToolInstallPurpose
SwiftLintbrew install swiftlintLinting
SwiftFormatbrew install swiftformatCode formatting
GitHub CLIbrew install ghUsed 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 pre-built .a files (libmariadb, libpq, etc.) from GitHub Releases into Libs/. Takes a few seconds.
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
  3. Change Team to your Apple Developer account (free account works)
The Debug build leaves out the iCloud capability, so a free personal team signs it without a paid Apple Developer Program membership. If you build a target that still shows a team error (a driver plugin or the MCP server), set its Team the same way.
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
8

Test a plugin you built

The app only loads plugins signed by the same team as the app, so a plugin you built separately will not install into a release build. To try one in your local build, add it to the Copy Plug-Ins build phase of the TablePro target and run, or set TABLEPRO_ALLOW_UNSIGNED_PLUGINS=1 in the scheme’s environment to skip the signature check. Once it works, open a PR so the official CI signs and ships it through the registry.
Xcode setup

​
Project Structure

TablePro
Models
ViewModels
Extensions
Theme
Resources
TableProTests

​
Running Tests

# All tests
xcodebuild -project TablePro.xcodeproj -scheme TablePro test -skipPackagePluginValidation

# Specific test class
xcodebuild -project TablePro.xcodeproj -scheme TablePro test -skipPackagePluginValidation \
    -only-testing:TableProTests/TestClassName

# Specific test method
xcodebuild -project TablePro.xcodeproj -scheme TablePro test -skipPackagePluginValidation \
    -only-testing:TableProTests/TestClassName/testMethodName
Or in Xcode: Cmd+U.

​
Linting and Formatting

# Check for issues
swiftlint lint

# Auto-fix
swiftlint --fix

# Format all code
swiftformat .
Run swiftlint --fix && swiftformat . before committing.

​
Troubleshooting

ProblemFix
Linker errors about missing symbolsRun scripts/download-libs.sh
SPM resolution failsClean build folder (Cmd+Shift+K), reopen Xcode
Build fails after pullingDelete derived data: rm -rf ~/Library/Developer/Xcode/DerivedData
Missing Secrets.xcconfig errorRun touch Secrets.xcconfig in project root
Code signing errorsChange Team in Signing & Capabilities
The -skipPackagePluginValidation flag is required because CodeEditSourceEditor (an SPM dependency) bundles a SwiftLint plugin. Without this flag, CLI builds fail with a validation error.