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.

Note: The version number, which is the number shown to your application’s users, identifies a released version of your application. It is stored in your application’s Info.plist as CFBundleShortVersionString ( Bundle versions string, short ) .

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

Important: When your app includes multiple targets, agvtool will set the version numbers of all your targets to the same number.

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 Note: The DYLIB_CURRENT_VERSION ( Current Library Version ) build setting specifies the current build version of a library or framework. if you are building a library or framework, be sure to follow the above steps and make sure that the Build Settings pane of your target includes this setting. Back to Top

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 Note: Running agvtool next-version -all increments your version number to the next highest integer value. For instance, it will update 2 to 3 and 1.3 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 Back to Top

Document Revision History

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