A brief history of xcode-install aka xcversion, as well as a guide on how to migrate from it, to a more modern tool.
For brevity sake I'm going to refer to this project always as xcode-install in this document.
The more time goes by, the more we realized this project had already provided the community the value it needed, served its purpose, and become obsolete. We believe it was the time to officially sunset this project, and this document will guide you to use a more modern and well maintained tool.
xcode-install (originally a @neonichu's project, which got transferred to @KrauseFx, which got transferred to the @xcpretty GitHub organization), had been around since April 2015, back when there were no other good options to manage multiple versions of Xcode.
Fast forward to Feb 2019, xcodes was born to provide a more user friendly experience. It based itself off of this project to figure out the complex Xcode downloading logic, but has since then been actively maintained and new features are incorporated into it on a regular basis. To name a few, that are not present in xcode-install:
- GUI (via
Xcodes.app) - Support to
aria2(which has been requested in #425 but we never got to implement it), which uses up to 16 connections to download Xcode 3-5x faster - Support to
unxip, providing unxipping up to 70% faster - New in Xcode 14: Sessionless downloads, just announced by @xcodesapp: https://twitter.com/xcodesapp/status/1570991082359627779?s=46&t=qVETxqxGI7ZZsFLLrledIg, available in https://github.com/RobotsAndPencils/XcodesApp/releases/tag/v1.8.0b16
These features, plus the fact that this project wasn't getting the attention it needed to keep supporting newer versions of Xcode and bug fixes, made us believe it was time to sunset this project.
As of fastlane/fastlane#20672, a new action was introduced to fastlane called xcodes. You can find its full documentation here: https://docs.fastlane.tools/actions/xcodes
Keep in mind that the xcodes action depends on xcodes CLI, so make sure you have it installed in your environment. For the installation guide, see: https://github.com/RobotsAndPencils/xcodes#installation
There are 3 actions that depend on xcode-install gem. Below you can find how to migrate each one of them:
xcode_install used to receive an Xcode version and "install if needed", which is the new xcodes action's main purpose.
Before:
xcode_install(
version: '14',
username: '[email protected]',
team_id: 'ABCD1234',
download_retry_attempts: 5,
)Now:
The team_id and download_retry_attempts options are no longer needed (nor supported).
xcodes(
version: '14',
username: '[email protected]',
)xcversion used to receive an Xcode version and select it for the current build steps, which in xcodes action that's the select_for_current_build_only option.
Before:
xcversion(version: '14')Now:
xcodes(
version: '14',
select_for_current_build_only: true,
)This action wasn't migrated to use xcodes within fastlane yet, mainly because of the somewhat complex logic around the non-strict version checking. This document as well as fastlane's ensure_xcode_version action documentation will be updated when the new xcodes action officially deprecates the ensure_xcode_version action. For now, if you don't use the strict: false option of ensure_xcode_version, you can migrate to xcodes action by passing select_for_current_build_only: true, which will raise an error if the given version can't be selected:
Before:
ensure_xcode_version(
version: '14',
strict: false,
)ensure_xcode_version(version: '14')Now:
xcodes(
version: '14',
select_for_current_build_only: true,
)You can install them via, e.g.:
xcodes runtimes install 'iOS 16.0'More documentation about this will be created soon, directly in the xcodes repository.
If there are other use cases that you don't see covered so far, check out the full documentation here: https://docs.fastlane.tools/actions/xcodes
All the lanes that supported .xcode-version still support it 🎉
If you're using xcode-install as a CLI, the process to migrate to xcodes is more straightforward: simply visit https://github.com/RobotsAndPencils/xcodes and check their installation and usage guide.
xcode-install CLI supported .xcode-version and so does xcodes 🎉
Huge shout out to @neonichu, @KrauseFx, @mrcljx, @jpsim, @timsutton, and many other contributors (which you can check here: https://github.com/xcpretty/xcode-install/graphs/contributors) for the work they put into this project! It advanced the state of the art in its field, and the community benefitted a lot from it! xcodes wouldn't be where it is today without your effort into this project 💟
Thank you all, and see you on the other side!