Create User-Defined Environment Variables (Macros) in Visual Studio

Motivation / Introduction

(You can skip this section if you already know its usage.)

User-define environment variables or user-defined macros are important in Visual C++ when we want to share certain properties across projects in a solution or even across solutions.  For example, a library set, such as ITK, may consist of multiple libraries.  If many projects in a solution need to use them, we may need to repetitively specify include paths and libraries to these projects.  This is error prone and time consuming.  Moreover, if we want to upgrade the library or just change the library folder, without using a user-defined environment variable, we will need to repeat the whole things.  If we create a macro, such as ITK_INC, that specifies include paths to ITK library headers, we then can just refer to $(ITK_INC) in the include directory.  Any change to the variable will be adopted by referring projects automatically.  Consequently, the projects will be more organized and ready for changes.

How to

So, how to create such a macro?  First of all, we need a new property sheet, which can be created as described in MSDN and is illustrated by Figure 1.  To make the solution even more organized, I suggest create a new project to specifically host this new property sheet.  Why?  Because when we have many projects and need to locate this property sheet, we will have a hard time locating the property sheet if we create it in any random project.  Thus, creating a solution project called 'SolutionSettings' is recommended.

Figure 1 Call up Property Manager to create a new property sheet.  Associate the property sheet with a specialized project in a solution is highly recommended.

Next, we are ready to create a user-defined macro.

  1. Go to the 'Property Manager' tab if it's not highlighted yet (Figure 2).

Figure 2 Propery Manager tab

  1. Double click on the newly created property sheet.

  1. Go to the 'User Macros' node and press the 'Add Macro' button (Figure 3).  Insert name to the value field as you'd like and 'set this macro as an environment variable in the build environment' (Figure 4).

Figure 3 'User Macros' node and 'Add Macro' button

Figure 4 Assign additional property to the user-defined macro

  1. As for the next step, we have to use the macro.  So, go back to the solution explorer tab and call up a property page of a project that is going to use the macro.

  1. The way we inherit the properties from another project is different between VS 2008 and 2010, as shown below.  It is worth noting that we can inherit property sheets across solutons, not only across projects.

VS 2008

Go to 'General' node and edit 'Inherited Project Property Sheets' by providing the path to the property sheet (Figure 5).  The property sheet usually has extension .vsprops, for example SolutionProperties.vsprops.  In my case, the path is ..\SolutionSettings\SolutionProperties.vsprops.  Once the change is applied, the project can refer to the macro instantly by using the form $(macro_name), mind the dollar sign and the parentheses--they are needed.

VS 2010

VS 2010 is more visual in this task.  It is well described in MSDN and depicted in Figure 6.  Basically, you right click on a project in a Property Manager and select  'Add Existing Property Sheet’ to browse for a target property sheet.

Figure 5 How to inherit a property page from another project.

Figure 6 VS 2010 inherit a property sheet by 'Add Existing Property Sheet.'

Special Thanks:  I first got an understanding of environment variable from a post at StackOverflow.  The answer in the post, however, used a text-based approach to create and handle property values.  But I'm new to this stuff and prefer to use a GUI.  Once I could get it done, I wrote this page and hope other people can make use of it.

Pinyo Taeprasartsit

June 12, 2010,  Feb 19, 2011