Surmagic
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 Create an XCFramework
- What is the Surfile
- Passing parameters
- Further Reading
- 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.
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>
</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
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!
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
Contribute to surmagic
🙋🏻♂️*Need contribution here!
*If you want to contribute please check out 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 file for more info.
![[Question] Create multiple xcframeworks with surfile](https://avatars.githubusercontent.com/u/739037?v=4)
647 Dec 25, 2022
60 Dec 8, 2022
1 Feb 11, 2022
2k Jan 7, 2023
792 Jan 4, 2023
1 Jan 17, 2022
607 Jan 3, 2023
6.1k Jan 7, 2023
49 Jan 4, 2023
4.3k Dec 29, 2022
11 Apr 2, 2020
438 Jan 4, 2023
28 Aug 28, 2022
483 Jan 8, 2023
2.3k Jan 9, 2023
2 Mar 29, 2022
200 Dec 19, 2022