xcodesorg/xcodesapp

The easiest way to install and switch between multiple versions of Xcode - with a mouse click.

Xcodes.app

The easiest way to install and switch between multiple versions of Xcode.

If you're looking for a command-line version of Xcodes.app, try xcodes.

🎉 Announcement

XcodesApp is now part of the XcodesOrg - read more here

Features

• List all available Xcode versions from Xcode Releases' data or the Apple Developer website.
• Install any Xcode version, fully automated from start to finish. Xcodes uses aria2, which uses up to 16 connections to download 3-5x faster than URLSession.
• Automatically resumes installs if network errors.
• Apple ID required to download Xcode versions.
• Just click a button to make a version active with xcode-select.
• View release notes, OS compatibility, included SDKs and compilers from Xcode Releases.
• Dark/Light Mode supported

Platforms/Runtimes

• Xcodes supports downloading the Apple runtimes via the app. Simply click on the Platform, and Xcodes will install automatically for you.

Experiments

• Thanks to the wonderful work of https://github.com/saagarjha/unxip, turn on the experiment to increase your unxipping time by up to 70%! More can be found on his repo, but bugs, high memory may occur if used.

Localization

Xcodes supports localization in several languages.

The following languages are supported because of the following community users!

French 🇫🇷	@dompepin	Italian 🇮🇹	gualtierofrigerio
Spanish 🇪🇸🇲	@cesartru88	Korean 🇰🇷	@ryan-son
Russian 🇷🇺	@alexmazlov	Turkish 🇹🇷	@egesucu
Hindi 🇮🇳	@KGurpreet	Chinese-Simplified 🇨🇳	@megabitsenmzq
Finnish 🇫🇮	@marcusziade	Chinese-Traditional 🇹🇼	@itszero
Ukranian 🇺🇦	@gelosi	Japanese 🇯🇵	@tatsuz0u
German 🇩🇪	@drct	Dutch 🇳🇱	@jfversluis
Brazilian Portuguese 🇧🇷	@brunomunizaf	Polish 🇵🇱	@jakex7
Catalan	@ferranabello

Want to add more languages? Simply create a PR with the updated strings file.

Installation

v1.X - requires MacOS 11 or newer v2.X - requires MacOS 13

Install with Homebrew

Developer ID-signed and notarized release builds are available on Homebrew. These don't require Xcode to already be installed in order to use.

brew install --cask xcodes

Manually install

1. Download the latest version here using the Xcodes.zip asset. These are Developer ID-signed and notarized release builds and don't require Xcode to already be installed in order to use.
2. Move the unzipped Xcodes.app to your /Applications directory

Support

Xcodes.app and CLI is updated, maintained with contributors like yourself. Even open source libraries and tools come with expenses. If you would like to support Xcodes or donate to the development and maintenance of the tool, it would be greatly appreciated. There is absolutely no obligation!

Development

You'll need macOS 13.5 Ventura and Xcode 15 in order to build and run Xcodes.app.

Unxip and aria2 must be compiled as a universal binary

# compile for Intel
 swiftc -parse-as-library -O -target x86_64-apple-macos11 unxip.swift
# compile for M1
 swiftc -parse-as-library -O -target arm64-apple-macos11 unxip.swift

# combine for universal binary
 lipo -create -output unxip unxip_intel unxip_m1  
# check it
 lipo -archs unxip

Notable design decisions are recorded in DECISIONS.md. The Apple authentication flow is described in Apple.paw, which will allow you to play with the API endpoints that are involved using the Paw app.

xcode-install and fastlane/spaceship both deserve credit for figuring out the hard parts of what makes this possible.

Releasing a new version

Follow the steps below to build and release a new version of Xcodes.app. For any of the git steps, you can use your preferred tool, but please sign the tag.

# Update the version number in Xcode and commit the change, if necessary

# Question: Did anything in XPCHelper change?
# - com.xcodesorg.xcodesapp.Helper folder and HelperXPCShared
# - if so, bump the version number in com.xcodesorg.xcodesapp.Helper target.
# Note: you do not have to bump the version number if nothing has changed.
# Note2: If you do bump the version, the end user, must re-install the XPCHelper and give permission again.

# Increment the build number
scripts/increment_build_number.sh

# Commit the change
git add Xcodes/Resources/Info.plist
git commit -asm "Increment build number"

# Tag the latest commit
# Replace $VERSION and $BUILD below with the latest real values
git tag -asm "v$VERSIONb$BUILD" "v$VERSIONb$BUILD"

# Push to origin
git push --follow-tags

# Build the app
# Make sure you have the Xcode Selected you want to build with
scripts/package_release.sh

# Notarize the app
# Do this from the Product directory so the app is zipped without being nested inside Product
# Create a app specific password on appleid.apple.com if you haven't already
# xcrun notarytool store-credentials "AC_PASSWORD" \
#              --apple-id "[email protected]" \
#              --team-id "teamid" \
#               --password "app specific password"

pushd Product
../scripts/notarize.sh Xcodes.zip <MYORG>

# Sign the .zip for Sparkle, note the signature in the output for later
# If you're warned about the signing key not being found, see the Xcodes 1Password vault for the key and installation instructions.
../scripts/sign_update Xcodes.zip
popd

# Go to https://github.com/XcodesOrg/XcodesApp/releases
# If there are uncategorized PRs, add the appropriate label and run the Release Drafter action manually
# Edit the latest draft release
# Set its tag to the tag you just pushed
# Set its title to a string with the format "$VERSION ($BUILD)"
# Polish the draft release notes, if necessary
# Add the signature to the bottom of the release notes in a comment, like:
<!-- sparkle:edSignature=$SIGNATURE -->
# Attach the zip that was created in the Product directory to the release
# Publish the release

# Update the [Homebrew Cask](https://github.com/RobotsAndPencils/homebrew-cask/blob/master/Casks/xcodes.rb).

Maintainers

Matt Kiazyk - Twitter

Twitter | GitHub | Mastadon |

xcodesapp's Issues

Catch and reword xip's "not enough free space" error

Tell us how we can improve Xcodes

When the volume doesn't have enough space to expand a .xip archive, the xip command used under the hood will fail.

From the logs:

2021-01-23 11:16:57.291081-0700 Xcodes[17671:962405] [subprocess] Process.run error: xip: error: The archive “Xcode-12.4.0-Release.Candidate+12D4e.xip” can’t be expanded because the selected volume doesn’t have enough free space.

This is the alert that is currently shown:

This is one of the most common errors I get when installing an Xcode.

What would you like to see? How would you like it to work?

Xcodes.app should present an alert with a good user-facing error message, like:

The archive “Xcode-12.4.0-Release.Candidate+12D4e.xip” can’t be expanded because the current volume doesn’t have enough free space.

Prerelease versions are shown when "Include prerelease versions" is unchecked

On first launch of the app I noticed all the beta and release candidate versions were listed. I looked for a way to hide those and only show full release versions. The closest option I could find was Updates -> Include prerelease versions which was already unchecked. Maybe this is because I was using the command line tool previously?

App icon

Ability to do an old Xcode Cleanup

Every so often, we as developers need to clean up old simulators, archives, etc. because we run out of disk space. It would be beneficial to provide this utility for the users of the app, so they can easily do this. Many devs forget to do this, or have to search a few times a year.

There are many other apps, gists, etc and do this type of thing - https://apps.apple.com/us/app/devcleaner-for-xcode/id1388020431?mt=12 is a good example.

This is a large and complex feature, so if you're interested in contributing to it, please comment below so that we can work out the details first.

Download step progress indicator tooltip doesn't update

Describe the bug

Download step progress indicator tooltip doesn't update

To Reproduce

1. Install a version
2. Wait a bit until the download progress indicator is showing a reasonable amount of progress
3. Hover your mouse over the progress indicator so the tooltip is presented, and see that the percentage shown doesn't match the progress indicator

Expected behavior

The tooltip should reflect the same completion as the progress indicator

Screenshots

Version

• OS: 11.1
• Xcodes: 1.0.3

Display File Size in Info panel

Tell us how we can improve Xcodes
Ideally, I'd like to be able to see the size of the Xcode release before downloading it (as I have a fairly limited data connection, so this information is important to me.)

Is your feature request related to a problem? Please describe.
No.

What would you like to see? How would you like it to work?
In the info panel, upon clicking a release, display the file size of the release. Just text is fine, no need to be fancy.

Add installation instructions that link to the latest release

These instructions should be marked as recommended, and placed above any instructions for building from source. Building from source can be folded, like in https://github.com/RobotsAndPencils/Xcodes#installation

Filter/info pane doesn't persist across app closes

Issue:
If I tap on the filter or the info pane, it should persist across app loads

Repro Steps:

1. Set the filter on, or the info pane on
2. Close the app, reopen
3. App shows all versions again

This was working previously.

Instruct user to move app to /Applications if launched from somewhere else

Tell us how we can improve Xcodes

Instruct user to move app to /Applications if launched from somewhere else.

Is your feature request related to a problem? Please describe.

Sparkle updates can fail otherwise (#70).

What would you like to see? How would you like it to work?

Something like this, which is common for macOS apps distributed outside the Mac App Store: https://github.com/potionfactory/LetsMove/. I'm not sure if this is the best implementation, it's just the first one I found, so do some more research on this before implementing.

Improve experience when an error requires the user to authenticate

Currently:

1. Sign out
2. Refresh
3. Note that an invalid session error alert is shown, as well as the sign in UI in preferences

Instead of showing both of these at the same time without explanation, we probably want to do something like one of these options:

• Show the error alert with a Sign In button that shows the sign in UI. There should be a way to indicate that certain errors require the user to sign in. I prefer this option.
• Skip the error alert, and only show the sign in UI
• Only show the error alert, and instruct the user to sign in in preferences.

Download will always use aria2. It should use the preference

Describe the bug
In AppState when we go to download, the install is always set to aria -

self.install(.version(availableXcode), downloader: .aria2)

We should switch that to the AppStorage on the preferences

Increasing windows size vertically is laggy

When increasing the size of the window vertically or diagonally it is very jumpy. Decreasing the size is fine.

Version

• OS: 11.2 Beta
• Xcodes: 1.0.3 (4)

About window

• Include 3rd party license acknowledgements

Add a Homebrew cask

https://github.com/Homebrew/homebrew-cask/blob/master/doc/development/adding_a_cask.md

Auto download

I hate waiting for Xcode to download, would be super cool if the latest beta could download and extract itself as soon as it’s available, so it’s there ready and waiting for me when I need it.

Prepare the user for helper installation alert before attempting it

This would be similar to what a lot of mobile apps do for location services permission. I'm imagining this will look something like: an alert that we show first, explaining what the helper is and why it's necessary, and only if they consent would we attempt to install the helper. If they decline then we don't attempt the install. The copy in Preferences > Advanced is probably close to what we'd show in the alert.

Updating AppState.allXcodes and other version comparisons aren't working well

This is a bit of a junk drawer for issues like:

• #44 (comment)
• #44 (comment)
• Making sure the correct Xcode version is installed when you click it
• Determining which available Xcode versions are installed, for both data sources

Part of the problem is that the Apple data source has less-specific versions compared to Xcode Releases, and any code taken from xcodes might be making bad assumptions as a result.

The other part of the problem is probably just poorly written code on my part 😄

I'd like to keep both data sources, but if these issues can't be solved with the Apple data source I think we could drop it for now.

Add .help(_:) modifier to appropriate controls

Adding help to a view configures the view’s accessibility hint and its tooltip (“help tag”) on macOS.
For more information on using help tags, see Help in the macOS Human Interface Guidelines.

https://developer.apple.com/documentation/swiftui/view/help(_:)-4y7cy#

Update available Xcodes

• There should be a refresh control and menu item
• This should happen automatically when other actions have been performed if a certain duration has passed since it was last updated
• We have code from xcodes that already does this, but which will need to be converted from PromiseKit to Combine.
• The bigger question is whether we should use the data from Xcode Releases instead of scraping Apple's site. It's probably less fragile and seems to be updated pretty fast and consistently. xcinfo is using it already. I'm not sure what the overhead of doing this might be, but it might be worth having both options available to choose from in some settings UI, and defaulting to one.

Preferences Window is shown multiple times

Describe the bug
The preferences window can be created multiple times. That isn't that bad amongst itself, however when you start presenting alerts on it, you can end up with multiple windows showing multiple alerts.

To Reproduce

1. Go to menu and open up preferences
2. Go back to main view and open up a open preferences from step 1

You now have multiple preferences windows

Expected behavior
I would expect only 1 preference window to be always shown. If the window is a presentView (ie I have to close it before going back to the main window) I think that's ok.

Authentication

• Match xcodes support: password and 2FA, not the older two-step.
• The sign in UI should be similar to the one used in Xcode > Preferences > Accounts
• Allow signing out in preferences
• Save credentials in the keychain after signing in

Determine InstalledXcode version based on build version alone when using Xcode Releases data

The scraped data from Apple rarely has the build versions. As a result, InstalledXcode.init?(path:) and Version.isEquivalentForDeterminingIfInstalled(toInstalled:) are relying on the naming scheme of Xcode versions on disk in order to reliably determine its specific version. Xcode Releases does have these build versions, and so if that's the current data source we could probably make this code more reliable by comparing the build version on disk to the list of all build versions.

We wouldn't need to change the naming scheme on disk, but this would give us flexibility to at least accurately determine the version of an Xcode that's not following it.

Indicate that a .xip was downloaded but hasn't been installed yet

One of the more common failures I run in to is downloading the .xip and then not having enough space to unarchive it. Perhaps this could be indicated in the Xcode list UI somehow, so that it's clear that installing will continue from where it left off.

For example, we could use one of the shipping box symbols beside the Install button, with a .help(_:) modifier explaining what it indicates.

I'm not sure if users would want to abort installing the version they just previously intended to install, but allowing an option to delete the .xip without installing it may also be useful. If it's not clear where to put this option then don't let it block implementation of the first part.

2FA security code text fields clip digits

Example:

The expected behaviour is for all of these text fields to be the correct size to contain the largest digit character without clipping. Each character should be centred to handle narrower characters.

Install instructions should instruct user to move app to /Applications

Got this message after checking Include prerelease versions

Display aggregate installation progress in dock icon

At a minimum, Xcodes should display an appropriate overlay on the dock icon when one or more versions are being installed. This could be modelled as a boolean internally.

A fancier implementation of this could provide richer indication of the aggregate installation progress, perhaps through a tree of Progress objects for all versions that are being installed, and each step within their installation.

A library that might make this easier to implement is https://github.com/sindresorhus/DockProgress

Auto download

I really hate waiting for Xcode to download and expand. Would be super cool if this app could check for new versions of Xcode and get the process going in the background so I do r feel like I’m having to wait so long.

Uninstall an Xcode

Support installation in an alternative directory

• Xcodes should support managing Xcode versions in a single directory, which defaults to /Applications
• Advanced preference pane should contain a field that displays the current directory. This should be stored in UserDefaults / AppStorage.
• Xcodes should install new versions into this directory
• Xcodes should detect installed versions in this directory

This should match the functionality of xcodes' --directory flag.

In the past I haven't had a reliable experience using Spotlight to find Xcodes on disk, and I think most people would have them installed in a single directory, so Spotlight wouldn't really add any value in that situation.

Select an Xcode

• Indicate which version is selected in the list
• Allow selecting another installed version with a list item context menu and menu item

Reveal the selected, installed Xcode in Finder

Make sure we build a universal binary

I haven't looked into this yet so I don't know what's involved, but I don't want to forget.

https://developer.apple.com/documentation/xcode/building_a_universal_macos_binary

After uninstalling an Xcode, the leftover action is "Open"

After uninstalling a version of Xcode, the icon beside the corresponding version disappeared, but the CTA showed as "Open". This seemed a bit confusing as I thought I removed it, and clicking "Open" resulted in nothing.

Improve SignIn/Authentication Errors

Given a user is trying to authenticate with Apple via the Xcodes.app
When they enter an incorrect code OR their account is locked out OR some other typical errors
Then we should show a meaningful error message that helps the user figure out what's wrong

Today, our alerts are showing a bunch of HTTP/JSON information which is not user friendly...

badStatusCode(400, 203 bytes, <NSHTTPURLResponse: 0x60000274ba40> { URL: https://idmsa.apple.com/appleauth/auth/verify/trusteddevice/securitycode } { Status Code: 400, Headers {
"Cache-Control" =     (
"no-cache",
"no-store",
"no-store"
);
Connection =     (
"keep-alive"
);
"Content-Encoding" =     (
gzip
);
"Content-Language" =     (
"en-CA-x-lvariant-CAN"
);
"Content-Security-Policy" =     (
"default-src 'self' ; connect-src 'self' ; font-src 'self' https://*.apple.com https://*.cdn-apple.com ; frame-src 'self' https://appleid.apple.com ; img-src 'self' https://*.apple.com https://*.cdn-apple.com data: https://*.icloud.com https://*.mzstatic.com ; media-src * data: ; object-src 'self' ; script-src 'self' https://*.apple.com https://*.cdn-apple.com ; style-src 'unsafe-inline' 'self' https://*.apple.com https://*.cdn-apple.com ; child-src blob: ;"
);
"Content-Type" =     (
"application/json;charset=UTF-8"
);
Date =     (
"Wed, 30 Dec 2020 21:22:00 GMT"
);
Expires =     (
"Thu, 01 Jan 1970 00:00:00 GMT"
);
Pragma =     (
"no-cache"
);
Server =     (
Apple
);
"Set-Cookie" =     (
"dslang=CA-EN; Domain=apple.com; Path=/; Secure; HttpOnly",
"site=CAN; Domain=apple.com; Path=/; Secure; HttpOnly"
);
"Strict-Transport-Security" =     (
"max-age=31536000; includeSubDomains; preload"
);
"Transfer-Encoding" =     (
Identity
);
Vary =     (
"accept-encoding"
);
"X-Apple-I-Ercd" =     (
"-21669"
);
"X-Apple-I-Request-ID" =     (
"6d6214c4-3376-462d-b977-04e7c4b24c81"
);
"X-BuildVersion" =     (
R3
);
"X-Content-Type-Options" =     (
nosniff
);
"X-FRAME-OPTIONS" =     (
DENY
);
"X-XSS-Protection" =     (
"1; mode=block"
);
scnt =     (
86f0259172d984056770365c0f0ea782
);
} })

Make a newly-installed version active if it's the only installed version

Tell us how we can improve Xcodes

Make a newly-installed version active if it's the only installed version.

Is your feature request related to a problem? Please describe.

No.

What would you like to see? How would you like it to work?

We currently do not automatically make versions active in any situation, and I think that's okay as 1) i'm not sure that all users would want to switch active versions in this situation 2) it's easy enough to do manually. In the case that there's only one version installed, though, I think all users would want it to be made active. The only situation I can think of that they might not want this is if they wanted the Command Line Tools to remain active, but those aren't currently a consideration of xcodes or Xcodes.app at all.

The user would have just been asked to install the helper for the post-install steps, so if the helper is not installed when Xcodes should automatically make the version active, maybe it should skip attempting this in order to not bug them about the helper again.

Install helper error shown multiple times after cancel install

Issue:
If I hit cancel on the privileged helper I shouldn't be prompted multiple times saying it couldn't communicate with helper app. It should just cancel

RepoSteps:

1. Tapped Make Active
2. Hit cancel on the prompt

3. Prompted multiple times with error

This may be resolved with changes in #66

2FA Screen: Disable button/spinner while sending

From #11 I've tapped the continue button a few times, thinking it didn't do anything.

Disable the button when an action is done, or spinner, something to let the user know it's trying.

Social preview image

"Make Active" button doesn't work until after restarting app

I installed the privileged helper from the options menu but the Make active button continued to do nothing until after I quit the app and reopened.

Make logging more consistent

We should use the unified log, probably via os_log, for the helper because it doesn't have a debugger connected during development. For the main app we should also use os_log so we can see it interleaved with the helper in Console.app, and maybe also printing to Xcode's console for the convenience of folks that don't care about the helper at the time. I can't recall if os_log also prints to Xcode's console or not, so I'll leave it up to the implementor to figure out how to achieve this.

No sign in UI presented with brew cask install on Big Sur 11.2

Describe the bug
No sign in UI is presented

To Reproduce
Steps to reproduce the behavior:
Click to install an XCode, no sign in UI is presented, error alert is immediately displayed.

Expected behavior
A clear and concise description of what you expected to happen.
Some UI affordance to sign into Apple Developer Portal should appear

Screenshots
If applicable, add screenshots to help explain your problem.

Version

• OS: Big Sur 11.2
• Xcodes: brew cask install

Changes are being published on a background thread

Describe the bug
Xcode is warning about a Publishing changes from background threads is not allowed; make sure to publish values from the main thread (via operators like receive(on:)) on model updates

Related to #66 and #69

To Reproduce

1. Tap Make Active
2. I got prompted for password for installing helper tool
3. Hit cancel
4. Xcode gives warning

Expected behavior
Xcode shouldn't give warnings about background threads

Screenshots

Version

• OS: 11.1
• Xcodes: main branch

When using apple data source remove brackets

Issue:

When using the Apple data source, the build # isn't included, which looks awkward on the views

Possible to remove the brackets if we don't know the build #?

XPC not working immediately after installing the helper

Might need to invalidate the connection after installing, for example.

Add progress to sidebar view as well

When downloading it can tike quite a long time without any visible progress since the indicator is tiny. I would appreciate a bigger indicator (maybe a linear progress bar) being added to the sidebar, maybe even with a time remaining estimate for the step and a display for the current step.

I think the space between the cancel button and the horizontal etched line would be best for the progress bar, the step label could be next to the cancel button.

Alternatively the long progress bar could be the along the lower edge of the blue highlight in the main table.

List available Xcodes

• List available Xcodes
• Indicate which are installed

Add Internet Access Policy

https://www.obdev.at/iap/index.html
https://help.obdev.at/littlesnitch4/ra-developers

Identical builds aren't represented clearly

Hi!
I installed the app and ran it and noticed it was out of date as it didnt include 12.4 as my command line did


I hit the refresh button and it did not show up. Then I went to preferences and signed in, hit refresh, still nothing. Not sure why its missing the 12.4 release (not the RC)

Software update mechanism

xcodes primarily uses homebrew for installation and updates, and while it might be possible to have a cask for Xcodes.app (I haven't looked into this) I think it'd be good to have something built in. We could probably have it check the GitHub repo's releases. I'm guessing someone has built something like this already, so check before we go down the path of rolling our own.

Possible resources:

• Sparkle and GitHub Releases
• https://github.com/mxcl/AppUpdater
• https://github.com/potionfactory/LetsMove/

Install an Xcode

• Support concurrent installs
• Cancel individual installs
• Show progress, both the steps in the installation process and progress within them if appropriate (probably just downloading)