wiki:WikiStart

Welcome to the COIN-OR Visual Studio Wiki

Note that these project web pages are based on Wiki, which allows users to modify the content to correct typos, add information, or share their experience and tips with other users. You are welcome to contribute to these web pages. To edit these pages you must first register and login.

Introduction

A fair number of COIN-OR projects come with solution files for Microsoft Visual Studio. This wiki describes the organization and use of Visual Studio solutions for two standard configurations and a third configuration currently used in the trunks of many of the project that is a revamping of the classic configuration (we refer to this as the neoclassical configuration):

  • The 'classic' COIN-OR package, in which the source code for the project and all dependencies (svn externals) is maintained as a monolithic unit; and
  • The 'neoclassical' configuration is philosophically similar to the classic configuration, but uses property sheets to store common settings and also allows for building with multiple toolset platforms (what Microsoft calls compiler versions) side by side using a single version of the MSVC++ GUI.
  • The 'split' configuration, in which the source code for each project is maintained individually.

The classic configuration is often the most convenient for a person who wants to make use of one COIN-OR project (only clp, for example, or only cbc). Simply download a tarball with the source code or check out a release from the project's subversion repository. The resulting binaries are built in a subdirectory of the package. The classic configuration will be replaced over time with the neoclassical configuration. This change should be transparent to users and mostly transparent to developers. Currently, the trunk version of many projects have changed to use the neoclassical configuration, which will be slowly migrated into stables over time.

The split configuration is more useful for a person who is using several COIN-OR projects (for example, clp and cbc) and does not want multiple copies of the source code for dependencies. You must check out the source code for each project, without externals. The resulting binaries are installed in a common installation directory.

Each configuration is explained in more detail below. Some COIN-OR projects provide Visual Studio projects with different organizations. Check the instructions for the project(s) of interest to you.

The standard location for Visual Studio solution files in a COIN-OR project is the MSVisualStudio subdirectory. As of June 2012, most COIN-OR projects maintain Visual Studio solutions primarily for Visual Studio 2010, with legacy support for Visual Studio 2008 SP1. Some projects provide solution and project files for older versions of Visual Studio; these are not maintained and are likely to require repair in order to be usable. We have endeavored to remove broken files from stable and release version, but you can check the trunk versions of individual projects if you want older files and are willing to repair them. Here's the naming convention:

Subdirectory Visual Studio Version Configuration Architecture
v10 2010 classic/neoclassical 64- and 32-bit
v10alt 2010 split 64- and 32-bit
v9 2008 classic 64- and 32-bit
v9alt 2008 split 64- and 32-bit
v8 2005 classic 32-bit
v7 .Net classic 32-bit
v6 Version 6 classic 32-bit

The v9alt and v10alt solution files are capable of building DLLs; only a debug build is provided with the distributed solution files but it's a relatively simple (if tedious) matter to modify the solution and project files to produce a release build. By default, native DLLs are built; again, it's a relatively simple matter to produce assemblies.

Many COIN-OR projects cannot be compiled using the compilers shipped with older versions of Visual Studio. In general, you are better off using the most recent version. Requests to update solution and project files prior to VS2008 will be discarded.

Classic Configuration

In the classic configuration, all necessary source code for a project, including any dependencies, comes in one monolithic package. The binaries (libraries and executables) that are produced when the project is built are placed in subdirectories of the MSVisualStudio build directory. Using clp as an example, the classic package produces the following directory structure (only the subdirectories of interest are shown, with progressively less detail from top to bottom):

  • Clp
    • BuildTools
    • Clp
      • MSVisualStudio
        • v9alt
        • v9
        • v8
      • src
      • test
      • examples
    • CoinUtils
    • Data
      • Sample
    • Osi
    • ThirdParty
      • Blas
      • Lapack

As you can see, the package includes the source code for clp (Clp\Clp\src), for clp's unit tests (Clp\Clp\test), and for examples (Clp\Clp\examples). It also includes the source code for the COIN-OR projects that clp depends on - CoinUtils and Osi - as well as COIN-OR utilities (Clp\BuildTools), data files (Clp\Data\Sample), and placeholders for third-party software (Clp\ThirdParty). Within the MSVisualStudio directory there are subdirectories for several Visual Studio solutions (v9, v9alt, and v8).

When you use v9\Clp.sln with Visual Studio to build clp libraries and executables, the results will be placed in subdirectories (Debug, Release, x64\Debug, x64\Release) within the v9 directory.

If you look inside the subdirectories for CoinUtils and Osi, you'll see that they, too, have subdirectories for src, test, examples, and MSVisualStudio. Of interest here is that the v9 solution for Clp will reference the v9 solutions for CoinUtils and Osi. The advantage is that the solution for Clp knows that it depends on the referenced solutions and automatically handles the dependencies. The resulting libraries (e.g., libCoinUtils.lib and libOsi.lib) will be placed in the same subdirectories with the clp libraries and executables, not in CoinUtils\MSVisualStudio\v9 or Osi\MSVisualStudio\v9.

Suppose that you want to work on both Clp and Cbc. If you were to download the classic packages for Clp and Cbc, you would have the following directory structure:

  • Clp
    • BuildTools
    • Clp
      • MSVisualStudio
        • v9alt
        • v9
        • v8
      • src
      • test
      • examples
    • CoinUtils
    • Data
      • Sample
    • Osi
    • ThirdParty
      • Blas
      • Lapack
  • Cbc
    • BuildTools
    • Cbc
      • MSVisualStudio
        • v9alt
        • v9
        • v8
      • src
      • test
      • examples
    • Cgl
    • Clp
    • CoinUtils
    • Data
      • Sample
    • Osi
    • ThirdParty
      • ASL
      • Blas
      • Glpk
      • Lapack

In particular, you would have two complete copies of the source code for CoinUtils, Osi, and Clp! As you download additional classic packages, you acquire additional copies of common source code. This wastes space, and if you modify one of the copies you need to remember to push the modification to all the others. At some point, if you work on multiple COIN-OR projects, you may wish to consider the split configuration.

Neoclassical Configuration

The neoclassical configuration is based on the classic configuration in spirit, with the following main differences:

Use of Property Sheets

Many of the settings that should be the same across all projects are now modified through the use of property sheets. Property sheets are Microsoft's cryptic and overly complicated way of allowing the specification of common properties. Previously, such properties were kept in sync by a painstaking process of editing each project file for each project individually. This is no longer necessary.

The common property sheets are hosted as part of the BuildTools project. You will find them in the BuildTools/MSVisualStudio/v10 directory. At the moment, there are three such property sheets:

  • Common.prop: Contains properties common to all projects in all configurations.
  • Debug.prop: Contains properties common to all projects in Debug configuration.
  • Release.prop: Contains properties common to all projects in Release configuration.

In general, there are now very few properties that should be changed by editing the project files of individual projects. As much as possible, one should edit the common property so that the properties are kept in sync for all projects. To edit the properties in the common property sheets, open the Property Manager from the View menu. You should then be able to see the property sheets from which each project is inheriting settings. Right-click on the sheet you want to edit and change the properties as you would when editing the properties of any individual project.

Installation Directories

The installation directory for the final binaries and libraries is now changed to $(SolutionDir)$(Platform)-$(PlatformToolset)-$(Configuration). The SolutionDir macro points to the directory of the solution file being used to build the project. The Platform macro is either x64 or Win32, the PlatformToolset macro is the version of the compiler used for the build (usually v90 or v100), while the Configuration macro is either Debug or Release. This means that if you build a release version of a given project using MSVC++ 2008 (version 9 of the compiler) on a 32-bit version of Windows, you will find the binaries and libraries in the directory Win32-v90-Release. The rationale for adding the platform toolset as part of the directory name is to support the ability to build with multiple version of the compiler using a single version of the GUI. In MSVC++ 2010, it is possible to build with the v9 compiler if it is also installed in the system. This is done by changing the Platform Toolset property for all the projects in a given solution. Note that this particular property cannot be set on a property sheet and thus has to be set for each project individually. However, this can be done en mass by highlighting all of the projects within a solution simultaneously in the solution explorer (hold down the shift or control keys while highlighting each one) and then right-click and choose "Properties". In the "General" Section under "Configuration Properties", you will see the Platform Toolset option.

Split Configuration

The alternative to the classic configuration is the split configuration (again, only subdirectories of interest are shown). Using Cbc as an example, you would have:

  • CoinRoot
    • Win32
      • Debug
        • bin
        • lib
      • DebugDLL
      • Release
    • x64
      • Debug
      • DebugDLL
      • Release
    • BuildTools
    • Cbc
      • Cbc
        • MSVisualStudio
          • v9alt
          • v9
          • v8
        • src
        • test
        • examples
    • CoinUtils
      • CoinUtils
        • MSVisualStudio
          • v9
          • v9alt
        • src
        • test
    • Clp
    • Cgl
    • Osi
    • Data
      • Sample
    • ThirdParty

In the split configuration, there is exactly one copy of the source code (MSVisualStudio, src, test, examples) for each required project. Each project must be checked out individually, without externals. (You will need to read the documentation for your svn client to determine how to do this.) Each project must be built individually. You will need to go to the MSVisualStudio\v9alt subdirectory of each of CoinUtils, Osi, Clp, Cgl, and Cbc (in that order) and build the libraries and executables for each project. All results will be installed in the appropriate subdirectory of one of the top-level directories CoinRoot\Win32 or CoinRoot\x64 (e.g., if you build the 64-bit release configuration, all executables are installed in CoinRoot\x64\Release\bin and all libraries are installed in CoinRoot\x64\Release\lib). Directories in the Win32 and x64 subtrees are created as needed during the build.

The disadvantages should be clear from the previous paragraph. You, the user, now have all the responsibility for making sure that projects are built in the correct order, and rebuilt when necessary. The advantages are that there is exactly one copy of the source code for each project, and all libraries and executables accumulate in a common location. At some point, if you work on multiple COIN-OR projects, the advantages outweigh the disadvantages.

It's a good idea to build the unit test for each project as you go, as confirmation that the build succeeded.

There are a couple of additions to the Windows environment that are necessary to use the split configuration and v9alt solution files.

  • You must define two environment variables that point to the CoinRoot directory. Using whatever method is appropriate for your version of Windows, set COIN_ROOT to the full path to the CoinRoot directory (e.g., f:\Some\Path\To\CoinRoot). You must also provide a second variable, COIN_ROOT_ESCAPED, in which the \ character is correctly escaped according to the C++ language specification (e.g., f:\\Some\\Path\\To\\CoinRoot). The value of this variable is used when it's necessary to embed a path to some COIN-OR directory in a project's source code.
  • You must augment your PATH to include the appropriate bin directory (e.g., add f:\Some\Path\To\CoinRoot\x64\DebugDLL\bin). This is particularly important for the DLL build because the Windows rules for locating DLLs at runtime search the directories specified in PATH (among others). If you'd rather not install all your software in the standard system directories, this is an important point.

Windows seems to make it difficult to change environment variables. On a Windows 7 system, you need to open the Control Panel and work your way through System -> Advanced System Settings -> Environment Variables.

Information about dependencies (the location of header files, required libraries, etc.) is conveyed between projects by property (.vsprops) files. Be sure to check inherited dependencies when you're exploring the connections between projects. The Visual Studio Property Manager view (View -> Other Windows -> Property Manager) provides the best access to the hierarchy of inherited property files.

Building DLLs and Assemblies

The trick to building DLLs from C++ source is telling the linker what symbols need to be exported. In the Microsoft ecosystem, one generally does this by decorating the symbols of interested with __declspec(dllexport). Everywhere else, this is just a syntax error. COIN-OR code must run on multiple platforms and we didn't want to litter the code with artifacts specific to Microsoft. Fortunately, there's an alternate method: one can use a .def (module-definition) file to list the names of the symbols to be exported. Two problems remain:

  • the average COIN-OR library exports between a few hundred and several thousand symbols; and
  • the names in the .def file must be the decorated (mangled) names.

Manual maintenance of a .def file is not practical. COIN-OR DLL builds adopt a brute force solution. A PowerShell script runs as a pre-link event. This script uses dumpbin to dump the symbols for all .obj files that will be linked into a library. The symbols are filtered to remove those that are unacceptable to link and the remainder are added to the .def file. The advantage is that the .def file is automatically regenerated with each rebuild of the library and is always up-to-date. The disadvantage is that there is no documentation that describes which symbols can be exported and which cannot. So the scripts which do the filtering are based entirely on trial and error. It's entirely possible that they will break, for no apparent reason. If you happen to encounter such an event, we'd like to know about it. Please submit a ticket, with the source code! Remember, it's all trial and error. If we can't reproduce the problem, we can't fix it. Better yet, just send us a patch for the filter script.

To a first approximation, an assembly is a DLL with a manifest. By default, the DLL builds will build native DLLs. If you want assemblies, all you need to do is enable CLR (Common Language Runtime) support on the Configuration -> General tab of Properties for each project. Try not to mix and match; the error messages are obscure. The rules for locating Windows assemblies are even more restrictive than the rules for locating DLLs. The assemblies built by the v9alt and v10alt solution files are not strong-named. Short of taking some extreme measures, the only way that the executable can find them is if they are in the same directory as the executable, or in a subdirectory.

Projects with Visual Studio Solutions

The following projects have Visual Studio solution files that observe the classic and split build conventions described above.

If your favourite project isn't in this list, check first to see if the project has a MSVisualStudio directory with solution files. If not, post to the project's email list or file a bug ticket against the project. Requests here are a waste of your time.

FAQS

Obtaining MS Visual Studio

The MSVS express edition is sufficient to build COIN-OR projects. The 2010 edition can be downloaded here.

Obtaining source code

Building

  • How do I build the code using Microsoft Visual Studio?
    To build COIN-OR project Prj, start Visual Studio and open the appropriate solution file for your version of Visual Studio:
    • with Version 6, open the v6 workspace file Prj.dsw
    • with .Net, open the v7 solution file Prj.sln
    • with VS2005, open the v8 solution file Prj.sln
    • with VS2008, open the v9 or v9alt solution file Prj.sln
    • with VS2010, open the v10alt solution file Prj.sln

Or just double-click on the .dsw or .sln file; if you have Visual Studio installed, it will try to open it. If it's the right version of Visual Studio for the solution file, you're in business. If Visual Studio offers to convert the project for you, you should back out and think carefully about what you're doing.

  • How do I build the code using Microsoft Visual Studio from a Visual Studio command shell?
    • With Version 6 use the command
      cd directory_containing_dsw_file
      msdev Prj.dsw /Make all /rebuild /out clpMsdev.txt
      
    • With VS2005 use the command
      cd directory_containing_sln_file
      msdev Prj.sln $ALL
      
    • With VS2008 or VS2010 use the command
      cd directory_containing_sln_file
      devenv Prj.sln /build "config|platform"
      
      where config will be one of Debug, Release, or DebugDLL and platform will be one of Win32 or x64.
  • How do I build from a Cygwin command line using GNU make and the Microsoft compiler?

See the standard instructions for unix systems and make sure you choose the configuration options that select cl and link instead of the GCC compiler and linker.

Configuration

Many COIN-OR projects can be built with a rich set of configuration options appropriate to the environment. In a unix environment with autotools, most of this configuration is automatic. But until some developer who really understands Visual Studio volunteers to help us with Visual Studio's automated configuration capabilities, manual configuration is the only option. Look in the file src\config_default.h, at the section that's active when HAVE_CONFIG_H is undefined. There you will find a common subset of the available compile-time options. You should also check the file src\config.h.in for a much more comprehensive set of options that are normally set by the unix configure script. You can copy any or all of these over into config_default.h. Finally, the file BuildTools\headers\configall_system_msc.h contains the default configuration options used when building with Visual Studio.

For example, if zlib is available then CoinUtils can read a compressed MPS file. In src\config_default.h, change

/* Define to 1 if zlib is available */
/* #define COIN_HAS_ZLIB */

to

/* Define to 1 if zlib is available */
#define COIN_HAS_ZLIB 1

Don't forget to tell Visual Studio where it should find the zlib library!

Maintenance

As source files are added to (or deleted from) a COIN-OR Project, the Visual Studio project files must be updated by hand. There is no automatic way that we are aware of to keep the VS project files in sync with the source files in a COIN-OR project. If Visual Studio complains that a source file is missing when building a project, the file may have been recently removed from the project without a matching update to the VS project file. Most COIN-OR developers work on Unix systems; this happens. Similarly, a large number of error messages about missing symbols often indicates that a file has been added to the project but not to the VS project file. If you run across this, please let us know. The self-help fix is to simply add or remove the offending source file from the relevant VS project file.


Last modified 11 months ago Last modified on Aug 5, 2016 11:28:51 AM