Integration of SBuild and Microsoft Visual Studio

 

Back to Command line user
Back to SBuild manual home
Table of content
Overview

Using your SBuild build script, you can generate Visual Studio project files. You can use those project files to fire an SBuild build without leaving Visual Studio or to fire a debugging session. Here is a very short overview:

  • Run build_something.py -M.  That will generate a .vcproj (or a .dsp) and starts Visual Studio with it.
  • Once in the IDE, you edit source files (or build scripts) as you usually do.
  • The shortcut F7 runs SBuild.  F5 starts the debugger.
  • Later on, to start working again, you have the choice between:
    • Double-click the generated project file in File Explorer
    • Start the IDE from an icon and choose in the menu "Recent workspaces"
    • Run again the same script with -M

Important warning: although it is possible to use SBuild through Visual Studio, that is fairly limited. Only the basic functionality is available in this way. For example, most features related to the C pre-processor and to the C parser included in SBuild are not surfaced, the parallel build is not possible, etc. The full power of SBuild is only available through the command line.

Back to top
The msdev action

SBuild implements an action, called msdev, to generate the Microsoft project files. For example, if you do build_something.py -b to build some application, then you use build_something.py action=msdev(...) to generate the project files that will cover the same build. Here are all the possibilities of this action with extensive explanations:

  • action=msdev(init8)
    • Generate a .vcproj file. The file name is computed from the build script name (and the target id, if you provided any). The file is placed in a subdirectory of the SBuild project directory. The directory is created if needed. Note that any existing project with the same name will get overwritten (in fact, clean8 is performed first).
  • action=msdev(init8,...)
    • A richer form of the above. init8 can be followed by a comma-separated list of target platforms to build for. That will add in the generated project some more Project Configurations. More details further below.
  • action=msdev(init)
  • action=msdev(init,...)
    • Same as above but generates a .dsp file. The .dsp files are useful for Visual Studio 6 (but also understood and converted on the fly by more recent versions of Visual Studio).
  • action=msdev(clean8)
    • Removes the .vcproj file generated with init8. Important, it also removes other temporary files that Visual Studio creates in relation to this .vcproj. Note that, since the generated files are in a dedicated subdirectory, it is also possible to clean that directory manually, if desired.
  • action=msdev(clean)
    • Same but it removes the .dsp file and related files
  • action=msdev(start8)
    • Attempts to start Visual Studio 2005 on your machine. But first it looks for a generated project corresponding to this build. If it doesn't find any, it performs init8 then it starts Visual Studio. If it find one, no matter how old, it only starts Visual Studio with it. SBuild tries first Visual Studio Express and then Visual Studio full.
  • action=msdev(start)
    • Same as above but starts Visual Studio 6
  • action=msdev() and -M
    • This scans the registry of your machine looking for versions of Visual Studio. If 2005 is found then it performs start8, otherwise it performs start
    • -M is a strict equivalent of action=msdev()

Note that -M, start8 and start are only provided for convenience. If ever the scanning of the registry fails, or starting the IDE fails, you can always and reliably use the init8 and init and then click on the generated files. init8 and init will generate the Microsoft project files even if no Visual Studio at all is installed on your machine.

The generated project files have been tested with Visual Studio 2005 and with Visual Studio 6. They also work with Visual Studio 2008, although SBuild is not yet able to start it automatically.

Back to top

Inside the IDE

Once you have the IDE started, you will notice a number of Visual Studio Project Configurations larger than what you use to have (you are likely used to see two of them, called "Debug" and "Release"). Now you will see 6 or more. The reason is that, within the IDE, you always start SBuild in the same way: by starting a build (shortcut F7). So you choose one Project Configuration to decide what SBuild will do for you. Here are the 6 configurations that SBuild puts in the generated .vcproj (the actual names are longer, this simplification for easier understanding):

  • List
    • List the .c sources and the .h headers in the Output pane. Double click a file name to open file in editor. This is the same as passing action=preproc(vssrcs) to a build script
  • Header tree
    • Shows a tree of .h inclusion. What files includes what exactly, with full absolute paths names. Same as passing action=preproc(tree)
  • dbg Build
    • Performs a build with F7. Same as -b bldopt=dbg. But it can be also the same as -B bldopt=dbg if you chose in the menu to do a full rebuild (Ctrl-Alt-F7 in Visual Studio 2005) or the same as -c bldopt=dbg  if you choose to clean up.
  • dbg Run
    • Same as -R bldopt=dbg. You must have built first. How to write build scripts so that targets are run by SBuild is explained elsewhere.
  • rls Build
  • rls Run
    • Same as above but with bldopt=rls instead of bldopt=dbg, meaning for a release build.

The first 2 configurations are independent of the target platform that you build for. By contrast, the last configurations are dependent and they are duplicated for every target platform you specified to init8 or init. More precisely, they are duplicated for each and every pair of <tgtplatform>:<toolchain>. See also explanation further below.

Take note that, among the configurations listed above, it only makes sense to hit F5 (to start a debugging session) for 2 configurations:

  • dbg Build
  • rls Build

Other details:

  • A project file is always generated in the same place, so you can easily place a shortcut on your desktop for it
  • In order to make it work also with Visual Studio 6 and 7, among other reasons, the field "Platform" that is available in Visual Studio 2005 and later is not used. That one will always show "Win32".

Back to top
Screen snapshots
Visual Studio 2005 with generated .vcproj opened. Note the sources in the left pane. Note the drop down list of Project configurations. Note the output in the lower pane showing the header inclusion tree.
Visual Studio 6 with generated .dsp opened. Note the sources in the left pane. Note the drop down list of Project configurations. Note the output in the lower pane showing the header inclusion tree.

Back to top

Advantages

Despite the many limitations compared to command line SBuild, there are also some advantages. A few are the ones  that you expect in any IDE. For example:

  • If there is a compilation error, you can double click it to open the file concerned at the relevant location
  • If you have Visual Assist installed, Alt-Shift-O will look up files in the project (similar to Ctrl-Shift-R in Eclipse)

Beyond that, the one and only significant advantage is that you can build from within one Visual Studio using the compilers of other versions of Visual Studio and also Cygwin and MinGW. You need to provide a lengthy action=msdev(init,...) but it is well worth the effort.

Here is the extended syntax of init8 and init, explained through examples:

  • action=msdev(init8,i86_win32,armv4_wce420,i86_win32_cygwin) This will generate a .vcproj file that is able to build for the following:
    • for your desktop Windows (target platform i86_win32) with the default Microsoft compiler (and that is Visual Studio 6 if you didn't specified otherwise with toolchain=<tool chain> or in the shell variable SBUILD_CCPP_TOOLCHAIN)
    • for Windows CE 4.20 with ARM processor using the default toolchain for that (which is Embedded Visual C++ 4.0). Of course the build will fail if you don't have that installed on your machine but the generation of the .vcproj will succeed.
    • for your desktop Windows but with Cygwin installed using the gcc compiler provided with Cygwin. Same as above, the generation will succeed with or without Cygwin installed and Visual Studio will open fine but the build will fail if you don't have Cygwin installed. If build_something.py tgtplatform=i86_win32_cygwin -b  succeeds from the command line on your machine, then it will succeed also with F7 from your generated .vcproj
  • action=msdev(init8,armv4_wce420,i86_win32_cygwin)
    • This will do the same as above, most likely. That is because i86_win32 is the default target platform and its also the current target platform (if not changed with tgtplatform=<...> or with SBUILD_CCPP_TGTPLATFORM) and the current platform is always added to the specified set by init8 and init
  • action=msdev(init8,armv4i_wce500,i86_win32:msvc6,i86_win32:msvc71,i86_win32:msvc80compat,armle_qnx641) This will make a .vcproj that builds
    • for Windows CE 5.0 with Standard Platform SDK using its default tool chain (Visual Studio 2005)
    • for your desktop Windows using either the compilers from Visual Studio 6 or from Visual Studio 2003 or from Visual Studio 2005 (with settings to shut off warning in code written for Visual Studio 6, that's why the toolchain id is msvc80compat)
    • for QNX 6.4.1 device with ARM processor and the Momentics tool chain on Windows
  • action=msdev(init,plat1,plat2:toolA,plat2:toolC,plat3,plat4:toolD) This will create a .dsp file that is able to build for the following:
    • for plat1 and for plat3 with the respective default toolchain for those platforms
    • for plat4 with tool chain toolD and also for plat4 with its default tool chain, if that is not toolD
    • for plat2 with tool chain toolA and also with tool chain toolC and with its default tool chain if not one of toolA or toolC
    • for the current target platform, if not one of plat1, plat2, plat3 or plat4

As you may expect, during generation, SBuild prints out the capabilities of the generated project file. You may check in this way if your command line options have been understood as you expected. Note also that no space is allowed in your possibly long action=msdev(...), a limitation of the shell, not of SBuild.

Back to top

Limitations for Visual Studio 2005

The most important limitation is the fact that the generation is a one-shot operation, not a continuous one. While you work in the IDE, if you edit a build script so that new sources files are now part of the build, the File View (in the left pane of the IDE windows) will NOT be automatically updated. Note that the build will always be accurate, it is only the list of files in the left pane that is not automatic. There are two workarounds for that:

  • You close the IDE and you regenerate the project files
  • You don't close the IDE. You select the List_files Configuration and hit F7. That gives you the (always accurate) list of sources. Start Find (Ctrl F) or simply scroll the output view until you spot your new file and double click it. The IDE will open it (and it will also remember it next time, like for all the files you have opened).

An important limitation is that you cannot distribute the generated .vcproj/.dsp files unless you also distribute the SBuild tool itself. That is because the generated Microsoft projects still use under the hood the SBuild build scripts for building and cleaning your software. It is theoretically possible to generate Microsoft project files that are completely independent of SBuild but extremely difficult to make the build the same (through IDE versus through command line).

Another limitation is the fact that you can debug only one executable. You build script may well build hundred  executables, hitting F5 will only start the first of them. That is why, when you intend to build and debug executables, we highly advice you to use tgt=<my_exec_target> together with action=msdev(...)  on the command line when you generate the project files. That makes that only one executable is built and that removes any confusion about which one will start. Know also that, if you configured your build script so that -r runs the built executable with parameters (or several times with several sets of parameters), those parameters will not be used when you start a debugging session with F5. You can still run your executable with those parameters (by choosing a "run" Project Configuration and hitting F7). You can still debug your built executables with parameters but you have to fill them in by hand (Alt-F7).

Another limitation is the fact that almost all command line options on the call with action=msdev(...) are either ignored or refused. The following 4 parameters may be provided and will be remembered by the generated Microsoft project files:

  • tgt=<target id>
  • toolchain=<tool chain>
  • tgtplatform=<target platform>
  • lint_usage=<code>

Another limitation is the fact that the source files are shown in the left pane in a flat list. There is no structure (for example, grouping by SBuild targets of the sources) and the order is chosen by Visual Studio. Related to that, also notice that SBuild generates one .vcproj (or .dsp) for one run. You can have as many generated .vcproj next to each other but SBuild will not assemble them into one larger .sln (or larger .dsw). You can do that easily by hand if you desire or with a script that calls several build scripts with action=msdev(...) and also writes the .sln at the end.

Another limitation is that this action=msdev() is not compatible with advanced customization of the SBuild project. That is because the msdev action needs to know a priori all the target platforms and all the tool chains that will be used from within the IDE (in order to generate that set of Project Configurations). If your SBuild projects is setting the value of tgtplatform and/or toolchain by program, the msdev(init,...) action will likely get confused.

Limitations for Visual Studio 6

For Visual Studio 6 all the limitations above apply and then some more. The reason is the fact that the .dsp files store less information than the .vcproj files.

Most important, there cannot be any information about how to run your just built executables under the debugger. So F5 will not work (out of the box). The workaround is to fire the dialog Project Setting (Alt-F7) and to fill in by hand what you want (the executable, the arguments, the current dir). Visual Studio stores this in a .opt binary file and it will remember it when you re-open this project (until you regenerate it).

Finally, note that in Visual Studio 6  you will see two more Project configurations

  • dbg Clean
  • rls Clean

And you clean selecting them and using F7, which is a bit counter intuitive for old time users. Fortunately, the cleaning is extremely rarely used (because the incremental build is so accurate with SBuild).

Back to top

Back to Command line user
Back to SBuild manual home