Surmagic

🚀 Create XCFramework with ease! Surmagic is a command-line tool to create XCFramework for multiple platforms at one shot! You don't need to waste your time with command-line scripts when you want to create an XCFramework! Surmagic adds an elegant layer between you and the compiler, for your comfort. You can use Surmagic with your current CI/CD pipeline, or as a standalone tool in your toolbox. The better way to deal with XCFrameworks for iOS, iPadOS, Mac Catalyst, tvOS, macOS, and watchOS.

Description

After Xcode 11 now Xcode fully supports using and creating binary frameworks in Swift. Simultaneously support devices and Simulator with the new XCFramework bundle type. XCFrameworks support binary distribution of Swift and C-based code. A single XCFramework can contain a variant for the simulator, and for the device. This means you can ship slices for any of the architectures, including simulator, any Apple OS and even separate slices for UIKit and AppKit apps.

Programming language: Swift

License: MIT License

Tags: Framework     Swift     iOS     Xcode     Swiftpm     macOS Catalyst     XCFrameworks    

README

Surmagic

🚀 Create XCFramework with ease! A Command Line Tool to create XCFramework for multiple platforms at one shot! The better way to deal with XCFrameworks for iOS, Mac Catalyst, tvOS, macOS, and watchOS.

Stop wasting your time with the Universal/Fat Framework Approach. You don't need to update your shell script periodically anymore.

• About
• Requirements
• Installing
• Setting up surmagic
• How To Use surmagic
  • How To Create an XCFramework
  • All Available Commands and Options
  • What is the Surfile
  • SDK Options
  • Passing parameters
• Further Reading
  • [What is a Swift package?](what-is-an-xcframework)
  • [What is an XCFramework?](what-is-an-xcframework)
  • Advantages in comparison with the FAT Framework approach
  • Why not the Swift Package Manager (SPM)?
• Uninstalling
• References
• Contribute
• License

About

After Xcode 11 now Xcode fully supports using and creating binary frameworks in Swift. Simultaneously support devices and Simulator with the new XCFramework bundle type. XCFrameworks support the binary distribution of Swift and C-based code. A single XCFramework can contain a variant for the simulator, and for the device. This means you can ship slices for any of the architectures, including simulator, any Apple OS and even separate slices for UIKit and AppKit apps.

Requirements

• macOS Version 11.2 and above
• Xcode 12 and above
• Swift 5.1 and above

Installing surmagic

Xcode command line tools (macOS)

Install the command line tools with the command below:

$ xcode-select --install

Homebrew (macOS)

Brew is the Recommended way to install/uninstall the surmagic.

$ brew tap gurhub/surmagic
$ brew install surmagic

This command will install surmagic to your desired bash.

Setting up surmagic

Open the desired terminal application and enter inside of your project directory's root:

$ cd [path-on-your-disk]/your-project

Use the command below to create the necessary surmagic directory and files.

$ surmagic init

This will create a surmagic directory and a Surfile like below:

• --- your-project
• ------ surmagic
• --------- Surfile

How To Create an XCFramework

After setting up your directory, and filling mandatory parameters in the Surfile you can simply use:

$ surmagic xcf

command to create an XCFramework. That's it. There are other commands too. Please keep reading.

All Available Commands and Options

Use 'surmagic --help' to learn all available commands in the surmagic.

USAGE: surmagic <subcommand>

OPTIONS:
  --version               Show the version.
  -h, --help              Show help information.

SUBCOMMANDS:
  init                    Creates the mandatory directory (surmagic) and files.
  xcf (default)           Creates an XCFramework via Surfile.
  env                     To use while creating an issue on Github, prints the
                          user's environment.

  See 'surmagic help <subcommand>' for detailed help.

Passing parameters to surmagic command-line tools

Surmagic contains several command-line tools, e.g. surmagic xcf or surmagic init. To pass parameters to these tools, append the option names and values as you would for a normal shell command:

$ surmagic [tool] --[option] --[option] ...∞

$ surmagic init
$ surmagic xcf --verbose

What is the Surfile

The Surfile is used to configure surmagic. Open it in your favorite text editor, and add desired targets.

It's a standard Plist (XML) file.

The Surfile has to be inside your ./SM directory.

The Surfile stores the automation configuration that can be run with surmagic.

<dict>
  <key>output_path</key>
  <string>_OUTPUT_DIRECTORY_NAME_HERE_</string>
  <key>framework</key>
  <string>_FRAMEWORK_NAME_HERE_</string>
  <key>targets</key>
  <array>
    <dict>
      <key>sdk</key>
      <string>_TARGET_OS_HERE_</string>
      <key>workspace</key>
      <string>_WORKSPACE_NAME_HERE_.xcworkspace</string>
      <key>scheme</key>
      <string>_SCHEME_NAME_HERE_</string>
    </dict>
     <!--
       Remove this comment and add more targets for Simulators and the Devices.
      -->
  </array>
  <key>finalActions</key>
  <array>
    <string>openDirectory</string>
  </array>
</dict>

SDK Options

Key	Description
iOS	iOS
iOSSimulator	iOS Simulator
macOS	macOS
macOSCatalyst	macOS Catalyst
tvOS	tvOS
tvOSSimulator	tvOS Simulator
watchOS	watchOS
watchSimulator	watch Simulator

Check the Demo project's example.

Further Reading

What is an XCFramework?

An XCFramework is a distributable binary package created by Xcode that contains variants of a framework or library so that it can be used on multiple platforms (iOS, macOS, tvOS, and watchOS), including Simulator builds. An XCFramework can be either static or dynamic and can include headers.

To use a prebuilt XCFramework, link the target to the XCFramework. Xcode ensures that the target can build against the XCFramework’s headers, link against its binary, and embed it for distribution. If your app has multiple targets (such as app extensions) that use the same XCFramework, you should pick one target (usually your app’s target) to embed the XCFramework and the others should link it without embedding.

Check in the official Apple documentation.

What is a Swift package?

A Swift package is a folder containing a manifest file and source files used to build software products.

The package manifest (a file named Package.swift at the top level of the package folder) defines the package’s name, products, targets, and dependencies on other packages. The manifest file is written in Swift using API from the Swift Package Manager's PackageDescription library

A package product defines the externally visible build artifact, such as libraries and executables, that are available to clients of a package. A package target defines a test or module from which the products in a package are built. Targets may have dependencies on targets in the same package and dependencies on products from its package dependencies.

A package dependency enables a package target, or Xcode project, to use a product in another package. A package dependency is specified by a URL to the remote Git repository containing the package, and the versions of the package that are supported by the client. The format of a package version uses the Semantic Versioning specification, which is typically a three period-separated integer, such as 2.1.4.

The source files for targets can be written in Swift, C/C++, Objective-C/C++, or assembler, and are located under the Sources folder in the package. Each target can either contain only Swift source code, or any combination of C, C++, Objective-C, Objective-C++, and assembler source code. The source files for Test targets are written using the XCTest framework, and are located under the Tests folder.

Check in the official Apple documentation.

Advantages of the XCFramework, comparison with the FAT Framework Approach:

• Packing dependencies under all target platforms and architectures into one single bundle from the box
• Connection of the bundle in the format of XCFramework, as a single dependency for all target platforms and architectures
• Missing the need of building fat/universal framework
• No need to get rid of x86_64 slices before uploading end applications to AppStore

Also, with surmagic, you won't need to be an expert on the questions listed below:

• How to create XCFramework in Xcode?
• How to build Universal iOS Frameworks using XCFramework
• XCFramework tutorial
• How do I use XCFramework?
• What is XCFramework?
• How do I create a custom framework in Swift?
• How to add XCFramework to Xcode project?
• How do I import framework into Xcode?
• What is Xcode framework?
• Convert a Universal (FAT) Framework to an XCFramework)
• Advances in XCFramework
• Automatic support for Apple Silicon via FAT binaries
• Built-in support for the BCSymbolMaps and dSYMs

Why not the Swift Package Manager (SPM)?

Well, why not!🤓 It's the easiest! But, Swift PM only allows you to perform the delivery of libs in the form of open source code with the description of dependencies.

Apple presented XCFramework as a new binary format of packing the libs, considering it as an alternative for Swift Packages.

References

• WWDC 2020 - 10147 presentation
• WWDC 2020 - 10170 presentation
• WWDC 2019 - 416 presentation
• Create an XCFramework
• Link a target to frameworks and libraries
• Distributing Binary Frameworks as Swift Packages

Wiki

If you didn't find what you're looking for, check Surmagic's Wiki page. Or maybe you'll want to improve the Wiki page🤓. Obviously, it's a great idea. 👏🏻

Contribute to surmagic

🙋🏻‍♂️*Need contribution here!

*If you want to contribute please check out [CONTRIBUTING.md](CONTRIBUTING.md) for more information on how to help with surmagic.

Contributers

• Muhammed Gurhan Yerlikaya, [email protected], @mgyky

License

"Surmagic" is available under the MIT License license. See the [LICENSE](LICENSE) file for more info.