Build Configurations

Article
10/12/2006

Build configurations provide a way to select the components you will build, exclude those you will not build, and determine how the projects selected will be built and on what platform. Two levels of build configurations can be defined in Visual Studio, solution build configurations and project configurations.

Solution Build Configurations

A solution build configuration specifies how certain projects in a solution are to be built and (if enabled) deployed. To define a new solution build configuration, open the Configuration Manager dialog box and select New from the Active Solution Configuration menu.

Each entry in a solution build configuration includes a Project name, drop-down lists of kinds of project builds (Configurations) and Platforms available, and Build and (if enabled) Deploy check boxes for selecting those projects that will be built. The combination of kind of build and platform chosen determines the project configuration that will be used.

You can create any number of solution build configurations, each with a unique name. The Visual Studio integrated development environment (IDE) automatically assigns solution build configurations whenever you:

Add a project platform with Also create new solution configuration(s) selected.
Add a project configuration with Also create new solution configuration(s) selected.
Add a new project that will be deployed on multiple platforms, one of which is new.

To determine how to create or rename solution build configurations when new project configurations and platforms are added, the IDE maintains a naming convention for solution build configurations. This naming convention takes the form <project configuration name> <platform name>. The solution build configuration name omits the platform name when all projects are built for a single platform.

Solution build configurations also provide general project context information to the IDE. For example, if the active solution build configuration specifies that a project will be built for a mobile device, the Toolbox will display only project items that can be used in a mobile device project while you are working on that project.

Project Configurations

The Project Property Pages dialog box displays the Common and Configuration properties of the selected project. The dropdown lists at the top of this dialog box indicate the available kinds of project builds (for example, Debug or Release) and available platforms (for example, .NET or Win32). For each combination of kind of build and platform, there is a project configuration, that is, a set of defined project properties. Most Visual Studio .NET programming language projects start with Debug and Release project configurations. All Visual Studio projects have at least one default project configuration.

Each project configuration appends to the Common properties of the project various Configuration properties specific to one kind of build for one platform (for example, Debug .NET or Release Win32). You can define the configuration-dependent properties in each project configuration as needed. Project properties can be used to determine, for example, which project items will be included in a particular build, what output files will be created, where the output files will be put, and how they will be optimized.

When you build a solution, Visual Studio applies the active solution build configuration, which specifies the project configurations to use for each project to be built. Project configurations can differ considerably. The properties of one project configuration might, for example, specify that its output file be optimized so that the resulting binary occupies the minimum space, while another project might be optimized such that its executable runs at the maximum speed. A third project might not have any optimizations at all.

Project configurations are not stored by user, but by solution, so that they can be shared by a team. Although project dependencies are configuration-independent, only those projects specified in the active solution build configuration will be built.

Changing Solution Build Configurations

The active solution build configuration is shown in a drop-down menu on the standard toolbar of the IDE. To create, rename, or delete solution build configurations, use the Configuration Manager dialog box. You can change the active configuration directly from Solution Configurations drop-down list in the Standard toolbar, or from the Configuration Manager. Updated solution build configurations are displayed in the Solution Property Pages dialog box. You can change which projects are to be built or (if enabled) deployed by a solution build configuration from either user interface. For example, if you clear the Build check box for a project in the Solution Property Pages dialog box, and then open the Configuration Manager dialog box to edit the same solution build configuration, the Build check box for that project will be cleared there as well.

How the IDE Assigns Project Configurations to be Built

When you create a new solution build configuration (rather than copy one that already exists), the IDE determines the default project configurations for the projects it will build using the following selection criteria for each project (evaluated in this order):

The new solution build configuration will build a project configuration whose name exactly matches its own. Configuration names are not case sensitive.
If there is no exact name match, the new solution build configuration will build a project configuration whose name matches the configuration portion of its name, whether or not the platform portion also matches. (Remember that the naming convention is <configuration name> <platform-name>.)
If there is still no match, the new solution configuration will build the first configuration listed for a project.

How the IDE Assigns Solution Build Configurations

When you create a project configuration and select Also create new project configuration(s), the IDE looks for an appropriately named solution build configuration to build the project on each platform it supports. In some cases, the IDE will rename existing solution build configurations or creates new ones.

The IDE determines how to assign solution build configurations using the following selection criteria:

If a project configuration does not specify a platform or specifies a single platform, then a solution build configuration whose name matches that of the new project configuration will either be found or added. In this case, the name of this default solution build configuration does not include a platform name; it takes the form <project configuration name>.
If a project supports multiple platforms, a solution build configuration is found or added for each project configuration to build each project on each platform it supports. The name of each solution build configuration includes both the project configuration name and the platform name; it takes the form <project configuration name> <platform name>.

For example, consider two projects, P1 and P2. P1 only supports the .NET Platform. P2 can be built on two platforms, .NET and PPC. Next, add a new solution build configuration named Sample and select Also create new project configuration(s) in the New Solution Configuration dialog box.

In P1, a single project configuration named Sample is created. In P2, the IDE creates two new project configurations named Sample .NET and Sample PPC. It also renames the first solution build configuration Sample .NET, and creates a second solution build configuration named Sample PPC. The Sample .NET solution build configuration will now build both projects on the .NET Platform, P1 using its Sample project configuration, and P2 using its Sample.NET project configuration. The added Sample PPC solution build configuration will build P2 on the PPC platform using its Sample.PPC project configuration, but will continue to build P1 on the .NET Platform using its Sample project configuration (since that is the only project configuration available for P1).

Then, if you wish, you can edit the Sample PPC solution build configuration in the Configuration Manager dialog box, for example to clear the Build check box for P1.