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 team should be frequently releasing new version i.e marketing version to AppStore as well as should be making multiple builds for each version before submitting an app to AppStore. The release might have different builds with different features. It’s very important to manage the builds numbers as well as version numbers of iOS apps in order to make sure we are shipping the right version of the build to AppStore. In this post, we will see how to use agvtool command line utility to manage the version and build number of our iOS apps.

Version and Build Numbers

Before diving into the agvtool, let’s understand what is version and build number of iOS apps.

Version Number

Basically, the version number is marketing number for the app 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)

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

The 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 xcrun utility.

$ xcrun agvtool
$ xcrun -find agvtool

You can read option available with tool from its documentation page

$ man agvtool

This will show all the commands comes with agvtool.

Now we will see how to use agvtool on the real iOS app. In order to so that, let’s create a single view iOS app called agvtool-Demo in the 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 that up inside the Xcode

Enable agvtool

In order to enable agvtool, we need to make sure we have that Current Project Version and Versioning System properties are set correctly in the target build settings. Select the target build settings and search for ‘versioning’. Now setup Current Project Version to 1 and Select the Versioning System value to “Apple Generic”

Next thing to verify is that make sure Info tab has Bundle versions and Bundle versions string, short values are set probably 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 few useful commands that we use frequently. We need to run agvtool command from the root of the project where your .xcodeproj file 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 build number to 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 we want 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 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.

What are Other Options

As of now, we have seen that we can use Apple’s native command line tool to manage 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 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 major or minor version as well as 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 is the number of options to manage the build and version numbers but these actions also use agvtool to all these changes.

Conclusion

The Apple’s native command line tools like agvtool can give you control over version and build numbers of iOS apps. It takes little bit of scripting to manage everything from source code i.e Infrastructure as Code for iOS apps rather than relying on third-party frameworks. I hope you enjoyed this post and feel free to share your experiences of using agvtool.

Like this post from XCBlog By XCTEQ ? You may also like some of our services like guest blogging or Mobile DevOps(CI/CD) or Test Automation. Chekout our services, open source projects on Github or Follow us on Twitter , Facebook, Youtube , LinkedIn. Download Our XCBlog iOS App to read the blogs offline.

XCTEQ Limited: Mobile DevOps, CI/CD and Automation

XCTEQ is a company specialised in Mobile DevOps, CI/CD, Mobile, AI/ML based Test Automation Checkout XCTEQ products and services at http://www.xcteq.co.uk or write to us on info@xcteq.co.uk..