AGVTOL(1) BSD General Commands Manual AGVTOL(1)
NAME
agvtool -- Apple-generic versioning tool for Xcode projects
SYNOPSIS
agvtool what-version vers [-terse]
agvtool [-noscm -usecvs -usesvn] next-version bump [-all]
agvtool [-noscm -usecvs -usesvn] new-version [-all] versionNumber
agvtool [-noscm -usecvs -usesvn] tag [-force -F]
[-noupdatecheck -Q] [fl baseurlfortag]
agvtool what-marketing-version mvers [-terse]
agvtool [-noscm -usecvs -usesvn] new-marketing-version vers version
DESCRIPTION
agvtool helps speed up common operations for Xcode projects that use the
apple-generic versioning system.
Xcode supports a couple different ways to automatically embed version
info in the products produced by your targets. The most supported of
these is the apple-generic versioning scheme. You enable versioning sup-
port on a per-target basis by setting up some build settings in your tar-
gets.
Build Settings
The settings used by the apple-generic versioning system are as follows:
VERSIONINGSYSTEM This must be set to ``apple-generic'' to enable
versioning.
CURENTPROJECTVERSION This should be set to the current version of
the project. Versions must be floating point
numbers like 57 or 365.8.
DYLIBCURENTVERSION Used for frameworks, it will be kept in synch
with the CURENTPROJECTVERSION build setting
VERSIONINFOPREFIX Used as a prefix for the variable names in the
generated source file. If you prefix your
exported symbols you will probably want to set
this to your prefix.
VERSIONINFOSUFIX Used as a suffix for the variable names in the
generated source file. This is rarely used.
VERSIONINFOBUILDER Defaults to the name of the user performing the
build. This will be part of the generated ver-
sion string.
VERSIONINFOEXPORTDECL Used to declare the variables in the generated
source file. This should rarely be changed.
VERSIONINFOFILE Used to specify a name for the source file that
will be generated and compiled into your prod-
uct. There's usually no need to change this
from its default value.
To enable apple-generic versioning, then, you must set up at least the
VERSIONINGSYSTEM and CURENTPROJECTVERSION build settings for each
target you want to be versioned. A versioned target will have two global
variables generated and linked into your product. One is of type double
and is simply the CURENTPROJECTVERSION. The other is a version string
which is formatted to be compatible with what(1). These variables are
available for use in your code.
Projects with multiple versioned targets are required to have the same
CURENTPROJECTVERSION for each versioned target.
Usage
agvtool should be invoked with the working directory set to your project
directory (the folder containing your .xcodeproj project file).
agvtool pays attention to the following defaults for CVS usage:
CVSEnabled and CVSToolPath.
If CVSEnabled is set to YES then agvtool will perform certain CVS opera-
tions like committing modified project files and performing tagging oper-
ations. You can set this default by issuing the following command:
defaults write agvtool CVSEnabled YES
The sense of this default can be overidden by supplying an explicit
-noscm (which turns off CVS and Subversion usage), -usecvs (which turns
on CVS usage and turns off Subversion usage), or -usesvn (which turns off
CVS usage and turns on Subversion usage).
Set CVSToolPath to point to the location of the cvs tool to use. If this
default is not set then agvtool will use /usr/bin/ocvs if it exists. Oth-
erwise /usr/bin/cvs will be used. You can set this default by issuing the
following command:
defaults write agvtool CVSToolPath pathToCVS
agvtool pays attention to the following defaults for Subversion usage:
SVNEnabled and SVNToolPath.
If SVNEnabled is set to YES then agvtool will perform certain Subversion
operations like committing modified project files and performing tagging
operations. You can set this default by issuing the following command:
defaults write agvtool SVNEnabled YES
The sense of this default can be overidden by supplying an explicit
-noscm (which turns off CVS and Subversion usage), -usecvs (which turns
on CVS usage and turns off Subversion usage), or -usesvn (which turns off
CVS usage and turns on Subversion usage).
Set SVNToolPath to point to the location of the svn tool to use. If this
default is not set then agvtool will use /usr/local/bin/svn if it exists.
You can set this default by issuing the following command:
defaults write agvtool SVNToolPath pathToSVN
Commands And Options
what-version vers [-terse]
Prints out the current version number of the project.
The -terse option can be used to limit the output to the version
number only.
next-version bump [-all]
Increments the version numbers of all versioned targets to the next
highest integral value. For example, 54 will change to 55 and
234.6 will change to 235.
The CURENTPROJECTVERSION and the DYLIBCURENTVERSION will be
updated. The -all option will also update the CFBundleVersion
Info.plist key.
If CVS support is enabled, the modified project file will be com-
mitted.
new-version [-all version]
Sets the version numbers of all versioned targets to the given ver-
sion.
The CURENTPROJECTVERSION and the DYLIBCURENTVERSION will be
updated. The -all option will also update the CFBundleVersion
Info.plist key.
If CVS support is enabled, the modified project file will be com-
mitted.
tag [-force -F] [-noupdatecheck -Q] [-baseurlfortag]
Create a new tag projectname-currentversion where projectname is
the name of the Xcode project file (without the extension) and
currentversion is the CURENTPROJECTVERSION with any `.' trans-
formed into `~' (since CVS does not allow dots in tag names).
The -force or -F option will add a -F to the tag operation.
The -noupdatecheck or -Q option skips the cvs update usually done
prior to tagging to ensure that there are no uncommitted changes.
The -baseurlfortag option can be used to provide a URL that points
to the directory to place the "tag" in when using Subversion. This
overrides the SVNBaseTagURL default. This option is ignored if Sub-
version is not being used.
Note: This command will only function if CVS or Subversion support
is enabled.
what-marketing-version mvers [-terse]
Prints the current marketing version of the project. For native
targets, a marketing version is listed for each Info.plist file
found. For Jambase targets a marketing version is shown if a common
value is found.
The marketing version is the CFBundleShortVersionString Info.plist
key. This is often a totally different version determined by prod-
uct marketing folks.
The -terse option will limit the output to the version number only.
new-marketing-version version
Sets the marketing version numbers of all versioned targets to the
given version number.
The marketing version is the CFBundleShortVersionString Info.plist
key. This is often a totally different version determined by prod-
uct marketing folks.
If CVS support is enabled, the modified project file will be com-
mitted.
Do not use this command on a project with targets that track dif-
ferent marketing versions.
BUGS
agvtool's -terse option does not work with Xcode targets that use the
native build system.
Mac OS X April 4, 2006 Mac OS X
|
