[pygccxml-commit] SF.net SVN: pygccxml: [1365]
Brought to you by:
mbaas,
roman_yakovenko
Menu
▾
▴
[pygccxml-commit] SF.net SVN: pygccxml: [1365]
|
From: <rom...@us...> - 2008-07-02 11:28:41
|
Revision: 1365
http://pygccxml.svn.sourceforge.net/pygccxml/?rev=1365&view=rev
Author: roman_yakovenko
Date: 2008-07-02 04:28:47 -0700 (Wed, 02 Jul 2008)
Log Message:
-----------
update docs
Modified Paths:
--------------
pygccxml_dev/docs/msvc/msvc.rest
website/site_creator/main.py
Modified: pygccxml_dev/docs/msvc/msvc.rest
===================================================================
--- pygccxml_dev/docs/msvc/msvc.rest 2008-07-01 16:55:48 UTC (rev 1364)
+++ pygccxml_dev/docs/msvc/msvc.rest 2008-07-02 11:28:47 UTC (rev 1365)
@@ -1,12 +1,12 @@
-=========================
-MS Visual Studio backends
-=========================
+==========================
+MS Visual Studio back-ends
+==========================
.. contents:: Table of contents
-----------------------------------------
-Why we need other than GCC-XML backends?
-----------------------------------------
+-----------------------------------------
+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,
@@ -14,75 +14,97 @@
your source code. Sometimes, changing the source code is not an option and different
solution is needed.
-Recently, I started to work on another back-end for `pygccxml`_, based on free tools,
-available and freely redistributable with MS Visual Studio:
+--------
+The idea
+--------
-* PDB - program database. A .pdb files hold debugging information about your
- program. In other words, it contains information about every type and function
- you use.
-* BSC - browse source code. A .bsc file is a comprehensive database that contains
- information about a program's symbols, including symbol references,
- function calltrees, and definition tables.
+The idea is the same as with `GCC-XML`_ - don't write custom C++ parser, but use
+the compiler to extract the information.
-Both .pdb and .bsc files contain valuable information about your source code.
-I guess, you will be surprised how much information it is possible to extract
-from them.
+During the build process, MS Visual Studio generates few files, which contain
+source code "description":
-----------------------------
-How it works?
-----------------------------
+* .pdb file. A "program database" file holds debugging information about your
+ program. It is generated automaticly during "Debug" builds.
-Microsoft provides API for extracting information from the files:
+* .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.
-* `DIA SDK`_ - Debug Interface Access Software Development Kit is able to read and
- provide more-or-less convenient access to the information stored in .pdb files.
- DIA SDK exposes it functionality via "COM" technology. `pygccxml`_ uses "comtypes"
- project to work with the API.
+I guess, you will be surprised how much information it is possible to extract.
-* `BSC Toolkit`_ comes with C API. `pygccxml`_ uses "ctypes" module, from the Python
- standard library.
+Microsoft provides API for working with the files:
-Both toolkits comes with their own terminolgy. Unless you want to help me, to
-develop this backend, you can fully ignore this fact. `pygccxml`_ bridges the
-domains and provide clear and consistent API.
+* `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.
-Both files, .pdb and .bsc, contain valuable information, but some pieces are
-presented in one file and not in other one. In near future `pygccxml`_ will be able
-to combine the information, extracted from the files. Hint: you can send me the
-patch :-).
+ `DIA SDK`_ exposes its functionality via "COM" technology. `pygccxml`_ uses
+ `comtypes package`_ to work with the API.
-------------------
-The backend status
-------------------
+* `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
-----------------
-I feel like this backend has "beta" state.
+The back-end has "alpha" state.
The long version
----------------
-`pygccxml`_ pdb backend is able to extract almost all declarations from the .pdb
-file. There are few exceptions and problems, that should be solved, before I will
-consider this backend as "production" ready:
+`pygccxml`_ MSVC back-end will consist from few packages:
-* 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 test - `pygccxml`_ comes with impressive amount of unit tests. Today only
- small amount of them supports pdb backend. This should be fixed.
-* performance - the backend is very slow right now, but this is "by design" and
- I believe it is possible to improve it.
+* ``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
Modified: website/site_creator/main.py
===================================================================
--- website/site_creator/main.py 2008-07-01 16:55:48 UTC (rev 1364)
+++ website/site_creator/main.py 2008-07-02 11:28:47 UTC (rev 1365)
@@ -82,7 +82,7 @@
curr_work_dir = os.path.abspath( os.curdir )
try:
- print 'file: ', destrination_file_name
+ print 'file:///' + destrination_file_name.replace( '\\', '/' )
os.chdir( dir_ )
tmpl = page_creator.Template( rest_file )
tmpl.write( destrination_file_name, encoding='utf-8', output='xhtml' )
@@ -105,4 +105,4 @@
c.copy_css()
c.create_html_files()
c.clean_www_dir()
- print 'done'
\ No newline at end of file
+ print 'done'
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
