Configurations
This is the help section to setup the Extension options.
Because each solution might need different extra parameters and different needs, the parser options with the extra parameters are stored in a file called StructLayoutSettings.json next to the solution.
The options page can be opened from:
Remember to use the Save button to apply your changes.
The first thing to consider is what layout extraction tool to use. This can be changed using the Extraction Tool dropdown:
This option will use a Clang Libtooling application. This will basically parse the code using a Clang compiler and extracting the layout data from the Clang AST (Abstract Syntax Tree). This means that the code must fully compile in Clang.
The options contain the following properties:
| Property | Description | Macros |
|---|---|---|
| Automatic Extraction | If true, it will try to extract from the current solution the architecture, include paths, preprocessor definitions... | No |
| Extra Preprocessor Defintions | Additional preprocessor definitions on top of the auto extracted form the project configuration. | Yes |
| Extra Include Dirs | Additional include directories on top of the auto extracted form the project configuration. | Yes |
| Extra Force Includes | Additional files to force include on top of the auto extracted form the project configuration. | Yes |
| Extra Parser Args | Additional command line arguments passed in to the clang parser. | Yes |
| Enable Warnings | If true, the clang parser will output the warnings found. | No |
| Parser Output Folder | The folder where the layout parser will generate the parsing results. Defaults to *$(ExtensionInstallationDir)Generated*. | Yes |
The additional include directories, force includes and preprocessor definitions can be typed in following the same format as the Visual Studio properties (; separated). Example:
includePathA;${SolutionDir}Folder/;${ProjectDir}...
The extra arguments will be appended at the end. Example:
-ftime-trace -I${SolutionDir}Folder/
⚠️ If the project is using PCHs, due to the fact that most of the struct definitions are in header files, the precompiled headers might need to be forced included.
⚠️ Structs within inline files (.inl) might not work due their nature. Being usually part of another header file, the inline file itself may lack dependency information.
⚠️ Some big projects use Unity builds or similar. This might lead to ill-formed dependency trees in some files, leading to parsing errors when attempting to parse a single unit.
For Visual Studio Projects the Automatic Extraction extracts:
- Active Configuration: x64/x86, C++ standard version, Working Directory...
- Active Project Properties: VC++ Directories -> Include Directories
- Active Project Properties: VC++ Directories -> Exclude Directories
- Active Project Properties: C/C++ -> Language -> C++ Language Standard
- Active Project Properties: C/C++ -> General -> Additional Include Directories
- Active Project Properties: C/C++ -> Preprocessor -> Preprocessor Definitions
- Active Project Properties: Advanced -> Forced Include File
- Active Project Properties: NMake -> Additional Include Directories
- Active Project Properties: NMake -> Additional Force Includes
- Active Project Properties: NMake -> Additional Preprocessor Definitions
- Active File Properties: C/C++ -> General -> Additional Include Directories
- Active File Properties: C/C++ -> Preprocessor -> Preprocessor Definitions
- Active File Properties: Advanced -> Forced Include File
There is a basic Visual Studio solution for testing at TestProjects/Regular
Unreal engine projects and build modules are handled natively if the automatic extraction is enabled allowing the find all relevant context from the build module.
More information about Unreal Engine 4 setup and issues here.
When dealing with CMake projects within Visual Studio add the following CMake flag:
CMAKE_EXPORT_COMPILE_COMMANDS / -DCMAKE_EXPORT_COMPILE_COMMANDS=1
The Extension needs to be able to find those compile commands, it will try to figure out its location automatically, but it can also be set explicitly in the options window.
The visual studio default configuration is the following:
Automatic Extraction: Yes
CMake Commands File: $(SolutionDir)out\build\$(Configuration)\compile_commands.json
You can find it also here.
Whenever a file is queried, the app will parse the compile commands list trying to find the best candidate file to extract the parameters from. Cpp files should just pick the same translation unit commands, but header files will try to match a similar file in the same directory or with the same name.
This is an assumption that should work for most of the use cases but it is not guarantee. If anyone has a better solution I would love to hear about it.
There is a basic CMake project for testing at TestProjects/CMake
This tool takes advantage to the fact that the pdb (program database) will most likely contain all the layout information for all user defined types.
| Property | Description | Macros |
|---|---|---|
| Automatic Extraction | If true, it will try to extract the pdb location from the current project configuration | No |
| PDB Location | This will specify where to find the pdb file to query. If empty if will default to: |
Yes |
⚠️ The PDB must contain the user defined type information. This means that the project needs to be set so the debug information is present in the pdb and not in the object files. Still, some structures might not be present.
⚠️ The PDB need to be up to date, this means that code must be built before performing any query.
⚠️ The PDBs line location does not provide full start/end span. This means that queries to the actual extractor must happen at the first line of the type definition. The extension will try to use the internal Visual Studio Code model information to automatically get the first line, but this might fail if intellisense is disabled.
⚠️ When dealing with Virtual inheritance there were some assumptions that had to be made in order to display the correct final type layout. There might be some inconsistencies in those.
Some fields accept macros in the form $(MACRO). The valid macros will depend on the nature of the solution, check below for allowed macros.
When dealing with Visual Studio projects all the MSBuild macros are available.
When dealing with UE4 projects you also have the following extra macros available:
| Name | Description |
|---|---|
| UE4ModuleName | Fetches the Name of the module that contains the Active File. This is done by moving up folders until finding a folder with a matching .Build.cs. This assumption might be wrong, please feel free to add an issue if there is a better way to detect this. |
Due to the fact that the project does not have an explicit VS project, the MSBuild macros can't be queried, still a small subset has been implemented:
| Name | Description |
|---|---|
| SolutionDir | Opened folder path |
| Configuration | The name of the active configuration |
This custom extra macros can be used by any configuration mode:
| Name | Description |
|---|---|
| ExtensionInstallationDir | Folder where this extension got installed in the local machine |