GNATcheck Reference Manual

GNATcheck, The GNAT coding standard checker

GNATcheck

Version 26.0w

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being ‘GNU Free Documentation License’, with the Front-Cover Texts being ‘GNATcheck Reference Manual’, and with no Back-Cover Texts. A copy of the license is included in the section entitled ‘GNU Free Documentation License’.

• 1. Getting Started
  • 1.1. Example of GNATcheck Usage
• 2. Using GNATcheck
  • 2.1. General GNATcheck Switches
  • 2.2. The Check GPR Package
  • 2.3. Sources pre-processing
  • 2.4. LKQL Rule Files
  • 2.5. GNATcheck Rule Options
  • 2.6. Mapping GNATcheck Rules Onto Coding Standards
  • 2.7. GNATcheck Exit Codes
  • 2.8. Format of the Report File
  • 2.9. Rule Exemption
    • 2.9.1. Using pragma Annotate to control rule and instance exemption
    • 2.9.2. GNATcheck Annotations Rules
    • 2.9.3. Using comments to control rule and instance exemption
  • 2.10. Using GNATcheck as a Known Problem Detector
  • 2.11. Performance and Memory Usage
  • 2.12. Transition from ASIS-based GNATcheck
    • 2.12.1. Switches No Longer Supported
    • 2.12.2. The new rule instance system
    • 2.12.3. Rule Aliases No Longer Supported
    • 2.12.4. New Defaults For Recursive_Subprograms Rule
    • 2.12.5. Argument Sources Legality And Project Files
• 3. Predefined Rules
  • 3.1. Style-Related Rules
    • 3.1.1. Tasking
      • 3.1.1.1. Multiple_Entries_In_Protected_Definitions
      • 3.1.1.2. Volatile_Objects_Without_Address_Clauses
    • 3.1.2. Object Orientation
      • 3.1.2.1. Constructors
      • 3.1.2.2. Deep_Inheritance_Hierarchies
      • 3.1.2.3. Direct_Calls_To_Primitives
      • 3.1.2.4. Downward_View_Conversions
      • 3.1.2.5. No_Inherited_Classwide_Pre
      • 3.1.2.6. Specific_Parent_Type_Invariant
      • 3.1.2.7. Specific_Pre_Post
      • 3.1.2.8. Specific_Type_Invariants
      • 3.1.2.9. Too_Many_Parents
      • 3.1.2.10. Too_Many_Primitives
      • 3.1.2.11. Visible_Components
    • 3.1.3. Portability
      • 3.1.3.1. Bit_Records_Without_Layout_Definition
      • 3.1.3.2. Forbidden_Aspects
      • 3.1.3.3. Forbidden_Attributes
      • 3.1.3.4. Forbidden_Pragmas
      • 3.1.3.5. Implicit_SMALL_For_Fixed_Point_Types
      • 3.1.3.6. Incomplete_Representation_Specifications
      • 3.1.3.7. Membership_For_Validity
      • 3.1.3.8. No_Explicit_Real_Range
      • 3.1.3.9. No_Scalar_Storage_Order_Specified
      • 3.1.3.10. Predefined_Numeric_Types
      • 3.1.3.11. Printable_ASCII
      • 3.1.3.12. Separate_Numeric_Error_Handlers
    • 3.1.4. Program Structure
      • 3.1.4.1. Deep_Library_Hierarchy
      • 3.1.4.2. Deeply_Nested_Generics
      • 3.1.4.3. Deeply_Nested_Instantiations
      • 3.1.4.4. Local_Packages
      • 3.1.4.5. Maximum_Expression_Complexity
      • 3.1.4.6. Maximum_Lines
      • 3.1.4.7. Maximum_Subprogram_Lines
      • 3.1.4.8. Non_Visible_Exceptions
      • 3.1.4.9. One_Tagged_Type_Per_Package
      • 3.1.4.10. Outside_References_From_Subprograms
      • 3.1.4.11. Raising_External_Exceptions
      • 3.1.4.12. Same_Instantiations
      • 3.1.4.13. Too_Many_Generic_Dependencies
    • 3.1.5. Programming Practice
      • 3.1.5.1. Access_To_Local_Objects
      • 3.1.5.2. Actual_Parameters
      • 3.1.5.3. Ada05_Formal_Packages
      • 3.1.5.4. Ada_2022_In_Ghost_Code
      • 3.1.5.5. Address_Attribute_For_Non_Volatile_Objects
      • 3.1.5.6. Address_Specifications_For_Initialized_Objects
      • 3.1.5.7. Address_Specifications_For_Local_Objects
      • 3.1.5.8. Anonymous_Arrays
      • 3.1.5.9. Binary_Case_Statements
      • 3.1.5.10. Boolean_Negations
      • 3.1.5.11. Calls_In_Exception_Handlers
      • 3.1.5.12. Calls_Outside_Elaboration
      • 3.1.5.13. Concurrent_Interfaces
      • 3.1.5.14. Constant_Overlays
      • 3.1.5.15. Default_Values_For_Record_Components
      • 3.1.5.16. Deriving_From_Predefined_Type
      • 3.1.5.17. Direct_Equalities
      • 3.1.5.18. Duplicate_Branches
      • 3.1.5.19. Enumeration_Ranges_In_CASE_Statements
      • 3.1.5.20. Exception_Propagation_From_Callbacks
      • 3.1.5.21. Exception_Propagation_From_Export
      • 3.1.5.22. Exception_Propagation_From_Tasks
      • 3.1.5.23. Exceptions_As_Control_Flow
      • 3.1.5.24. EXIT_Statements_With_No_Loop_Name
      • 3.1.5.25. Exits_From_Conditional_Loops
      • 3.1.5.26. Final_Package
      • 3.1.5.27. Function_OUT_Parameters
      • 3.1.5.28. Global_Variables
      • 3.1.5.29. GOTO_Statements
      • 3.1.5.30. Improper_Returns
      • 3.1.5.31. Integer_Types_As_Enum
      • 3.1.5.32. Local_Instantiations
      • 3.1.5.33. Local_USE_Clauses
      • 3.1.5.34. Maximum_OUT_Parameters
      • 3.1.5.35. Maximum_Parameters
      • 3.1.5.36. Misplaced_Representation_Items
      • 3.1.5.37. Nested_Paths
      • 3.1.5.38. Nested_Subprograms
      • 3.1.5.39. No_Closing_Names
      • 3.1.5.40. No_Others_In_Exception_Handlers
      • 3.1.5.41. Non_Component_In_Barriers
      • 3.1.5.42. Non_Constant_Overlays
      • 3.1.5.43. Non_Short_Circuit_Operators
      • 3.1.5.44. Nonoverlay_Address_Specifications
      • 3.1.5.45. Not_Imported_Overlays
      • 3.1.5.46. Null_Paths
      • 3.1.5.47. Objects_Of_Anonymous_Types
      • 3.1.5.48. Operator_Renamings
      • 3.1.5.49. OTHERS_In_Aggregates
      • 3.1.5.50. OTHERS_In_CASE_Statements
      • 3.1.5.51. OTHERS_In_Exception_Handlers
      • 3.1.5.52. Outbound_Protected_Assignments
      • 3.1.5.53. Overly_Nested_Control_Structures
      • 3.1.5.54. Overly_Nested_Scopes
      • 3.1.5.55. Parameters_Aliasing
      • 3.1.5.56. POS_On_Enumeration_Types
      • 3.1.5.57. Positional_Actuals_For_Defaulted_Generic_Parameters
      • 3.1.5.58. Positional_Actuals_For_Defaulted_Parameters
      • 3.1.5.59. Positional_Components
      • 3.1.5.60. Positional_Generic_Parameters
      • 3.1.5.61. Positional_Parameters
      • 3.1.5.62. Potential_Parameters_Aliasing
      • 3.1.5.63. Recursive_Subprograms
      • 3.1.5.64. Redundant_Boolean_Expressions
      • 3.1.5.65. Redundant_Null_Statements
      • 3.1.5.66. Restrictions
      • 3.1.5.67. Same_Logic
      • 3.1.5.68. Same_Operands
      • 3.1.5.69. Same_Tests
      • 3.1.5.70. Side_Effect_Parameters
      • 3.1.5.71. Silent_Exception_Handlers
      • 3.1.5.72. Single_Value_Enumeration_Types
      • 3.1.5.73. Size_Attribute_For_Types
      • 3.1.5.74. SPARK_Procedures_Without_Globals
      • 3.1.5.75. Suspicious_Equalities
      • 3.1.5.76. Trivial_Exception_Handlers
      • 3.1.5.77. Unavailable_Body_Calls
      • 3.1.5.78. Unchecked_Address_Conversions
      • 3.1.5.79. Unchecked_Conversions_As_Actuals
      • 3.1.5.80. Uninitialized_Global_Variables
      • 3.1.5.81. Unnamed_Blocks_And_Loops
      • 3.1.5.82. Unnamed_Exits
      • 3.1.5.83. Use_Array_Slices
      • 3.1.5.84. Use_Case_Statements
      • 3.1.5.85. Use_For_Loops
      • 3.1.5.86. Use_For_Of_Loops
      • 3.1.5.87. Use_If_Expressions
      • 3.1.5.88. Use_Memberships
      • 3.1.5.89. USE_PACKAGE_Clauses
      • 3.1.5.90. Use_Ranges
      • 3.1.5.91. Use_Record_Aggregates
      • 3.1.5.92. Use_Simple_Loops
      • 3.1.5.93. Use_While_Loops
      • 3.1.5.94. Variable_Scoping
      • 3.1.5.95. Warnings
    • 3.1.6. Readability
      • 3.1.6.1. End_Of_Line_Comments
      • 3.1.6.2. Headers
      • 3.1.6.3. Identifier_Casing
      • 3.1.6.4. Identifier_Prefixes
      • 3.1.6.5. Identifier_Suffixes
      • 3.1.6.6. Lowercase_Keywords
      • 3.1.6.7. Max_Identifier_Length
      • 3.1.6.8. Min_Identifier_Length
      • 3.1.6.9. Misnamed_Controlling_Parameters
      • 3.1.6.10. Name_Clashes
      • 3.1.6.11. No_Dependence
      • 3.1.6.12. Numeric_Format
      • 3.1.6.13. Object_Declarations_Out_Of_Order
      • 3.1.6.14. One_Construct_Per_Line
      • 3.1.6.15. Overriding_Indicators
      • 3.1.6.16. Profile_Discrepancies
      • 3.1.6.17. Style_Checks
      • 3.1.6.18. Uncommented_BEGIN
      • 3.1.6.19. Uncommented_BEGIN_In_Package_Bodies
      • 3.1.6.20. Uncommented_End_Record
  • 3.2. Feature-Related Rules
    • 3.2.1. Abort_Statements
    • 3.2.2. Abstract_Type_Declarations
    • 3.2.3. Anonymous_Access
    • 3.2.4. Anonymous_Subtypes
    • 3.2.5. At_Representation_Clauses
    • 3.2.6. Blocks
    • 3.2.7. Complex_Inlined_Subprograms
    • 3.2.8. Conditional_Expressions
    • 3.2.9. Controlled_Type_Declarations
    • 3.2.10. Declarations_In_Blocks
    • 3.2.11. Deeply_Nested_Inlining
    • 3.2.12. Default_Parameters
    • 3.2.13. Discriminated_Records
    • 3.2.14. Enumeration_Representation_Clauses
    • 3.2.15. Explicit_Full_Discrete_Ranges
    • 3.2.16. Explicit_Inlining
    • 3.2.17. Expression_Functions
    • 3.2.18. Fixed_Equality_Checks
    • 3.2.19. Float_Equality_Checks
    • 3.2.20. Function_Style_Procedures
    • 3.2.21. Generic_IN_OUT_Objects
    • 3.2.22. Generics_In_Subprograms
    • 3.2.23. Implicit_IN_Mode_Parameters
    • 3.2.24. Improperly_Located_Instantiations
    • 3.2.25. Library_Level_Subprograms
    • 3.2.26. Membership_Tests
    • 3.2.27. Non_Qualified_Aggregates
    • 3.2.28. Number_Declarations
    • 3.2.29. Numeric_Indexing
    • 3.2.30. Numeric_Literals
    • 3.2.31. Parameters_Out_Of_Order
    • 3.2.32. Predicate_Testing
    • 3.2.33. Quantified_Expressions
    • 3.2.34. Raising_Predefined_Exceptions
    • 3.2.35. Relative_Delay_Statements
    • 3.2.36. Renamings
    • 3.2.37. Representation_Specifications
    • 3.2.38. Separates
    • 3.2.39. Simple_Loop_Statements
    • 3.2.40. Subprogram_Access
    • 3.2.41. Too_Many_Dependencies
    • 3.2.42. Unassigned_OUT_Parameters
    • 3.2.43. Unconditional_Exits
    • 3.2.44. Unconstrained_Array_Returns
    • 3.2.45. Unconstrained_Arrays
    • 3.2.46. USE_Clauses
  • 3.3. Metrics-Related Rules
    • 3.3.1. Metrics_Cyclomatic_Complexity
    • 3.3.2. Metrics_Essential_Complexity
    • 3.3.3. Metrics_LSLOC
  • 3.4. SPARK-Related Rules
    • 3.4.1. Annotated_Comments
    • 3.4.2. Boolean_Relational_Operators
    • 3.4.3. Expanded_Loop_Exit_Names
    • 3.4.4. Non_SPARK_Attributes
    • 3.4.5. Non_Tagged_Derived_Types
    • 3.4.6. Outer_Loop_Exits
    • 3.4.7. Overloaded_Operators
    • 3.4.8. Slices
    • 3.4.9. Universal_Ranges
• 4. Writing Your Own Rules
  • 4.1. How To Write Rules
    • 4.1.1. Boolean Rules
    • 4.1.2. Unit Rules
    • 4.1.3. Rule Arguments
  • 4.2. Debugging Your Rules
    • 4.2.1. The LKQL interpreter
    • 4.2.2. Print Technique
  • 4.3. A Complete Step By Step Example
• 5. LKQL Language Reference
  • 5.1. General Purpose Language Subset
    • 5.1.1. Data Types
      • 5.1.1.1. Basic Data Types
      • 5.1.1.2. Composite Data Types
    • 5.1.2. Declarations
      • 5.1.2.1. Function Declaration
      • 5.1.2.2. Value Declaration
      • 5.1.2.3. Docstrings
    • 5.1.3. Expressions
      • 5.1.3.1. Block Expression
      • 5.1.3.2. Field Access
      • 5.1.3.3. Unwrap Expression
      • 5.1.3.4. Call Expression
      • 5.1.3.5. Constructor call
      • 5.1.3.6. Indexing Expression
      • 5.1.3.7. Comparison Expression
      • 5.1.3.8. Object Literal
      • 5.1.3.9. List Literal
      • 5.1.3.10. List Comprehension
      • 5.1.3.11. If Expression
      • 5.1.3.12. Match Expression
      • 5.1.3.13. Tuple Literal
      • 5.1.3.14. Anonymous Function
      • 5.1.3.15. Literals and Operators
      • 5.1.3.16. Module Importation
  • 5.2. Query Language Subset
    • 5.2.1. Query Expression
      • 5.2.1.1. Specifying the selector
    • 5.2.2. Pattern
      • 5.2.2.1. Node patterns
      • 5.2.2.2. Regular Values Patterns
      • 5.2.2.3. Special and Composite Patterns
      • 5.2.2.4. Filtered Patterns and Binding Patterns
    • 5.2.3. Selector Declaration
      • 5.2.3.1. Defining a Selector
      • 5.2.3.2. Built-in Selectors
  • 5.3. Language changes
    • 5.3.1. 25.0
      • 5.3.1.1. Conditional expression alternatives are now optional
      • 5.3.1.2. Syntax of pattern details (breaking)
      • 5.3.1.3. Syntax of selectors recursion definition (breaking)
      • 5.3.1.4. Or patterns syntax (breaking)
      • 5.3.1.5. Binding patterns without value pattern
      • 5.3.1.6. More patterns
  • 5.4. LKQL API
    • 5.4.1. Libadalang API
    • 5.4.2. Standard library
      • 5.4.2.1. Builtin functions
      • 5.4.2.2. Builtin methods
    • 5.4.3. stdlib’s API doc
      • 5.4.3.1. Functions
      • 5.4.3.2. Selectors
• 6. LKQL Driver
  • 6.1. Sub-commands List
    • 6.1.1. lkql refactor
    • 6.1.2. lkql run
    • 6.1.3. lkql check
    • 6.1.4. lkql doc-api
    • 6.1.5. lkql doc-rules
    • 6.1.6. lkql gnatcheck_worker

• Alphabetical List of Rules
• GNU Free Documentation License