Technical Q&A QA1827

Automating Version and Build Numbers Using agvtool

Q: How do I auto-increment my build and version numbers using `agvtool`?

A: The version and build number keys respectively specify the marketing and internal versions of your application. agvtool is a command-line tool that allows you to automatically increment these numbers to the next highest number or to a specific number. This document provides step-by-step instructions for updating your build and version numbers using agvtool. The "Xcode" and "Command Line" sections indicate the steps to be respectively performed in Xcode and the command line.

The build number identifies an unreleased or released version of your application. It is stored in your application’s Info.plist as CFBundleVersion (Bundle version). See the Information Property List Key Reference for more information about these keys.

See Figure 1 for an example showing the version number and the build number of the App Store app, which are respectively 1.3 and 201.4.

**Figure 1** App Store application's version and build numbers

Xcode

You must complete the following steps in your Xcode project.

1) Enable agvtool.

Navigate to the Build Settings pane of your target, then update it for all your build configurations as follows:

Set Current Project Version to a value of your choosing.
Your Xcode project data file, project.pbxproj, includes a CURRENT_PROJECT_VERSION (Current Project Version) build setting, which specifies the current version of your project. agvtool searches project.pbxproj for CURRENT_PROJECT_VERSION. It continues running if CURRENT_PROJECT_VERSION exists and stops running, otherwise. Its value is used to update the build number.
Note: The value of Current Project Version must be an integer or a floating point number such as 34.6. You should set this setting to 1 if you are working on a new project.
Set Versioning System to Apple Generic.
By default, Xcode does not use any versioning system. Setting Versioning System to Apple Generic ensures that Xcode will include all agvtool-generated version information in your project.

**Figure 2** Setting up the Current Project Version and Versioning System build settings

2) Set up your version and build numbers.

agvtool searches your application’s Info.plist for your version and build numbers. It updates them if they exist and does nothing, otherwise. Make sure that the CFBundleVersion (Bundle version) and CFBundleShortVersionString (Bundle versions string, short) keys exist in your Info.plist as seen in Figure 3.

**Figure 3** Version and build numbers in the Info pane

Command Line

Quit Xcode, then navigate to the directory containing your .xcodeproj project file in the Terminal application before running any of the following commands. The .xcodeproj project file contains project.pbxproj, which is used by agvtool.

Updating the Version Number

To update the version number to a specific version, run

agvtool new-marketing-version <your_specific_version>

where <your_specific_version> is a number of your choosing as seen in Listing 1.

Listing 1 Update the version number to 2.0

$ xcrun agvtool new-marketing-version 2.0

Setting CFBundleShortVersionString of project MyProject to:

    2.0.

Updating CFBundleShortVersionString in Info.plist(s)...

Updated CFBundleShortVersionString in "MyProject.xcodeproj/../MyProject/MyProject-Info.plist" to 2.0

Updating the Build Number

To automatically increment your build number, run

agvtool next-version -all

Listing 2 Auto-increment the build number to the next highest integer

$ xcrun agvtool next-version -all

Setting version of project MyProject to:

2.

Also setting CFBundleVersion key (assuming it exists)

Updating CFBundleVersion in Info.plist(s)...

Updated CFBundleVersion in "MyProject.xcodeproj/../MyProject/MyProject-Info.plist" to 2

To set the build number of your application to a specific version, run

agvtool new-version -all <your_specific_version>

where <your_specific_version> is a number of your choosing.

Listing 3 Set the build number to 2.6.9

$ xcrun agvtool new-version -all 2.6.9

Setting version of project MyProject to:

    2.6.9

Also setting CFBundleVersion key (assuming it exists)

Updating CFBundleVersion in Info.plist(s)...

Updated CFBundleVersion in "MyProject.xcodeproj/../MyProject/MyProject-Info.plist" to 2.6.9

Viewing Version Numbers

To view the current version number, run

agvtool what-marketing-version

Listing 4 Display the current version number

$ xcrun agvtool what-marketing-version

No marketing version number (CFBundleShortVersionString) found for Jambase targets.

Looking for marketing version in native targets...

Looking for marketing version (CFBundleShortVersionString) in native targets...

Found CFBundleShortVersionString of "2.0" in "MyProject.xcodeproj/../MyProject/MyProject-Info.plist"

To view the current build number, run

agvtool what-version

Listing 5 Display the current build number

$ xcrun agvtool what-version

Current version of project MyProject is:

2.2

Document Revision History

Date	Notes
2014-05-12	New document that describes how to auto-increment build and version numbers using agvtool.