C and C++ models can prove challenging to interpret if the file structure of the model does not reflect the structure that the project team are used to seeing (which might happen for a number of reasons). Structure101 Studio has a set of features for manipulating the generated file and folder names into the desired structure.
A common cause of the disparity between expected and actual model structure is manipulation of the source files during the build. For example, we have seen header files moved into a single folder (to simplify include arguments) and their original folder names concatenated with the file name (to guarantee a unique name). In this case both the folder path and the file name in the Structure101 model are not present on the file system.
In other cases the file system structure is not the preferred view of the code. For example, the use of a sophisticated developer IDE can introduce its own disconnect between the file system structure and the tree views presented in the IDE; Visual Studio’s Solution Explorer view, for example.
Structure101 has several features to manipulate the folder and file names of the generated model. These are listed below in the order they are applied during the loading of the Structure101 model.
The Name Map
The Name Map is a text file with each line having tab separated input and output file names. The mapping is applied when the file names are read from the model file. There is no wildcard matching. The input file name must be an exact match with the file name read from the model file. Both names must include the complete path from the root of the model separated by /.
The Name Map is useful for correcting fundamental discrepancies in the file and folder structure such as the rename and move of the header files described above.
Since each file must be mapped individually, scripting is often used to generate the Name Map.
Pre-transformations
Pre-transformations are rules with an input pattern and an output pattern to match and transform a file name. The patterns support wildcard matching. They are maintained via the Structure101 Studio project settings dialog and are persisted in the project file.
Pre-transformations can be used to create alternative views of the model such as the Microsoft Visual Studio Solution view.
Excludes
The Excludes are rules with an input pattern. A file that matches a rule is removed from the model. The patterns support wildcard matching. They are maintained via the Structure101 Studio project settings dialog and are persisted in the project file. Excluding a file also removes all of its contained nodes and their dependencies.
Excludes are useful for removing files that are creating ‘noise’ in the model. Auto-generated code often creates tangles, fat files and fat classes that can overwhelm problems in the code. It isn’t worth trying to correct structural issues in auto-generated code. Excluding the auto-generated files simplifies the model and removes the noise such that the focus can be on the issues that need to be addressed.
Merging
Merging is under the Views tab in Structure101 Studio. It uses rules to define that specific files should be merged into other files. The rules support wildcards.
Typically merging is used to combine .h and .c files in combination with the Linker model option to create a logical modular view of the code.
Transformations
Transformations behave in the same way as pre-transformations. However, their purpose is different. Transformations are a means to refactor the as-is model into an improved structure and are analogous to file level Actions in an Action Set. Transformations are persisted in the project file but are maintained via their own dialog (not via project properties).
Note that Excludes are applied BEFORE Transformations. So for a model with transformations the excludes pattern may not match the file structure visible in the LSM. (Note the LSM context menu “Exclude from project” will create an exclude using the correct ‘before transformations’ name)
Sharing the Rules across Structure101 Projects
The Pre-transformation, Excludes, Merging and Transformations all support the export of their rule set into a text file. The exported file can be imported into other Structure101 Studio projects.
Pre-transformation, Excludes, and Transformations all have Import and Export buttons on their settings dialog. The Merging view has Import and Export options under the Data button of the Merge Rules panel.
The Name Map is a separate file that can be used with multiple projects by renaming a copy. The file must be named the same as the project file with an extension of .namemap and must be in the same folder as the project file.
Leave a Reply