В этом примере показов, как создать и изменить XML- файл, чтобы задать формат аннотации и сопоставить его с Polyspace® синтаксис аннотации. После создания и редактирования XML-файла передайте файл в Polyspace с помощью опции -xml-annotations-description
.
Для определения нескольких пользовательских форматов аннотаций см. раздел «Определение нескольких пользовательских синтаксисов аннотаций».
Чтобы начать, скопируйте следующий код в текстовый редактор и сохраните его на своей машине как annotations_description.xml
.
|
XML- файл состоит из двух частей:
<Expressions>...</Expressions>
где задается формат синтаксиса аннотации.
<Mapping>...</Mapping>
где вы сопоставляете синтаксис с синтаксисом аннотации Polyspace.
После редактирования этого файла Polyspace может интерпретировать аннотацию пользовательского кода, когда вы вызываете опцию -xml-annotations-description
.
Чтобы определить синтаксис аннотации в Polyspace, ваш синтаксис должен следовать шаблону, который можно представлять с регулярным выражением. См. раздел Регулярные выражения. Рекомендуется включить ключевое слово в шаблон синтаксиса аннотации, чтобы помочь идентифицировать его. В этом примере ключевое слово myKeyword
. Установите атрибут Search_For_Keywords
равен этому ключевому слову.
Как только вы знаете шаблон вашей аннотации, можно задать его в XML-файле, добавив <Expression/>
элемент и определение, по крайней мере, атрибутов Mode
, Regex
, и Rule_Identifier_Position
. Например, первый <Expression/>
элемент в annotations_description.xml
задает аннотацию с этими атрибутами:
Mode="SAME_LINE"
. Аннотация применяется к коду в той же линии.
Regex="myKeyword\s+(\w+(\s*,\s*\w+)*)"
. Polyspace использует регулярное выражение для поиска строки, которая начинается с myKeyword
, за которым следует пространство \s+
. Затем Polyspace ищет группу захвата (\w+(\s*,\s*\w+)*)
который включает алфавитно-цифровой идентификатор правила \w+
и, опционально, дополнительные идентификаторы правил, разделенных запятыми (\s*,\s*\w+)*
.
Rule_Identifier_Position="1"
. Целое значение этого атрибута соответствует количеству открывающих круглых скобок, предшествующих соответствующей группе захвата в регулярном выражении. В myKeyword\s+(\w+(\s*,\s*\w+)*)
, одна открывающая круглая скобка предшествует группе захвата идентификатора правила (\w+(\s*,\s*\w+)*)
. Если вы хотите соответствовать идентификаторам правил, захваченным (\s*,\s*\w+)
, затем вы задаете Rule_Identifier_Position="2"
потому что две открывающие круглые скобки предшествуют этой группе захвата.
Список атрибутов и их значений перечислены в этой таблице. Столбец примера ссылается на формат, заданный в annotations_description.xml
.
Признак | Использовать | Значение | Пример |
---|---|---|---|
Mode | Необходимый | SAME_LINE | Применяется только к той же линии, что и аннотация. code; //myKeyword 100 |
GOTO_INCREMENT
| Применяется к той же линии, что и аннотация, и к следующим n линиям: 3. code; // myKeyword +3 ALL_MISRA
4. /*comments */
5.
6. code;
7. code;
Предыдущая аннотация применяется только к линиям 3-6. | ||
BEGIN
| Применяется к тому же линия и ко всем следующим линиям до соответствующего выражения с атрибутом //myKeyword 50, 51 Block_on
Code block 1;
... | ||
END
| Останавливает применение идентификатора правила, объявленного соответствующим выражением с атрибутом //myKeyword 50, 51 Block_on Code block 1; ... More code; //myKeyword 50 Block_off Отключается только идентификатор правила 50. Идентификатор правила 51 все еще применяется. | ||
END_ALL
| Останавливает все идентификаторы правил, объявленные выражением с атрибутом //myKeyword 50, 51 Block_on Code block 1; ... More code; //myKeyword Block_off_all Идентификаторы правил 50 и 51 отключены. | ||
Regex | Необходимый | Строка поиска регулярного выражения | См. раздел Регулярные выражения. // myKeyword 50, 51
/* myKeyword ALL_MISRA, 100 */ |
Rule_Identifier_Position | Обязательно, кроме тех случаев, когда вы настраиваете Mode="END_ALL" | Целое число | Целое значение этого атрибута соответствует количеству открывающих круглых скобок в регулярном выражении перед соответствующим поисковым выражением. <Expression Mode="GOTO_INCREMENT" Regex="myKeyword\s+(\+\d+\s)(\w+(\s*,\s*\w+)*)" Increment_Position="1" Rule_Identifier_Position="2"/> Поисковое выражение идентификатора правила |
Increment_Position | Требуется только при установке Mode="GOTO_INCREMENT" | Целое число | Целое значение этого атрибута соответствует количеству открывающих круглых скобок в регулярном выражении перед соответствующим поисковым выражением. <Expression Mode="GOTO_INCREMENT" Regex="myKeyword\s+(\+\d+\s)(\w+(\s*,\s*\w+)*)" Increment_Position="1" Rule_Identifier_Position="2"/> Поисковое выражение шага |
Status_Position | Дополнительный | Целое число | См. Increment_Position пример. При использовании этого атрибута запись в аннотации отображается в столбце Status на панели Results List пользовательского интерфейса. |
Severity_Position | Дополнительный | Целое число | См. Increment_Position пример. При использовании этого атрибута запись в аннотации отображается в столбце Severity на панели Results List пользовательского интерфейса. |
Comment_Position
| Дополнительный | Целое число | См. Increment_Position пример. При использовании этого атрибута запись в аннотации отображается в столбце Comment на панели Results List пользовательского интерфейса. Ваш комментарий добавляется к строке Justified by annotation in source: |
Case_Insensitive
| Дополнительный | Правда или ложь | Когда вы устанавливаете этот атрибут в «true», регулярное выражение нечувствительно к регистру, в противном случае оно чувствительно к регистру. Если вы не объявляете этот атрибут в своем выражении, регулярное выражение чувствительно к регистру. Для //MYKEYWORD ALL_MISRA BLOCK_ON
//mykeyword all_misra block_on
|
После определения формата аннотации можно сопоставить идентификаторы правил, которые вы используете, с соответствующим синтаксисом аннотации Polyspace. Вы можете сделать это отображение, добавив <Result_Name_Mapping/>
элемент и определяющие атрибуты Rule_Identifier
, Family
, и Result_Name
. Например, если идентификатор 50 правила соответствует MISRA C®: 2012 правило 8.4, сопоставить его с синтаксисом Polyspace MISRA-C3:8.4
при помощи этого элемента:
<Result_Name_Mapping Rule_Identifier="50" Family="MISRA-C3" Result_Name="8.4"/>
Список атрибутов и их значений перечислены в этой таблице. Столбец примера ссылается на формат, заданный в annotations_description.xml
.
Признак | Использовать | Значение | Пример |
---|---|---|---|
Rule_Identifier | Необходимый | Определено пользователем. Каждое значение должно быть уникальным. | Смотрите раздел отображения annotations_description.xml |
Family | Необходимый | Соответствует семейству результатов Polyspace. Список допустимых значений см. в разделе «Допустимые значения». | Смотрите раздел отображения annotations_description.xml |
Result_Name | Необходимый | Соответствует именам результатов Polyspace. Список допустимых значений см. в разделе «Допустимые значения». | Смотрите раздел отображения annotations_description.xml |
Чтобы задать более одного синтаксиса аннотации, в XML- файлом укажите разделенный запятыми список ключевых слов, сопоставленных с каждым синтаксисом Search_For_Keywords
атрибут.
Для примера, если вы используете пользовательские аннотации, следующие этим шаблонам, чтобы аннотировать нарушения правил MISRA C: 2012:
int func(int p) //customSyntax M123 $ customSyntax M124
{
int i;
int j = 1;
i = 1024 / (j - p);
return i;
}
int func2(void){ //otherCustomSyntax 50
int x=func(2);
return x;
}
<?xml version="1.0" encoding="UTF-8"?>
<Annotations xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="annotations_xml_schema.xsd"
Group="multipleCustomSyntax">
<!-- Enter comma separated list of keywords -->
<Expressions Search_For_Keywords="customSyntax,otherCustomSyntax"
Separator_Result_Name="$" >
<!-- This section defines the annotation syntax format -->
<Expression Mode="SAME_LINE"
Regex="customSyntax\s(\w+(\s*,\s*\w+)*)"
Rule_Identifier_Position="1"
/>
<Expression Mode="SAME_LINE"
Regex="otherCustomSyntax\s(\w+(\s*,\s*\w+)*)"
Rule_Identifier_Position="1"
/>
</Expressions>
<!-- This section maps the user annotation to the Polyspace
annotation syntax -->
<Mapping>
<!-- Mapping for customSyntax rules -->
<Result_Name_Mapping Rule_Identifier="M123" Family="MISRA-C3" Result_Name="8.7"/>
<Result_Name_Mapping Rule_Identifier="M124" Family="MISRA-C3" Result_Name="D4.6"/>
<!-- Mapping for otherCustomSyntax rules -->
<Result_Name_Mapping Rule_Identifier="50" Family="MISRA-C3" Result_Name="8.4"/>
</Mapping>
</Annotations>
M123
с otherCustomSyntax
.