{"id":5770,"date":"2020-03-24T21:02:36","date_gmt":"2020-03-25T04:02:36","guid":{"rendered":"https:\/\/visualgdb.com\/w\/?p=5770"},"modified":"2021-08-26T07:08:03","modified_gmt":"2021-08-26T14:08:03","slug":"visualgdb-msbuild-project-structure","status":"publish","type":"post","link":"https:\/\/visualgdb.com\/documentation\/projects\/msbuild\/","title":{"rendered":"VisualGDB MSBuild Project Structure"},"content":{"rendered":"<p>This page describes the structure of the MSBuild-based VisualGDB projects and gives an overview of common settings and file types.<\/p>\n<h1>Overview<\/h1>\n<p>MSBuild-based projects are supported for most Embedded and Linux targets and are very similar to the regular Win32 C\/C++ projects. The main advantages of MSBuild projects over other project types are:<\/p>\n<ul>\n<li>Ability to define multiple configurations\/platforms with different settings<\/li>\n<li>Ability to customize build settings for individual files<\/li>\n<li>Use of the VS configuration GUI similar to the regular Win32 projects<\/li>\n<li>Ability to combine VisualGDB-based and non-VisualGDB-based platforms in the same project (see <a href=\"https:\/\/visualgdb.com\/tutorials\/porting\/multiplatform\/\">this tutorial<\/a>)<\/li>\n<li>Much faster building compared to GNU Make (same speed as CMake with Ninja)<\/li>\n<\/ul>\n<p>The only drawback of the MSBuild-based projects is that they cannot be easily built outside Visual Studio (see <a href=\"#standalone\">this section<\/a> for possible workarounds).<\/p>\n<p>You can easily tell whether the current project is using MSBuild by checking the active platform name and the project icon:<a href=\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/03\/platform.png\"><img loading=\"lazy\" decoding=\"async\" class=\"aligncenter size-full wp-image-5771\" src=\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/03\/platform.png\" alt=\"\" width=\"1181\" height=\"186\" \/><\/a>If the project has the regular VC++ project icon and the platform name is <strong>VisualGDB<\/strong>, this is an MSBuild-based project.<\/p>\n<h1><a id=\"files\"><\/a>Files<\/h1>\n<p>A typical MSBuild-based project consists of the following files and subdirectories:<\/p>\n<table style=\"border-collapse: collapse; width: 100%;\" border=\"1\">\n<tbody>\n<tr>\n<td style=\"width: 33.3333%;\">File\/subdirectory<\/td>\n<td style=\"width: 33.3333%;\">Meaning<\/td>\n<td style=\"width: 33.3333%;\">Source Control Action<\/td>\n<\/tr>\n<tr>\n<td style=\"width: 33.3333%;\">&lt;Project&gt;.vcxproj<\/td>\n<td style=\"width: 33.3333%;\">Visual Studio project file. Contains the list of source files, and various build settings.<\/td>\n<td style=\"width: 33.3333%;\">Check In<\/td>\n<\/tr>\n<tr>\n<td style=\"width: 33.3333%;\">&lt;Project&gt;.vcxproj.filters<\/td>\n<td style=\"width: 33.3333%;\">Visual Studio virtual folders file. Maps files to virtual folders in Solution Explorer.<\/td>\n<td style=\"width: 33.3333%;\">Check In<\/td>\n<\/tr>\n<tr>\n<td style=\"width: 33.3333%;\">*.user<\/td>\n<td style=\"width: 33.3333%;\">Contains non-vital per-user preferences<\/td>\n<td style=\"width: 33.3333%;\">Usually, ignore<\/td>\n<\/tr>\n<tr>\n<td style=\"width: 33.3333%;\">&lt;MCU&gt;.xml<\/td>\n<td style=\"width: 33.3333%;\">Stores VisualGDB-specific settings that are specific to embedded projects (e.g. device type)<\/td>\n<td style=\"width: 33.3333%;\">Check In<\/td>\n<\/tr>\n<tr>\n<td style=\"width: 33.3333%;\">&lt;MCU&gt;.props<\/td>\n<td style=\"width: 33.3333%;\">Generated property sheet containing device-specific build settings<\/td>\n<td style=\"width: 33.3333%;\">Check In<\/td>\n<\/tr>\n<tr>\n<td style=\"width: 33.3333%;\">*.vgdbsettings<\/td>\n<td style=\"width: 33.3333%;\">VisualGDB-specific settings stored separately for each configuration<\/td>\n<td style=\"width: 33.3333%;\">Check In<\/td>\n<\/tr>\n<tr>\n<td style=\"width: 33.3333%;\">.vs\\*<\/td>\n<td style=\"width: 33.3333%;\">Temporary Visual Studio files<\/td>\n<td style=\"width: 33.3333%;\">Ignore<\/td>\n<\/tr>\n<tr>\n<td style=\"width: 33.3333%;\">VisualGDB\\*<\/td>\n<td style=\"width: 33.3333%;\">Generated object and binary files<\/td>\n<td style=\"width: 33.3333%;\">Ignore<\/td>\n<\/tr>\n<tr>\n<td style=\"width: 33.3333%;\">.visualgdb\\*<\/td>\n<td style=\"width: 33.3333%;\">Temporary VisualGDB files<\/td>\n<td style=\"width: 33.3333%;\">Ignore<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>The <strong>&lt;MCU&gt;.xml<\/strong> and <strong>&lt;MCU&gt;.props<\/strong> files are automatically generated by VisualGDB based on a device definition from the BSP (board support package). The device definitions are typically stored under <strong>%LOCALAPPDATA%\\VisualGDB\\EmbeddedBSPs\\&lt;target&gt;\\&lt;ID&gt;\\BSP.XML<\/strong> files. See <a href=\"https:\/\/visualgdb.com\/documentation\/embedded\/stm32\/\">this page<\/a> for a detailed description of the structure of embedded projects.<\/p>\n<h1><a id=\"settings\"><\/a>Settings<\/h1>\n<p>MSBuild projects contain 2 types of settings: <strong>MSBuild-level settings<\/strong> (e.g. preprocessor macros, optimization type, linker script) and <strong>VisualGDB-level settings<\/strong> (e.g. debug settings, static analysis settings, custom actions).<\/p>\n<p><strong>MSBuild-level settings<\/strong> can be edited by right-clicking on the project node in Solution Explorer and selecting &#8220;Properties&#8221; (or pressing Alt-Enter). The MSBuild settings for VisualGDB projects are similar to the regular VS project settings:<a href=\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/03\/msb.png\"><img loading=\"lazy\" decoding=\"async\" class=\"aligncenter size-full wp-image-5772\" src=\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/03\/msb.png\" alt=\"\" width=\"1181\" height=\"864\" \/><\/a>Note that the MSBuild settings are defined separately for each configuration (e.g. Debug\/Release).<\/p>\n<p>You can also define MSBuild-level settings for individual files, overriding the per-project settings:<a href=\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/03\/perfile.png\"><img loading=\"lazy\" decoding=\"async\" class=\"aligncenter size-full wp-image-5773\" src=\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/03\/perfile.png\" alt=\"\" width=\"1127\" height=\"556\" \/><\/a><strong>VisualGDB-level settings<\/strong> are stored in the <strong>.vgdbsettings<\/strong> files and can be edited by right-clicking on the project and selecting <strong>VisualGDB Project Properties<\/strong>:<a href=\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/03\/vgdb.png\"><img loading=\"lazy\" decoding=\"async\" class=\"aligncenter size-full wp-image-5774\" src=\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/03\/vgdb.png\" alt=\"\" width=\"1063\" height=\"885\" \/><\/a>Note that the <strong>MSBuild Settings<\/strong> page of VisualGDB Project Properties is a shortcut to the most commonly used MSBuild-level settings. Editing the settings there will have the same effect as using the regular Visual Studio Properties window: <a href=\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/03\/msbpage.png\"><img loading=\"lazy\" decoding=\"async\" class=\"aligncenter size-full wp-image-5775\" src=\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/03\/msbpage.png\" alt=\"\" width=\"1053\" height=\"367\" \/><\/a><\/p>\n<h1><a id=\"commonsettings\"><\/a>Locations of Common Settings<\/h1>\n<p>Below are the locations of common MSBuild-level settings for VisualGDB projects (under the VS Project Properties window for the entire project):<\/p>\n<table style=\"border-collapse: collapse; width: 100%; height: 264px;\" border=\"1\">\n<tbody>\n<tr style=\"height: 24px;\">\n<td style=\"width: 50%; height: 24px;\">Setting<\/td>\n<td style=\"width: 50%; height: 24px;\">Location<\/td>\n<\/tr>\n<tr style=\"height: 24px;\">\n<td style=\"width: 50%; height: 24px;\">Directory of the ELF file<\/td>\n<td style=\"width: 50%; height: 24px;\">General -&gt; Output Directory<\/td>\n<\/tr>\n<tr style=\"height: 24px;\">\n<td style=\"width: 50%; height: 24px;\">Directory of the object files<\/td>\n<td style=\"width: 50%; height: 24px;\">General -&gt; Intermediate Directory<\/td>\n<\/tr>\n<tr style=\"height: 24px;\">\n<td style=\"width: 50%; height: 24px;\">Name\/Extension of the ELF file<\/td>\n<td style=\"width: 50%; height: 24px;\">General-&gt;Target Name\/Extension<\/td>\n<\/tr>\n<tr style=\"height: 24px;\">\n<td style=\"width: 50%; height: 24px;\">Optimization Level<\/td>\n<td style=\"width: 50%; height: 24px;\">C\/C++-&gt;Optimization-&gt;Optimization Level<\/td>\n<\/tr>\n<tr style=\"height: 24px;\">\n<td style=\"width: 50%; height: 24px;\">Preprocessor Macros<\/td>\n<td style=\"width: 50%; height: 24px;\">C\/C++-&gt;Preprocessor-&gt;Preprocessor Definitions<\/td>\n<\/tr>\n<tr style=\"height: 24px;\">\n<td style=\"width: 50%; height: 24px;\">Include Directories<\/td>\n<td style=\"width: 50%; height: 24px;\">C\/C++-&gt;General-&gt;Additional Include Directories<\/td>\n<\/tr>\n<tr style=\"height: 24px;\">\n<td style=\"width: 50%; height: 24px;\">Custom Post-Compile Step (per-file)<\/td>\n<td style=\"width: 50%; height: 24px;\">C\/C++-&gt;Custom Step<\/td>\n<\/tr>\n<tr style=\"height: 24px;\">\n<td style=\"width: 50%; height: 24px;\">Additional Linker Inputs<\/td>\n<td style=\"width: 50%; height: 24px;\">Linker-&gt;General (see <a href=\"https:\/\/visualgdb.com\/documentation\/linkerinputs\/\">here<\/a> for more details)<\/td>\n<\/tr>\n<tr style=\"height: 24px;\">\n<td style=\"width: 50%; height: 24px;\">Linker Script<\/td>\n<td style=\"width: 50%; height: 24px;\">Linker-&gt;Linker Script<\/td>\n<\/tr>\n<tr style=\"height: 24px;\">\n<td style=\"width: 50%; height: 24px;\">Map File<\/td>\n<td style=\"width: 50%; height: 24px;\">Linker-&gt;Generate Map File\/Map File Name<\/td>\n<\/tr>\n<tr>\n<td style=\"width: 50%;\">Additional CFLAGS (both C and C++)<\/td>\n<td style=\"width: 50%;\">C\/C++-&gt;Command Line<\/td>\n<\/tr>\n<tr>\n<td style=\"width: 50%;\">Additional CFLAGS\/CXXFLAGS (per language)<\/td>\n<td style=\"width: 50%;\">C\/C++-&gt;Advanced-&gt;Additional Options (C\/C++ files)<\/td>\n<\/tr>\n<tr>\n<td style=\"width: 50%;\">Additional LDFLAGS<\/td>\n<td style=\"width: 50%;\">Linker-&gt;Command Line<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h1><a id=\"configurations\"><\/a>Configurations<\/h1>\n<p>The recommended way of adding\/removing configurations to MSBuild-based VisualGDB projects is via the top of VisualGDB Project Properties window:<a href=\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/03\/cfg1.png\"><img loading=\"lazy\" decoding=\"async\" class=\"aligncenter size-full wp-image-5776\" src=\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/03\/cfg1.png\" alt=\"\" width=\"1063\" height=\"74\" \/><\/a>This will automatically create the <strong>.vgdbsettings<\/strong> files for the new configurations.<\/p>\n<p>Alternatively, you can use the regular VS Configuration Manager:<a href=\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/03\/cfg2.png\"><img loading=\"lazy\" decoding=\"async\" class=\"aligncenter size-full wp-image-5777\" src=\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/03\/cfg2.png\" alt=\"\" width=\"1044\" height=\"254\" \/><\/a>However, in this case, you would need to manually copy the <strong>.vgdbsettings<\/strong> file for the new configuration, or link the new configuration with an existing <strong>.vgdbsettings<\/strong> file:<a href=\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/03\/settingslink.png\"><img loading=\"lazy\" decoding=\"async\" class=\"aligncenter size-full wp-image-5778\" src=\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/03\/settingslink.png\" alt=\"\" width=\"786\" height=\"544\" \/><\/a><\/p>\n<h1><a id=\"references\"><\/a>Toolchain\/BSP References<\/h1>\n<p>Embedded MSBuild-based projects use special variables, such as <strong>$(BSP_ROOT)<\/strong> to refer to files managed by VisualGDB:<\/p>\n<pre class=\"\">\u00a0   &lt;ClCompile Include=\"$(BSP_ROOT)\\STM32F4xxxx\\StartupFiles\\startup_stm32f407xx.c\" \/&gt;<\/pre>\n<p>These paths are resolved as shown below:<\/p>\n<ol>\n<li>When VisualGDB is initialized, it generates\/updates the <strong>%LOCALAPPDATA%\\VisualGDB\\FindComponents.props<\/strong> file. Each MSBuild project implicitly references this file via the VisualGDB MSBuild platform.<\/li>\n<li>Each MSBuild-based project would define variables like <strong>BSP_ID<\/strong> (embedded only) and <strong>ToolchainID<\/strong>:\n<pre class=\"\">  &lt;PropertyGroup Label=\"Globals\"&gt;\r\n    &lt;BSP_ID&gt;com.sysprogs.arm.stm32&lt;\/BSP_ID&gt;\r\n    &lt;BSP_VERSION&gt;2020.01&lt;\/BSP_VERSION&gt;\r\n  &lt;\/PropertyGroup&gt;<\/pre>\n<\/li>\n<li>The <strong>FindComponents.props<\/strong> file (more specifically, <strong>FindBSP.props<\/strong>, <strong>FindToolchain.props<\/strong>, etc) would set the <strong>BSP_ROOT\/ToolchainDir<\/strong> variables based on the ID and version defined in the project file. This allows sharing the same project file between multiple users with different BSP\/toolchain installation directories.<\/li>\n<\/ol>\n<p>You can force VisualGDB to regenerate the <strong>FindXXX.props<\/strong> files outside Visual Studio by running the following command:<\/p>\n<pre class=\"\">VisualGDB.exe \/pkgmgr<\/pre>\n<p>Note that it will also open the VisualGDB Package Manager, letting you install\/uninstall various packages.<\/p>\n<h1><a id=\"troubleshooting\"><\/a>Troubleshooting Build<\/h1>\n<p>For projects built on the Windows machine, VisualGDB will save arguments for each tool involved in building the project in <strong>.rsp<\/strong> files in the object file directory. You can examine them to see what exact arguments are being passed to gcc, or edit them and quickly test out your changes by running the following command line from the project directory:<\/p>\n<pre class=\"\">&lt;full path to gcc.exe&gt; @&lt;relative path to the .rsp file&gt;<\/pre>\n<p>Note that VisualGDB will overwrite any changes made to the .rsp files next time you build the project.<\/p>\n<p>For projects built remotely, VisualGDB generates a special <strong>.msbuild-mak<\/strong> file based on the MSBuild project properties. The file contains all targets and command lines used to build the project and can be built using GNU Make.<\/p>\n<p>You can analyze complicated build errors by enabling diagnostic <strong>MSBuild logging via Tools-&gt;Options-&gt;Projects And Solutions-&gt;MSBuild Log Verbosity<\/strong>:<a href=\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/03\/diag.png\"><img loading=\"lazy\" decoding=\"async\" class=\"aligncenter size-full wp-image-6996\" src=\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/03\/diag.png\" alt=\"\" width=\"744\" height=\"434\" \/><\/a>Once verbose logging is enabled, the <strong>View-&gt;Output<\/strong> window (not the VisualGDB Build window), or the build log file will show very detailed information about every MSBuild target, parameter and variable involved in build.<\/p>\n<h1><a id=\"standalone\"><\/a>Building outside Visual Studio<\/h1>\n<p>You can configure VisualGDB to dump all command lines involved in building an MSBuild-based project into a <strong>.bat<\/strong> file as shown below:<a href=\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/03\/localbuild.png\"><img loading=\"lazy\" decoding=\"async\" class=\"aligncenter size-full wp-image-5781\" src=\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/03\/localbuild.png\" alt=\"\" width=\"786\" height=\"544\" \/><\/a>Note that the .bat file will reference the <strong>.rsp<\/strong> files that are created in the object file directory. If you would like to run the .bat file on a different machine, ensure you deploy the <strong>.rsp<\/strong> files together with it.<\/p>\n<h1><a id=\"seealso\"><\/a>See Also<\/h1>\n<p>For more details on the embedded project structure, see <a href=\"https:\/\/visualgdb.com\/documentation\/embedded\/stm32\/\">this page<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>This page describes the structure of the MSBuild-based VisualGDB projects and gives an overview of common settings and file types.<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[201],"tags":[],"_links":{"self":[{"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/posts\/5770"}],"collection":[{"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/comments?post=5770"}],"version-history":[{"count":10,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/posts\/5770\/revisions"}],"predecessor-version":[{"id":7456,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/posts\/5770\/revisions\/7456"}],"wp:attachment":[{"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/media?parent=5770"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/categories?post=5770"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/tags?post=5770"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}