mirrors
/
sonarqube
mirror of https://github.com/SonarSource/sonarqube.git
Watch 1
Star 0
Fork 0
Code Issues 0 Releases 237 Wiki Activity
Browse Source

SONAR-15680 Fail the build if an analyzer documentation file is missing

tags/9.3.0.51899
Wouter Admiraal 2 years ago
parent
8389944391
commit
5645ca9451
24 changed files with 81 additions and 1432 deletions
Split View Show Diff Stats
  1. 58
    25
      server/sonar-docs/plugins/sonarsource-source-filesystem/index.js
  2. 1
    10
      server/sonar-docs/src/pages/analysis/languages/abap.md
  3. 1
    15
      server/sonar-docs/src/pages/analysis/languages/apex.md
  4. 1
    123
      server/sonar-docs/src/pages/analysis/languages/cfamily.md
  5. 1
    309
      server/sonar-docs/src/pages/analysis/languages/cobol.md
  6. 1
    15
      server/sonar-docs/src/pages/analysis/languages/csharp.md
  7. 1
    14
      server/sonar-docs/src/pages/analysis/languages/flex.md
  8. 1
    32
      server/sonar-docs/src/pages/analysis/languages/go.md
  9. 1
    12
      server/sonar-docs/src/pages/analysis/languages/html.md
  10. 1
    325
      server/sonar-docs/src/pages/analysis/languages/java.md
  11. 1
    108
      server/sonar-docs/src/pages/analysis/languages/javascript.md
  12. 1
    9
      server/sonar-docs/src/pages/analysis/languages/kotlin.md
  13. 1
    86
      server/sonar-docs/src/pages/analysis/languages/php.md
  14. 1
    57
      server/sonar-docs/src/pages/analysis/languages/pli.md
  15. 1
    34
      server/sonar-docs/src/pages/analysis/languages/plsql.md
  16. 1
    103
      server/sonar-docs/src/pages/analysis/languages/python.md
  17. 1
    84
      server/sonar-docs/src/pages/analysis/languages/rpg.md
  18. 1
    9
      server/sonar-docs/src/pages/analysis/languages/ruby.md
  19. 1
    9
      server/sonar-docs/src/pages/analysis/languages/scala.md
  20. 1
    9
      server/sonar-docs/src/pages/analysis/languages/swift.md
  21. 1
    9
      server/sonar-docs/src/pages/analysis/languages/tsql.md
  22. 1
    6
      server/sonar-docs/src/pages/analysis/languages/vb6.md
  23. 1
    19
      server/sonar-docs/src/pages/analysis/languages/vbnet.md
  24. 1
    10
      server/sonar-docs/src/pages/analysis/languages/xml.md

+ 58
- 25
server/sonar-docs/plugins/sonarsource-source-filesystem/index.js View File

@@ -21,13 +21,22 @@ const { createFilePath, createRemoteFileNode } = require('gatsby-source-filesyst
const fs = require('fs-extra');
const path = require('path');

const documentationFileName = 'documentation.md';
const manifestFileName = 'manifest.mf';
const manifestIssueTrackerUrlSection = 'Plugin-IssueTrackerUrl';
const DOCUMENTATION_FILE_NAME = 'documentation.md';
const MANIFEST_FILE_NAME = 'manifest.mf';
const MANIFEST_ISSUE_TRACKER_URL_SECTION = 'Plugin-IssueTrackerUrl';
const LANG_TO_ANALYZER_MAP = {
vb6: 'vb'
};
const STATIC_NAV_TREE_DEFINITION = path.normalize(
`${__dirname}/../../static/StaticNavigationTree.json`
);
const EXPANDED_PLUGIN_DOCS_DIR = path.normalize(
`${__dirname}/../../build/tmp/plugin-documentation`
);

let overrides;

function processPluginOverridesIfAvailable(content) {
function processPluginOverrides(content) {
if (overrides === undefined) {
const pluginFileList = getPluginFilesList();

@@ -50,51 +59,71 @@ function processPluginOverridesIfAvailable(content) {
}

function addIssueTrackerLink(page) {
let issueTrackerLink = '## Issue Tracker';
issueTrackerLink += '\r\n';
issueTrackerLink += `Check the [issue tracker](${page.issueTrackerUrl}) for this language.`;
if (page.issueTrackerUrl) {
let issueTrackerLink = '## Issue Tracker';
issueTrackerLink += '\r\n';
issueTrackerLink += `Check the [issue tracker](${page.issueTrackerUrl}) for this language.`;

page.content = `${page.content}\r\n${issueTrackerLink}`;
page.content = `${page.content}\r\n${issueTrackerLink}`;
}

return page;
}

function getPluginFilesList() {
const dir = path.normalize(`${__dirname}/../../build/tmp/plugin-documentation/`);
const analyzers = [];
const walk = leaf => {
if (typeof leaf === 'object') {
if (leaf.children) {
leaf.children.forEach(walk);
}
} else {
const match = leaf.match(/^\/analysis\/languages\/(\w+)\/$/);
if (match && match[1] && match[1] !== 'overview') {
analyzers.push(LANG_TO_ANALYZER_MAP[match[1]] || match[1]);
}
}
};

if (fs.pathExistsSync(dir)) {
return fs.readdirSync(dir).map(subDir => {
const pluginDir = path.normalize(`${dir}/${subDir}`);
const tree = JSON.parse(fs.readFileSync(STATIC_NAV_TREE_DEFINITION, 'utf8'));
tree.forEach(walk);

if (fs.pathExistsSync(pluginDir)) {
return fs
.readdirSync(pluginDir)
.map(fileName => path.normalize(`${pluginDir}/${fileName}`));
}
return analyzers.map(analyzer => {
const analyzerDir = path.normalize(`${EXPANDED_PLUGIN_DOCS_DIR}/sonar-${analyzer}-plugin`);

return [];
});
}
if (!fs.pathExistsSync(analyzerDir)) {
throw Error(
`Couldn't find the "${analyzer}" analyzer in the build dir. Looked for "${analyzerDir}", but couldn't find it.`
);
}

return [];
return fs
.readdirSync(analyzerDir)
.map(fileName => path.normalize(`${analyzerDir}/${fileName}`));
});
}

function processPluginFileList(pluginFileList) {
let md;
let mf;
let pluginDir;

pluginFileList.forEach(fileFullName => {
const fileName = path.basename(fileFullName);

if (fileName.toLowerCase() === documentationFileName.toLowerCase()) {
if (pluginDir === undefined) {
pluginDir = path.dirname(fileFullName);
}

if (fileName.toLowerCase() === DOCUMENTATION_FILE_NAME.toLowerCase()) {
md = fileFullName;
} else if (fileName.toLowerCase() === manifestFileName.toLowerCase()) {
} else if (fileName.toLowerCase() === MANIFEST_FILE_NAME.toLowerCase()) {
mf = fileFullName;
}
});

if (!md) {
return undefined;
throw Error(`Couldn't find the "${DOCUMENTATION_FILE_NAME}" file in "${pluginDir}".`);
}

return { ...parsePluginMarkdownFile(md), ...parsePluginManifestFile(mf) };
@@ -115,6 +144,10 @@ function parsePluginMarkdownFile(fileFullPath) {
}

function parsePluginManifestFile(fileFullPath) {
if (!fileFullPath) {
return undefined;
}

const mfContent = fs.readFileSync(fileFullPath, 'utf-8');
const regex = /^Plugin-IssueTrackerUrl:\s*(.+\r?\n?\s?\w+)$/m;
const match = mfContent.match(regex);
@@ -133,7 +166,7 @@ function loadNodeContent(fileNode) {
}

function loadNodeContentSync(fileNode) {
let content = processPluginOverridesIfAvailable(fs.readFileSync(fileNode.absolutePath, 'utf-8'));
let content = processPluginOverrides(fs.readFileSync(fileNode.absolutePath, 'utf-8'));

content = cleanContent(content);
content = handleIncludes(content, fileNode);

+ 1
- 10
server/sonar-docs/src/pages/analysis/languages/abap.md View File

@@ -3,13 +3,4 @@ title: ABAP
url: /analysis/languages/abap/
---

_ABAP analysis is available starting in [Developer Edition](https://redirect.sonarsource.com/editions/developer.html)._


## Language-Specific Properties

Discover and update the ABAP-specific [properties](/analysis/analysis-parameters/) in: <!-- sonarcloud -->Project <!-- /sonarcloud -->**[Administration > General Settings > ABAP](/#sonarqube-admin#/admin/settings?category=abap)**

## Source Code Extraction

In order to analyze your source code with SonarQube you need to first extract it from SAP onto a filesystem. You can use your own tool or an open source tool; SonarSource does not provide any connectors or source code extraction tools.
This is a placeholder file. It is required for Gatsby, but its content will be dynamically replaced.

+ 1
- 15
server/sonar-docs/src/pages/analysis/languages/apex.md View File

@@ -3,18 +3,4 @@ title: Apex
url: /analysis/languages/apex/
---

<!-- sonarqube -->

_Apex analysis is available starting in [Enterprise Edition](https://redirect.sonarsource.com/editions/enterprise.html)._

<!-- /sonarqube -->


## Language-Specific Properties

Discover and update the Apex-specific [properties](/analysis/analysis-parameters/) in: <!-- sonarcloud -->Project <!-- /sonarcloud -->[**Administration > General Settings > Apex**](/#sonarqube-admin#/admin/settings?category=apex)

## Related Pages

- [Importing External Issues](/analysis/external-issues/) (PMD Apex)
- [Test Coverage & Execution](/analysis/coverage/) (For Salesforce DX project)
This is a placeholder file. It is required for Gatsby, but its content will be dynamically replaced.

+ 1
- 123
server/sonar-docs/src/pages/analysis/languages/cfamily.md View File

@@ -3,126 +3,4 @@ title: C/C++/Objective-C
url: /analysis/languages/cfamily/
---

_C/C++/Objective-C analysis is available starting with [Developer Edition](https://redirect.sonarsource.com/editions/developer.html)._



C/C++/Objective-C analysis is officially registered as [CWE Compatible](https://cwe.mitre.org/compatible/).

## Supported Compilers, Language Standards and Operating Systems
* Any version of Clang, GCC and Microsoft C/C++ compilers
* Any version of Intel compiler for Linux and macOS
* ARM5 and ARM6 compilers
* IAR compiler for ARM, Renesas RL78, Renesas RX, Renesas V850, Texas Instruments MSP430 and for 8051
* Compilers based wholly on GCC including for instance Linaro GCC and WindRiver GCC are also supported
* C89, C99, C11, C++03, C++11, C++14 and C++17 standards
* GNU extensions
* Microsoft Windows, Linux and macOS for runtime environment

## Language-Specific Properties

Discover and update the C/C++/Objective-C specific properties in: <!-- sonarcloud -->Project <!-- /sonarcloud -->**[Administration > General Settings > C / C++ / Objective-C](/#sonarqube-admin#/admin/settings?category=c+%2F+c%2B%2B+%2F+objective-c)**

## Prerequisites
### Build Wrapper
Analysis of C/C++/Objective-C projects requires the **SonarQube Build Wrapper**. It gathers all the configuration required for correct analysis of C/C++/Objective-C projects (such as macro definitions, include directories, …) directly from your project's build process. The Build Wrapper does not impact your build; it merely eavesdrops on it and writes what it learns into files a directory you specify.

<!-- sonarqube -->
You can download the *Build Wrapper* directly from your SonarQube server, so that its version perfectly matches your version of the plugin.
* Download *Build Wrapper* for Linux from [{SonarQube URL}/static/cpp/build-wrapper-linux-x86.zip](/#sonarqube#/static/cpp/build-wrapper-linux-x86.zip)
* Download *Build Wrapper* for macOS from [{SonarQube URL}/static/cpp/build-wrapper-macosx-x86.zip](/#sonarqube#/static/cpp/build-wrapper-macosx-x86.zip)
* Download *Build Wrapper* for Windows from [{SonarQube URL}/static/cpp/build-wrapper-win-x86.zip](/#sonarqube#/static/cpp/build-wrapper-win-x86.zip)
<!-- /sonarqube -->
<!-- sonarcloud -->
You can download the *Build Wrapper* directly from SonarCloud:
* [Download *Build Wrapper* for Linux](https://sonarcloud.io/static/cpp/build-wrapper-linux-x86.zip)
* [Download *Build Wrapper* for macOS](https://sonarcloud.io/static/cpp/build-wrapper-macosx-x86.zip)
* [Download *Build Wrapper* for Windows](https://sonarcloud.io/static/cpp/build-wrapper-win-x86.zip)
<!-- /sonarcloud -->


Unzip the downloaded *Build Wrapper* and configure it in your `PATH` because doing so is just more convenient.

### SonarQube Scanner
Analysis of C/C++/Objective-C projects requires the [*SonarScanner*](https://redirect.sonarsource.com/doc/install-configure-scanner.html) CLI.

## Analysis Steps
* If you use macOS or Linux operating systems make sure your source tree is in a directory called `src`
* Add execution of the *Build Wrapper* as a prefix to your usual build command (the examples below use `make`, `xcodebuild` and `MSBuild`, but any build tool that performs a full build can be used)
```
// example for linux
build-wrapper-linux-x86-64 --out-dir build_wrapper_output_directory make clean all
// example for macOS
build-wrapper-macosx-x86 --out-dir build_wrapper_output_directory xcodebuild clean build
// example for Windows
build-wrapper-win-x86-64.exe --out-dir build_wrapper_output_directory MSBuild.exe /t:Rebuild
```
* In the *sonar-project.properties* file at the root of your project add the property `sonar.cfamily.build-wrapper-output` with the path to the *Build Wrapper* output directory relative to the project directory (`build_wrapper_output_directory` in these examples).

Sample *sonar-project.properties*:
```
sonar.projectKey=myFirstProject
sonar.projectName=My First C++ Project
sonar.projectVersion=1.0
sonar.sources=src
sonar.cfamily.build-wrapper-output=build_wrapper_output_directory
sonar.sourceEncoding=UTF-8
```
* Execute the SonarScanner (`sonar-scanner`) from the root directory of the project
```
sonar-scanner
```
* Follow the link provided at the end of the analysis to browse your project's quality metrics in the UI

## Multithreaded Code Scan

It is possible to use all the cores available on the machine running the code scan. This can be activated by configuring the property `sonar.cfamily.threads` at the scanner level. Its default value is 1.

* This feature must not be activated on a machine with only 1 core.

* The analyzer will not guess which value is most suitable for your project. It's up to you to test and find the best value.

* If a build machine with 2 cores is already configured to potentially run two code scans at the same time, there is no guarantee that configuring `sonar.cfamily.threads=2` will bring the expected performance benefits. It can even be worse than running with the default value.

* The multithreaded execution requires more memory than single-threaded execution.

* A machine with 64 cores configured with `sonar.cfamily.threads=64` is not certain to bring a large performance gain compared to a machine with 32 cores. The performance tradeoff will vary depending on the machine, project and setup, so some testing will be required to decide if the performance gain justifies moving to a larger machine.

## Solution with a Mix of C# and C++

When you have a Solution made of C++ and C#, to both use the SonarQube *Build Wrapper* and have an accurate analysis of the C# code, you must to use the [SonarScanner for MSBuild](https://github.com/SonarSource/sonar-scanner-msbuild).
Note that in this scenario source code stored in shared folders, not considered as a "Project" by Visual Studio, won't be scanned.

* Download and install both the [SonarScanner for MSBuild](https://redirect.sonarsource.com/doc/install-configure-scanner-msbuild.html) and the SonarQube *Build Wrapper* (see *Prerequisites* section).
* Execute the SonarQube Scanner for MSBuild `begin` step
* Add execution of *Build Wrapper* to your normal MSBuild build command
* Execute the SonarQube Scanner for MSBuild `end` step to complete the analysis

For example:
```
SonarScanner.MSBuild.exe begin /k:"cs-and-cpp-project-key" /n:"My C# and C++ project" /v:"1.0" /d:sonar.cfamily.build-wrapper-output="bw_output"
build-wrapper-win-x86-64.exe --out-dir bw_output MSBuild.exe /t:Rebuild
SonarScanner.MSBuild.exe end
```

## Measures for Header Files
Each time we analyze a header file as part of a compilation unit, we compute for this header the measures: statements, functions, classes, cyclomatic complexity and cognitive complexity. That means that each measure may be computed more than once for a given header. In that case, we store the largest value for each measure.

## Building with Bazel

[Bazel](https://www.bazel.build/) recommends that you use the [`--batch`](https://docs.bazel.build/versions/master/bazel-user-manual.html#flag--batch) option when running in a Continuous Build context. When using the *BuildWrapper*, you are in such context. Also, you need to deactivate the ["sandbox"](https://docs.bazel.build/versions/master/bazel-user-manual.html#sandboxing) mechanism of *Bazel* so that the compiled file paths could be retrieved after the compilation phase.
Here is an example of the *BuildWrapper* command with Bazel parameters on macOS:
```
build-wrapper-macosx-x86 --out-dir bw bazel
--batch
--spawn_strategy=standalone
--genrule_strategy=standalone
--bazelrc=/dev/null build
//main:hello-world
```

## Related Pages
* [Test Coverage & Execution](/analysis/coverage/) (CPPUnit, GCOV, llvm-cov, Visual Studio, Bullseye)
* [Sample project](https://github.com/SonarSource/sonar-scanning-examples/tree/master/sonarqube-scanner-build-wrapper-linux) for C/C++ (Linux)
* [Sample project](https://github.com/SonarSource/sonar-scanning-examples/tree/master/objc-llvm-coverage) for Objective-C
* [SonarScanner for Azure Devops](https://redirect.sonarsource.com/doc/install-configure-scanner-tfs-ts.html) (analyzing Visual C++ project)
This is a placeholder file. It is required for Gatsby, but its content will be dynamically replaced.

+ 1
- 309
server/sonar-docs/src/pages/analysis/languages/cobol.md View File

@@ -3,312 +3,4 @@ title: COBOL
url: /analysis/languages/cobol/
---

_Cobol analysis is available starting in [Enterprise Edition](https://redirect.sonarsource.com/editions/enterprise.html)._


## Language-Specific Properties

You can discover and update the COBOL-specific [properties](/analysis/analysis-parameters/) in: <!-- sonarcloud -->Project <!-- /sonarcloud -->**[Administration > General Settings > Cobol](/#sonarqube-admin#/admin/settings?category=cobol)**

## Source Code Extraction

In order to analyze your source code with SonarQube you need to first extract it onto a filesystem. You can use your own tool or an open source tool; SonarSource does not provide any connectors or source code extraction tools.

## Advanced Configuration

### Defining Source Code Format

The supported source code formats are:

- Fixed format
- Free format
- Variable format

To set the format, go to <!-- sonarcloud -->Project <!-- /sonarcloud -->**[Administration > General Settings > Cobol](/#sonarqube-admin#/admin/settings?category=cobol)** and set the "Source format" property.

The fixed format has three main areas:

```
Area1 | Area2 | Area3
000100* MY COMMENT
000100 IDENTIFICATION DIVISION.
000200 PROGRAM-ID. HELLOWORLD. *xxx
100000 PROCEDURE DIVISION. *yyy
100100
100200 START.
100400 DISPLAY "HELLO COBOL !" LINE 42 POSITION 12.
100500 STOP RUN.
```

Areas #1 and #3 contain non-significant characters.
Area #2 contains the source code. The first character of Area #2 is the Indicator Area, which has a special meaning (for instance `*` means that the line is a comment line, `D` means that the line is only taken into account in debug mode, etc.).

The free format:

```
Area1 | Area2
* MY COMMENT
IDENTIFICATION DIVISION.
PROGRAM-ID. HELLOWORLD.
PROCEDURE DIVISION.
DISPLAY "HELLO COBOL !" LINE 42 POSITION 12.
STOP RUN.
```

The Indicator Area that has a special meaning (for instance `*` means that the line is a comment line, `D` means that the line in only taken into account in debug mode, etc.) is located at column 0. The size of the source code area is not limited.

Variable format is also supported: it's similar to the fixed format but without Area #3.

### Defining COBOL Dialect

Go to <!-- sonarcloud -->Project <!-- /sonarcloud -->**[Administration > General Settings > Cobol](/#sonarqube-admin#/admin/settings?category=cobol)** and set the "Dialect" property.

The COBOL analyzer supports the following dialects:

- `bull-gcos-cobol`
- `hp-tandem-cobol`
- `ibm-os/vs-cobol`
- `ibm-ile-cobol`
- `ibm-cobol/ii`
- `ibm-cobol/400`
- `ibm-enterprise-cobol`
- `microfocus-cobol`
- `microfocus-acucobol-gt-cobol`
- `opencobol/cobol-it`

### Making Copybooks Available to the Analysis

Copybooks are, by definition, COBOL files that are not syntactically valid by themselves. However, copybooks are usually needed to properly parse COBOL programs. Thus, paths to the copybooks must be listed through the `sonar.cobol.copy.directories` property.

### Raising Issues Against Copybooks

To have copybooks imported into a project, and issues logged against them, the copybook directories must be added to `sonar.sources` AND the copybook file suffixes must be added to `sonar.cobol.file.suffixes`. E.G.:

```
sonar.sources=cobol,copy1,commonCopy
sonar.cobol.file.suffixes=cbl,cpy
sonar.cobol.copy.suffixes=cpy
sonar.cobol.copy.directories=copy1,commonCopy
```

In the case where a number of projects share a common set of copybooks, it may not be desirable to increment each project’s technical debt with the issues from the common copybooks. In such cases, the directory holding the common copybooks should be listed in `sonar.cobol.copy.directories` (as before) but left out of sonar.sources, E.G.:

```
sonar.sources=cobol,copy1
sonar.cobol.file.suffixes=cbl,cpy
sonar.cobol.copy.suffixes=cpy
sonar.cobol.copy.directories=copy1,commonCopy
```

### Analyzing without file suffixes

Note that it is possible to analyze a COBOL project without file suffixes. To do this, remove the two suffix-related properties from your configuration and substitute the following setting for `sonar.lang.patterns.cobol`:

```
sonar.lang.patterns.cobol=**/*
```

### Switching Off Issues

There are three ways to switch off issues:

- Flagging issues as [false positive](/user-guide/issues/)
- [Ignoring the issues](/project-administration/narrowing-the-focus/)
- Using the `NOSONAR` tag. To switch off an issue, place the `NOSONAR` tag in a comment line located right before the line containing the issue. Example:

```
* NOSONAR, in such case call to GO TO is tolerated, blabla...
GO TO MY_PARAGRAPH.
```

### ACUCOBOL-GT Source Code Control Directives

The COBOL analyzer supports the ACUCOBOL-GT’s Source Code Control directives. This mechanism allows you to conditionally modify the program at compile time by excluding or including lines. This can be used to maintain different versions of the program, perhaps to support different machine environments.

The `-Si` (include) flag controls the actions of the source code control system. It must be followed by an argument that specifies a pattern that the compiler will search for in the Identification Area of each source line. If the pattern is found, then the line will be included in the source program, even if it is a comment line. However, if the pattern is immediately preceded by an exclamation point, then the line will be excluded from the source (i.e., commented out).

The `-Sx` (exclude) flag works the same way except that its meaning is reversed (lines with the pattern will be commented out and lines with a preceding exclamation point will be included).

For example, suppose a program is being maintained for both the UNIX and VMS environments. The following piece of code is in the program:

```
MOVE "SYS$HELP:HELPFILE" TO FILE-NAME. VMS
*MOVE "/etc/helpfile" TO FILE-NAME. UNX
OPEN INPUT HELP-FILE.
```

This program fragment is ready to be compiled for the VMS system. If a UNIX version is desired, then the following flags will correct the source during compilation:

```
-Si UNX -Sx VMS
```

Please consult the ACUCOBOL-GT documentation for more on the mechanism.

There are two ways in SonarQube to specify the list of ACUCOBOL-GT flags to be used in order to preprocess the source code. The first option is to define a list of global flags which will be used to preprocess all source files. This can be done in the **[Administration > General Settings > Cobol](/#sonarqube-admin#/admin/settings?category=cobol) > Preprocessor**.

The second option is to provide a list of relative paths (with help of the ‘sonar.cobol.acucobol.preprocessor.directives.directories’ property) which contain the list of flags to be used for each COBOL source file. Let’s take a simple example. If a file ‘MY_PROGRAM.CBL’ is going to be processed, the SonarQube ACUCOBOL-GT preprocessor, will try to find a file ‘MY_PROGRAM.CMD’. If this file is found, then the flags contained in this file is going to be used to preprocess the program ‘MY_PROGRAM.CBL’. If the file ‘MY_PROGRAM.CMD’ doesn’t exist, then the preprocess will use the content of the file ‘DEFAULT.CMD’ if exists.

### Microfocus Compiler Constants

If your code takes advantage of conditional compilation features provided by Microfocus, you may have to configure compiler constants for your analysis. You can define a compiler constant by setting a property named s`onar.cobol.compilationConstant.[constant name here].`

For example, if your COBOL code looks like this:

```
IDENTIFICATION DIVISION.
$IF myconstant DEFINED
PROGRAM-ID. x.
$END
$IF otherconstant DEFINED
PROGRAM-ID. y.
$END
```

You can set the value of a compiler constant named "myconstant" by inserting the following line in your sonar-project.properties file:

```
sonar.cobol.compilationConstant.myconstant=myvalue
```

## Database Catalog (DB2)

The COBOL analyzer offers rules which target embedded SQL statements and require the analyzer to have knowledge of the database catalog (E.G. the primary key column(s) of a given table).
These rules will raise issues only if the database catalog is provided to the analysis. For the moment, this is available only for IBM DB2 (z/OS) catalogs, and the catalog must be provided via a set of CSV ("Comma Separated Values") files.

These rules rely on two analysis properties:

| Key | Description |
| --------------------------------------- | -------------------------------------------------------------------------------- |
| `sonar.cobol.sql.catalog.csv.path` | relative path of the directory containing CSV files for the database catalog |
| `sonar.cobol.sql.catalog.defaultSchema` | comma-separated list of default database schemas used in embedded SQL statements |

`sonar.cobol.sql.catalog.csv.path` should define a directory which contains 8 CSV files. Each of these CSV files contains data for a specific DB2 catalog table and is named after it. The following table lists the required files and their respective mandatory columns. Additional columns may be listed, but will be ignored:

| Table | File name | Required Columns |
| ---------------------- | ------------------- | -------------------------------------------------------------------------------------- |
| `SYSIBM.SYSCOLUMNS` | `SYSCOLUMNS.csv` | `TBNAME`,`TBCREATOR`,`NAME`,`PARTKEY_COLSEQ`,`DEFAULT`,`NULLS`,`DEFAULTVALUE` |
| `SYSIBM.SYSINDEXES` | `SYSINDEXES.csv` | `NAME`,`CREATOR`,`TBNAME`,`TBCREATOR`,`UNIQUERULE`,`INDEXTYPE` |
| `SYSIBM.SYSINDEXPART` | `SYSINDEXPART.csv` | `IXNAME`,`IXCREATOR`,`PARTITION` |
| `SYSIBM.SYSKEYS` | `SYSKEYS.csv` | `IXNAME`,`IXCREATOR`,`COLNAME`,`COLSEQ` |
| `SYSIBM.SYSSYNONYMS` | `SYSSYNONYMS.csv` | `NAME`,`CREATOR`,`TBNAME`,`TBCREATOR` |
| `SYSIBM.SYSTABLES` | `SYSTABLES.csv` | `NAME`,`CREATOR`,`TYPE`,`PARTKEYCOLNUM`,`TSNAME`,`DBNAME`,`TBNAME`,`TBCREATOR`,`CARDF` |
| `SYSIBM.SYSTABLESPACE` | `SYSTABLESPACE.csv` | `NAME`,`DBNAME`,`PARTITIONS` |
| `SYSIBM.SYSVIEWS` | `SYSVIEWS.csv` | `NAME`,`CREATOR`,`STATEMENT` |

The CSV format is the following:

- Each file must be named for the table it represents.
- First line must contain the exact names of the columns.
- Order of the columns is not meaningful.
- Fields are comma-delimited.
- If a field contains a comma, then its value must be surrounded by double quotes (").
- If a field which is surrounded by double quotes contains a double quote character ("), then this character must be doubled ("").

Example for `SYSVIEWS.csv`:

```
CREATOR,NAME,STATEMENT
USER1,VIEW1,select x from table1
USER1,VIEW2,"select x, y from table1"
USER1,VIEW3,"select x, ""y"" from table1"
```

The `UNLOAD` DB2 utility with the `DELIMITED` option should produce the required files except for the column names on the first line.

<!-- sonarqube -->

## Custom Rules

### Overview

The COBOL analyzer parses the source code, creates an Abstract Syntax Tree (AST) and then walks through the entire tree. A coding rule can subscribe to be notified every time a node of a certain type is visited.

As soon as the coding rule is notified, it can navigate the tree around the node and raise issues if necessary.

### Writing a Plugin

Writing new COBOL coding rules is a six-step process:

- Create a standard SonarQube plugin.
- Attach this plugin to the SonarQube COBOL plugin (see the `pom.xml` file of the provided sample plugin project).
- Create as many custom COBOL coding rules as required by extending `com.sonarsource.api.ast.CobolCheck` and add them to the previous repository.
- Generate the SonarQube plugin (jar file).
- Place this jar file in the `$SONARQUBE_HOME/extensions/plugins` directory.
- Restart the SonarQube server.

### Plugin Project Sample

To get started, clone the sample plugin project and follow the steps below:

- Install Maven
- Build the plugin by running `mvn install` from the project directory. This will generate a SonarQube plugin jar file in the target directory.
- Add your newly created jar into the `$SONARQUBE_HOME/extensions/plugins` directory
- Restart the SonarQube server

If you now look at the COBOL Quality Profiles, you will find the new coding rule (“Sample check”). Don’t forget to activate it. Run an analysis of a COBOL project, and you will find that an issue was logged at line 5 on every file.

### Subscribing to a NodeType

Very often when writing a coding rule, you will want to subscribe to a NodeType. A NodeType can be either a rule of the grammar or a keyword of the language. As an example, here is the code of the implementation of the “Avoid using Merge statement” coding rule:

```
public class MergeStatementUsageCheck extends CobolCheck {

public void init() {
subscribeTo(getCobolGrammar().mergeStatement);
}

public void visitNode(AstNode node) {
reportIssue("Avoid using MERGE statement.").on(node);
}
}
```

Note that CICS and SQL grammars can be accessed using `getCicsGrammar()` and `getSqlGrammar()`.

### Coding Rule Lifecycle

A coding rule can optionally override six methods inherited from the CobolCheck class. Those methods are called sequentially in the following order:

- `public void init() {…}`: This method is called only once and should be used to subscribe to one or more NodeType(s).
- `public void visitFile(AstNode astNode) {…}`: This method is called on each file before starting the parsing.
- `public void visitNode(AstNode astNode) {…}`: This method is called when an AstNode matches a subscribed NodeType (see Subscribing to a NodeType) and before analyzing its content.
- `public void leaveNode(AstNode astNode) {…}`: This method is called when an AstNode matches a desired NodeType (see Subscribing to a NodeType) and after analyzing its content.
- `public void leaveFile(AstNode astNode) {…}`: This method is called before exiting a file.
- `public void destroy() {…}`: This method is called before shutting down the coding rule.
- The `reportIssue(…)` method, used to log an issue, should be called only inside the `visitFile(…)`, `visitNode(…)`, `leaveNode(…)` and `leaveFile(…)` methods. Indeed, the file context isn’t known when the `init()` and `destroy()` methods are called, so the issue can’t be associated to a file.

More advanced features are documented in the [API Javadoc](http://javadocs.sonarsource.org/cobol/apidocs/).

### Navigating the AST (Abstract Syntax Tree) with the SSLR COBOL Toolkit

When starting to write a new COBOL coding rule, the main difficulty is to understand the COBOL AST in order to know which NodeType(s) need to be visited. This can be achieved by using the [SSLR COBOL Toolkit](https://binaries.sonarsource.com/CommercialDistribution/sslr-cobol-toolkit/), a Swing application that enables loading a COBOL file and displaying its representation as an Abstract Syntax Tree.

Each node in the AST is a COBOL grammar rule and each leaf in the AST is a COBOL token. Let’s say you want to visit the node `ifStatement`. In this case, the `init()` method of your COBOL coding rule must contain the following statement: `subscribeTo(getCobolGrammar().ifStatement);`

### API Changes

_Since 4.0_
A new API is available to write the rules but also to implement the tests.

Custom rules should now extend `CobolCheck` (`CobolAstCheck` is deprecated) and issues should be logged using the `reportIssue(...)` method.
Tests on custom rules should now use `CobolCheckVerifier`: the assertions about issues should now be added as comments inside COBOL test files.
Custom rules should be listed in an implementation of `CobolCheckRepository` (`CobolAstCheckRepository` is now deprecated) and metadata should be loaded by implementing `RulesDefinitionExtension`.
You can now store your custom rules into a dedicated rule repository by implementing SonarQube's `RulesDefinition`: in that case, you don't need to implement `RulesDefinitionExtension`.
![](/images/exclamation.svg) For users who already have custom rules in production: existing issues will be closed and re-opened because the internal keys of the rules are changing.
If you wrote a custom plugin against SonarCOBOL 3.x, it should still be compatible at runtime with SonarCOBOL 4.0.

To migrate to the new API ([full example on github](https://github.com/SonarSource/sonar-custom-rules-examples/pull/14)):

- First, migrate tests without modifying rule classes. That mainly requires moving assertions from java test classes to comments inside test cobol files ([see an example on github](https://github.com/SonarSource/sonar-custom-rules-examples/commit/c95b6a84b6fd1efc832a46cd5e1101ee51e6268e)).
- Update check classes to replace the calls to deprecated methods with the new methods which create issues ([see an example on github](https://github.com/SonarSource/sonar-custom-rules-examples/commit/d6f6ef7457d99e31990fa64b5ff9cc566775af96)).
- Implement `CobolRulesDefinitionExtension` and `CobolCheckRepository`, remove the class extending `CobolAstCheckRepository` ([see an example on github](https://github.com/SonarSource/sonar-custom-rules-examples/commit/ea15f07ce79366a08fee5b60e9a93c32a4625918)).
- Update check classes to extend `CobolCheck` instead of `CobolAstCheck` to stop using deprecated APIs ([see an example on github](https://github.com/SonarSource/sonar-custom-rules-examples/commit/8e1d746900f5411e9700fea04700cd804e45e034)).

To move your custom rules to a dedicated rule repository, see [an example on github](https://github.com/SonarSource/sonar-custom-rules-examples/commit/16ad89c4172c259f15bce56edcd09dd5b489eacd).

## Related Pages

- [Adding Coding Rules](/extend/adding-coding-rules/)
<!-- /sonarqube -->
This is a placeholder file. It is required for Gatsby, but its content will be dynamically replaced.

+ 1
- 15
server/sonar-docs/src/pages/analysis/languages/csharp.md View File

@@ -3,18 +3,4 @@ title: C#
url: /analysis/languages/csharp/
---



## Language-Specific Properties

Discover and update the C#-specific [properties](/analysis/analysis-parameters/) in: <!-- sonarcloud -->Project <!-- /sonarcloud --> **[Administration > General Settings > C#](/#sonarqube-admin#/admin/settings?category=c%23)**.

### Analyze Generated Code

To analyze tool-generated code (e.g. WCF code generated by `SvcUtil.exe`, protobuf code generated by `protoc`, Swagger client code generated by `NSwag`) for a specific C# project, enable the "Analyze generated code" setting inside **Project > Administration > General Settings > C#**. By default, tool-generated code files are skipped from analysis.

## Related Pages
* [Excluding External Roslyn Issues](/analysis/external-issues/) (See "Notes on external .NET issues")
* [Test Coverage & Execution](/analysis/coverage/) (Visual Studio Code Coverage, dotCover, OpenCover, Coverlet, NCover 3)
* [SonarScanner for MSBuild](/analysis/scan/sonarscanner-for-msbuild/)
* [SonarScanner for Azure DevOps](/analysis/scan/sonarscanner-for-azure-devops/)
This is a placeholder file. It is required for Gatsby, but its content will be dynamically replaced.

+ 1
- 14
server/sonar-docs/src/pages/analysis/languages/flex.md View File

@@ -3,17 +3,4 @@ title: Flex
url: /analysis/languages/flex/
---


## Supported Versions
* ActionScript 2
* ActionScript 3

## Language-Specific Properties
Discover and update the Flex-specific [properties](/analysis/analysis-parameters/) in: <!-- sonarcloud -->Project <!-- /sonarcloud -->[**Administration > General Settings > Flex**](/#sonarqube-admin#/admin/settings?category=flex)

## Related Pages

* [Test Coverage & Execution](/analysis/coverage/) (Cobertura)
<!-- sonarqube -->
* [Adding Coding Rules](/extend/adding-coding-rules/)
<!-- /sonarqube -->
This is a placeholder file. It is required for Gatsby, but its content will be dynamically replaced.

+ 1
- 32
server/sonar-docs/src/pages/analysis/languages/go.md View File

@@ -3,35 +3,4 @@ title: Go
url: /analysis/languages/go/
---




## Prerequisites

* SonarQube Scanner should run on a x86-64 Windows, macOS or Linux 64bits machine
* You need the [Go](https://golang.org/) installation on the scan machine only if you want to import coverage data

## Language-Specific Properties

You can discover and update the Go-specific [properties](/analysis/analysis-parameters/) in: <!-- sonarcloud -->Project <!-- /sonarcloud -->**[Administration > General Settings > Go](/#sonarqube-admin#/admin/settings?category=go)**

## "sonar-project.properties" Sample

Here is a good first version of a `sonar-project.properties`, correctly excluding "vendor" directories and categorizing files as "main" or "test":

```
sonar.projectKey=com.company.projectkey1
sonar.projectName=My Project Name

sonar.sources=.
sonar.exclusions=**/*_test.go,**/vendor/**

sonar.tests=.
sonar.test.inclusions=**/*_test.go
sonar.test.exclusions=**/vendor/**
```

## Related Pages

* [Test Coverage & Execution](/analysis/coverage/)
* [Importing External Issues](/analysis/external-issues/) (GoVet, GoLint, GoMetaLinter)
This is a placeholder file. It is required for Gatsby, but its content will be dynamically replaced.

+ 1
- 12
server/sonar-docs/src/pages/analysis/languages/html.md View File

@@ -3,15 +3,4 @@ title: HTML
url: /analysis/languages/html/
---



## Language-Specific Properties

You can discover and update HTML-specific [properties](/analysis/analysis-parameters/) in: <!-- sonarcloud -->Project <!-- /sonarcloud -->**[Administration > General Settings > HTML](/#sonarqube-admin#/admin/settings?category=html)**.

## PHP Code Analysis
SonarPHP and SonarHTML both analyze files with extensions: `.php`, `.php3`, `.php4`, `.php5`, `.phtml`.

File metrics, such as the number of lines of code, can only be measured by one of the languages, PHP or HTML. They are handled by SonarPHP by default, and by SonarHTML if for some reason SonarPHP is not present.

SonarHTML analyzes PHP files even if the PHP file extensions are not included in the list of file extensions to analyze.
This is a placeholder file. It is required for Gatsby, but its content will be dynamically replaced.

+ 1
- 325
server/sonar-docs/src/pages/analysis/languages/java.md View File

@@ -3,328 +3,4 @@ title: Java
url: /analysis/languages/java/
---



## Language-Specific Properties

You can discover and update the Java-specific [properties](/analysis/analysis-parameters/) in: <!-- sonarcloud -->Project <!-- /sonarcloud -->[Administration > General Settings > Java](/#sonarqube-admin#/admin/settings?category=java)

## Java Analysis and Bytecode

Compiled `.class` files are required for java projects with more than one java file. If not provided properly, analysis will fail with the message:

Please provide compiled classes of your project with sonar.java.binaries property.

If only some `.class` files are missing, you'll see warnings like this:

Class 'XXXXXX' is not accessible through the ClassLoader.

If you are not using Maven or Gradle for analysis, you must manually provide bytecode to the analysis.
You can also analyze test code, and for that you need to provide tests binaires and test libraries properties.

Key | Value
---|---|
`sonar.java.binaries` (required) | Comma-separated paths to directories containing the compiled bytecode files corresponding to your source files.
`sonar.java.libraries` | Comma-separated paths to files with third-party libraries (JAR or Zip files) used by your project. Wildcards can be used: `sonar.java.libraries=path/to/Library.jar,directory/**/*.jar`
`sonar.java.test.binaries` | Comma-separated paths to directories containing the compiled bytecode files corresponding to your test files
`sonar.java.test.libraries` | Comma-separated paths to files with third-party libraries (JAR or Zip files) used by your tests. (For example, this should include the junit jar). Wildcards can be used: `sonar.java.test.libraries=directory/**/*.jar`

[[warning]]
| Android users, Jack doesn't provide the required `.class` files.


## Turning issues off

The best way to deactivate an individual issue you don't intend to fix is to mark it "Won't Fix" or "False Positive" through the SonarQube UI.

If you need to deactivate a rule (or all rules) for an entire file, then [issue exclusions](/project-administration/narrowing-the-focus/) are the way to go. But if you only want to deactivate a rule across a subset of a file - all the lines of a method or a class - you can use `@SuppressWarnings("all")` or `@SuppressWarnings` with rule keys: `@SuppressWarnings("squid:S2078")` or `@SuppressWarnings({"squid:S2078", "squid:S2076"})`.

## Handling Java Source Version

The Java Analyzer is able to react to the java version used for sources. This feature allows the deactivation of rules that target higher versions of Java than the one in use in the project so that false positives aren't generated from irrelevant rules.

The feature relies entirely on the `sonar.java.source` property, which is automatically filled by most of the scanners used for analyses (Maven, Gradle). Java version-specific rules are not disabled when `sonar.java.source` is not provided. Concretely, rules which are designed to target specific java versions (tagged "java7" or "java8") are activated by default in the Sonar Way Java profile. From a user perspective, the feature is fully automatic, but it means that you probably want your projects to be correctly configured.

When using SonarScanner to perform analyses of project, the property `sonar.java.source` can to be set manually in `sonar-project.properties`. Accepted formats are:
* "1.X" (for instance 1.6 for java 6, 1.7 for java 7, 1.8 for java 8, etc.)
* "X" (for instance 7 for java 7, 8 for java 8, etc. )

Example: `sonar.java.source=1.6`

If the property is provided, the analysis will take the source version into account, and execute related rules accordingly. At run time, each of these rules will be executed – or not – depending of the Java version used by sources within the project. For instance, on a correctly configured project built with Java 6, rules targeting Java 7 and Java 8 will never raise issues, even though they are enabled in the associated rule profile.

## Related Pages

* [Test Coverage & Execution](/analysis/coverage/) (JaCoCo, Surefire)
* [Importing External Issues](/analysis/external-issues/) ([SpotBugs](https://spotbugs.github.io/), [FindBugs](http://findbugs.sourceforge.net/), [FindSecBugs](https://github.com/find-sec-bugs/find-sec-bugs/wiki/Maven-configuration), [PMD](http://maven.apache.org/plugins/maven-pmd-plugin/usage.html), [Checkstyle](http://maven.apache.org/plugins/maven-checkstyle-plugin/checkstyle-mojo))
<!-- sonarqube -->* [Adding Coding Rules](/extend/adding-coding-rules/)<!-- /sonarqube -->

<!-- sonarqube -->
## Custom Rules

The tutorial [Writing Custom Java Rules 101](https://redirect.sonarsource.com/doc/java-custom-rules-guide.html) will help to quickly start writing custom rules for Java.

### API changes

#### **6.1**

* The `ExpressionTree` interface, from the AST API, is now enriched by two new methods `Optional<Object> asConstant()` and `<T> Optional<T> asConstant(Class<T> type)`. These methods let you try to retrieve the equivalent constant value of an expression (from a variable, for instance). An example of usage would be:

```
class A {
public static final String CONSTANT1 = "abc";
public static final String CONSTANT2 = CONSTANT1 + "def";

void foo() {
System.out.println(CONSTANT2);
// ^^^^^^^^^ calling 'identifier.asConstant(String.class)' will return 'Optional.of("abcdef")'
}
}
```

#### **6.0**

* Deprecated method `org.sonar.plugins.java.api.JavaFileScannerContext.addIssue(File, JavaCheck, int, String)` has been **removed**. Custom rules relying on it should report issues on a given `Tree` from now on.
* Deprecated method `org.sonar.plugins.java.api.JavaFileScannerContext.getFile()` has been **removed**. Custom rules relying on it should rely on content of SQ's API `InputFile`.
* Deprecated method `org.sonar.plugins.java.api.tree.TryStatementTree.resources()` has been **removed**, in favor of `org.sonar.plugins.java.api.tree.TryStatementTree.resourceList()`, as Java 9 allows other trees than `VariableTree` to be placed as resources in try-with-resources statements.
* Method `org.sonar.plugins.java.api.semantic.Symbol.owner()` has been **flagged** with `@Nullable` annotation, to explicitly document the fact that some symbols (package, unknown, recovered) might well return `null`.

* **Semantic engine**
* Return type of constructor is now `void type` instead of `null`.
* A **raw type** is now explicitly different from an **erasure type**. It is recommended to systematically use type erasure for type comparison when dealing with generics.
```
class A<T> {
// ^^^^ Definition of a Generic Type
boolean equals(Object o) {
if (o instance of A) {
// ^ this is a raw type, not erasure of A<T>
return true;
}
return false;
}

A<String> foo() {
return new A<String>();
// ^^^^^^^^^ Parameterization of a Generic Type
}
}
```
* According to Java Language Specification every array type implements the interface `java.io.Serializable`, calling `isSubtypeOf("java.io.Serializable")` on an array type now consistently returns `true`.
* Symbol corresponding to generic method invocations are now correctly parameterized.
* In some special cases (mostly missing bytecode dependencies, misconfigured projects), and due to ECJ recovery system, unknown/recovered types can now lead to unknown symbols, even on `ClassTree`/`MethodTree`/`VariableTree`. To illustrate this, the following example now associate the method to an unknown symbol, while previous semantic engine from SonarJava 5.X series was creating a `Symbol.MethodSymbol` with an unknown return type.
```
Class A {
UnknownType<String> myMethod() { /* ... */ }
// ^^^^^^^^ symbol corresponding to the MethodTree will be unknown,
}
```
* Thanks to improved semantic provided by ECJ engine, new semantic is now able to say that an *unknown* symbol is supposed to be type/variable/method (`isTypeSymbol()`, `isVariableSymbol()`, ...). Old semantic was answering `false` for all of them. Consequently, be sure to always use `isUnknown()` to validate symbol resolution. Other `is...Symbol()` methods are only designed to know how to cast the symbols (e.g from `Symbol` to `Symbol.MethodSymbol`).

#### **5.12**
* **Dropped**
* `org.sonar.plugins.java.api.JavaFileScannerContext`: Drop deprecated method used to retrieve trees contributing to the complexity of a method from (deprecated since SonarJava 4.1).
```
//org.sonar.plugins.java.api.JavaFileScannerContext
/**
* Computes the list of syntax nodes which are contributing to increase the complexity for the given methodTree.
* @deprecated use {@link #getComplexityNodes(Tree)} instead
* @param enclosingClass not used.
* @param methodTree the methodTree to compute the complexity.
* @return the list of syntax nodes incrementing the complexity.
*/
@Deprecated
List<Tree> getMethodComplexityNodes(ClassTree enclosingClass, MethodTree methodTree);
```
* `org.sonar.plugins.java.api.JavaResourceLocator`: The following method has been dropped (deprecated since SonarJava 4.1), without replacement.
```
//org.sonar.plugins.java.api.JavaResourceLocator
/**
* get source file key by class name.
* @deprecated since 4.1 : will be dropped with no replacement.
* @param className fully qualified name of the analyzed class.
* @return key of the source file for the given class.
*/
@Deprecated
String findSourceFileKeyByClassName(String className);
```
* `org.sonar.plugins.surefire.api.SurefireUtils`: Dropping deprecated field with old property (deprecated since SonarJava 4.11)
```
//org.sonar.plugins.surefire.api.SurefireUtils
/**
* @deprecated since 4.11
*/
@Deprecated
public static final String SUREFIRE_REPORTS_PATH_PROPERTY = "sonar.junit.reportsPath";
```
* **Deprecated**
* `org.sonar.plugins.java.api.JavaFileScannerContext`: Deprecate usage of File-based methods from API, which will be removed in future release. Starting from this version, methods relying on InputFile has to be preferred.
```
//org.sonar.plugins.java.api.JavaFileScannerContext
/**
* Report an issue at a specific line of a given file.
* This method is used for one
* @param file File on which to report
* @param check The check raising the issue.
* @param line line on which to report the issue
* @param message Message to display to the user
* @deprecated since SonarJava 5.12 - File are not supported anymore. Use corresponding 'reportIssue' methods, or directly at project level
*/
@Deprecated
void addIssue(File file, JavaCheck check, int line, String message);
/**
* FileKey of currently analyzed file.
* @return the fileKey of the file currently analyzed.
* @deprecated since SonarJava 5.12 - Rely on the InputFile key instead, using {@link #getInputFile()}
*/
@Deprecated
String getFileKey();

/**
* File under analysis.
* @return the currently analyzed file.
* @deprecated since SonarJava 5.12 - File are not supported anymore. Use {@link #getInputFile()} or {@link #getProject()} instead
*/
@Deprecated
File getFile();
```
* Deprecate methods which are not relevant anymore in switch-related trees from API, following introduction of the new Java 12 `switch` expression:
```
//org.sonar.plugins.java.api.tree.CaseLabelTree
/**
* @deprecated (since 5.12) use the {@link #expressions()} method.
*/
@Deprecated
@Nullable
ExpressionTree expression();

/**
* @deprecated (since 5.12) use the {@link #colonOrArrowToken()} method.
*/
@Deprecated
SyntaxToken colonToken();
```
* **Added**
* `org.sonar.plugins.java.api.JavaFileScannerContext`: Following methods have been added in order to provide help reporting issues at project level, and access data through SonarQube's InputFile API, which won't be possible anymore through files:
```
//JavaFileScannerContext: New methods
/**
* Report an issue at at the project level.
* @param check The check raising the issue.
* @param message Message to display to the user
*/
void addIssueOnProject(JavaCheck check, String message);
/**
* InputFile under analysis.
* @return the currently analyzed inputFile.
*/
InputFile getInputFile();
/**
* InputComponent representing the project being analyzed
* @return the project component
*/
InputComponent getProject();
```
* In order to cover the Java 12 new switch expression, introduce a new Tree in the SonarJava Syntax Tree API (Corresponding `Tree.Kind`: `SWITCH_EXPRESSION` ). New methods have also been added to fluently integrate the new switch expression into the SonarJava API.
```
//org.sonar.plugins.java.api.tree.SwitchExpressionTree
/**
* 'switch' expression.
*
* JLS 14.11
*
* <pre>
* switch ( {@link #expression()} ) {
* {@link #cases()}
* }
* </pre>
*
* @since Java 12
*/
@Beta
public interface SwitchExpressionTree extends ExpressionTree {
SyntaxToken switchKeyword();
SyntaxToken openParenToken();
ExpressionTree expression();
SyntaxToken closeParenToken();
SyntaxToken openBraceToken();
List<CaseGroupTree> cases();
SyntaxToken closeBraceToken();
}
```
```
//org.sonar.plugins.java.api.tree.SwitchStatementTree
/**
* Switch expressions introduced with support Java 12
* @since SonarJava 5.12
*/
SwitchExpressionTree asSwitchExpression();
```
```
//org.sonar.plugins.java.api.tree.CaseLabelTree
/**
* @return true for case with colon: "case 3:" or "default:"
* false for case with arrow: "case 3 ->" or "default ->"
* @since 5.12 (Java 12 new features)
*/
boolean isFallThrough();
/**
* @since 5.12 (Java 12 new features)
*/
SyntaxToken colonOrArrowToken();
```
```
//org.sonar.plugins.java.api.tree.BreakStatementTree
/**
* @since 5.12 (Java 12 new features)
*/
@Nullable
ExpressionTree value();
```
```
//org.sonar.plugins.java.api.tree.TreeVisitor
void visitSwitchExpression(SwitchExpressionTree tree);
```

#### **5.7**
* **Breaking**
* This change will impact mostly the custom rules relying on semantic API. The type returned by some symbols will change from raw type to parameterized type with identity substitution and this will change how subtyping will answer.

It is possible to get the previous behavior back by using type erasure on the newly returned type. Note that not all returned types are impacted by this change.

Example:
```
@Rule(key = "MyFirstCustomRule")
public class MyFirstCustomCheck extends IssuableSubscriptionVisitor {
@Override
public List<Kind> nodesToVisit() {
return ImmutableList.of(Kind.METHOD);
}
@Override
public void visitNode(Tree tree) {
MethodTree method = (MethodTree) tree;
MethodSymbol symbol = method.symbol();
Type returnType = symbol.returnType().type();
// When analyzing the code "MyClass<Integer> foo() {return null; }"
// BEFORE: returnType == ClassJavaType
// NOW: returnType == ParametrizedTypeJavaType
// Getting back previous type
Type erasedType = returnType.erasure();
// erasedType == ClassJavaType
}
}
```
<!-- /sonarqube -->
This is a placeholder file. It is required for Gatsby, but its content will be dynamically replaced.

+ 1
- 108
server/sonar-docs/src/pages/analysis/languages/javascript.md View File

@@ -3,111 +3,4 @@ title: JavaScript
url: /analysis/languages/javascript/
---



## Prerequisites

In order to analyze JavaScript code, you need to have Node.js >= 8 installed on the machine running the scan. Set property `sonar.nodejs.executable` to an absolute path to Node.js executable, if standard `node` is not available.
## Language-Specific Properties

Discover and update the JavaScript-specific properties in: **<!-- sonarcloud -->Project <!-- /sonarcloud -->[Administration > General Settings > JavaScript](/#sonarqube-admin#/admin/settings?category=javascript)**

## Supported Frameworks and Versions
* ECMAScript 5 / ECMAScript 2015 (ECMAScript 6) / ECMAScript 2016 / ECMAScript 2017
* React JSX
* Vue.js
* Flow

## Rule Profiles

There are 2 built-in rule profiles for JavaScript: `Sonar way` (default) and `Sonar way Recommended`.
* `Sonar way` profile is activated by default. It defines a trimmed list of high-value/low-noise rules useful in almost any JS development context.
* `Sonar way Recommended` contains all rules from `Sonar way`, plus more rules that mandate high code readability and long-term project evolution.

<!-- sonarqube -->
## Custom rules
[[warning]]
| This feature is deprecated
### Overview

The JavaScript Analyzer parses the source code, creates an Abstract Syntax Tree (AST) and then walks through the entire tree. A coding rule is a visitor that is able to visit nodes from this AST.

As soon as the coding rule visits a node, it can navigate the tree around the node and log issues if necessary.

### Create SonarQube Plugin
Custom rules for JavaScript can be added by writing a SonarQube Plugin and using JavaScript analyzer APIs.

To get started a sample plugin can be found here: [javascript-custom-rules](https://github.com/SonarSource/sonar-custom-rules-examples/tree/master/javascript-custom-rules).
Here are the step to follow:

* Create a standard SonarQube plugin project
* Attach this plugin to the SonarQube JavaScript analyzer through the `pom.xml`:
* Add the dependency to the JavaScript analyzer.
* Add the following line in the sonar-packaging-maven-plugin configuration.
```
<basePlugin>javascript</basePlugin>
```
* Implement the following extension points:
* [Plugin](http://javadocs.sonarsource.org/latest/apidocs/index.html?org/sonar/api/Plugin.html)
* [RulesDefinition](http://javadocs.sonarsource.org/latest/apidocs/index.html?org/sonar/api/server/rule/RulesDefinition.html)
* `CustomRuleRepository`, this interface registers rule classes with JavaScript plugin, so they are invoked during analysis of JavaScript files.
* Declare `RulesDefinition` as an extension in the `Plugin` extension point.

You can implement both `RulesDefinition` and `CustomRulesRepository` in a single class.

### Implement a Rule

* Create a class that will hold the implementation of the rule. It should:
* Extend `DoubleDispatchVisitorCheck` or `SubscriptionVisitorCheck`
* Define the rule name, key, tags, etc. with Java annotations.
* Declare this class in the `RulesDefinition`.

### Implementation Details

#### Using DoubleDispatchVisitorCheck
`DoubleDispatchVisitorCheck` extends `DoubleDispatchVisitor` which provide a set of methods to visit specific tree nodes (these methods' names start with `visit`). To explore a part of the AST, override the required method(s). For example, if you want to explore `if` statement nodes, override the `DoubleDispatchVisitor#visitIfStatement` method that will be called each time an `IfStatementTree` node is encountered in the AST.

[[warning]]
| When overriding a visit method, you must call the `super` method in order to allow the visitor to visit the rest of the tree.

#### Using SubscriptionVisitorCheck
`SubscriptionVisitorCheck` extends `SubscriptionVisitor`. To explore a part of the AST, override `SubscribtionVisitor#nodesToVisit()` by returning the list of the `Tree#Kind` of node you want to visit. For example, if you want to explore `if` statement nodes the method will return a list containing the element `Tree#Kind#IF_STATEMENT`.

#### Create issues
Use these methods to log an issue:

* `JavaScriptCheck#addIssue(tree, message)` creates and returns an instance of `PreciseIssue`. In the SonarQube UI this issue will highlight all code corresponding to the tree passed as the first parameter. To add cost (effort to fix) or secondary locations provide these values to your just-created instance of `PreciseIssue`.
* `JavaScriptCheck#addIssue(issue)` creates and returns the instance of `Issue`. Use this method to create non-standard issues (e.g. for a file-level issue instantiate `FileIssue`).

#### Check context
Check context is provided by `DoubleDispatchVisitorCheck` or `SubscriptionVisitorCheck` by calling the `JavaScriptCheck#getContext` method. Check context provides you access to the root tree of the file, the file itself and the symbol model (information about variables).

#### Test rule
To test the rule you can use `JavaScriptCheckVerifier#verify()` or `JavaScriptCheckVerifier#issues()`. To be able to use these methods add a dependency to your project:
```
<dependency>
<groupId>org.sonarsource.javascript</groupId>
<artifactId>javascript-checks-testkit</artifactId>
<version>XXX</version>
<scope>test</scope>
</dependency>
```

### API Changes
#### SonarJS 4.2.1
* `CustomJavaScriptRulesDefinition` is deprecated. Implement extension `RulesDefinition` and `CustomRuleRepository` instead.

#### SonarJS 4.0
* Method `TreeVisitorContext#getFile()` is removed.

<!-- /sonarqube -->

## Related Pages

* [Test Coverage & Execution](/analysis/coverage/) (LCOV format)
* [Importing External Issues](/analysis/external-issues/) (ESLint)
* [SonarJS Plugin for ESLint](https://github.com/SonarSource/eslint-plugin-sonarjs)
<!-- sonarqube -->
* [Adding Coding Rules](/extend/adding-coding-rules/)
<!-- /sonarqube -->
This is a placeholder file. It is required for Gatsby, but its content will be dynamically replaced.

+ 1
- 9
server/sonar-docs/src/pages/analysis/languages/kotlin.md View File

@@ -3,12 +3,4 @@ title: Kotlin
url: /analysis/languages/kotlin/
---



## Language-Specific Properties

You can discover and update Kotlin-specific [properties](/analysis/analysis-parameters/) in: <!-- sonarcloud -->Project <!-- /sonarcloud -->**[Administration > General Settings > Kotlin](/#sonarqube-admin#/admin/settings?category=kotlin)**.

## Related Pages
* [Importing External Issues](/analysis/external-issues/) (AndroidLint and Detekt)
* [Test Coverage & Execution](/analysis/coverage/) (JaCoCo)
This is a placeholder file. It is required for Gatsby, but its content will be dynamically replaced.

+ 1
- 86
server/sonar-docs/src/pages/analysis/languages/php.md View File

@@ -3,89 +3,4 @@ title: PHP
url: /analysis/languages/php/
---



## Language-Specific Properties

Discover and update the PHP-specific [properties](/analysis/analysis-parameters/) in: <!-- sonarcloud -->Project <!-- /sonarcloud -->**[Administration > General Settings > PHP](/#sonarqube-admin#/admin/settings?category=php)**

## Analyze php.ini Files

The PHP analyzer can analyze `php.ini` files with some specific rules (if these rules are activated in your Quality Profile). `php.ini` files must be part of the project you are analyzing, meaning the `php.ini` files have to be inside the directories listed in `sonar.sources`.
Rules targeting `php.ini` files can be quickly identified through the ["php-ini"](https://rules.sonarsource.com/php/tag/php-ini) tag set on them.

<!-- sonarqube -->

## Custom Rules

### Overview

The PHP analyzer parses the source code, creates an Abstract Syntax Tree (AST) and then walks through the entire tree. A coding rule is a visitor that is able to visit nodes from this AST.

As soon as the coding rule visits a node, it can navigate its children and log issues if necessary.

### Example Plugin

To get started a sample plugin can be found here: [php-custom-rules](https://github.com/SonarSource/sonar-custom-rules-examples/tree/master/php-custom-rules).

### Writing a Plugin

Custom rules for PHP can be added by writing a SonarQube Plugin and using PHP analyzer APIs.
Here are the step to follow:

#### Create SonarQube Plugin

* create a standard SonarQube plugin project
* attach this plugin to the SonarQube PHP analyzer through the `pom.xml`:
* add the dependency to the PHP analyzer.
* add the following line in the sonar-packaging-maven-plugin configuration.
```
<basePlugin>php</basePlugin>
```
* implement the following extension points:
* [Plugin](http://javadocs.sonarsource.org/latest/apidocs/index.html?org/sonar/api/Plugin.html)
* [RulesDefinition](http://javadocs.sonarsource.org/latest/apidocs/index.html?org/sonar/api/server/rule/RulesDefinition.html) and [PHPCustomRuleRepository](https://github.com/SonarSource/sonar-php/blob/master/php-frontend/src/main/java/org/sonar/plugins/php/api/visitors/PHPCustomRuleRepository.java), which can be implemented by a single class, to declare your custom rules
* declare the RulesDefinition as an extension in the Plugin extension point.

#### Implement a Rule

* create a class that will hold the implementation of the rule, it should:
* extend `PHPVisitorCheck` or `PHPSubscriptionCheck`
* define the rule name, key, tags, etc. with Java annotations.
* declare this class in the `RulesDefinition`.

#### Implementation Details

**Using `PHPVisitorCheck`**

To explore a part of the AST, override a method from the PHPVisitorCheck. For example, if you want to explore "if statement" nodes, override [PHPVisitorCheck#visitIfStatement](https://github.com/SonarSource/sonar-php/blob/master/php-frontend/src/main/java/org/sonar/plugins/php/api/visitors/PHPVisitorCheck.java#L265) method that will be called each time an [ifStatementTree](https://github.com/SonarSource/sonar-php/blob/master/php-frontend/src/main/java/org/sonar/plugins/php/api/tree/statement/IfStatementTree.java) node is encountered in the AST.

[[warning]]
| When overriding a visit method, you must call the super method in order to allow the visitor to visit the children the node.

**Using `PHPSubscriptionCheck`**

To explore a part of the AST, override [`PHPSubscriptionCheck#nodesToVisit`](https://github.com/SonarSource/sonar-php/blob/master/php-frontend/src/main/java/org/sonar/plugins/php/api/visitors/PHPSubscriptionCheck.java#L33) by returning the list of the [`Tree#Kind`](https://github.com/SonarSource/sonar-php/blob/master/php-frontend/src/main/java/org/sonar/plugins/php/api/tree/Tree.java#L124) of node you want to visit. For example, if you want to explore "if statement" nodes the method will return a list containing the element [`Tree#Kind#IF_STATEMENT`](https://github.com/SonarSource/sonar-php/blob/master/php-frontend/src/main/java/org/sonar/plugins/php/api/tree/Tree.java#L761).

**Create Issues**

From the check, issue can be created by calling [`CheckContext#newIssue`](https://github.com/SonarSource/sonar-php/blob/master/php-frontend/src/main/java/org/sonar/plugins/php/api/visitors/CheckContext.java#L90) method.

**Testing Checks**

To test custom checks you can use method [`PHPCheckVerifier#verify`](https://github.com/SonarSource/sonar-php/blob/master/php-frontend/src/main/java/org/sonar/plugins/php/api/tests/PHPCheckVerifier.java#L55). You should end each line with an issue with a comment in the following form:

```
// Noncompliant {{Message}}
```

Comment syntax is described [here](https://github.com/SonarSource/sonar-analyzer-commons/blob/master/test-commons/README.md).

<!-- /sonarqube -->

## Related Pages

* [Test Coverage & Execution](/analysis/coverage/)
<!-- sonarqube -->
* [Adding Coding Rules](/extend/adding-coding-rules/)
<!-- /sonarqube -->
This is a placeholder file. It is required for Gatsby, but its content will be dynamically replaced.

+ 1
- 57
server/sonar-docs/src/pages/analysis/languages/pli.md View File

@@ -3,60 +3,4 @@ title: PLI
url: /analysis/languages/pli/
---

_PL/I analysis is available starting in [Enterprise Edition](https://redirect.sonarsource.com/editions/enterprise.html)._


## Language-Specific Properties

Discover and update the PL/I-specific properties in: **[Administration > General Settings > PL/I](/#sonarqube-admin#/admin/settings?category=pl%2Fi)**

## Source Code Extraction

In order to analyze your source code with SonarQube you need to first extract it onto a filesystem. You can use your own tool or an open source tool; SonarSource does not provide any connectors or source code extraction tools.

## Dealing with Includes

There are two possible ways to tell SonarQube where to retrieve the source code referenced by an %INCLUDE statement.

The following syntaxes are supported:

```
%INCLUDE 'C:/temp/myLib.pli'
%INCLUDE ddname(member);
%INCLUDE member; /* With member not enclosed within single or double quotes, i.e. a SYSLIB member */
```

Example:

If you want to interpret:

```
%INCLUDE O (XX02511) as %INCLUDE 'C:/temp/o/XX02511.99IPO';
%INCLUDE lib1 as %INCLUDE 'C:/temp/syslib/lib1.pli';
```

the Ddnames are defined as:

```
sonar.pli.includeDdnames=O,SYSLIB

sonar.pli.includeDdname.O.path=c:/temp/o
sonar.pli.includeDdname.O.suffix=.99IPO

sonar.pli.includeDdname.SYSLIB.path=c:/temp/syslib
sonar.pli.includeDdname.SYSLIB.suffix=.pli
```

Note that the following constructs, involving at least two members, are currently not supported:

```
%INCLUDE member1, member2;
%INCLUDE ddname1(member1), member2;
%INCLUDE member1, ddname1(member2);
%INCLUDE ddname1(member1), ddname2(member2);
```

## Related Pages
<!-- sonarqube -->
* [Adding Coding Rules](/extend/adding-coding-rules/)
<!-- /sonarqube -->
This is a placeholder file. It is required for Gatsby, but its content will be dynamically replaced.

+ 1
- 34
server/sonar-docs/src/pages/analysis/languages/plsql.md View File

@@ -3,37 +3,4 @@ title: PL/SQL
url: /analysis/languages/plsql/
---



## Language-Specific Properties

Discover and update the PL/SQL-specific [properties](/analysis/analysis-parameters/) in: <!-- sonarcloud -->Project <!-- /sonarcloud --> **[Administration > General Settings > PL/SQL](/#sonarqube-admin#/admin/settings?category=pl%2Fsql)**

## Advanced parameters

### Default Schema
Parameter | Description
--- | ---
`sonar.plsql.defaultSchema` | When a schema object (table, view, index, synonym) is referenced in SQL code without a schema prefix, the analyzer will assume that it belongs to this schema.


### Data Dictionary
Some rules raise issues only when a data dictionary is provided during analysis. To provide a data dictionary, you must define the following properties in the `sonar-project.properties` file or on the scanner command line using the  `-D` prefix:


|Parameter|Description|
| --- | --- |
|`sonar.plsql.jdbc.url`|URL of the JDBC connection. **Required for data dictionary lookup**. For example: `jdbc:oracle:thin:@my-oracle-server:1521/my-db`
|`sonar.plsql.jdbc.user`|JDBC user to authenticate the connection.
|`sonar.plsql.jdbc.password`|JDBC password provided to authenticate the connection.
|`sonar.plsql.jdbc.driver.path`|Path or URL of the Oracle jdbc driver jar.
|`sonar.plsql.jdbc.driver.class`|Java class name of the Oracle Driver. For example: `oracle.jdbc.OracleDriver`

Providing this configuration allows SonarPLSQL to query data dictionary views such as `SYS.ALL_TAB_COLUMNS` in order to to better analyze your SQL.


<!-- sonarqube -->
## Related Pages
* [Adding Coding Rules](/extend/adding-coding-rules/)
<!-- /sonarqube -->

This is a placeholder file. It is required for Gatsby, but its content will be dynamically replaced.

+ 1
- 103
server/sonar-docs/src/pages/analysis/languages/python.md View File

@@ -3,106 +3,4 @@ title: Python
url: /analysis/languages/python/
---



## Supported Versions
* Python 3.X
* Python 2.X

## Language-Specific Properties

Discover and update the Python-specific [properties](/analysis/analysis-parameters/) in: <!-- sonarcloud -->Project <!-- /sonarcloud --> **[Administration > General Settings > Python](/#sonarqube-admin#/admin/settings?category=python)**.

## Pylint
[Pylint](http://www.pylint.org/) is an external static source code analyzer, it can be used in conjunction with SonarPython.

You can enable Pylint rules directly in your Python Quality Profile. Their rule keys start with "*Pylint:*".

Once the rules are activated you should run Pylint and import its report:
```
pylint <module_or_package> -r n --msg-template="{path}:{line}: [{msg_id}({symbol}), {obj}] {msg}" > <report_file>
```
Then pass the generated report path to analysis via the `sonar.python.pylint.reportPath` property.

<!-- sonarqube -->

## Custom Rules

### Overview

The Python analyzer parses the source code, creates an Abstract Syntax Tree (AST) and then walks through the entire tree. A coding rule is a visitor that is able to visit nodes from this AST.

As soon as the coding rule visits a node, it can navigate its children and log issues if necessary.

### Writing a Plugin

Custom rules for Python can be added by writing a SonarQube Plugin and using Python analyzer APIs.
Here are the step to follow:

#### Create SonarQube Plugin

* create a standard SonarQube plugin project
* attach this plugin to the SonarQube Python analyzer through the `pom.xml`:
* add the dependency to the Python analyzer.
* add the following line in the sonar-packaging-maven-plugin configuration.
```
<requirePlugins>python:2.0-SNAPSHOT</requirePlugin>
```
* implement the following extension points:
* [Plugin](http://javadocs.sonarsource.org/latest/apidocs/org/sonar/api/Plugin.html)
* [RulesDefinition](http://javadocs.sonarsource.org/latest/apidocs/org/sonar/api/server/rule/RulesDefinition.html) and [PythonCustomRuleRepository](https://github.com/SonarSource/sonar-python/blob/master/python-frontend/src/main/java/org/sonar/plugins/python/api/PythonCustomRuleRepository.java), which can be implemented by a single class, to declare your custom rules
* declare the RulesDefinition as an extension in the Plugin extension point.

#### Implement a Rule

* create a class that will hold the implementation of the rule, it should:
* extend `PythonCheckTree` or `PythonSubscriptionCheck`
* define the rule name, key, tags, etc. with Java annotations.
* declare this class in the `RulesDefinition`.

### Example Plugin

To get started a sample plugin can be found here: [python-custom-rules](https://github.com/SonarSource/sonar-custom-rules-examples/tree/master/python-custom-rules).

#### Implementation Details

**Using `PythonCheckTree`**

To explore a part of the AST, override a method from the PythonCheckTree. For example, if you want to explore "if statement" nodes, override [PythonCheckTree#visitIfStatement](https://github.com/SonarSource/sonar-python/blob/39b6126e9fdef42b93004cf6cc5818e861051334/python-frontend/src/main/java/org/sonar/plugins/python/api/tree/BaseTreeVisitor.java#L56) method that will be called each time an [ifStatement](https://github.com/SonarSource/sonar-python/blob/master/python-frontend/src/main/java/org/sonar/plugins/python/api/tree/IfStatement.java) node is encountered in the AST.

[[warning]]
| When overriding a visit method, you must call the super method in order to allow the visitor to visit the children the node.

**Using `PythonSubscriptionCheck`**

To explore a part of the AST, override [`PythonSubscriptionCheck#initialize`](https://github.com/SonarSource/sonar-python/blob/master/python-frontend/src/main/java/org/sonar/plugins/python/api/SubscriptionCheck.java#L26) and call the [`SubscriptionCheck.Context#registerSyntaxNodeConsumer`](https://github.com/SonarSource/sonar-python/blob/master/python-frontend/src/main/java/org/sonar/plugins/python/api/SubscriptionCheck.java) with the [`Tree#Kind`](https://github.com/SonarSource/sonar-python/blob/master/python-frontend/src/main/java/org/sonar/plugins/python/api/tree/Tree.java#L42) of node you want to visit. For example, if you want to explore "if statement" you should register to the kind [`Tree#Kind#IF_STATEMENT`](https://github.com/SonarSource/sonar-python/blob/master/python-frontend/src/main/java/org/sonar/plugins/python/api/tree/Tree.java#L97) and then provide a lambda that will consume a [`SubscriptionContext`](https://github.com/SonarSource/sonar-python/blob/master/python-frontend/src/main/java/org/sonar/plugins/python/api/SubscriptionContext.java#L27) to act on such ndoes.

**Create Issues**

From the check, issue can be created by calling [`SubscriptionContext#addIssue`](https://github.com/SonarSource/sonar-python/blob/master/python-frontend/src/main/java/org/sonar/plugins/python/api/SubscriptionContext.java#L30) method or [`PythonCheckTree#addIssue`](https://github.com/SonarSource/sonar-python/blob/master/python-frontend/src/main/java/org/sonar/plugins/python/api/PythonCheckTree.java#L36) method.

**Testing Checks**

To test custom checks you can use method [`PythonCheckVerifier#verify`](https://github.com/SonarSource/sonar-python/blob/master/python-checks-testkit/src/main/java/org/sonar/python/checks/utils/PythonCheckVerifier.java). Don't forget to add the testkit dependency to access this class from your project :
```
<dependency>
<groupId>org.sonarsource.python</groupId>
<artifactId>python-checks-testkit</artifactId>
<version>${project.version}</version>
<scope>test</scope>
</dependency>
```

You should end each line with an issue with a comment in the following form:

```
# Noncompliant {{Message}}
```

Comment syntax is described [here](https://github.com/SonarSource/sonar-analyzer-commons/blob/master/test-commons/README.md).

<!-- /sonarqube -->

## Related Pages
* [Importing External Issues](/analysis/external-issues/) ([Pylint](http://www.pylint.org/), [Bandit](https://github.com/PyCQA/bandit/blob/master/README.rst))
* [Test Coverage & Execution](/analysis/coverage/) (the [Coverage Tool](http://nedbatchelder.com/code/coverage/) provided by [Ned Batchelder](http://nedbatchelder.com/), [Nose](https://nose.readthedocs.org/en/latest/), [pytest](https://docs.pytest.org/en/latest/))
This is a placeholder file. It is required for Gatsby, but its content will be dynamically replaced.

+ 1
- 84
server/sonar-docs/src/pages/analysis/languages/rpg.md View File

@@ -3,87 +3,4 @@ title: RPG
url: /analysis/languages/rpg/
---

_RPG analysis is available starting in [Enterprise Edition](https://redirect.sonarsource.com/editions/enterprise.html)._


## Language-Specific Properties

Discover and update the RPG-specific [properties](/analysis/analysis-parameters/) in: **[Administration > General Settings > RPG](/#sonarqube-admin#/admin/settings?category=rpg)**

## Source Code Extraction

In order to analyze your source code with SonarQube you need to first extract it onto a filesystem. You can use your own tool or an open source tool; SonarSource does not provide any connectors or source code extraction tools.

## RPG Source Format

Depending on your extraction process, your RPG source files may include an extra margin on the left of the 80 columns used for code. This margin is in addition to the standard margin which takes up characters 1-5 in the 80-character source format. The extra margin is controlled through the `sonar.rpg.leftMarginWidth` property. By default, it is set to 12, which is the size of the margin in an IBM “source physical file”. If your RPG source files do not contain such a margin, you should set `sonar.rpg.leftMarginWidth` to `0`.

You can find an [example file](https://raw.githubusercontent.com/SonarSource/sonar-scanning-examples/master/sonarqube-scanner/src/rpg/MYPROGRAM.rpg) illustrating a 12-character margin in our sample project.

You should also make sure to set `sonar.sourceEncoding` to the appropriate encoding. Please check the [documentation of this property](/analysis/analysis-parameters/).

## Free-Form Support

Free-form is supported for C-specs and SQL statements. Free-form is not yet supported for H, F, D and P specs (which were [added in IBM i 7.2](http://www-01.ibm.com/support/knowledgecenter/ssw_ibm_i_72/rzasd/rpgrelv7r2.htm)).

## Custom Rules for RPG

To get started you can [browse](https://github.com/SonarSource/sonar-custom-rules-examples/tree/master/rpg-custom-rules) or [download](https://github.com/SonarSource/sonar-custom-rules-examples/archive/master.zip) a simple plugin.

### Pre-requisites

- JDK 8
- SonarRPG 2.0+

### Creating a Maven Project

You should first create a Maven project: re-using the [pom.xml from the RPG example](https://github.com/SonarSource/sonar-custom-rules-examples/blob/master/rpg-custom-rules/pom.xml) is a good start.

The following dependencies need to be defined in the pom.xml:

- `sonar-plugin-api` to get access to SonarQube APIs
- `sonar-rpg-plugin` to use the APIs of the RPG plugin

### Writing a Custom Rule

Each rule needs to be defined in a class which:

- Implements [`com.sonarsource.rpg.api.checks.Check`](http://javadocs.sonarsource.org/rpg/apidocs/2.3/index.html?com/sonarsource/rpg/api/checks/Check.html). Instead of implementing this interface directly, the class can also extend [`VisitorBasedCheck`](http://javadocs.sonarsource.org/rpg/apidocs/2.3/index.html?com/sonarsource/rpg/api/checks/Check.html?com/sonarsource/rpg/api/checks/VisitorBasedCheck.html) which makes it easier to target some specific parts of the analyzed source code.
- Has an `org.sonar.check.Rule` annotation to define the key of the rule.

#### Navigating the Syntax Tree

The analyzed source code is represented as a tree structure. The top-most tree is an instance of [`ModuleTree`](http://javadocs.sonarsource.org/rpg/apidocs/2.3/index.html?com/sonarsource/rpg/api/checks/Check.html?com/sonarsource/rpg/api/tree/ModuleTree.html) which has references to other trees. Some of the trees represent a group of RPG calculations (for example, an `IF` group is represented as a tree which references the calculations which are executed when the condition is true), some others represent expressions such as `a + b`.

The instance of [`CheckContext`](http://javadocs.sonarsource.org/rpg/apidocs/2.3/index.html?com/sonarsource/rpg/api/checks/Check.html?com/sonarsource/rpg/api/checks/CheckContext.html) which is passed to the checks gives a reference to the `ModuleTree` of the analyzed source code. The whole tree structure can be navigated from that object.

Most often, it's easier to extend `VisitorBasedCheck` and to override one or more methods which name starts with visit, e.g. `visitIfGroup`. That way, it's possible to define what should be executed when visiting some specific kinds of trees.

#### Creating Issues

[`CheckContext`](http://javadocs.sonarsource.org/rpg/apidocs/2.3/index.html?com/sonarsource/rpg/api/checks/Check.html?com/sonarsource/rpg/api/checks/CheckContext.html) provides methods to create issues either at file level or at line level.

#### Testing the Rule

It's possible to write unit tests for custom rules using `com.sonarsource.rpg.api.test.RpgCheckVerifier`. This utility class executes a custom rule against a given RPG test file. The RPG test file should contain comments denoting lines where issues should be expected:

- if the line ends with "// Noncompliant", `RpgCheckVerifier` expects an issue on that line.
- if the line ends with "// Noncompliant {{my message}}", `RpgCheckVerifier` expects an issue on that line and checks that the issue message is "my message".

The example project contains an [example test class](https://github.com/SonarSource/sonar-custom-rules-examples/blob/master/rpg-custom-rules/src/test/java/com/sonarsource/rpg/example/checks/DataStructureNamingConventionCheckTest.java) and the [associated RPG file](https://github.com/SonarSource/sonar-custom-rules-examples/blob/master/rpg-custom-rules/src/test/resources/data-structure-name.rpg).

### Rules Definition

One class should extend [`com.sonarsource.rpg.api.CustomRulesDefinition`](http://javadocs.sonarsource.org/rpg/apidocs/2.3/index.html?com/sonarsource/rpg/api/checks/Check.html?com/sonarsource/rpg/api/CustomRulesDefinition.html): it should list the classes of the custom rules and use the SonarQube API to define the metadata of these rules: name, HTML description, default severity...

### Plugin Class

The entry point of the custom plugin is a class which lists SonarQube extensions. This list should contain the class created at the previous step.

### Packaging the Custom Plugin

To package your custom plugin, the pom.xml should use `org.sonarsource.sonar-packaging-maven-plugin`, as described in the [documentation explaining how to build a plugin](/extend/developing-plugin/).

In the configuration for `sonar-packaging-maven-plugin`, basePlugin should be set to "rpg".

Building the Maven project will produce a JAR file which can be deployed to a SonarQube server.
This is a placeholder file. It is required for Gatsby, but its content will be dynamically replaced.

+ 1
- 9
server/sonar-docs/src/pages/analysis/languages/ruby.md View File

@@ -3,12 +3,4 @@ title: Ruby
url: /analysis/languages/ruby/
---



## Language-Specific Properties

Discover and update the Ruby-specific [properties](/analysis/analysis-parameters/) in: <!-- sonarcloud -->Project <!-- /sonarcloud --> **[Administration > General Settings > Ruby](/#sonarqube-admin#/admin/settings?category=ruby)**

## Related Pages
* [Importing External Issues](/analysis/external-issues/) (Rubocop)
* [Test Coverage & Execution](/analysis/coverage/) (SimpleCov)
This is a placeholder file. It is required for Gatsby, but its content will be dynamically replaced.

+ 1
- 9
server/sonar-docs/src/pages/analysis/languages/scala.md View File

@@ -3,12 +3,4 @@ title: Scala
url: /analysis/languages/scala/
---



## Language-Specific Properties

Discover and update the Scala-specific [properties](/analysis/analysis-parameters/) in: <!-- sonarcloud -->Project <!-- /sonarcloud --> **[Administration > General Settings > Scala](/#sonarqube-admin#/admin/settings?category=scala)**.

## Related Pages
* [Importing External Issues](/analysis/external-issues/) (Scalastyle or Scapegoat)
* [Test Coverage & Execution](/analysis/coverage/) (Scoverage)
This is a placeholder file. It is required for Gatsby, but its content will be dynamically replaced.

+ 1
- 9
server/sonar-docs/src/pages/analysis/languages/swift.md View File

@@ -3,12 +3,4 @@ title: Swift
url: /analysis/languages/swift/
---



## Language-Specific Properties

Discover and update the Swift-specific [properties](/analysis/analysis-parameters/) in: <!-- sonarcloud -->Project <!-- /sonarcloud --> **[Administration > General Settings > Swift](/#sonarqube-admin#/admin/settings?category=swift)**.

## Related Pages
* [Importing External Issues](/analysis/external-issues/) (Xcode A.K.A. ProfData)
* [Test Coverage & Execution](/analysis/coverage/) (SwiftLint)
This is a placeholder file. It is required for Gatsby, but its content will be dynamically replaced.

+ 1
- 9
server/sonar-docs/src/pages/analysis/languages/tsql.md View File

@@ -3,12 +3,4 @@ title: T-SQL
url: /analysis/languages/tsql/
---



## Language-Specific Properties

Discover and update the T-SQL-specific [properties](/analysis/analysis-parameters/) in: <!-- sonarcloud -->Project <!-- /sonarcloud -->**[Administration > General Settings > T-SQL](/#sonarqube-admin#/admin/settings?category=t-sql)**.

## Important Note
With the default configuration, only files with the `.tsql` are analyzed as T-SQL, and files with the `.sql` file extension are analyzed as PL/SQL. This behavior is defined in <!-- sonarcloud -->Project <!-- /sonarcloud -->**[Administration > General Settings > T-SQL > File Suffixes](/#sonarqube-admin#/admin/settings?category=t-sql)** and <!-- sonarcloud -->Project <!-- /sonarcloud -->**[Administration > General Settings > PL/SQL > File Suffixes](/#sonarqube-admin#/admin/settings?category=pl%2Fsql)**. You can override these properties <!-- sonarqube -->either at server level or<!-- /sonarqube --> at project level.

This is a placeholder file. It is required for Gatsby, but its content will be dynamically replaced.

+ 1
- 6
server/sonar-docs/src/pages/analysis/languages/vb6.md View File

@@ -3,9 +3,4 @@ title: VB6
url: /analysis/languages/vb6/
---

_VB6 analysis is available starting in [Enterprise Edition](https://redirect.sonarsource.com/editions/enterprise.html)._


## Language-Specific Properties

You can discover and update VB6-specific [properties](/analysis/analysis-parameters/) in: <!-- sonarcloud -->Project <!-- /sonarcloud -->**[Administration > General Settings > Visual Basic](/#sonarqube-admin#/admin/settings?category=visual+basic)**.
This is a placeholder file. It is required for Gatsby, but its content will be dynamically replaced.

+ 1
- 19
server/sonar-docs/src/pages/analysis/languages/vbnet.md View File

@@ -3,22 +3,4 @@ title: VB.NET
url: /analysis/languages/vbnet/
---



## Language-Specific Properties

Discover and update the VB.NET-specific [properties](/analysis/analysis-parameters/) in: <!-- sonarcloud -->Project <!-- /sonarcloud --> **[Administration > General Settings > VB.NET](/#sonarqube-admin#/admin/settings?category=vb.net)**

### Analyze Generated Code

To analyze tool-generated code (e.g. WCF code generated by `SvcUtil.exe`) for a specific VB.NET project, enable the "Analyze generated code" setting inside **Project > Administration > General Settings > VB.NET**. By default, tool-generated code files are skipped from analysis.

## Known Limitations
Currently an error will be thrown when an issue is raised on a line of code containing the following pattern `\s+error\s*:` (i.e. one or more spaces, the string 'error', zero or more spaces and a ':' ) . This is a well known problem on the Microsoft side (see [issue](https://github.com/dotnet/roslyn/issues/5724/)). In order to work around this problem, our analyzer will skip issues reported on any line where the pattern is detected.


## Related Pages
* [Importing External Issues](/analysis/external-issues/) (VSTest, NUnit, MSTest, xUnit)
* [Test Coverage & Execution](/analysis/coverage/) (Visual Studio Code Coverage, dotCover, OpenCover, Coverlet, NCover 3)
* [SonarScanner for MSBuild](/analysis/scan/sonarscanner-for-msbuild/)
* [SonarScanner for Azure DevOps](/analysis/scan/sonarscanner-for-azure-devops/)
This is a placeholder file. It is required for Gatsby, but its content will be dynamically replaced.

+ 1
- 10
server/sonar-docs/src/pages/analysis/languages/xml.md View File

@@ -3,13 +3,4 @@ title: XML
url: /analysis/languages/xml/
---



## Language-Specific Properties

Discover and update the XML-specific [properties](/analysis/analysis-parameters/) in: <!-- sonarcloud -->Project <!-- /sonarcloud -->**[Administration > General Settings > XML](/#sonarqube-admin#/admin/settings?category=xml)**

<!-- sonarqube -->
## Related Pages
* [Adding Coding Rules](/extend/adding-coding-rules/)
<!-- /sonarqube -->
This is a placeholder file. It is required for Gatsby, but its content will be dynamically replaced.

Write Preview
Loading…
Cancel
Save