Manual Pages for UNIX Darwin command on man agvtool

AGVTOOL(1) BSD General Commands Manual AGVTOOL(1)

NAME

aaggvvttooooll - Apple-generic versioning tool for Xcode projects

SYNOPSIS

aaggvvttooooll what-version | vers [-tteerrssee]

aaggvvttooooll [-nnoossccmm | -uusseeccvvss | -uusseessvvnn] next-version | bump [-aallll]

aaggvvttooooll [-nnoossccmm | -uusseeccvvss | -uusseessvvnn] new-version [-aallll] versionNumber

aaggvvttooooll [-nnoossccmm | -uusseeccvvss | -uusseessvvnn] tag [-ffoorrccee | -FF]

[-nnoouuppddaatteecchheecckk | -QQ] [-bbaasseeuurrllffoorrttaagg]

aaggvvttooooll what-marketing-version | mvers [-tteerrssee | -tteerrssee11]

aaggvvttooooll [-nnoossccmm | -uusseeccvvss | -uusseessvvnn] new-marketing-version version

DESCRIPTION

aaggvvttooooll helps speed up common operations for Xcode projects that use the Apple Generic Versioning system. You enable versioning support by setting up some build settings in your project. BBuuiilldd SSeettttiinnggss

The settings used by the apple-generic versioning system are as follows:

VERSIONINGSYSTEM This must be set to ``apple-generic'' at the

project level to enable versioning. CURRENTPROJECTVERSION This setting defines the the current version of the project. The value must be a integer or floating point number like 57 or 365.8. DYLIBCURRENTVERSION This setting defines the the current version of any framework built by the project. Like CURRENTPROJECTVERSION the value must be an integer or floating point number like 57 or 365.8. By default it is set to

``$(CURRENTPROJECTVERSION)''.

VERSIONINFOPREFIX Used as a prefix for the name of the version info symbol in the generated versioning source file. If you prefix your exported symbols you

will probably want to set this to the same pre-

fix. VERSIONINFOSUFFIX Used as a suffix for the name of the version info symbol in the generated versioning source file. This is rarely used. VERSIONINFOBUILDER This defines a reference to the user performing a build to be included in the generated stub,

and defaults to the value of the USER environ-

ment variable. VERSIONINFOEXPORTDECL This defines a prefix string for the version info symbol declaration in the generated stub. This can be used, for example, to add an optional `export' keyword to the version symbol declaration. 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. By default this is set to

``$(PRODUCTNAME)vers.c''.

To enable Apple Generic Versioning, then, you must set up at least the VERSIONINGSYSTEM and CURRENTPROJECTVERSION project build settings for each project you want to be versioned. The target of a versioned project will have two global variables generated and linked into your product. One is of type double and is simply the CURRENTPROJECTVERSION. 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 targets are required to have the same CURRENTPROJECTVERSION for each target. The easiest way to achieve this is to set CURRENTPROJECTVERSION at the project level. UUssaaggee aaggvvttooooll should be invoked with the working directory set to your project directory (the folder containing your .xcodeproj project file). aaggvvttooooll pays attention to the following defaults for CVS usage: CVSEnabled and CVSToolPath.

If CVSEnabled is set to YES then aaggvvttooooll 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

-nnoossccmm (which turns off CVS and Subversion usage), -uusseeccvvss (which turns

on CVS usage and turns off Subversion usage), or -uusseessvvnn (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 aaggvvttooooll 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

aaggvvttooooll pays attention to the following defaults for Subversion usage: SVNEnabled and SVNToolPath. If SVNEnabled is set to YES then aaggvvttooooll 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

-nnoossccmm (which turns off CVS and Subversion usage), -uusseeccvvss (which turns

on CVS usage and turns off Subversion usage), or -uusseessvvnn (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 aaggvvttooooll 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 [-tteerrssee]

Prints out the current version number of the project.

The -tteerrssee option can be used to limit the output to the version

number only.

next-version | bump [-aallll]

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 CURRENTPROJECTVERSION and the DYLIBCURRENTVERSION will be

updated. The -aallll option will also update the CFBundleVersion

Info.plist key.

If CVS support is enabled, the modified project file will be com-

mitted.

new-version [-aallll version]

Sets the version numbers of all versioned targets to the given ver-

sion. The CURRENTPROJECTVERSION and the DYLIBCURRENTVERSION will be

updated. The -aallll option will also update the CFBundleVersion

Info.plist key.

If CVS support is enabled, the modified project file will be com-

mitted.

tag [-ffoorrccee | -FF] [-nnoouuppddaatteecchheecckk | -QQ] [-bbaasseeuurrllffoorrttaagg]

Create a new tag projectname-currentversion where projectname is

the name of the Xcode project file (without the extension) and

currentversion is the CURRENTPROJECTVERSION with any `.' trans-

formed into `~' (since CVS does not allow dots in tag names).

The -ffoorrccee or -FF option will add a -FF to the tag operation.

The -nnoouuppddaatteecchheecckk or -QQ option skips the cvs update usually done

prior to tagging to ensure that there are no uncommitted changes.

The -bbaasseeuurrllffoorrttaagg 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 [-tteerrssee]

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 -tteerrssee option will limit the output to the version number only.

The -tteerrssee11 option will limit the output to the first version num-

ber found, and only display the version number.

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. Mac OS X April 4, 2006 Mac OS X