Traccar Client for macOS
An independent, unofficial native Traccar client for Apple Silicon Macs.
Development status: initial application shell for issue #1. This build stays paused. Location access, tracking, server configuration and position/SOS delivery are not implemented; their menu actions are disabled.
Requirements
- Apple Silicon, starting with M1.
- macOS 15.0 or later. Deployment target 15.0 does not by itself establish runtime test coverage.
- Stable Xcode 27.1 for the initial development toolchain; Swift 6 language mode.
Build and run
Open TraccarClient.xcodeproj, select the shared TraccarClient scheme and run the macOS target. Set Xcode's Derived Data and Archives locations to your external development volume before building if internal storage is limited.
For a terminal build, supply an absolute build directory on that volume:
scripts/build.sh /path/to/external/build-directory Debug
Replace the example path with your actual directory. The app is produced at DerivedData/Build/Products/Debug/Traccar Client macOS.app beneath it. Use Release instead of Debug for an optimized build. The shared scheme also supports archiving; configure Xcode's archive location separately.
The app uses ad hoc signing, with no Apple developer account, provisioning profile or paid certificate. It is not notarized. Downloaded application Gatekeeper behaviour and DMG installation will be validated in issue #16.
Initial shell smoke check
- Launch the built app. It should show a menu-bar icon, no permanent Dock icon and a paused status.
- Confirm Start tracking, Send location now and Send SOS are disabled.
- Open Settings, close its window and reopen it from the menu. The process should remain running.
- Open About and check the version, unofficial-client statement and Apache-2.0 license information.
- Quit from the menu. The process should terminate.
No location permission request or server connection is part of this shell. Real-Mac UI checks remain distinct from automated compilation.
Continuous integration
The workflow in .github/workflows/ci.yml runs on pull requests, pushes to main and manual dispatch. It exposes three checks:
| Check | Runner | Toolchain | Work |
|---|---|---|---|
| SwiftLint | macos-15 arm64 |
Xcode 26.3; SwiftLint 0.65.1 | Strict lint, including warnings |
| Build (primary) | xcode-27 arm64 |
Xcode 27.1, build 27A9275; macOS SDK 27.0 | Debug and Release |
| Build (macOS 15) | macos-15 arm64 |
Xcode 26.3, build 17C529; macOS SDK 26.2 | Debug and Release |
Both build jobs verify the host architecture, OS major version, selected Xcode/build and SDK before compiling. They also verify arm64 binaries, deployment target 15.0 and application signatures. A missing or unexpected toolchain fails the check. The xcode-27 runner image is a public preview, accepted for early CI; Xcode 27.1 build 27A9275 itself is an Apple final release. Review the runner's status before automating releases.
This stage performs lint and compilation only: there is no test target yet. Configuration tests start with issue #3; subsequent features extend this workflow with meaningful tests. Builds do not validate location permissions, sleep behaviour or Gatekeeper.
Local checks before pushing
Run all local checks with one command, supplying an absolute validation directory outside the repository, preferably on your external development volume:
scripts/check-local.sh /path/to/external/local-ci
Replace the example with your actual path. The default primary profile requires macOS 27 arm64, Xcode 27.1 build 27A9275 and SDK 27.0. The script uses the Xcode selected by xcode-select, or the DEVELOPER_DIR environment variable if set. To select a particular installation without changing the system selection:
DEVELOPER_DIR=/path/to/Xcode.app/Contents/Developer \
scripts/check-local.sh /path/to/external/local-ci
The command checks the toolchain, shell syntax and whitespace in staged/unstaged tracked changes, runs strict SwiftLint, builds Debug and Release, then verifies both binaries' architecture, deployment target and signatures. It stops at the first failure and returns a nonzero exit code. Tools are cached under tools/ and incremental build products under build/ in the supplied directory. The toolchain, lint, build and binary verification scripts are shared with CI.
On a separate macOS 15 arm64 environment with Xcode 26.3 build 17C529 and SDK 26.2, select the minimum-system profile explicitly:
scripts/check-local.sh /path/to/external/local-ci-macos15 macos15
Profiles verify the actual machine and toolchain; they do not emulate another macOS version. This command does not reproduce GitHub's clean hosted environment, triggers, permissions or artifact uploads. It does not launch the application; perform the manual smoke check separately. A successful local run does not establish hosted CI or minimum-OS runtime coverage.
Individual checks
Run the same lint locally, using an absolute tools directory outside the repository:
scripts/lint.sh /path/to/external/tools-directory
The script downloads the official portable SwiftLint release, verifies its pinned SHA-256 and checks the executable version. .swiftlint.yml applies the default rules to application sources, with mandatory trailing commas in multiline collections. No baseline or automatic fixes are applied. SwiftLint is a development tool, not an application package dependency.
For a matching machine, reproduce the main toolchain check with:
scripts/verify-toolchain.sh 27.1 27A9275 27.0 27
CI uses read-only repository permissions, Actions pinned to full commit SHAs, bounded timeouts and cancellation of superseded runs. Checkout does not persist credentials. It requires no production secrets or Apple account and does not run the application or send positions. Failed builds retain only text diagnostics, with workspace, temporary and home paths replaced, for seven days; app bundles and build caches are not uploaded.
Swift analysis in SonarQube requires Developer Edition, so SonarQube Community is not a required check. CycloneDX SBOM publication to Dependency-Track is deferred until the application has external dependencies; include it in release automation when applicable.
Artwork
The application and menu-bar icons are derived from the editable SVG in Artwork. PNG assets are checked in; normal builds require no artwork tooling. The menu-bar image uses system template rendering for light and dark appearances.
License
Apache License 2.0. This project is independent of the official Traccar project and does not claim official affiliation.