Documentation for the M3 Model

[linuswagner]

It would be helpful to have the M3 model documented:

• which relations are there?
• what can they be used for?
• example

Reason: To benefit from the level of abstraction provided by the M3, it needs to be understandable. Discovering what the M3 captures might lead to misunderstandings, missed data that is contained in the M3, and too much focus on understanding inner workings rather than to work on the abstraction itself.

[jurgenvinju]

To give this a start let's collect the information here and then move it to the docs of the clair project:

generic M3

• see https://www.rascal-mpl.org/docs/Library/analysis/m3/Core/, but these are most relevant:
  • rel[loc name, loc src] declarations = {}, // maps declarations to where they are declared. contains any kind of data or type or code declaration (classes, fields, methods, variables, etc. etc.)
  • set[loc] implicitDeclarations = {}, // some languages provide builtin implicit declarations, e.g. |java+class:///java/lang/Object| may not have a source location but still exist.
  • rel[loc from, loc to] containment = {}, // what inner declaration (to) is logically contained in what outer declaration (from) (not necessarily physically, but usually also)

C/C++ specific M3

• rel[loc base, loc derived] extends = {}, -- which class extends which other class
• rel[loc caller, loc callee] methodInvocations = {}, -- from caller id to callee id (usually a function, or virtual method). Calls to constructors also end up here as calls to new:///.... See also methodOverrides
• rel[loc field, loc accesser] fieldAccess = {},
• rel[loc caller, loc typeName] typeDependency = {},
• rel[loc base, loc override] methodOverrides = {}, -- for every new call the code (constructor, function, template) that the new invokes, and for every (virtual) method that is implemented or overridden, by whom. This is a one-to-many relation.
• rel[loc file, loc macro] macroExpansions = {}, -- explains where in the input file which macro was expanded
• rel[loc macro, loc src] macroDefinitions = {}, -- a subset of declarations focuses only on macros. perhaps should be folded into declarations for simplicity's sake.
• rel[loc directive, loc occurrence] includeDirectives = {}, -- TODO?
• rel[loc directive, loc occurrence] inactiveIncludes = {}, -- TODO?
• rel[loc directive, loc resolved] includeResolution = {}, -- maps #include instances to the file they were resolved to. after merging M3 models, this can be become a one-to-many relation if the include path was different when extracting from different compilation units.
• rel[loc decl, TypeSymbol typ] declaredType = {}, -- TODO?
• rel[loc decl, loc visiblity] memberAccessModifiers = {}, -- TODO? how is this different from modifiers in Core?
• rel[loc decl, loc src] functionDefinitions = {}, -- TODO? why is this different from declarations in Core?
• rel[loc decl, loc src] cFunctionsToNoArgs = {}, -- TODO?
• rel[loc decl, loc impl] declarationToDefinition = {}, -- TODO?
• rel[loc directive, loc file] unresolvedIncludes = {}, -- reports which #include's where not resolved for easy diagnostics and assessing the impact on the accuracy of the rest of the model.
• list[loc] comments = [], -- lists where all the comments are
• rel[loc includer, loc includee] requires = {}, -- TODO ?
• rel[loc provider, loc providee] provides = {}, -- TODO ?
• rel[loc decl, loc file] partOf = {}, -- TODO?
• rel[loc caller, loc callee] callGraph = {} -- an initial call graph links caller (functions, methods, constructors, static blocks) to callee (functions, methods, constructors, virtual methods, methods). Make sure to complete with methodOverrides. This is called methodInvocation in the Java M3 model, but Java only has methods and C/C++ also has other things that can be called.

[jurgenvinju]

@rodinaarssen if you have some time, could you help with these TODO's?