Columbus/CAN

Available at FrontEndArt
Platform: Windows

Setup Notes

Your Windows machine should be set up to do command line c++ compiling. You can test this by trying to compile a C++ program by entering 'cl myprogram.cpp' on the command line. If the system doesn't recognize the cl command, then you should run the vcvars32 bat file, which is located in the Visual C++ bin directory. On the computer this note was typed on it was located in 'C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\bin'. For those of you not familiar with bat files, on the command prompt, just cd to that directory, type 'vcvars32' and press enter.

The installation instructions mention that you can run the 'runme.bat' file to setup the CANPP.ini file. 'runme.bat' will locate include directories on your system and update the CANPP.ini file with the locations. When extracting source files I found I was getting an enormous amount of errors. Removing the include statements between the <include_path> tags in the CANPP.ini file fixed this problem. I suspect that Columbus/CAN was finding the include directories, but was unable to parse their contents correctly, resulting in too many errors. I don't recommend running the 'runme.bat' file. See the following section for more information about preprocessing.

Usage Notes

I found that Columbus/CAN produced better results than Cppx, but there are limitations. Columbus does not give you the ability to cherry pick only the elements in your code that you want to see. You can filter out structs and unions, or entire classes, but not an individual function inside a class. Columbus uses its own schema for C/C++ extraction.

Exporting to HTML is the fastest way to examine the results of an extraction. The HTML page organizes the data, which allows you to quickly check if the extraction provided the expected information.

For exporting to RSF, the Rigi documentation recommends that unstructured RSF be created for use with Rigiedit. You should generate the Columbus domain files if they are not already in the Rigi domain directory.

To have functions in your source code appear in the extractor output you may need to select 'namespace members' in the filtering options dialog.

The user manual suggests that preprocessing the C++ file(s) with an external preprocessor may produce better results, though my results were no better when I did this. I used CANPP, the internal Columbus preprocessor, and it worked well for me. On the Project menu, go to Settings and click the Preprocessor tab. You can select which preprocessor to use and what switches are in the command line. I found the default switches to be fine. If you choose to do external preprocessing, see notes below for more information.

A significant problem I had with extracting was that a lot of nodes were created from the library functions. There were also a lot of errors in parsing the library functions, possibly due to changes between the Visual Studio .NET 2003 release and the Visual Studio 6.0 release (Columbus/CAN was developed in the 6.0 era). Errors aside, I was most interested in seeing the operations and attributes that I created in my source code, and I was not particularly interested in the string, io, and other standard library stuff I used. I found that you can trick the system by using the CANPP preprocessor and removing the include path information from the CANPP.ini file in the Columbus install directory. If the 'runme.bat' file was not run after installation you may not need to do this, but if it was, just remove the <include_path> and </include_path> tags and all of the paths listed in between them. When you extract using CANPP it will look in the CANPP.ini file and not find any include paths. Columbus will display 'include error' messages, but it will extract the rest of the information. The result contains just the elements that the programmer created without the clutter of library operations. If you want the library operations, you can select the Microsoft Visual C++ preprocessor under Project Settings. I found the extraction done using the MS preprocessor and the CANPP preprocessor to be virtually identical when the CANPP.ini file has the include paths.

To preprocess outside of Columbus/CAN on the command line use this command (MS compiler):
cl /P /C myfile.cpp
This will generate a file with a .i extension that you can use in Columbus.

To perform external preprocessing on a Visual C++ project, open the project in Visual C++ (these steps refer to Visual Studio .NET 2003) go to Project menu, select Properties, choose "Release" or "Active release" for configuration, click the C++ folder, select "Command line" and enter /P in additional options, click OK. On the toolbar area at the top select "Release" and then rebuild the project. You should get a linking error, which is expected. Look for the file(s) with a .i extension in your project directory. The .i files should go in the 'Other files' folder in a Columbus project.