Groom your Xcode environment.

Related tags

Tools xcenv
Overview

Build Status

Groom your Xcode environment with xcenv.

Use xcenv to document and manage the Xcode version for your project and system. When working on multiple projects, it is often needed to support older versions of Xcode. Managing multiple Xcodes can be a problem when executing builds on the command line.

The current solutions require setting the values with xcode-select, using the path to the desired Xcode.app file. Additional solutions include setting DEVELOPER_DIR value to the desired Xcode.app path.

While these solutions work, it requires a team to use the same Xcode.app naming scheme, which can conflict from team to team. One team may desire Xcode.app to be version 6.4 and another may want it to be latest app store build. Alternatively one team may want Xcode7.2.app and another may want Xcode_7_2.app. For this reason xcenv uses the version number to synchronize this required toolset for a project.

This active documentation will help your team make sure they have the right tool to build the project. Additionaly this file can be tracked in the source code changes, and therefore will be tracked. So as your project changes Xcode versions, it can be tracked. Going back to a previous commit will warn you if it may not compile with the current tools installed.

Table Of Contents

How It Works

Shims

Shims are a script that is executed instead of the desired application to inject the desired Xcode version before the command is executed.

The shims supported will work with numerous third party tools. Some tools include Fastlane, Cocoapods, Shenzhen, and current build scripts that use xcodebuild, xcrun, or other Xcode binaries (which also includes git).

Choosing the Xcode Version

When you execute a shim, xcenv determines which Xcode version to use by reading it from the following sources, in this order:

  1. If DEVELOPER_DIR is defined, as environment or shell variable, that value will be respected and not overriden.

  2. If XCENV_VERSION is defined, as environemnt or shell variable, that value will be used to find the matching Xcode app bundle. This can be set using the xcenv shell command

  3. The first .xcode-version file found by searching the current working directory and each of its parent directories until reaching the root of your filesystem. You can modify the .xcode-version file in the current working directory with the xcenv local command.

  4. The global ~/.xcenv/.xcode-version file. You can modify this file using the xcenv global command. If the global version file is not present, xcenv assumes you want to use the "system" Xcode—i.e. whatever is returned by xcode-select -p.

Xcode Version

Xcenv supports multiple value types for the .xcode-version file.

You can set the value to the specific version desired, which will only match the specific version.

7.3.1

You can set the value with a regular expression. This example will match any 7.3 or 7.3.x app bundles.

7.3+

Finding Xcode.app

Xcenv uses Spotlight with the command mdfind "kMDItemCFBundleIdentifier == 'com.apple.dt.Xcode'" to search for any .app bundle with the identifier that matches Xcodes

Plugins

Xcenv supports the ability to add commands via plugins. [More Details To Come.]

Installation

Basic Git Installation

To install xcenv:

$ git clone [email protected]:xcenv/xcenv.git ~/.xcenv

Copy the following into your shell profile file:

export PATH="$HOME/.xcenv/bin:$PATH"
eval "$(xcenv init -)"

Homebrew

To install xcenv

$ brew install xcenv

Follow the instructions after installing, by copying the following to shell profile:

eval "$(xcenv init -)"

Command Reference

xcenv local

Sets a local project-specific Xcode version by writing the version to a .xcode-version file in the current directory. This version can be overriden by the DEVELOPER_DIR environment variable and the XCENV_VERSION variable set by the xcenv shell command.

$ xcenv local 7.3.1

When ran without a version number, xcenv local will output the current version if available.

$ xcenv local
7.3.1

To unset the local version use the --unset parameter.

$ xcenv local --unset

xcenv global

Sets a global Xcode version by writing the version to a .xcode-version file in the XCENV_ROOT folder. This version can be overriden by the DEVELOPER_DIR environment variable, the XCENV_VERSION variable set by the xcenv shell command, and the xcenv local command.

$ xcenv global 7.3.1

When ran without a version number, xcenv global will output the current version if available.

$ xcenv global
7.3.1

To unset the local version use the --unset parameter.

$ xcenv global --unset

xcenv shell

Sets a shell-specific Xcode version, by creating the environment variable XCENV_VERSION. This version can be overriden by the DEVELOPER_DIR.

$ xcenv shell 7.3.1

When ran without a version number, xcenv shell will output the current version if available.

$ xcenv shell
7.3.1

To unset the local version use the --unset parameter.

$ xcenv shell --unset

xcenv version

Displays the current active Xcode version.

$ xcenv version
7.3.1 set by /Users/xcenv/ProjectX/.xcode-version

xcenv rehash

Install shims for all Xcode binaries in the /usr/bin folder. The shim files will temporarily set DEVELOPER_DIR before calling the real /usr/bin/${command}

$ xcenv rehash

Environment Variables

XCENV_ROOT

If you want to change where all the shims and global settings are set for xcenv, you can use the XCENV_ROOT environment variable to do so. By default the value is set to XCENV_ROOT="${HOME}/.xcenv".

If you absolutely need to store everything under Homebrew's prefix, include this in your profile:

export XCENV_ROOT=#{var}/xcenv

XCENV_DO_NOT_SHIM_LIST

Sometimes you don't want xcenv to shim a tool. One example is if you prefer to use the latest git from homebrew.

To exclude a file from being shimmed, set the XCENV_DO_NOT_SHIM_LIST to a list of space delimited filenames in your profile:

export XCENV_DO_NOT_SHIM_LIST="git c++"
Comments
  • [version-name] Try stripping .0 patch version to find a matching Xcode

    [version-name] Try stripping .0 patch version to find a matching Xcode

    The purpose of this PR is to add handling to xcenv-version-name to account for versions specified as X.X.0. Even though Xcode's CFBundleShortVersionString tends to drop the trailing patch number in the version specifier, it's conceivable that someone might want to include the patch version in their command for the sake of consistency (i.e.: 11.6.0, 11.6.1 etc).

    This functionality has been written such that it doesn't assume that Apple will continue the pattern of dropping the patch version in Xcode's CFBundleShortVersionString, however, this means that in all cases of a failed version match, the find_xcode_app_from_version function will be run twice. Instead, if we accept the aforementioned assumption, we can simply check whether the version passed into the command meets the X.X.0 format and simply drop the patch version immediately. Happy to take feedback on this!

    opened by robertbressi 3
  • xcenv: no such command `shell'

    xcenv: no such command `shell'

    Description

    Hi, The command xcenv shell does not seem to work in the version 1.0.4

    [Description of the bug or feature]

    Versions

    OSX El Capitan

    Steps to Reproduce

    brew install xcenv
xcenv shell 7.3.1

    Expected behavior: [What you expected to happen]

    Actual behavior: [What actually happened]

    xcenv: no such command `shell'
    opened by JanC 3
  • Use lastest `git` from brew

    Use lastest `git` from brew

    Apple Git is from Xcode, it is older. I want to use newer version, so I exec brew install git.

    But now the git in the brew will not work. The PATH of xcenv is front of /usr/local/bin:

    $ echo $PATH
/Users/whirlwind/.rvm/gems/ruby-2.4.1/bin:/Users/whirlwind/.rvm/gems/ruby-2.4.1@global/bin:/Users/whirlwind/.rvm/rubies/ruby-2.4.1/bin:/Users/whirlwind/.xcenv/shims:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Users/whirlwind/.rvm/bin
    opened by Whirlwind 2
  • Xcode 9.1 not detected

    Xcode 9.1 not detected

    Description

    xcenv is not detecting XCode 9.1

    Versions

    Xcode 7.3.1 Xcode 8.3.3 Xcode 9.1

    Steps to Reproduce

    I downloaded Xcode 9.1 from the dev portal and installed it in /Applcations. xcenv is detecting other XCode versions except the 9.1:

    xcenv rehash
xcenv versions
8.3.3
7.3.1

xcenv xcodes
/Applications/Xcode.app
/Applications/Xcode7.3.app

ls -al /Applications/
Xcode.app
Xcode7.3.app
Xcode9.1.app

 xcode-select -p
/Applications/Xcode9.1.app/Contents/Developer

 xcenv version
/Applications/Xcode9.1.app/ (set by system)
    opened by JanC 2
  • xcenv not setting the correct Xcode

    xcenv not setting the correct Xcode

    Description

    Hi, I have 3 Xcode version installed (6.4, 7.3.1 and 8.0) as follows

     mdfind "kMDItemCFBundleIdentifier == 'com.apple.dt.Xcode'"
/Applications/Xcode8.app
/Applications/Xcode7.app
/Applications/Xcode6.app

    When I select the version using xcenv shell 8.0 it selects all the time the Xcode7.app. It works correctly when using xcenv local 8.0

    Versions

    OSX El Capitan

    Steps to Reproduce

    xcenv  version
/Applications/Xcode7.app/ (set by system)

xcenv shell 8.0
xcenv version
/Applications/Xcode7.app/ (set by XCENV_VERSION environment variable)

xcenv local 8.0
xcenv version
/Applications/Xcode8.app (set by /Users/admin/jenkins/workspace/sdk/sdk-compile/.xcode-version)

    Any idea what could be wrong with my setup?

    cheers

    opened by JanC 2
  • Homebrew repository is not accessible

    Homebrew repository is not accessible

    The Homebrew repository (https://github.com/xcenv/homebrew-xcenv) is a private one.

    It is not possible to access it using Homebrew, git or in the browser, making the installation instructions broken.

    opened by bojan 2
  • `xcenv` does not affect the result of `xcode-select -p`

    `xcenv` does not affect the result of `xcode-select -p`

    Description

    xcenv does not affect the result of xcode-select -p.

    I'm afraid this may break some tools like fastlane, which use xcode-select -p to get the path of Xcode.

    https://github.com/fastlane/fastlane/blob/05597f5e3f93d3808b3c6b8794052df44192cf4d/fastlane_core/lib/fastlane_core/helper.rb#L110

    Versions

    xcenv 1.1.0 It reproduces at least on Mac OS X, Xcode [6.1|7.3.1|8.1]

    Steps to Reproduce

    1. sudo xcode-select -s /Applications/Xcode6.1.app/Contents/Developer
    2. xcenv local 8.1 or xcenv shell 8.1
    3. xcode-select -p

    Expected behavior: [What you expected to happen]

    Step 3 shows /Applications/Xcode8.1.app/Contents/Developer

    Actual behavior: [What actually happened]

    Step 3 shows /Applications/Xcode6.1.app/Contents/Developer

    xcode-select always ignores xcenv.

    opened by manicmaniac 1
  • [Feature Request] Allow version ranges (e.g. 12.2-12.3+)

    [Feature Request] Allow version ranges (e.g. 12.2-12.3+)

    Description

    Allow repos to require a range of versions. For example our dev team currently prefers 12.2 for the repo, but we are also ok with people using 12.3 locally if they choose. However we are not ok with 12.1 so we cannot use "12+". Would be great to be able to list 12.2-12.3+, or >12.2 <=12.3+

    Versions

    macos 10.15.7, Xcode 12.2-12.3

    opened by tinder-owenthomas 0
  • [Feature Request] Add a shell execution command with `DEVELOPER_DIR` temporarily set to xcenv version

    [Feature Request] Add a shell execution command with `DEVELOPER_DIR` temporarily set to xcenv version

    Description

    [Description of the bug or feature]

    For example, when bootstrapping carthage frameworks, carthage doesn't use xcenv's Xcode version; Instead, it will use DEVELOPER_DIR or xcode-select's Xcode version. This will cause the project failing to build with carthage frameworks.

    Specifically, I have both Xcode 12 and Xcode 11 installed in my computer. the default xcode-select version is 12, but one of my projects is using 11, so I use xcenv local 11.7 to set the project's Xcode version to 11. But unfortunately carthage is still using 12 because that's what xcode-select sets, and DEVELOPER_DIR is empty.

    So if there's some command like xcenv exec which temporarily sets DEVELOPER_DIR it would be very convenient to collaborate with carthage. The command may be used like this:

    xcenv exec carthage bootstrap

    And that command should run:

    DEVELOPER_DIR=</Path_To_Xcode_Set_By_XCENV/Contents/Developer> carthage bootstrap

    Versions

    [e.g. Mac OS X, Xcode 7.3.1]

    macOS 10.15.7（19H2） Xcode 11.7.1 Xcode 12.0.1

    opened by el-hoshino 1
  • Handle multiple Xcodes with the same version number

    Handle multiple Xcodes with the same version number

    It would be great to be able to handle multiple Xcodes with the same version number, i.e. Xcode 9.0 beta 2 and Xcode 9.0 beta 3. I suppose these could be identified by their build version, i.e. 9M174d.

    opened by chrisellsworth 1
Releases(v1.2.0)
Owner
xcenv
xcenv
GitHub http://xcenv.org
Xcode storyboards diff and merge tool.

StoryboardMerge Storyboard diff and merge tool which: compares and merges two storyboard files, provides an automatic merge-facility, The storyboardin

null 238 Sep 12, 2022
Xcode .appiconset generator for Adobe Illustrator.

Creating AppIcon sets from Adobe Illustrator This repo is rewrited from original repo https://github.com/CaryChamplin/CreatingIconsFromAI. Just genera

gitmerge 73 Nov 9, 2020
Script to support easily using Xcode Asset Catalog in Swift.

Misen Misen is a script to support using Xcode Asset Catalog in Swift. Features Misen scans sub-directories in the specified Asset Catalog and creates

Kazunobu Tasaka 123 Jun 29, 2022
A git plugin for real-world xcode versioning workflow.

git-xcp The most simplest, safe, and fully automatic git plugin for versioning workflow of real-world xcode projects. Current working or draft content

gitmerge 11 Dec 29, 2019
An Xcode Plugin to convert Objective-C to Swift

XCSwiftr Convert Objective-C code into Swift from within Xcode. This plugin uses the Java applet of objc2swift to do the conversion. Noticed that the

Ignacio Romero Zurbuchen 338 Nov 29, 2022
Xcode-compatible build tool.

xcbuild xcbuild is an Xcode-compatible build tool with the goal of providing faster builds, better documentation of the build process and running on m

Meta Archive 2k Dec 11, 2022
An executable that can be called from a Run Script Build Phase that makes comments such as // TODO: or // SERIOUS: appear in Xcode's Issue Navigator giving them project-wide visibility.

XcodeIssueGenerator An executable that can be called from a Run Script Build Phase that makes comments such as // TODO: or // SERIOUS: appear in Xcode

Wunderman Thompson Apps 143 Oct 11, 2022
This repository contains rules for Bazel that can be used to generate Xcode projects

rules_xcodeproj This repository contains rules for Bazel that can be used to generate Xcode projects. If you run into any problems with these rules, p

BuildBuddy 233 Dec 28, 2022
Shows your current framerate (fps) in the status bar of your iOS app

WatchdogInspector Shows your current framerate (fps) in the status bar of your iOS app Be a good citizen! Don't block your main thread! WatchdogInspec

Christian Menschel 510 Nov 24, 2022
SwiftGen is a tool to automatically generate Swift code for resources of your projects

SwiftGen SwiftGen is a tool to automatically generate Swift code for resources of your projects (like images, localised strings, etc), to make them ty

null 8.3k Jan 5, 2023
AVXCAssets Generator takes path for your assets images and creates appiconset and imageset for you in just one click

AVXCAssets Generator Often while developing an app, We ran into a condition when we need to scale images to each and every aspect ratios for icons and

Angel Vasa 339 Dec 6, 2022
All new design. Inspect your iOS application at runtime.

Peek: All new design Peek 5 with an all new design and all new features. Whether you're a developer, designer or QA/tester, Peek can help you at all s

Shaps 2.6k Dec 17, 2022
UIEnvironment - A framework that mimics the SwiftUI view's environment to replicate the value distribution thought your UIKit app.

A framework that mimics the SwiftUI view's environment to replicate the value distribution thought your UIKit view hierarchy. Overview D

Łukasz Śliwiński 15 Dec 5, 2022
A library to derive and compose Environment's in The Composable Architecture.

ComposableEnvironment This library brings an API similar to SwiftUI's Environment to derive and compose Environment's in The Composable Architecture.

Thomas Grapperon 129 Dec 14, 2022
A library that allows you to generate and update environment maps in real-time using the camera feed and ARKit's tracking capabilities.

ARKitEnvironmentMapper Example To run the example project, clone the repo, and run pod install from the Example directory first. Installation ARKitEnv

SV Hawks 91 Dec 4, 2022
A library that allows you to generate and update environment maps in real-time using the camera feed and ARKit's tracking capabilities.

ARKitEnvironmentMapper Example To run the example project, clone the repo, and run pod install from the Example directory first. Installation ARKitEnv

SV Hawks 91 Dec 4, 2022
A key value store for storing per-developer environment and application keys

A key value store for enviroment and application keys. Its good security practice to keep production keys out of developer hands. CocoaPods-keys makes

Orta Therox 1.5k Dec 20, 2022
Learning Swift using Docker containers as development environment

100-days-of-swift Small setup to help me learn Swift. I don't own a mac so this is what I came up with ?? .

Diogo Cavaleiro 1 Feb 14, 2022
AREarthObservatory - A minimal iOS AR app that visualizes time-series changes in the global environment based on data from NASA satellites

A minimal iOS AR app that visualizes time-series changes in the global environment based on data from NASA satellites

Yasuhito Nagatomo 3 Aug 11, 2022
Swift programming language hackathon. Implementation of the main logic of working with an ATM in the Playground environment.

Hackaton-ATM-PJ04 Swift programming language hackathon. Implementation of the main logic of working with an ATM in the Playground environment. The tas

Raman Kozar 2 Oct 4, 2022