Merge branch 'topic/getting_started_update' into 'master'

Update 'getting_started.rst'

Closes #359 and #330

See merge request eng/libadalang/langkit-query-language!308

Author: HugoGGuerrier

lkql_checker/doc/gnatcheck_rm/getting_started.rst

@@ -23,7 +23,7 @@ Invoking ``gnatcheck`` on the command line has the form::
   $ gnatcheck [switches] {filename}
         [-files=arg_list_filename]
         [-r rule_names]
-        [--rules=lkql_rule_filename]
+        [--rule-file=lkql_rule_filename]
         [-cargs gcc_switches]
 
 
@@ -80,10 +80,6 @@ project file named :file:`gnatcheck_example.gpr` with the following content:
      for Object_Dir use "obj";
      for Main use ("main.adb");
 
-     package Check is
-        for Default_Switches ("ada") use ("--rules", "coding_standard.lkql");
-     end Check;
-
   end Gnatcheck_Example;
 
 
@@ -169,7 +165,7 @@ and :file:`main.adb`:
 And suppose we call ``gnatcheck`` from the current directory using
 the project file as the only parameter of the call::
 
-     gnatcheck -Pgnatcheck_example.gpr
+     gnatcheck -Pgnatcheck_example.gpr --rule-file coding_standard.lkql
 
 
 As a result, ``gnatcheck`` is called to check all the files from the

lkql_checker/doc/gnatcheck_rm/using_gnatcheck.rst

@@ -305,10 +305,56 @@ one (non-aggregate) project, the gnatcheck behavior is the same as for the
 case of non-aggregate argument project file.
 
 
+.. _Check_GPR_Package:
+
+The *Check* GPR Package
+=======================
+
+In addition to the command-line options, you can use attributes offered by the
+``Check`` package to configure a GNATcheck run. In order to do this you may add
+the ``Check`` package in the GPR file you're providing to GNATcheck through the
+``-P`` command line options, example given:
+
+.. code-block:: ada
+
+  project My_Project is
+     package Check is
+        ...
+     end Check;
+  end My_Project;
+
+Inside this package you can define the following attributes to configure
+GNATcheck:
+
+* ``Switches``
+  Index is a language name. Value is a list of additional switches to be used
+  when invoking ``gnatcheck``.
+
+  .. attention::
+
+    There are several command-line switches that you cannot pass through the
+    ``Switches`` attribute:
+
+    * ``-P``
+    * ``-U``
+    * ``-Xname=value``
+    * ``-eL``
+    * ``-r, --rule [rule_name]``
+    * ``--rule-file=filename``
+
+    If you're providing one of those switches through the ``Switches`` or the
+    ``Default_Switches`` attribute, GNATcheck will raise an error message and
+    exit with an error code.
+
+* ``Default_Switches``
+  Same as ``Switches``, but provided additional switches will apply only if
+  there is no applicable ``Switches`` attribute.
+
+
 .. _LKQL_options_file:
 
-LKQL rule options file
-======================
+LKQL Rule Files
+===============
 
 You can configure GNATcheck rules using an LKQL file, provided through the
 ``--rule-file`` command-line option.

lkql_checker/src/gnatcheck-projects.adb

@@ -676,8 +676,7 @@ package body Gnatcheck.Projects is
         (Switches_Attr,
          "Index is a language name. Value is a " &
            "list of switches to be used when invoking 'gnatcheck' for a " &
-           "source of the language, if there is no applicable attribute " &
-           "Switches.");
+           "source of the language.");
       Add_Alias (Name     => Default_Switches_Attr,
                  Alias_Of => Switches_Attr);
       GPR2.Project.Registry.Attribute.Description.Set_Attribute_Description

testsuite/tests/gnatcheck/print_gpr_registry/test.out

@@ -1 +1 @@
-{"packages":[{"attributes":[{"attribute_def":{"builtin":false,"config_concatenable":false,"empty_value":"ALLOW","has_default_in":{"abstract":false,"aggregate":false,"aggregate_library":false,"configuration":false,"library":false,"standard":false},"index_optional":false,"index_type":"LANGUAGE_INDEX","inherit_from_extended":"NOT_INHERITED","is_allowed_in":{"abstract":true,"aggregate":true,"aggregate_library":true,"configuration":true,"library":true,"standard":true},"is_toolchain_config":false,"value":"LIST","value_case_sensitive":true,"value_is_set":false},"attribute_descr":"Index is a language name. Value is a list of switches to be used when invoking 'gnatcheck' for a source of the language, if there is no applicable attribute Switches.","attribute_name":"Default_Switches"},{"attribute_def":{"builtin":false,"config_concatenable":false,"empty_value":"ALLOW","has_default_in":{"abstract":false,"aggregate":false,"aggregate_library":false,"configuration":false,"library":false,"standard":false},"index_optional":false,"index_type":"LANGUAGE_INDEX","inherit_from_extended":"NOT_INHERITED","is_allowed_in":{"abstract":true,"aggregate":true,"aggregate_library":true,"configuration":true,"library":true,"standard":true},"is_toolchain_config":false,"value":"LIST","value_case_sensitive":true,"value_is_set":false},"attribute_descr":"Index is a language name. Value is a list of switches to be used when invoking 'gnatcheck' for a source of the language, if there is no applicable attribute Switches.","attribute_name":"Switches"}],"package_descr":"This package specifies the options used when calling the checking tool 'gnatcheck'. Its attribute Default_Switches has the same semantics as for the package Builder. The first string should always be -rules to specify that all the other options belong to the -rules section of the parameters to 'gnatcheck'.","package_name":"Check","projects_kind":{"abstract":true,"aggregate":true,"aggregate_library":true,"configuration":true,"library":true,"standard":true}},{"attributes":[{"attribute_def":{"builtin":false,"config_concatenable":false,"empty_value":"ALLOW","has_default_in":{"abstract":false,"aggregate":false,"aggregate_library":false,"configuration":false,"library":false,"standard":false},"index_optional":false,"index_type":"NO_INDEX","inherit_from_extended":"NOT_INHERITED","is_allowed_in":{"abstract":true,"aggregate":true,"aggregate_library":true,"configuration":true,"library":true,"standard":true},"is_toolchain_config":false,"value":"LIST","value_case_sensitive":true,"value_is_set":false},"attribute_descr":"If you want to override ada default file extensions (ada, ads, adb, spc & bdy), use this attribute which includes a list of file patterns where you can specify the following meta characters: * : matches any string of 0 or more characters, ? : matches any character,  [list of chars] : matches any character listed, [char-char] : matches any character in given range, [^list of chars] : matches any character not listed. These patterns are case insensitive.","attribute_name":"File_Patterns"}],"package_descr":"This package specifies the options used when calling the tool 'codepeer'.","package_name":"Codepeer","projects_kind":{"abstract":true,"aggregate":true,"aggregate_library":true,"configuration":true,"library":true,"standard":true}}]}
+{"packages":[{"attributes":[{"attribute_def":{"builtin":false,"config_concatenable":false,"empty_value":"ALLOW","has_default_in":{"abstract":false,"aggregate":false,"aggregate_library":false,"configuration":false,"library":false,"standard":false},"index_optional":false,"index_type":"LANGUAGE_INDEX","inherit_from_extended":"NOT_INHERITED","is_allowed_in":{"abstract":true,"aggregate":true,"aggregate_library":true,"configuration":true,"library":true,"standard":true},"is_toolchain_config":false,"value":"LIST","value_case_sensitive":true,"value_is_set":false},"attribute_descr":"Index is a language name. Value is a list of switches to be used when invoking 'gnatcheck' for a source of the language, if there is no applicable attribute Switches.","attribute_name":"Default_Switches"},{"attribute_def":{"builtin":false,"config_concatenable":false,"empty_value":"ALLOW","has_default_in":{"abstract":false,"aggregate":false,"aggregate_library":false,"configuration":false,"library":false,"standard":false},"index_optional":false,"index_type":"LANGUAGE_INDEX","inherit_from_extended":"NOT_INHERITED","is_allowed_in":{"abstract":true,"aggregate":true,"aggregate_library":true,"configuration":true,"library":true,"standard":true},"is_toolchain_config":false,"value":"LIST","value_case_sensitive":true,"value_is_set":false},"attribute_descr":"Index is a language name. Value is a list of switches to be used when invoking 'gnatcheck' for a source of the language.","attribute_name":"Switches"}],"package_descr":"This package specifies the options used when calling the checking tool 'gnatcheck'. Its attribute Default_Switches has the same semantics as for the package Builder. The first string should always be -rules to specify that all the other options belong to the -rules section of the parameters to 'gnatcheck'.","package_name":"Check","projects_kind":{"abstract":true,"aggregate":true,"aggregate_library":true,"configuration":true,"library":true,"standard":true}},{"attributes":[{"attribute_def":{"builtin":false,"config_concatenable":false,"empty_value":"ALLOW","has_default_in":{"abstract":false,"aggregate":false,"aggregate_library":false,"configuration":false,"library":false,"standard":false},"index_optional":false,"index_type":"NO_INDEX","inherit_from_extended":"NOT_INHERITED","is_allowed_in":{"abstract":true,"aggregate":true,"aggregate_library":true,"configuration":true,"library":true,"standard":true},"is_toolchain_config":false,"value":"LIST","value_case_sensitive":true,"value_is_set":false},"attribute_descr":"If you want to override ada default file extensions (ada, ads, adb, spc & bdy), use this attribute which includes a list of file patterns where you can specify the following meta characters: * : matches any string of 0 or more characters, ? : matches any character,  [list of chars] : matches any character listed, [char-char] : matches any character in given range, [^list of chars] : matches any character not listed. These patterns are case insensitive.","attribute_name":"File_Patterns"}],"package_descr":"This package specifies the options used when calling the tool 'codepeer'.","package_name":"Codepeer","projects_kind":{"abstract":true,"aggregate":true,"aggregate_library":true,"configuration":true,"library":true,"standard":true}}]}