agvtool: Automating iOS Build and Version Numbers

devops and continuous delivery practices enable continuous builds deployed to our internal or beta testing platform. it's essential to manage the version and build numbers of ios apps. as a best devops practice, ios teams should be frequently releasing a new version, i.e. marketing version, to the app store, as well as making multiple builds for each version before submitting an app to the app store. the release might have different builds with different features. it's very important to manage the build numbers as well as version numbers of ios apps in order to make sure we are shipping the right version of the build to the app store. in this post, we will see how to use the agvtool command line utility to manage the version and build number of our ios apps.

version and build numbers

before diving into agvtool, let's understand the version and build number of ios apps.

version number

basically, the version number is the marketing number for the app, which is the number shown to your application’s users. it identifies a released version of your application. it is stored in your application’s info.plist as cfbundleshortversionstring (bundle versions string, short) .

build number

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) . we can make multiple builds for a specific version.

agvtool

agvtool is a command-line tool comes that allows you to automatically increment these numbers to the next highest number or to a specific number. this tool comes with xcode command line tools and can be directly accessed from the xcrun utility.

$ xcrun agvtool
$ xcrun -find agvtool

you can read about the options available with the tool from its documentation page.

$ man agvtool

this will show all the commands that come with agvtool.

now we will see how to use agvtool on a real ios app. in order to do that, let's create a single-view ios app called "agvtool-demo" in xcode. there are a couple of things we need to ensure before we start using agvtool from the command line:

• enable the agvtool and versioning system

• disable/enable source control setup

we will see how to set it up in xcode.

enable agvtool

in order to enable agvtool, we need to make sure we have current project version and versioning system properties set correctly in the target build settings. select the target build settings and search for "versioning." now set current project version to 1 and select the versioning system value to "apple generic."

next thing to verify is that make sure the info tab has bundle versions and bundle versions string, short values are probably set to 1 for the new project.

disable/enable source control (cvs, svn)

the agvtool will make changes in some files inside the xcode project when it changes the version or build number. we can commit those changes to source control if we use cvs or svn. no need to worry about these settings if you are not using svn or cvs. by default committing the changes to cvs or svn are on, however, we can disable that setting by running following commands:

$ defaults write agvtool svnenabled no
$ defaults write agvtool cvsenabled no

command line agvtool

now, we have done all the setup to use agvtool from the command line. we will see a few useful commands that we use frequently. we need to run the agvtool command from the root of the project where your .xcodeproj file is located.

view existing values

• version number

we can view current version number using the following command:

$ xcrun agvtool what-marketing-version

• build number

we can view current build number using the following command:

$ xcrun agvtool what-version

update to next values

• next version number

it's not ideal to automatically upgrading to next version so we have to specify the value of the next version that we will be updating to in the command. we can update the value to next version number using the following command:

$ xcrun agvtool new-marketing-version 2.0

• next build number

we can increment the build number to the next build number using the following command:

$ xcrun agvtool next-version -all

we can also specify the specific value of the build number using the command, e.g. if we want to set the build number to 3.2, then we can do that with the following command:

$ xcrun agvtool new-version -all 3.2

note that when we update the version or build number values, it changes the in the info.plist file or .xcodeproj file. we need to have some source control mechanism to commit the changes back into the source control.

other options

as of now, we have seen that we can use apple's native command line tool to manage the version and build numbers, however, there are some other third-party tools like fastlane which can also do the same thing. fastlane has actions to increment both the build and version number. the increment_version_number action can be used to increment version number, which has various options as well. we can bump to a major or minor version, and we can specify the version number.

increment_version_number(
  bump_type: "major" 
)

the increment_build_number action can be used to update the build number values.

increment_build_number(
  build_number: "5" 
)

there are a number of options to manage the build and version numbers but these actions also use agvtool to all these changes.

conclusion

apple's native command line tools, like agvtool, can give you control over the version and build numbers of ios apps. it takes a little bit of scripting to manage everything from the source code, i.e infrastructure as code, for ios apps rather than relying on third-party frameworks. i hope you enjoyed this post; feel free to share your experiences with using agvtool.