Rename global variable relations

This is the beginning of a series of commits that will try to unify the naming
conventions of the Fact Generator and Datalog code. It's important to undertake
this while the git history of the project is relatively short, so as to not hide
valuable history by doing it later.

At the same time, this set of changes will endeavor to make consistent,
reasonable trade-offs between identifier clarity and brevity, and document these
choices.

FactGenerator/include/predicates.inc

@@ -15,17 +15,17 @@ PREDICATE(basic_block, predecessor, _basicblock_preds)
 GROUP_END(basic_block)
 
 GROUP_BEGIN(global_var)
-PREDICATE(global_var, id, global_variable)
-PREDICATE(global_var, name, global_variable_has_name)
-PREDICATE(global_var, unmangl_name, global_variable_has_unmangled_name)
-PREDICATE(global_var, type, global_variable_has_type)
-PREDICATE(global_var, initializer, global_variable_has_initializer)
-PREDICATE(global_var, section, global_variable_in_section)
-PREDICATE(global_var, align, global_variable_aligned_to)
-PREDICATE(global_var, flag, global_variable_has_flag)
-PREDICATE(global_var, linkage, global_variable_has_linkage_type)
-PREDICATE(global_var, visibility, global_variable_has_visibility)
-PREDICATE(global_var, threadlocal_mode, global_variable_in_threadlocal_mode)
+PREDICATE(global_var, id, global_var)
+PREDICATE(global_var, name, global_var_name)
+PREDICATE(global_var, demangled_name, global_var_demangled_name)
+PREDICATE(global_var, type, global_var_type)
+PREDICATE(global_var, initializer, global_var_initializer)
+PREDICATE(global_var, section, global_var_in_section)
+PREDICATE(global_var, align, global_var_aligned_to)
+PREDICATE(global_var, flag, global_var_flag)
+PREDICATE(global_var, linkage, global_var_linkage_type)
+PREDICATE(global_var, visibility, global_var_visibility)
+PREDICATE(global_var, threadlocal_mode, global_var_threadlocal_mode)
 GROUP_END(global_var)
 
 GROUP_BEGIN(alias)
@@ -555,10 +555,10 @@ PREDICATE(function_constant, id, function_constant)
 PREDICATE(function_constant, name, function_constant_fn_name)
 GROUP_END(function_constant)
 
-GROUP_BEGIN(global_variable_constant)
-PREDICATE(global_variable_constant, id, global_variable_constant)
-PREDICATE(global_variable_constant, name, global_variable_constant_name)
-GROUP_END(global_variable_constant)
+GROUP_BEGIN(global_var_constant)
+PREDICATE(global_var_constant, id, global_var_constant)
+PREDICATE(global_var_constant, name, global_var_constant_name)
+GROUP_END(global_var_constant)
 
 GROUP_BEGIN(constant_array)
 PREDICATE(constant_array, id, constant_array)

FactGenerator/src/constants.cpp

@@ -68,8 +68,8 @@ auto FactGenerator::writeConstant(const llvm::Constant &c)
     const auto &global_var = cast<GlobalVariable>(c);
     const std::string varname = "@" + global_var.getName().str();
 
-    writeFact(pred::global_variable_constant::id, id);
-    writeFact(pred::global_variable_constant::name, id, varname);
+    writeFact(pred::global_var_constant::id, id);
+    writeFact(pred::global_var_constant::name, id, varname);
   } else if (isa<ConstantExpr>(c)) {
     writeConstantExpr(cast<ConstantExpr>(c), id);
   } else if (isa<ConstantArray>(c)) {

FactGenerator/src/globals.cpp

@@ -69,8 +69,8 @@ void FactGenerator::writeGlobalVar(
   refmode_t varType = recordType(gv.getType()->getElementType());
   refmode_t thrLocMode = refmode(gv.getThreadLocalMode());
 
-  // Record unmangled variable name
-  writeFact(pred::global_var::unmangl_name, id, demangle(gv.getName().data()));
+  // Record demangled variable name
+  writeFact(pred::global_var::demangled_name, id, demangle(gv.getName().data()));
 
   // Record external linkage
   if (!gv.hasInitializer() && gv.hasExternalLinkage())

datalog/export/debug-output-extended.dl

@@ -438,21 +438,21 @@
 .output global_allocation_by_name (compress=true)
 .output global_allocation_by_variable (compress=true)
 .output global_region (compress=true)
-.output global_variable (compress=true)
-.output global_variable_aligned_to (compress=true)
-.output global_variable_constant (compress=true)
-.output global_variable_constant_name (compress=true)
-.output global_variable_constant_reference (compress=true)
-.output global_variable_has_flag (compress=true)
-.output global_variable_has_initializer (compress=true)
-.output global_variable_has_linkage_type (compress=true)
-.output global_variable_has_name (compress=true)
-.output global_variable_has_type (compress=true)
-.output global_variable_has_unmangled_name (compress=true)
-.output global_variable_has_visibility (compress=true)
-.output global_variable_in_section (compress=true)
-.output global_variable_in_threadlocal_mode (compress=true)
-.output global_variable_is_constant (compress=true)
+.output global_var (compress=true)
+.output global_var_aligned_to (compress=true)
+.output global_var_constant (compress=true)
+.output global_var_constant_name (compress=true)
+.output global_var_constant_reference (compress=true)
+.output global_var_flag (compress=true)
+.output global_var_initializer (compress=true)
+.output global_var_linkage_type (compress=true)
+.output global_var_name (compress=true)
+.output global_var_type (compress=true)
+.output global_var_demangled_name (compress=true)
+.output global_var_visibility (compress=true)
+.output global_var_in_section (compress=true)
+.output global_var_in_threadlocal_mode (compress=true)
+.output global_var_is_constant (compress=true)
 .output half_type (compress=true)
 .output heap_alloc_function (compress=true)
 .output heap_allocation (compress=true)
@@ -685,7 +685,7 @@
 .output schema_invalid_alias (compress=true)
 .output schema_invalid_constant (compress=true)
 .output schema_invalid_function (compress=true)
-.output schema_invalid_global_variable (compress=true)
+.output schema_invalid_global_var (compress=true)
 .output schema_invalid_instruction (compress=true)
 .output schema_invalid_type (compress=true)
 .output schema_multiple_function_names (compress=true)

datalog/export/debug-output.dl

@@ -285,8 +285,8 @@
 .output global_allocation_by_name (compress=true)
 .output global_allocation_by_variable (compress=true)
 .output global_region (compress=true)
-.output global_variable_constant_reference (compress=true)
-.output global_variable_is_constant (compress=true)
+.output global_var_constant_reference (compress=true)
+.output global_var_is_constant (compress=true)
 .output half_type (compress=true)
 .output heap_alloc_function (compress=true)
 .output heap_allocation (compress=true)
@@ -424,7 +424,7 @@
 .output schema_invalid_alias (compress=true)
 .output schema_invalid_constant (compress=true)
 .output schema_invalid_function (compress=true)
-.output schema_invalid_global_variable (compress=true)
+.output schema_invalid_global_var (compress=true)
 .output schema_invalid_instruction (compress=true)
 .output schema_invalid_type (compress=true)
 .output schema_multiple_function_names (compress=true)

datalog/points-to/allocations-decl.dl

@@ -88,7 +88,7 @@ ptr_compatible_allocation(?alloc) :-
 // would change their contents
 ptr_compatible_allocation(?alloc) :-
    global_allocation_by_variable(?globalVar,?alloc),
-   ! global_variable_constant(?globalVar).
+   ! global_var_constant(?globalVar).
 
 //-------------------------------------
 // Additional pseudo-allocation types

datalog/points-to/allocations-globals.dl

@@ -9,8 +9,8 @@
 global_allocation(?alloc),
 global_allocation_by_variable(?gVar, ?alloc)
  :-
-   global_variable(?gVar),
-   global_variable_has_name(?gVar, ?name),
+   global_var(?gVar),
+   global_var_name(?gVar, ?name),
    ?alloc = cat("*global_alloc",?name).
 
 /// 2. Function Allocations
@@ -25,7 +25,7 @@ global_allocation_by_function(?func, ?alloc)
    ?alloc = cat("*global_alloc",?name).
 
 global_allocation_by_name(?globalName, ?alloc) :-
-   global_variable_has_name(?global, ?globalName),
+   global_var_name(?global, ?globalName),
    global_allocation_by_variable(?global, ?alloc).
 
 global_allocation_by_name(?globalName, ?alloc) :-
@@ -38,4 +38,4 @@ static_allocation_type(?alloc, ?type) :-
 
 static_allocation_type(?alloc, ?type) :-
    global_allocation_by_variable(?gVar, ?alloc),
-   global_variable_has_type(?gVar, ?type).
+   global_var_type(?gVar, ?type).

datalog/points-to/allocations-sizes.dl

@@ -14,7 +14,7 @@ array_allocation(?alloc) :-
 
 allocation_size(?globalAlloc, ?n) :-
   global_allocation_by_variable(?globalVar, ?globalAlloc),
-  global_variable_has_linkage_type(?globalVar, ?linkage),
+  global_var_linkage_type(?globalVar, ?linkage),
   ! external_linkage_type(?linkage),
   static_allocation_type(?globalAlloc, ?type),
   type_has_size(?type, ?n),
@@ -23,7 +23,7 @@ allocation_size(?globalAlloc, ?n) :-
 // The sizes of external globals may not match the size of their types.
 dynamically_sized_alloc(?alloc) :-
   external_linkage_type(?externalLinkage),
-  global_variable_has_linkage_type(?globalVar, ?externalLinkage),
+  global_var_linkage_type(?globalVar, ?externalLinkage),
   global_allocation_by_variable(?globalVar, ?alloc).
 
 //-----------------------

datalog/points-to/class-type.dl

@@ -61,12 +61,12 @@ class_type_name(?type, ?name) :-
 
 .decl class_type_typeinfo(?classType: ClassType, ?typeInfo: GlobalVariable)
 
-// Extract class name from unmangled type info name. The latter is of
+// Extract class name from demangled type info name. The latter is of
 // the form: typeinfo for CLASS-NAME
 .decl _typeinfo_class_name(?typeInfo: GlobalVariable, ?className: symbol)
 _typeinfo_class_name(?typeInfo, ?className) :-
    typeinfo(?typeInfo),
-   global_variable_has_unmangled_name(?typeInfo, ?tIName),
+   global_var_demangled_name(?typeInfo, ?tIName),
    contains("typeinfo for ", ?tIName),
    ?n = strlen(?tIName),
    ?className = substr(?tIName, 13, ?n - 13).
@@ -81,15 +81,15 @@ class_type_typeinfo(?classType, ?typeInfo) :-
    class_type_name(?classType, ?className),
    _typeinfo_by_class_name(?className, ?typeInfo).
 
-// Extract class name from unmangled vtable name. The latter is of the
+// Extract class name from demangled vtable name. The latter is of the
 // form: vtable for CLASS-NAME
 .decl _vtable_class_name(?vt: GlobalVariable, ?className: symbol)
 _vtable_class_name(?vt, ?className) :-
    vtable(?vt, _),
-   global_variable_has_unmangled_name(?vt, ?unmangledName),
-   contains("vtable for ", ?unmangledName),
-   ?n = strlen(?unmangledName),
-   ?className = substr(?unmangledName, 11, ?n - 11).
+   global_var_demangled_name(?vt, ?demangledName),
+   contains("vtable for ", ?demangledName),
+   ?n = strlen(?demangledName),
+   ?className = substr(?demangledName, 11, ?n - 11).
 
 .decl _vtable_by_class_name(?className: symbol, ?vt: GlobalVariable)
 _vtable_by_class_name(?className, ?vt) :-

datalog/points-to/constant-init.dl

@@ -3,11 +3,11 @@
 .decl initialized_by_constant(?alloc: Allocation, ?constant: Constant)
 
 initialized_by_constant(?baseAlloc, ?init) :-
-   global_variable_has_initializer(?var, ?init),
+   global_var_initializer(?var, ?init),
    global_allocation_by_variable(?var, ?baseAlloc).
 
 initialized_by_constant(?alloc, ?init) :-
-   global_variable_has_initializer(?var, ?init),
+   global_var_initializer(?var, ?init),
    global_allocation_by_variable(?var, ?baseAlloc),
    static_subobjects.alloc_subregion_at_array_index(?baseAlloc, 0, ?alloc).
 

datalog/points-to/constant-points-to.dl

@@ -21,8 +21,8 @@ constant_points_to(?constant, ?null) :-
 // allocation.
 
 constant_points_to(?constant, ?alloc) :-
-   global_variable_constant_name(?constant, ?name),
-   global_variable_has_name(?gVar, ?name),
+   global_var_constant_name(?constant, ?name),
+   global_var_name(?gVar, ?name),
    global_allocation_by_variable(?gVar, ?alloc).
 
 constant_points_to(?constant, ?alloc) :-

datalog/points-to/cplusplus-exceptions.dl

@@ -153,8 +153,8 @@ _type_info_by_alloc(?obj, ?excTypeInfo) :-
 typeinfo(?var),
    external_typeinfo(?var) :-
    external_linkage_type(?externalLinkage),
-   global_variable_has_linkage_type(?var, ?externalLinkage),
-   global_variable_has_name(?var, ?name),
+   global_var_linkage_type(?var, ?externalLinkage),
+   global_var_name(?var, ?name),
    substr(?name, 0, strlen("@_ZTI")) = "@_ZTI".
 
 .comp ThrowInstruction {

datalog/points-to/cplusplus.dl

@@ -8,7 +8,7 @@
 .decl cxx_new_function(?func: FunctionDecl)
 
 // Consider only functions with a single parameter of integer type, no
-// definition, and whose unmangled name contains the keyword `new`
+// definition, and whose demangled name contains the keyword `new`
 
 cxx_new_function(?func),
    heap_alloc_function(?func)

datalog/points-to/virtual-tables.dl

@@ -24,8 +24,8 @@ vtable(?vt, ?name) :-
 
 typeinfo_vtable(?vt, ?name) :-
    external_linkage_type(?externalLinkage),
-   global_variable_has_linkage_type(?vt, ?externalLinkage),
-   global_variable_has_name(?vt, ?name),
+   global_var_linkage_type(?vt, ?externalLinkage),
+   global_var_name(?vt, ?name),
    contains("class_type_info", ?name),
    contains("cxxabi", ?name).
 
@@ -51,7 +51,7 @@ typeinfo_vtable_multiple_inheritance(?vt, ?name) :-
 
 .decl constant_contains_vptr(?vt: VirtualTable, ?constant: Constant)
 constant_contains_vptr(?vt, ?constant) :-
-   global_variable_constant_name(?constant, ?name),
+   global_var_constant_name(?constant, ?name),
    vtable(?vt, ?name).
 
 constant_contains_vptr(?vt, ?outer) :-
@@ -74,7 +74,7 @@ typeinfo(?typeInfo),
 typeinfo_has_vtable(?typeInfo,?vt) :-
    constant_contains_vptr(?vt, ?initializer),
    typeinfo_vtable(?vt, _),
-   global_variable_has_initializer(?typeInfo, ?initializer).
+   global_var_initializer(?typeInfo, ?initializer).
 
 .decl typeinfo_baseclass(?typeInfo: GlobalVariable)
 typeinfo_baseclass(?typeInfo) :-
@@ -96,7 +96,7 @@ typeinfo_multiple_inheritance(?typeInfo) :-
 
 .decl _constant_contains_typeinfo(?typeInfo: GlobalVariable, ?constant:Constant)
 _constant_contains_typeinfo(?typeInfo, ?constant) :-
-   global_variable_constant_reference(?constant, ?typeInfo),
+   global_var_constant_reference(?constant, ?typeInfo),
    typeinfo(?typeInfo).
 
 _constant_contains_typeinfo(?typeinfo, ?outer) :-
@@ -105,8 +105,8 @@ _constant_contains_typeinfo(?typeinfo, ?outer) :-
 
 vtable(?vt, ?name),
 vtable_typeinfo(?vt,?typeinfo) :-
-   global_variable_has_name(?vt, ?name),
-   global_variable_has_initializer(?vt, ?initializer), // get array constant of vtable
+   global_var_name(?vt, ?name),
+   global_var_initializer(?vt, ?initializer), // get array constant of vtable
    constant_array_index(?initializer, 1, ?tic),    // type info is at index 1
    _constant_contains_typeinfo(?typeinfo, ?tic).
 
@@ -116,7 +116,7 @@ vtable_typeinfo(?vt,?typeinfo) :-
 .decl _typeinfo_contains_typeinfo(?outer: GlobalVariable, ?index:number, ?inner: GlobalVariable)
 _typeinfo_contains_typeinfo(?outer, ?index, ?inner) :-
    typeinfo(?outer),
-   global_variable_has_initializer(?outer, ?init),
+   global_var_initializer(?outer, ?init),
    constant_struct_index(?init, ?index, ?tic),
    _constant_contains_typeinfo(?inner, ?tic).
 
@@ -131,7 +131,7 @@ typeinfo_base_class(?typeinfo, 0, ?baseTypeinfo) :-
 typeinfo_base_class(?typeinfo, ?offset, ?baseTypeinfo) :-
    typeinfo_multiple_inheritance(?typeinfo),
    _typeinfo_contains_typeinfo(?typeinfo, ?index, ?baseTypeinfo),
-   global_variable_has_initializer(?typeinfo, ?init),
+   global_var_initializer(?typeinfo, ?init),
    constant_struct_index(?init, ?index + 1, ?constant),
    constant_to_int(?constant, ?offsetMask),
    ?offset = ?offsetMask / 256.
@@ -143,7 +143,7 @@ typeinfo_base_class(?typeinfo, ?offset, ?baseTypeinfo) :-
 
 vtable_function(?vt,?index,?func) :-
    vtable(?vt, _),
-   global_variable_has_initializer(?vt,?init),
+   global_var_initializer(?vt,?init),
    constant_array_index(?init, ?index, ?funcAsInteger),
    bitcast_constant_expression_from(?funcAsInteger, ?funcConstant),
    function_constant_fn_name(?funcConstant, ?funcName),

datalog/schema/constants.dl

@@ -37,7 +37,7 @@
 .decl fp_constant(c:FPConstant)
 .decl nullptr_constant(c:NullPtrConstant)
 .decl function_constant(c:FunctionConstant)
-.decl global_variable_constant(c:GlobalVariableConstant)
+.decl global_var_constant(c:GlobalVariableConstant)
 .decl constant_array(c:ConstantArray)
 .decl constant_struct(c:ConstantStruct)
 .decl constant_vector(c:ConstantVector)
@@ -52,7 +52,7 @@ constant(c) :-
    constant_expression(c)
  ; constant_array(c)
  ; constant_struct(c)
- ; global_variable_constant(c)
+ ; global_var_constant(c)
  ; integer_constant(c)
  ; fp_constant(c)
  ; nullptr_constant(c)
@@ -83,28 +83,28 @@ schema_invalid_constant(Constant, __FILE__, __LINE__) :-
 // Constant that references global variable
 //---------------------------------------------
 
-.decl global_variable_constant_name(c:GlobalVariableConstant, name:symbol)
-.decl global_variable_constant_reference(c:GlobalVariableConstant, gv:GlobalVariable)
+.decl global_var_constant_name(c:GlobalVariableConstant, name:symbol)
+.decl global_var_constant_reference(c:GlobalVariableConstant, gv:GlobalVariable)
 
-global_variable_constant_reference(C, GVar) :-
-   global_variable_constant_name(C, Name),
-   global_variable_has_name(GVar, Name).
+global_var_constant_reference(C, GVar) :-
+   global_var_constant_name(C, Name),
+   global_var_name(GVar, Name).
 
 schema_invalid_constant(Constant, __FILE__, __LINE__) :-
    schema_sanity(),
-   global_variable_constant(Constant),
-   !global_variable_constant_name(Constant, _).
+   global_var_constant(Constant),
+   !global_var_constant_name(Constant, _).
 
 schema_invalid_constant(Constant, __FILE__, __LINE__) :-
    schema_sanity(),
-   global_variable_constant(Constant),
-   !global_variable_constant_reference(Constant, _).
+   global_var_constant(Constant),
+   !global_var_constant_reference(Constant, _).
 
 schema_invalid_constant(Constant, __FILE__, __LINE__) :-
    schema_sanity(),
-   global_variable_constant(Constant),
-   global_variable_constant_reference(Constant, GVar),
-   global_variable_has_type(GVar, Type),
+   global_var_constant(Constant),
+   global_var_constant_reference(Constant, GVar),
+   global_var_type(GVar, Type),
    constant_has_type(Constant, PtrType),
    !pointer_type_has_component(PtrType, Type).
 

datalog/schema/global.dl

@@ -1,33 +1,33 @@
 // http://llvm.org/docs/LangRef.html#global-variables
 
 .type GlobalVariable <: symbol
-.decl global_variable(gv:GlobalVariable)
-.decl global_variable_has_type(gv:GlobalVariable, type:Type)
-.decl global_variable_has_name(gv:GlobalVariable, name:GlobalVarName)
-.decl global_variable_has_unmangled_name(gv:GlobalVariable, name:symbol)
-.decl global_variable_has_flag(gv:GlobalVariable, flag:Flag)
-.decl global_variable_has_linkage_type(gv:GlobalVariable, link:LinkageType)
-.decl global_variable_has_initializer(gv:GlobalVariable, init:Constant)
-.decl global_variable_has_visibility(gv:GlobalVariable, vis:Visibility)
-.decl global_variable_in_section(gv:GlobalVariable, sect:symbol)
-.decl global_variable_in_threadlocal_mode(gv:GlobalVariable, mode:ThreadLocalMode)
-.decl global_variable_aligned_to(gv:GlobalVariable, alignment:number)
+.decl global_var(gv:GlobalVariable)
+.decl global_var_type(gv:GlobalVariable, type:Type)
+.decl global_var_name(gv:GlobalVariable, name:GlobalVarName)
+.decl global_var_demangled_name(gv:GlobalVariable, name:symbol)
+.decl global_var_flag(gv:GlobalVariable, flag:Flag)
+.decl global_var_linkage_type(gv:GlobalVariable, link:LinkageType)
+.decl global_var_initializer(gv:GlobalVariable, init:Constant)
+.decl global_var_visibility(gv:GlobalVariable, vis:Visibility)
+.decl global_var_in_section(gv:GlobalVariable, sect:symbol)
+.decl global_var_threadlocal_mode(gv:GlobalVariable, mode:ThreadLocalMode)
+.decl global_var_aligned_to(gv:GlobalVariable, alignment:number)
 
-flag(Flag) :- global_variable_has_flag(_, Flag).
+flag(Flag) :- global_var_flag(_, Flag).
 
 
 // For constraints
-.decl schema_invalid_global_variable(gv:GlobalVariable, file:File, line:Line)
+.decl schema_invalid_global_var(gv:GlobalVariable, file:File, line:Line)
 
-schema_invalid_global_variable(GVar, __FILE__, __LINE__) :-
+schema_invalid_global_var(GVar, __FILE__, __LINE__) :-
    schema_sanity(),
-   global_variable(GVar),
-   !global_variable_has_visibility(GVar, _).
+   global_var(GVar),
+   !global_var_visibility(GVar, _).
 
-schema_invalid_global_variable(GVar, __FILE__, __LINE__) :-
+schema_invalid_global_var(GVar, __FILE__, __LINE__) :-
    schema_sanity(),
-   global_variable(GVar),
-   !global_variable_has_linkage_type(GVar, _).
+   global_var(GVar),
+   !global_var_linkage_type(GVar, _).
 
 
 //------------------------------------------------------------------------------
@@ -42,10 +42,10 @@ schema_invalid_global_variable(GVar, __FILE__, __LINE__) :-
 //
 //------------------------------------------------------------------------------
 
-.decl global_variable_is_constant(gv:GlobalVariable)
+.decl global_var_is_constant(gv:GlobalVariable)
 
-global_variable_is_constant(GVar) :-
-   global_variable_has_flag(GVar, "constant").
+global_var_is_constant(GVar) :-
+   global_var_flag(GVar, "constant").
 
 
 //------------------------------------------------------------------------------

datalog/symbol-lookup/resolve-function-calls.dl

@@ -34,9 +34,9 @@ constant_references_function(FC, Func) :-
 
 // Retrieve variable names from constants
 constant_references_variable(GC, GVar) :-
-  global_variable_constant(GC),
-  global_variable_constant_name(GC, Name),
-  global_variable_has_name(GVar, Name).
+  global_var_constant(GC),
+  global_var_constant_name(GC, Name),
+  global_var_name(GVar, Name).
 
 
 // A constant may be enclosed by a bitcast constant

doc/dev.rst

@@ -31,6 +31,39 @@ on Github. Worked example:
 After waiting for the CI build, manually edit the release as required and hit
 "publish".
 
+Naming Conventions
+******************
+
+Due to historical circumstance, cclyzer++ has many different naming conventions
+in use in the Datalog code. The conventions in this section are prescriptive,
+but only apply to new code.
+
+Abbreviations
+~~~~~~~~~~~~~
+
+Names must strike a balance between brevity and comprehensibility. This section
+enumerates abbreviations that are considered reasonable trade-offs in this
+space. This judgment is highly subjective, but must be made somehow.
+
+- ``asm``: Assembly
+- ``block``: LLVM basic block
+- ``const``: Constant
+- ``global_var``: Global variable
+- ``expr``: Expression
+- ``func``: Function
+- ``gep``: ``getelementptr``
+- ``instr``: Instruction
+- ``int``: Integer
+- ``ptr``: Pointer
+- ``var``: Variable
+- ``vec``: Vector
+
+Explicitly **not** further abbreviated:
+
+- ``array``
+- ``struct``
+- ``type``
+
 Performance Tuning
 ******************