Setup & Developer Workflow
Relevant source files
The following files were used as context for generating this wiki page:
The developer workflow for putio-ios is designed to support both public contributors and internal teammates. It leverages a standard iOS toolchain (Xcode, Ruby, CocoaPods) and provides tiered configuration levels ranging from open-source-safe defaults to private, signed builds. The project emphasizes a "verify early" approach using a mix of unit tests, mocked E2E tests, and simulator-based validation.
Sources: CONTRIBUTING.md:1-12, CLAUDE.md:1-15, README.md:1-30
Project Environment Setup
Getting started requires a specific environment baseline to ensure compatibility across development machines and CI environments.
Prerequisites & Installation
The project relies on specific versions of Xcode and the iOS SDK. Dependencies are managed via Bundler (for Ruby/Fastlane) and CocoaPods (via the make bootstrap command).
| Requirement | Value / Tool |
|---|---|
| Xcode Version | 26.x |
| iOS Runtime | 26.x |
| Ruby Version | Defined in .ruby-version |
| Dependency Manager | CocoaPods, Bundler |
Sources: CONTRIBUTING.md:10-14, CLAUDE.md:4-5
Bootstrap Process
To initialize the development environment, the following command is the primary entry point:
make bootstrap
This command ensures the local toolchain and checked-in development defaults are configured. Public contributors do not need additional secrets to run the basic test suite or build the app using the io.put.dev identity.
Sources: CONTRIBUTING.md:7-16, AGENTS.md:18-20
Configuration Management
The repository uses a multi-layered configuration strategy to separate open-source code from private secrets and team-specific settings.
Configuration Layers
- Shared Defaults:
Config/Shared.xcconfigcontains settings applicable to all builds. - Local Overrides:
Config/Local.xcconfigis used for private secrets and team settings. This file is gitignored. - Placeholders:
Info.plistcontains placeholders that are populated at runtime or build time.
Sources: CONTRIBUTING.md:18-24, CONTRIBUTING.md:65-70
Private Local Configuration (Teammates)
For internal developers requiring signed builds or private service integrations, the project provides a 1Password-integrated setup.
The helper script make secrets-setup materializes the local config from a template using the 1Password desktop app or an OP_SERVICE_ACCOUNT_TOKEN.
Sources: CONTRIBUTING.md:28-36, CLAUDE.md:22-26
Developer Workflow & Commands
The workflow follows a strict validation matrix to maintain code quality and prevent regressions in core areas like authentication and persistence.
Core Commands Reference
| Command | Purpose |
|---|---|
make verify | Performs an unsigned simulator build and runs unit tests. |
make e2e-simulator | Runs fast mocked XCUITests against fixture-backed SDK responses. |
make run-simulator | Uses a signed build to test keychain and auth persistence. |
make secrets-clean | Removes local private configuration. |
Sources: CONTRIBUTING.md:46-60, CLAUDE.md:16-21
Testing and Validation Matrix
The project uses a tiered validation approach:
- Unit Tests: Located in
PutioTests, focusing on pure logic and model parsing. - Mocked E2E: Utilizes
PutioE2EMockURLProtocolto intercept network requests toapi.put.ioand return static fixtures when thePUTIO_E2E_MOCK_APIenvironment variable is set to1. - Persistence Tests: Required for changes to auth or keychain to ensure signed-in persistence behaves correctly.
Sources: Putio/Common/API/PutioE2EMockURLProtocol.swift:5-15, CLAUDE.md:42-49, CONTRIBUTING.md:55-60
Network & SDK Architecture
The app routes behavior through a local SDK wrapper. During development and testing, this SDK can be configured to use a mock protocol for hermetic testing.
SDK Initialization
The PutioSDKFactory determines whether to use a real network session or a mocked one based on the environment.
Mock Data Flow
When PUTIO_E2E_MOCK_API is enabled, PutioE2EMockURLProtocol intercepts requests and maps them to predefined routes:
GET /v2/account/info: Returns mocked account details.GET /v2/files/list: Returns a static list of files including avideoFilefixture.GET /v2/files/42/mp4: Returns a completed MP4 conversion status.
Sources: Putio/Common/API/PutioE2EMockURLProtocol.swift:65-75, Putio/Common/API/PutioSDK.swift:15-22
Coding Patterns & Guidelines
Developers are expected to follow established architectural patterns to maintain consistency across the legacy UIKit codebase.
- Architecture: Prefer existing UIKit, Storyboard, Presenter, and View-Model patterns.
- Location: Feature-specific code lives in
Putio/Features/<Area>, while shared logic resides inPutio/Common. - Persistence: Use
PutioRealmhelpers for database operations. - Error Handling: Surface internal failures via
InternalFailurePresenterrather than failing silently. - Localization: All user-facing copy must be placed in
Putio/en.lproj/Localizable.strings.
Sources: CLAUDE.md:30-40, CONTRIBUTING.md:71-74
Summary
The putio-ios workflow is optimized for rapid local iteration while maintaining a high bar for stability. By providing a fully mocked E2E environment and clear commands for bootstrapping and verification, the project allows developers to validate complex flows—including media playback and authentication—without needing a live backend or private API keys.