Skip to content
giginetPublic

About

A new build tool to generate XCFramework

Resources

Stars

551 stars

Watchers

11 watching

Forks

Latest commit

Β 

History

1,532 Commits

Folders and files

Repository files navigation

Scipio

GitHub Workflow Status (with event) Swift 6.2 Xcode 26.0.1 SwiftPM Documentation Platforms License

Carthago delenda est

Scipio proposes a new workflow to integrate dependencies into your applications.

This product is highly inspired by Carthage and swift-create-xcframework.

Abstract

SwiftPM is the best way to integrate dependencies into your app. However, build artifacts built by Xcode are difficult to cache.

On the other hand, XCFramework is a good way to keep binaries portable.

Scipio provides a new hybrid way to manage dependencies.

First, use SwiftPM to resolve dependencies and checkout repositories. After that, this tool converts each dependency into XCFramework.

Usage

See Scipio Official Documentation for detail.

Installation

The easiest way to install Scipio is to use nest. nest install giginet/Scipio

Prepare all dependencies for your application

The concept of Scipio, all dependencies wanted to be used in your application should be defined in one Package manifest.

prepare command is to build all dependencies as XCFrameworks in the manifest.

This mode is called prepare mode. See Prepare All Dependencies for Your Application for detail.

Define Package.swift to describe your application's dependencies

// swift-tools-version: 6.0
// The swift-tools-version declares the minimum version of Swift required to build this package.

import PackageDescription

let package = Package(
    name: "MyAppDependencies",
    platforms: [
        // Specify platforms to build
        .iOS(.v14),
    ],
    products: [],
    dependencies: [
        // Add dependencies
        .package(url: "https://github.com/onevcat/APNGKit.git", exact: "2.2.1"),
    ],
    targets: [
        .target(
            name: "MyAppDependency",
            dependencies: [
                // List all dependencies to build
                .product(name: "APNGKit", package: "APNGKit"),
            ]),
    ]
)

Run prepare command

$ scipio prepare path/to/MyAppDependencies
> πŸ” Resolving Dependencies...
> πŸ—‘οΈ Cleaning MyAppDependencies...
> πŸ“¦ Building APNGKit for iOS
> πŸš€ Combining into XCFramework...
> πŸ“¦ Building Delegate for iOS
> πŸš€ Combining into XCFramework...
> ❇️ Succeeded.

All XCFrameworks are generated into MyAppDependencies/XCFrameworks by default.

Library Evolution support

Scipio disables to support Library Evolution feature by default.

It means built frameworks can be used only from products built with the same Swift version.

The primary reason why is Library Evolution limitation. In fact, some packages can't build with enabling Library Evolution. (https://developer.apple.com/forums/thread/123253, apple/swift-collections#94, apple/swift-nio#1257)

If you want to distribute generated XCFrameworks, it's recommended to enable Library Evolution. Pass --enable-library-evolution flag if you need. However, it means some packages can't be built.

Build Cache System

By default, Scipio checks whether re-building is required or not for existing XCFrameworks.

$ swift run scipio prepare --framework-cache-policy project path/to/MyAppDependencies
> πŸ” Resolving Dependencies...
> πŸ—‘οΈ Cleaning MyAppDependency...
> βœ… Valid APNGKit.xcframework is exists. Skip building.
> βœ… Valid Delegate.xcframework is exists. Skip building.
> ❇️ Succeeded.

Scipio supports Project/Local Disk/Remote Disk cache backends.

Using a remote cache, share built XCFrameworks among developers.

See Learn the Cache System for details.

Swift macros

When a selected library target depends on a SwiftPM .macro target, Scipio builds the plugin for the host Mac and supplies it when compiling that library. Plugin artifacts are written to <package>/.build/scipio/MacroPlugins/<module>/<module>, inside the Scipio workspace regardless of the XCFramework output directory. .build/scipio/MacroPlugins/plugins.json maps each plugin module to its relative executable path and dependent library targets.

Targets that use the macro must load the plugin when they compile, for example:

-load-plugin-executable /path/to/package/.build/scipio/MacroPlugins/ExamplePlugin/ExamplePlugin#ExamplePlugin

Declare the library-to-macro dependency in the package manifest; Scipio does not discover macros that are absent from the selected dependency graph. The executable is a build-time host tool and must not be embedded in an app.

Macro artifacts use project and Local Disk caches when the full host dependency graph has pinned revisions. Custom framework cache storages can optionally implement MacroPluginsCacheStorage; older storages continue to cache frameworks only. Existing S3 storage versions require an update to cache macros.

Set Runner.Options.requireMacroArtifactStorage to reject producer policies without macro artifact support when publication is required.

The host build currently uses SwiftPM's deprecated native build system and requires the macro product to be reachable from the resolved package graph. Host architectures and toolchains other than the one running Scipio require separate builds. The current artifact assembly copies all bundles and dylibs in SwiftPM's host products directory; dependency-specific selection and portability of dynamically linked artifacts require further validation.

See Use Swift Macros for package setup, consumer configuration, and caching details.

Create XCFramework from a single Swift Package

Scipio also can generate XCFrameworks from a specific Swift Package. This feature is similar to swift-create-xcframework.

$ scipio create path/to/MyPackage
> πŸ” Resolving Dependencies...
> πŸ—‘οΈ Cleaning MyPackage...
> πŸ“¦ Building MyPackage for iOS
> πŸš€ Combining into XCFramework...
> ❇️ Succeeded.

See Convert Single Swift Package to XCFramework for detail.

Supported Xcode and Swift version

We support Xcode 26 and later, with Swift 6.2 or later. Xcode 16.4 is deprecated and is no longer tested in CI.

The following versions are tested in CI:

Xcode Swift
βœ… 26.0.1 6.2
βœ… 26.4.1 6.3
βœ… 27.0 6.4

Reliability

Scipio only builts with standard dependencies and Apple official tools to keep reliability.

How to resolve dependencies

Just run swift package resolve.

How to parse package manifests and generate Xcode projects

Scipio depends on swift-package-manager as a library.

Parsing package manifests and generating Xcode project is provided from the package. So it will be maintained in the future.

How to build XCFrameworks

Scipio only uses xcodebuild to build Frameworks and XCFrameworks.

Notice

Scipio copies several source files from Swift Package Manager. The copies are placed in Sources/ScipioKit/SwiftPM, and are licensed under the Apache License, Version 2.0.

Why Scipio

Scipio names after a historical story about Carthage.

About

A new build tool to generate XCFramework

Resources

Stars

551 stars

Watchers

11 watching

Forks

Releases

Packages

Used by

Contributors

Languages