Build Scripts for Palmier Pro: Development, Bundling, and Release Automation

Palmier Pro uses three Bash scripts in the scripts/ directory—dev.sh, bundle.sh, and release.sh—to handle debug builds, code signing, notarization, and distribution packaging.

The palmier-io/palmier-pro repository relies on a minimal yet comprehensive build system written in Bash. These scripts wrap Swift Package Manager commands to streamline development cycles and automate the complex steps required for distributing signed macOS applications.

Core Build Scripts Overview

The build system consists of three executable scripts located in scripts/. Each handles a distinct phase of the development lifecycle, from rapid iteration to production distribution.

dev.sh: Fast Development Builds with Log Streaming

The scripts/dev.sh script optimizes the edit-compile-test loop for daily development. It invokes bundle.sh debug --fast to generate a quick debug build that skips dSYM generation and deep signing for speed. After compilation, it automatically opens the built app and optionally streams OSLog entries from the io.palmier.pro subsystem using log stream --predicate.

When executed with the --no-stream flag, the script launches the app without attaching the log monitor, which is useful for testing background behavior or when terminal noise must be minimized.

bundle.sh: Core Bundling and Signing Logic

scripts/bundle.sh contains the heavy lifting for both debug and release configurations. It parses build arguments (debug or release) and configures the Swift build environment, including paths, provisioning profiles, and signing identities.

For debug builds, the script runs swift build -c debug and produces .build/PalmierPro.app. For release builds, it supports additional flags:

• --sign: Applies Developer ID code signing using the certificate referenced in the configuration
• --dist: Executes the full distribution pipeline including notarization via xcrun altool, stapling with stapler staple, and DMG generation

The script references scripts/PalmierPro.entitlements for sandbox permissions and scripts/Palmier_Pro_Developer_ID.provisionprofile for provisioning during signing operations.

release.sh: Automated Version Publishing

scripts/release.sh serves as a convenience wrapper for cutting new releases. Accepting a semantic version number (e.g., 0.2.0) as its primary argument, it orchestrates the end-to-end release process.

The script calls bundle.sh release --dist to produce a signed and notarized distribution, generates a changelog entry, commits the version bump, and pushes a Git tag to the repository. This ensures that every release tag corresponds to a properly notarized build artifact ready for distribution.

How the Build Pipeline Works

The scripts follow a hierarchical execution model designed to minimize configuration duplication while supporting flexible usage patterns.

dev.sh → bundle.sh debug --fast: This chain produces the fastest possible builds for local testing. It prioritizes compilation speed over optimization and skips code-signing deep verification.

bundle.sh: Acts as the central build engine. When called directly with release --dist, it performs the complete macOS distribution workflow including:

1. Compiling with swift build -c release
2. Signing the binary with codesign using Developer ID credentials
3. Uploading to Apple for notarization via xcrun altool --notarize
4. Stapling the resulting ticket to the app bundle
5. Packaging the final artifact into a DMG file

release.sh: Provides the entry point for CI/CD integration. By encapsulating versioning logic and git operations, it ensures consistent release practices across different environments.

Practical Usage Examples

Build and Run with Log Streaming

Execute the development script to compile a fast debug build and monitor application logs in real time:

./scripts/dev.sh

To launch without attaching the log stream:

./scripts/dev.sh --no-stream

The log stream command used internally is:

log stream --predicate 'subsystem == "io.palmier.pro"' --level info --style compact

Create a Debug Bundle

For a standard debug build without the automatic app launch:

./scripts/bundle.sh debug

This produces a signed debug build at .build/PalmierPro.app suitable for debugging in Xcode or testing manually.

Produce a Signed Release Distribution

To build, sign, notarize, and package a release version:

./scripts/bundle.sh release --dist

This command runs the full release pipeline and generates PalmierPro.dmg in the repository root, ready for distribution.

Publish a New Version

To release version 0.2.0, update the changelog, and push a Git tag:

./scripts/release.sh 0.2.0

The script validates the version format, invokes the distribution build, and manages repository tagging automatically.

Configuration and Dependencies

The build scripts rely on standard macOS development tools and configuration files stored alongside the scripts:

• Package.swift: Defines the Swift Package Manager manifest, app targets, and dependencies
• scripts/PalmierPro.entitlements: Specifies sandbox entitlements and capabilities for code signing
• scripts/Palmier_Pro_Developer_ID.provisionprofile: The provisioning profile required for Developer ID distribution signing

All scripts assume a macOS environment with Xcode command line tools installed, providing access to swift, codesign, xcrun, and log utilities without additional dependencies.

Summary

• Three script architecture: dev.sh for development, bundle.sh for compilation logic, and release.sh for versioning
• Debug optimization: Use ./scripts/dev.sh for the fastest compile-run cycles with optional OSLog streaming
• Production pipeline: Release builds support code signing, Apple notarization, and DMG creation via bundle.sh release --dist
• Zero external dependencies: The system relies solely on macOS native tools and Swift Package Manager
• Extensible design: Plain Bash implementation allows easy CI/CD integration without modifying Swift source code

Frequently Asked Questions

Where are the build scripts located in the repository?

The build scripts are located in the scripts/ directory at the repository root. The three primary files are scripts/dev.sh, scripts/bundle.sh, and scripts/release.sh, alongside configuration files like PalmierPro.entitlements.

Do I need any special certificates to run the debug build scripts?

No. Debug builds using dev.sh or bundle.sh debug use ad-hoc or automatic code signing suitable for local testing. However, release builds using --sign or --dist flags require a valid Apple Developer ID certificate and the provisioning profile located at scripts/Palmier_Pro_Developer_ID.provisionprofile.

How does the log streaming feature work in dev.sh?

When you run ./scripts/dev.sh without the --no-stream flag, the script launches a background process that executes log stream filtered to the io.palmier.pro subsystem. This captures OSLog entries from the running application in real-time, displaying them in your terminal with compact formatting until you terminate the script.

Can I use these scripts in CI/CD pipelines?

Yes. The scripts are designed to be portable and require no interactive input when provided with proper environment variables for signing. The release.sh script is particularly suitable for automation, as it handles versioning, building, notarization, and git tagging in a single command that can be triggered from GitHub Actions or similar platforms.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}