==========================
MS Visual Studio back-ends
==========================

.. contents:: Table of contents

-----------------------------------------
Why we need other than GCC-XML back-ends?
-----------------------------------------

It is not a secret, that Windows is not a native environment for GCC. There are 
cases, that it cant compile the code, "produced" for other compilers. On Windows, 
if you want to use `GCC-XML`_, you should treat it as another compiler and adopt 
your source code. Sometimes, changing the source code is not an option and different
solution is needed.

--------
The idea
--------

The idea is the same as with `GCC-XML`_ - don't write custom C++ parser, but use
the compiler to extract the information.

During the build process, MS Visual Studio generates few files, which contain 
source code "description":

* .pdb file. A "program database" file holds debugging information about your 
  program. It is generated automaticly during "Debug" builds.

* .bsc file. A "browse source code" file is a comprehensive database that contains 
  information about a program's symbols, including symbol references, function 
  calltrees, and definition tables. .bsc file is not generated by default, so 
  you will have to turn-on this option.

I guess, you will be surprised how much information it is possible to extract.

Microsoft provides API for working with the files:

* `DIA SDK`_ - Debug Interface Access Software Development Kit reads and gives
  more or less convenient access to the information stored in the .pdb files. 
  `DIA SDK`_ is an integral part of MS Visual Studio.

  `DIA SDK`_ exposes its functionality via "COM" technology. `pygccxml`_ uses 
  `comtypes package`_ to work with the API. 

* `Browse Source Code Toolkit`_ comes with C API. In order to read .bsc files you
  have to `install the toolkit`_. 

  `pygccxml`_ uses "ctypes" module, from the Python standard library.

Both API's comes with documentation and examples. 

`pygccxml`_ is going to introduce another back-end based on these tools. Each of 
these tools doesn't tell the "whole story" about your source code, but if we 
merge the information, extracted from the files, you can get almost the complete
picture.


-------------------
The back-end status
-------------------

The short version
-----------------

The back-end has "alpha" state.

The long version
----------------

`pygccxml`_ MSVC back-end will consist from few packages:

* ``pdb`` package reads the declaration tree from the .pdb file. This package is 
  almost complete. I still have to resolve few problems and your help is welcome:

  * add support for bit fields - should not be a problem

  * function exception specification - this information is missing in the file

  * a declaration location within source code - from the DIA API I understand the 
    information is there and should be available, but for some reason I can access 
    it.

  * there is some problem with extracting the exact integral type, used in the 
    source code - for example I have a problem to decide whether "long long int" 
    or "long int" is used within the code. I believe, it should be possible to 
    partially solve this problem.

  * unit tests - `pygccxml`_ comes with impressive amount of unit tests. Today 
    only some of them support pdb backend.

  * performance - the backend is very slow right now, but this is "by design" and 
    I believe it is possible to improve it.

* ``bsc`` package is a Python wrapper for `BSC Toolkit`_. I am almost sure, it is 
  not possible to create "declarations tree" from the .bsc file. So this package
  will be used to complete the information, extracted from the .pdb files.

* ``msvc`` package will be the top level package that will provide a convinient 
  access to the both sub-packages and provide "merge" functionality. As you can 
  guess this package doesn't exist.


.. _`DIA SDK`: http://msdn.microsoft.com/en-us/library/x93ctkx8.aspx
.. _`Browse Source Code Toolkit` : http://www.microsoft.com/downloads/details.aspx?FamilyId=621AE185-1C2A-4D6B-8146-183D66FE709D&displaylang=en
.. _`BSC Toolkit`: http://www.microsoft.com/downloads/details.aspx?FamilyId=621AE185-1C2A-4D6B-8146-183D66FE709D&displaylang=en
.. _`pygccxml`: ./../pygccxml.html
.. _`GCC-XML`: http://www.gccxml.org
.. _`comtypes package` : http://starship.python.net/crew/theller/comtypes/
.. _`install the toolkit` : http://www.microsoft.com/downloads/details.aspx?FamilyId=621AE185-1C2A-4D6B-8146-183D66FE709D&displaylang=en
