SciTools Understand Flavor for Structure 101g

Transcription

1 SciTools Understand Flavor for Structure 101g By Marcio Marchini ) 2014/10/10 1) WHAT IS THE UNDERSTAND FLAVOR FOR STRUCTURE101G? 1 2) WHY VARIOUS FLAVORS, AND NOT JUST ONE? 1 3) USING COM.SGLEBS.UNDERSTAND.* 2 3.1) CONFIGURE UNDERSTAND (32- BIT) 2 3.2) CREATE THE UNDERSTAND PROJECT 2 PROJECT NAME: 2 LANGUAGE (C/C++): 3 ADD THE SOURCE DIRECTORIES: 3 CONFIGURE MORE SETTINGS 5 EXAMPLE OF EXTRA CONFIG: 6 LET UNDERSTAND ANALYZE 6 3.3) LOAD THE UDB INTO STRUCTURE 101G WITH THE PLUGIN 7 FLAVOR SELECTION 8 UDB SELECTION 8 MODEL LOADED INTO STRUCTURE 101G 9 4) RUNNING ANY FLAVOR FROM THE CONSOLE 10 5) TIPS AND TROUBLESHOOTING ) MERGING CPP AND H FILE PAIRS ) FAILURE TO CONVERT / RUN THE FLAVOR 12 1) What is the Understand Flavor for Structure101g? This is a sort of a plugin for Structure 101g (called a flavor). It allows you to analyze projects in various programming languages by analyzing the Understand UDB files using Structure 101g. 2) Why Various Flavors, and Not Just One? Understand is not uniform in the way it models different entities and relationships in languages. This means that we need to have custom parameters for each language. This can be accomplished with different metadata.xml and runner.xml files in the flavor (you don t need to know about these). This allows for optimal parsing and modeling for each programming language.

2 3) Using com.sglebs.understand.* The steps described here apply equally to all understand flavors. 3.1) Configure Understand In order to run this plugin, you will need a valid Understand license from Make sure to install Understand 2.6 build 598 or above, and add Understand's bin directory to the PATH, so that its DLLs required by our flavor can be loaded at runtime. This is how to do it, when you install Understand: NOTE: Make sure the version of Understand used to create the.udb file is the exact same version/build- number as the version of the Understand udbapi.dll that is picked up from your PATH environment variable. You may need to use the Understand GUI app to upgrade an older UDB to the version in the PATH. NOTE: if you install Understand 64- bit in the PATH, make sure to run Structure 101g 64- bit (with a 64- bit Java). If you install Understand 32- bit in the PATH, make sure to run Structure 101g 32- bit (with a 32- bit Java). The two architecture modes cannot be mixed. See Failure to Convert / Run the Flavor for details. 3.2) Create the Understand Project After launching Understand, use File- >New- >Project, and fill in the fields as shown below. We will use C++ as an example (com.sglebs.understand.c++ flavor). Project Name:

3 Language (C/C++): Add The Source Directories:

4 The tool will show its progress: And eventually it will present a Dialog with the selected folders:

5 Configure More Settings If you need to make extra tweaks to the project, make sure to select this non- default radio button at the end of the wizard: This will allow us to configure some more options.

6 Example of Extra Config: Let Understand Analyze Now you can click OK and confirm when Understand asks to Analyze your files (if you changed the config options): You should get a dialog showing progress, until it finishes:

7 3.3) Load the UDB into Structure 101g with the Plugin Load Structure 101g and choose File- >New, then select our plugin (flavor):

8 Flavor Selection Click Next and make sure to point at the UDB file you created (C:\temp\FlightGear udb in our case): UDB Selection Note that the GUI allows you to tweak some other values: Files to keep: leave the default value.* until you become an advanced user. This is a regex that filters which files you really want to capture from the UDB file. It may be useful to tweak this

9 parameter to filter out library files. For example, if all interesting files are under a folder called MyProject, you can use MyProject as the regex. Dependencies to keep: leave the default value.* until you become an advanced user. This is a regex that filters what kind of dependencies you really want to capture from the UDB file. The types of dependencies are listed in metadata.xml of this flavor. Some values are: includes, extends, hasparam, etc. So, for example, if you just want to capture the dependencies of include files in your C++ project, you want to use the value includes. If you want to capture includes and also subclass relationships, you want to use includes extends. Use any regular expression to filter the possible values that you want to filter in. Entities to keep: leave the default value.* until you become an advanced user. This is a regex that filters what kind of entities you really want to capture from the UDB file. The types of entities are listed in metadata.xml of this flavor. So, for example, if you just want to capture the dependencies of include files in your C++ project, you want to capture just the file entities, and therefore you want to use the value file. Entities like classes, structs etc will be discarded in this case (producing a more compact DSM). Use any regular expression to filter the possible values that you want to filter in. After it processes the UDB file, you should get your model loaded, like below: Model Loaded Into Structure 101g

10 You can now analyze your system using Structure 101g s great features. 4) Running any flavor from the console Each flavor directory comes with a copy of the Udb2Structure101g.exe file. If you run it without parameters, you will get something like this: We highly recommend that you use the GUI wizard and use the little Copy command line link at the bottom/right of the Dialog. It will copy to the clipboard the full command-line used by the wizard behind the scenes. For instance, here's an example of what we used to run it on the FlightGear C++ source files: C:\Users\marcio\structure101g\flavors\com.sglebs.understand.c++_1.0.8 /Udb2Structure101g.exe -in ""C:\temp\FlightGear udb"" - namespacemode none -namespacesacrossfiles true -out "C:\Users\marcio\AppData\Local\Temp\s101g_ tmp" - serial "C:\Users\marcio\structure101g\flavors\com.sglebs.understand.c++_1.0. 8/udb2101g.lic" -keepfiles.* -keepdep.* -keepent ".*" - livetypesquery "type ~Unknown ~Local ~Unresolved" -subclassrelation base -importrelation import -flavor com.sglebs.understand.c++ - moduletypes file -order file Try this approach different ways until you become familiar with the command-line options. Then you can invoke the executable on your own customizing the parameters as you want. Note that the serial value can be either the serial/license itself or a valid text file path containing the actual serial/license value 1. This is a key (serial) that you must obtain from us so you can run our converter on your PC. It is tied to your specific machine, unless we provided you with a TRIAL. Therefore, if the converter fails to run we ask that you send us your Machine ID. To obtain your 1 You can have multiple lines in the file, with license values to use. This is useful in cases you have the Machine ID change depending on your configuration. In this case, use multiple serial values in the file.

11 Machine ID, run this from the console: Udb2Structure101g print This should print your machine. You should get an output similar to this: Machne ID: Invalid '-in' parameter - no index.xml found in inout dir passed (.) 5) Tips and Troubleshooting 5.1) Merging CPP and H file pairs Most of the time, H files and CPP files are used in pairs, and the dependencies can become a bit awkward because you have two separate entities in the Structure 101 GUI. In these cases, you may want to use Structure 101 s Model- >Transformations, and group pairs of H and CPP files together as a single entity. The example below creates a virtual folder with both files: Note that files such as foo.h and foo.cpp will be put together under a (new logic) folder called foo: foo/foo.h and foo/foo.cpp. This comes in handy when analyzing some C++ systems.

12 5.2) Failure to Convert / Run the Flavor In some cases the flavor may fail to run. In these cases you will get an error dialog like this: If you open the log file shown, you should find the reason. Example: [Err] Error during conversion: 3 The possible errors and their causes are: 5: The flavor could not open the UDB file. Please make sure your local copy of Understand, in the PATH, can load this file without problems (details below). In most cases this error happens when a UDB file created with an older Understand version is being loaded, without upgrading the file first using Understand itself (our flavor cannot do this automatic conversion). Another case is when you don t have enough floating licenses for Understand (running the conversion consumes 1 Understand license). In order to make sure you can run this flavor, do this: o Open a command prompt ( DOS ) o Execute: und db yourdbfile.db o Make sure it can load the file without errors and without asking to re- analyze sources. If it needs to reanalyze/rebuild/reparse, our flavor will fail. o The complete set of possible errors is: DBAlreadyOpen DBCorrupt DBOldVersion DBUnknownVersion DBUnableOpen - only one database may be open at once - bad database file - database needs to be rebuilt - database needs to be rebuilt - database is unreadable or does not exist

13 o NoApiLicense - Understand license required 4: The flavor could not find the Understand DLLs. Are you sure Understand is in the PATH for the user running the process that is performing the conversion? 3: Corrupt input. There is something wrong with the input UDB file. Check its file size. If it is too small (just a few KB), there is a chance that the UDB was not populated by Understand. Load it in Understand and Project - > Analyze All Files 2: Licensing error. You need an updated udb2101g.lic file in the flavors dir, customized for your Machine ID. 1: An Unknown error has happened. Please report the issue to us.