Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
86 lines (60 loc) · 4.82 KB

DEVELOPMENT.md

File metadata and controls

86 lines (60 loc) · 4.82 KB
Raw

Development

Prerequisites

  • Swift 6.3 or later and Make. CI and Linux containers use Swift 6.4.0.
  • Homebrew for make init, which installs actionlint, dprint, pre-commit, and SwiftLint.
  • Docker for container-based Linux build and test targets.

Build from source

Clone the repository and build:

git clone https://github.com/techprimate/apple-docs-cli.git
cd apple-docs-cli
make build
./dist/apple-docs --help

The release binary is written to dist/apple-docs. You can run it directly or install it into a directory on your PATH.

Setup

From the repository root, install development tools and resolve SwiftPM dependencies:

make init

Install the Git hooks separately:

pre-commit install

make init requires Homebrew. If you manage development tools yourself, install the tools listed above and run make resolve to resolve SwiftPM dependencies.

Development commands

Command Purpose
make run ARGS="types view Button --technology SwiftUI" Run the executable through SwiftPM.
make build Build the release binary at dist/apple-docs.
make test Run deterministic unit and in-process interactive tests.
make test-linux Run tests in pinned Swift 6.4.0 containers for amd64 and arm64.
make test-integration Build the release binary and run live tests against Apple documentation. Requires internet access.
make analyze Run SwiftLint, formatting checks, and actionlint.
make format Format Swift with swift format and JSON, YAML, Markdown, and TOML with dprint.
make help Show all development commands.

Linux workflows

Container commands mount the source read-only and keep build products in Docker volumes, separate from the host build directory. The two test architectures use isolated volumes. Select one architecture or narrow the tests when needed:

make test-linux-amd64
make test-linux-arm64 TEST_ARGS="--filter AppleDocumentationClientSearchTests"
make build-linux-native
make test-integration-linux

make test includes the offline BrowserApplicationTests suite. It runs a real Twill application on a pseudo-terminal, feeds keys, and asserts the visible screen rather than searching accumulated terminal output. To focus on it locally, use make test TEST_ARGS="--filter BrowserApplicationTests". CLIIntegrationTests run the release executable as a subprocess for one-shot commands; their live documentation cases run only with make test-integration and require internet access. Both live integration targets accept INTEGRATION_FILTER=SuiteName. make test also accepts TEST_ARGS. Do not count sending keys to a release process and observing only its exit as verification of browser behavior.

For static release builds, use the matching Swift.org 6.4.0 toolchain, not Xcode's bundled compiler:

make install-linux-sdk
make build-linux SWIFT_SDK=x86_64-swift-linux-musl
make build-linux SWIFT_SDK=aarch64-swift-linux-musl

Alternatively, install the SDK and build inside the container without changing the host toolchain:

make install-linux-sdk-container
make build-linux-container SWIFT_SDK=x86_64-swift-linux-musl
make run-linux ARGS="swift sdk list"

Container targets accept LINUX_DOCKER_FLAGS. Direct container targets also accept LINUX_BUILD_VOLUME and LINUX_SDK_VOLUME to isolate build and SDK storage. Static outputs remain in SwiftPM's SDK-specific release directory. make build-linux-native uses the container's libc for release CLI integration tests.

Before submitting

Follow the repository instructions, keep changes focused, and add a regression test for behavior changes and bug fixes.

Run make test, make analyze, and make build. After Swift edits, run make format and rerun make analyze. For command-facing changes, exercise the affected release command and check its result, not just its exit status. Interactive behavior is covered by the PTY tests in make test.