Build Type BuildDirectoryPath => Build Agent Working Directory
In Team Build version 1, all information about how to perform the build was stored in the Build Type, which was basically a folder that contained the TfsBuild.proj file, the WorkspaceMapping.xml file, and the TfsBuild.rsp file. In the Orcas release, we have divided the information up so that some of it now resides in the Team Build database. One of the pieces of information that moved to the database is the build location (now called the working directory).
A Change in Location and Usability
In version 1, the user could override the build location when starting a build. In Orcas, the user can't do that. The build location (working directory) is part of the information associated with the Build Agent and can only be changed on the Build Agent Properties dialog. Why, you may ask? As we move towards a model where the user doesn't pick the actual machine that the build runs on (not there yet in Orcas), it is important to keep the details of how the build will actually be performed, tucked away in a safe place. For example, what if the user expected the build agent to have a d: drive and used that as the build location. The build would succeed on some machines but would fail on any that didn't have a d: drive. Assuming that the build machines are maintained by a central IT group (or perhaps the one IT guy), it is much easier for that group to also maintain the build agent information like the working directory. By centrally locating this information and keeping it out of the hands of the average user, we hope to avoid needless build breaks.
Fixing the Problems
One of the problems that some users encountered in version 1 was that the directory structure under the build location root was too long. There is a limit of 260 characters in any path. The real problem is that the user couldn't change anything but the root of the directory structure. Setting the build location to "d:\BL" still produced a path like "d:\BL\TeamProject\TypeName\Sources" as the root of the workspace. In some cases, this was just too long when appended with the longest workspace path. To help fix this problem in Orcas, we now allow the user to specify most of the working directory path. And you can use environment variables as well! The default working directory is "$(Temp)\$(BuildDefinitionPath)" which ends up being something like "C:\DOCUME~1\jpricket\LOCALS~1\Temp\TeamProject\daily\". On to the end of this root we still add "Sources". If that's too long, you can change it to a hard coded path. But we recommend that you make the path unique for each Build Definition. To do that in the shortest space possible, we have provided $(BuildDefinitionId) which you can use in place of $(BuildDefinitionPath). Both of these values are unique for each build definition in the database. For example, a working directory of "d:\BL\$(BuildDefinitionId)" would produce a root folder something like "d:\BL\1245\Sources". By giving you control of this path, we hope to solve the problems associated with long paths in source control.
The Structure Under the Root
In V1 the structure under the build location was something like this:
c:\BuildLocation\TeamProject\TypeName\Binaries - The Output Directory for MSBuild is overridden so that all the outputs of the build process are put under this folder.
c:\BuildLocation\TeamProject\TypeName\BuildType - The build type information is downloaded here.
c:\BuildLocation\TeamProject\TypeName\Sources - The root of the workspace is mapped to this folder.
c:\BuildLocation\TeamProject\TypeName\TestResults - The results of the test runs are placed in this folder.
In Orcas, we have maintained this same structure by default, but you can change it! In TfsBuildService.exe.config file, there are keys for each one of the above subfolders that can be overriden. The only real reason to do this is to shorten the names of these folders to avoid the 260 character limit on paths. Keep in mind, that this entire structure only serves as a working area for MSBuild. When the compilation and tests are done, all of the important files like the Binaries, Test Results, and build log are copied to the Drop Location share. Then this space can be reused by the next build.