diff options
| author | Elena Vilchik <elena.vilchik@sonarsource.com> | 2019-06-03 13:52:05 +0200 |
|---|---|---|
| committer | SonarTech <sonartech@sonarsource.com> | 2019-06-03 20:21:17 +0200 |
| commit | 3719149e27fe217939d27cd0995535a4324a8f5f (patch) | |
| tree | debdad0b791b1b00661995c425a5bf31e4ef71ac | |
| parent | c1c4796d937a9b4307d71519024dcfc46ef082f3 (diff) | |
| download | sonarqube-3719149e27fe217939d27cd0995535a4324a8f5f.tar.gz sonarqube-3719149e27fe217939d27cd0995535a4324a8f5f.zip | |
SONAR-12168 Define embedded documentation for languages (#1592)
41 files changed, 1759 insertions, 64 deletions
diff --git a/server/sonar-docs/README.md b/server/sonar-docs/README.md index 7c885ca6431..89646417296 100644 --- a/server/sonar-docs/README.md +++ b/server/sonar-docs/README.md @@ -27,13 +27,8 @@ yarn ## Each time -Rebuild and start your SonarQube server (yarn needs this running) +Start a SonarQube server (yarn needs this running). -``` -cd sonar-enterprise/ -./build.sh -x test -x obfuscate -./start.sh -``` To start the SonarQube Embedded docs dev server on port 3000: @@ -169,11 +164,6 @@ You can also use these comments inline: this content is displayed on <!-- sonarcloud -->SonarCloud<!-- /sonarcloud --><!-- sonarqube -->SonarQube<!-- /sonarqube --> ``` -### Page-level ToC - -All h2 tags will automatically be part of the TOC both in the static and embed documentation. -The resulting table of contents will also list all h1 items, but h1 is used for the page title, and by convention should not also be used further down the page. - ### Formatting #### Links diff --git a/server/sonar-docs/src/pages/analysis/coverage.md b/server/sonar-docs/src/pages/analysis/coverage.md index 3c05f14249e..5acd676572a 100644 --- a/server/sonar-docs/src/pages/analysis/coverage.md +++ b/server/sonar-docs/src/pages/analysis/coverage.md @@ -5,7 +5,9 @@ url: /analysis/coverage/ This page lists analysis parameters related to test coverage and execution reports. For more other parameters, see [Analysis Parameters](/analysis/analysis-parameters/). -SonarSource analyzers do not run your tests or generate reports. They only import pre-generated reports. Below you'll find language- and tool-specific analysis parameters for importing coverage and execution reports. For information on generating reports, see the language-specific information in the analyzers' subdirectories [here](https://docs.sonarqube.org/display/PLUG/SonarSource+Plugins). +SonarSource analyzers do not run your tests or generate reports. They only import pre-generated reports. Below you'll find language- and tool-specific analysis parameters for importing coverage and execution reports. + +In the [Guides](https://community.sonarsource.com/c/announce/guides) category of the [SonarSource Community forum](https://community.sonarsource.com/) you might find instructions on generating these reports. Some properties support the following wildcards in paths. The remarks for properties that support wildcards will mention that fact. If the remarks do not say wildcards are supported, then they are not.: @@ -25,9 +27,9 @@ Language|Property|Remarks **Any**|`sonar.coverageReportPaths`|Path to coverage report in the [Generic Test Data](/analysis/generic-test/) format. Apex|`sonar.apex.coverage.reportPath`|Path to the `test-result-codecoverage.json` report file generated by the [`apex:test:run`](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_force_apex.htm?search_text=apex%20test#cli_reference_test_run) command of the [Salesforce CLI](https://developer.salesforce.com/tools/sfdxcli). Note, you must have a [Salesforce DX project](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_workspace_setup.htm) set up and linked to your Org C / C++ / Objective-C|`sonar.cfamily.gcov.reportsPath`|Path to the directory containing native `*.gcov` reports (not the XML reports generated by gcovr) -C / C++ / Objective-C|`sonar.cfamily.llvm-cov.reportPath`| +C / C++ / Objective-C|`sonar.cfamily.llvm-cov.reportPath`| Path to a llvm-cov report C / C++ / Objective-C|`sonar.cfamily.vscoveragexml.reportsPath`|Path may be absolute or relative to the solution directory. Path wildcards (see above) are supported. Note that the `.coveragexml` report format offered by Visual Studio is not supported. -C / C++ / Objective-C|`sonar.cfamily.bullseye.reportPath`|Reports from Bullseye versions 8.9.59 to 8.9.62 are not supported because of format imcompatibility. +C / C++ / Objective-C|`sonar.cfamily.bullseye.reportPath`| Path to the report from Bullseye, version >= 8.9.63 (use [covxml](http://www.bullseye.com/help/ref-covxml.html) tool) C#|`sonar.cs.vscoveragexml.reportsPaths`|Path to Visual Studio Code Coverage report. Multiple paths may be comma-delimited, or included via wildcards. See _Notes on importing .NET reports_ below. C#|`sonar.cs.dotcover.reportsPaths`|Path to dotCover coverage report. See _Notes on importing .NET reports_ below. C#|`sonar.cs.opencover.reportsPaths`|Path to OpenCover coverage report. See _Notes on importing .NET reports_ below. @@ -54,13 +56,14 @@ Unless otherwise specified, these properties require values that are relative to Language|Property|Remarks ---|---|--- **All**|`sonar.testExecutionReportPaths`|Comma-delimited list of paths to execution reports in the [Generic Execution Data](/analysis/generic-test/) format. -C / C++ / Objective-C|`sonar.cfamily.cppunit.reportsPath`|Path to the directory holding the CPPUnit reports. Note that while measures such as the number of tests are displayed at project level, no drilldown is available. +C / C++ / Objective-C|`sonar.cfamily.cppunit.reportsPath`|Path to the directory holding the [CPPUnit](http://sourceforge.net/projects/cppunit/) reports. Note that while measures such as the number of tests are displayed at project level, no drilldown is available. C#|`sonar.cs.vstest.reportsPaths`|Paths to VSTest reports. Multiple paths may be comma-delimited, or included via wildcards. Note that while measures such as the number of tests are displayed at project level, no drilldown is available. C#|`sonar.cs.nunit.reportsPaths`|Paths to NUnit execution reports. Multiple paths may be comma-delimited, or included via wildcards. Note that while measures such as the number of tests are displayed at project level, no drilldown is available. C#|`sonar.cs.mstest.reportsPaths`|Paths to MSTest execution reports. Multiple paths may be comma-delimited, or included via wildcards. Note that while measures such as the number of tests are displayed at project level, no drilldown is available. C#|`sonar.cs.xunit.reportsPaths`|Paths to xUnit execution reports. Multiple paths may be comma-delimited, or included via wildcards. Note that while measures such as the number of tests are displayed at project level, no drilldown is available. Go|`sonar.go.tests.reportPaths`|Comma-delimited list of paths to unit test report files. Paths may be absolute or relative to project root. Java|`sonar.junit.reportPaths`|Comma-delimited list of paths to Surefire XML-format reports. +JavaScript| |You can use [jest-sonar-reporter](https://www.npmjs.com/package/jest-sonar-reporter) or[karma-sonarqube-unit-reporter](https://github.com/tornaia/karma-sonarqube-unit-reporter) to create reports in the [Generic Execution Data](/analysis/generic-test/) format. Both packages are available on npm. PHP|`sonar.php.tests.reportPath`|Path to the PHPUnit unit test execution report file. Path may be absolute or relative to project root. Python|`sonar.python.xunit.reportPath`|Path to unit test execution report. Leave unset to use the default (`xunit-reports/xunit-result-*.xml`). Path wildcards (see above) are supported. If any paths in the report are invalid, set `sonar.python.xunit.skipDetails=true` to collect only project-level details. TypeScript| |You can use [jest-sonar-reporter](https://www.npmjs.com/package/jest-sonar-reporter) or[karma-sonarqube-unit-reporter](https://github.com/tornaia/karma-sonarqube-unit-reporter) to create reports in the [Generic Execution Data](/analysis/generic-test/) format. Both packages are available on npm. diff --git a/server/sonar-docs/src/pages/analysis/external-issues.md b/server/sonar-docs/src/pages/analysis/external-issues.md index 20315f53627..fa08e6ec83c 100644 --- a/server/sonar-docs/src/pages/analysis/external-issues.md +++ b/server/sonar-docs/src/pages/analysis/external-issues.md @@ -5,7 +5,9 @@ url: /analysis/external-issues/ This page lists analysis parameters related to the import of issues raised by external, third-party analyzers. For more other parameters, see [Analysis Parameters](/analysis/analysis-parameters/). -SonarSource analyzers do not run your external analyzers or generate reports. They only import pre-generated reports. Below you'll find language- and tool-specific analysis parameters for importing reports generated by external analzyers. Additional language-specific details on some external analyzers can be found in the subdirectories for the relevant SonarSource language analyzers [here](https://docs.sonarqube.org/display/PLUG/SonarSource+Plugins). +SonarSource analyzers do not run your external analyzers or generate reports. They only import pre-generated reports. Below you'll find language- and tool-specific analysis parameters for importing reports generated by external analyzers. + +In the [Guides](https://community.sonarsource.com/c/announce/guides) category of the [SonarSource Community forum](https://community.sonarsource.com/) you might find instructions on generating these reports. Some properties support the following wildcards in paths. The remarks for properties that support wildcards will mention that fact. If the remarks do not say wildcards are supported, then they are not.: @@ -19,7 +21,7 @@ Unless otherwise specified, the following properties accept both absolute paths Langauge|Property|Remarks ----|----|---- -Apex|`sonar.apex.pmd.reportPaths`|Comma-delimited list of paths to [PMD Apex](https://pmd.github.io/pmd-5.5.7/pmd-apex/rules/index.html) reports| +Apex|`sonar.apex.pmd.reportPaths`|Comma-delimited list of paths to [PMD Apex](https://pmd.github.io/pmd-5.5.7/pmd-apex/rules/index.html) [XML reports](https://pmd.github.io/latest/pmd_userdocs_installation.html#running-pmd-via-command-line)| CSS|`sonar.css.stylelint.reportPaths`|Comma-delimited list of paths to [StyleLint.io](https://stylelint.io/) reports| Go|`sonar.go.govet.reportPaths`|Comma-delimited list of paths to [GoVet](https://golang.org/cmd/vet/) reports| Go|`sonar.go.golint.reportPaths`|Comma-delimited list of paths to [GoLint](https://github.com/golang/lint) reports| @@ -27,7 +29,7 @@ Go|`sonar.go.gometalinter.reportPaths`|Comma-delimited list of paths to [GoMetaL Java|`sonar.java.spotbugs.reportPaths`|Comma-delimited list of paths to reports from [SpotBugs](https://spotbugs.github.io/), FindSecBugs, or FindBugs| Java|`sonar.java.pmd.reportPaths`|Comma-delimited list of paths to reports from [PMD](http://maven.apache.org/plugins/maven-pmd-plugin/usage.html) Java|`sonar.java.checkstyle.reportPaths`|Comma-delimited list of paths to reports from [Checkstyle](http://maven.apache.org/plugins/maven-checkstyle-plugin/checkstyle-mojo) -JavaScript|`sonar.eslint.reportPaths`|Comma-delimited list of paths to JSON ESLint reports +JavaScript|`sonar.eslint.reportPaths`|Comma-delimited list of paths to JSON [ESLint](https://eslint.org/) reports (use `-f json` ESLint option) Kotlin|`sonar.androidLint.reportPaths`|Comma-delimited list of paths to AndroidLint reports Kotlin|`sonar.kotlin.detekt.reportPaths`|Comma-delimited list of paths to [Detekt](https://github.com/arturbosch/detekt) reports Python|`sonar.python.pylint`|Path to a [Pylint](http://www.pylint.org/) report. Wildcards are supported| @@ -37,14 +39,14 @@ Ruby|`sonar.ruby.rubocop.reportPaths`|Comma-delimited list of paths to [Rubocop] Scala|`sonar.scala.scalastyle.reportPaths`|Comma-delimited list of paths to [Scalastyle](http://www.scalastyle.org/) reports Scala|`sonar.scala.scapegoat.reportPaths`|Comma-delimited list of paths to [Scapegoat](https://github.com/sksamuel/scapegoat) reports in the **Scalastyle format** Swift|`sonar.swift.swiftLint.reportPaths`|Comma-delimited list of paths to [SwiftLint](https://github.com/realm/SwiftLint) reports in JSON format -TypeScript|`sonar.typescript.tslint.reportPaths`|Comma-delimited list of paths to TSLint reports in JSON format| +TypeScript|`sonar.typescript.tslint.reportPaths`|Comma-delimited list of paths to [TSLint](https://palantir.github.io/tslint/) reports in JSON format (use `-t json` TSLint option)| **Notes on external .NET issues** Issues from third-party analyzers are included in the MSBuild output and imported by default into {instance}, so no properties exist to enable that behavior. Instead, properties are available to adjust the import and to _stop_ importing those issues. Note that Roslyn issues with an *error* severity automatically fail the build, and it is not recommended to run the Scanner for MSBuild's end step if the MSBuild step fails for any reason because it will result in an essentially empty analysis, which will close all outstanding issues in the project. -Langauge|Property|Remarks +Language|Property|Remarks ----|----|---- C#|`sonar.cs.roslyn.ignoreIssues`|Set to `true` to disable import of external issues. Defaults to `false`. C#|`sonar.cs.roslyn.bugCategories` `sonar.cs.roslyn.vulnerabilityCategories` `sonar.cs.roslyn.codeSmellCategories`|Comma-delimited list of categories whose issues should be classified as Bugs, Vulnerabilities, or Code Smells. diff --git a/server/sonar-docs/src/pages/analysis/languages/abap.md b/server/sonar-docs/src/pages/analysis/languages/abap.md new file mode 100644 index 00000000000..799833548eb --- /dev/null +++ b/server/sonar-docs/src/pages/analysis/languages/abap.md @@ -0,0 +1,25 @@ +--- +title: ABAP +url: /analysis/languages/abap/ +--- + +<!-- sonarqube --> + +_ABAP is available as part of [Developer Edition](https://redirect.sonarsource.com/editions/developer.html) and [above](https://redirect.sonarsource.com/editions/editions.html)._ + +<!-- /sonarqube --> + +<!-- static --> + +[[info]] +| <iframe src="http://update.sonarsource.org/plugins/abap-confluence-include.html" height="125px">Your browser does not support iframes.</iframe> + +<!-- /static --> + +## 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. diff --git a/server/sonar-docs/src/pages/analysis/languages/apex.md b/server/sonar-docs/src/pages/analysis/languages/apex.md new file mode 100644 index 00000000000..0445bcefebd --- /dev/null +++ b/server/sonar-docs/src/pages/analysis/languages/apex.md @@ -0,0 +1,26 @@ +--- +title: Apex +url: /analysis/languages/apex/ +--- + +<!-- sonarqube --> + +_Apex analysis is available as part of the [Enterprise Edition](https://redirect.sonarsource.com/editions/enterprise.html) and [above](https://redirect.sonarsource.com/editions/editions.html)._ + +<!-- /sonarqube --> + +<!-- static --> + +[[info]] +| <iframe src="http://update.sonarsource.org/plugins/sonarapex-confluence-include.html" height="125px">Your browser does not support iframes.</iframe> + +<!-- /static --> + +## 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) diff --git a/server/sonar-docs/src/pages/analysis/languages/cfamily.md b/server/sonar-docs/src/pages/analysis/languages/cfamily.md new file mode 100644 index 00000000000..1eb17766744 --- /dev/null +++ b/server/sonar-docs/src/pages/analysis/languages/cfamily.md @@ -0,0 +1,134 @@ +--- +title: C/C++/Objective-C +url: /analysis/languages/cfamily/ +--- + +<!-- sonarqube --> +_C/C++/Objective-C analysis is available as part of [Developer Edition](https://redirect.sonarsource.com/editions/developer.html) and [above](https://redirect.sonarsource.com/editions/editions.html)._ +<!-- /sonarqube --> + +<!-- static --> +[[info]] +| <iframe src="http://update.sonarsource.org/plugins/cpp-confluence-include.html" height="125px">Your browser does not support iframes.</iframe> +<!-- /static --> + + +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) diff --git a/server/sonar-docs/src/pages/analysis/languages/cobol.md b/server/sonar-docs/src/pages/analysis/languages/cobol.md new file mode 100644 index 00000000000..f8c8e3f21f7 --- /dev/null +++ b/server/sonar-docs/src/pages/analysis/languages/cobol.md @@ -0,0 +1,323 @@ +--- +title: COBOL +url: /analysis/languages/cobol/ +--- + +<!-- sonarqube --> + +_Cobol analysis is available as part of the [Enterprise Edition](https://redirect.sonarsource.com/editions/enterprise.html) and [above](https://redirect.sonarsource.com/editions/editions.html)._ + +<!-- /sonarqube --> + +<!-- static --> + +[[info]] +| <iframe src="http://update.sonarsource.org/plugins/cobol-confluence-include.html" height="125px">Your browser does not support iframes.</iframe> + +<!-- /static --> + +## 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 +``` + +Note that it is possible to analyze a cobol project without file suffixes, and for projects without suffixes, the two suffix-related properties are not required. E.G.: + +``` +sonar.sources=cobol,copy1,commonCopy +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 +``` + +### 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`. + 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 --> diff --git a/server/sonar-docs/src/pages/analysis/languages/csharp.md b/server/sonar-docs/src/pages/analysis/languages/csharp.md new file mode 100644 index 00000000000..0d8ecf65b8e --- /dev/null +++ b/server/sonar-docs/src/pages/analysis/languages/csharp.md @@ -0,0 +1,18 @@ +--- +title: C# +url: /analysis/languages/csharp/ +--- + +<!-- static --> +[[info]] +| <iframe src="http://update.sonarsource.org/plugins/csharp-confluence-include.html" height="125px">Your browser does not support iframes.</iframe> +<!-- /static --> + + +## 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)**. + +## 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) diff --git a/server/sonar-docs/src/pages/analysis/languages/css.md b/server/sonar-docs/src/pages/analysis/languages/css.md new file mode 100644 index 00000000000..2fe4bc5a5cf --- /dev/null +++ b/server/sonar-docs/src/pages/analysis/languages/css.md @@ -0,0 +1,22 @@ +--- +title: CSS +url: /analysis/languages/css/ +--- + +<!-- static --> +[[info]] +| <iframe src="http://update.sonarsource.org/plugins/cssfamily-confluence-include.html" height="125px">Your browser does not support iframes.</iframe> +<!-- /static --> + + +## Prerequisites +In order to analyze CSS code, you need to have Node.js >= 6 installed on the machine running the scan. Set property `sonar.css.node` to an absolute path to Node.js executable, if standard `node` is not available. + +If you have a community plugin that handles CSS installed on your SonarQube instance it will conflict with SonarCSS, so it should be removed. + +## Language-Specific Properties + +Discover and update the CSS-specific [properties](/analysis/analysis-parameters/) in: <!-- sonarcloud -->Project <!-- /sonarcloud -->**[Administration > General Settings > CSS](/#sonarqube-admin#/admin/settings?category=css)** + +## Related Pages +* [Importing External Issues](/analysis/external-issues/) (StyleLint.io) diff --git a/server/sonar-docs/src/pages/analysis/languages/flex.md b/server/sonar-docs/src/pages/analysis/languages/flex.md new file mode 100644 index 00000000000..2cddf0e26a1 --- /dev/null +++ b/server/sonar-docs/src/pages/analysis/languages/flex.md @@ -0,0 +1,23 @@ +--- +title: Flex +url: /analysis/languages/flex/ +--- + +<!-- static --> +[[info]] +| <iframe src="http://update.sonarsource.org/plugins/flex-confluence-include.html" height="125px">Your browser does not support iframes.</iframe> +<!-- /static --> + +## 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 --> diff --git a/server/sonar-docs/src/pages/analysis/languages/go.md b/server/sonar-docs/src/pages/analysis/languages/go.md new file mode 100644 index 00000000000..293625200f3 --- /dev/null +++ b/server/sonar-docs/src/pages/analysis/languages/go.md @@ -0,0 +1,41 @@ +--- +title: Go +url: /analysis/languages/go/ +--- + +<!-- static --> +[[info]] +| <iframe src="http://update.sonarsource.org/plugins/go-confluence-include.html" height="125px">Your browser does not support iframes.</iframe> +<!-- /static --> + + + +## 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) diff --git a/server/sonar-docs/src/pages/analysis/languages/html.md b/server/sonar-docs/src/pages/analysis/languages/html.md new file mode 100644 index 00000000000..7e0b7a602d7 --- /dev/null +++ b/server/sonar-docs/src/pages/analysis/languages/html.md @@ -0,0 +1,21 @@ +--- +title: HTML +url: /analysis/languages/html/ +--- + +<!-- static --> +[[info]] +| <iframe src="http://update.sonarsource.org/plugins/web-confluence-include.html" height="125px">Your browser does not support iframes.</iframe> +<!-- /static --> + + +## 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. diff --git a/server/sonar-docs/src/pages/analysis/languages/java.md b/server/sonar-docs/src/pages/analysis/languages/java.md new file mode 100644 index 00000000000..0a31d991dc6 --- /dev/null +++ b/server/sonar-docs/src/pages/analysis/languages/java.md @@ -0,0 +1,282 @@ +--- +title: Java +url: /analysis/languages/java/ +--- + +<!-- static --> +[[info]] +| <iframe src="http://update.sonarsource.org/plugins/java-confluence-include.html" height="125px">Your browser does not support iframes.</iframe> +<!-- /static --> + + +## 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. + +<!-- 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 + +#### **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 --> + +## Related Pages + +* [Test Coverage & Execution](/analysis/coverage/) ([SpotBugs](https://spotbugs.github.io/), FindBugs, [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)) +* [Importing External Issues](/analysis/external-issues/) (JaCoCo, Surefire) +<!-- sonarqube --> +* [Adding Coding Rules](/extend/adding-coding-rules/) +<!-- /sonarqube --> diff --git a/server/sonar-docs/src/pages/analysis/languages/javascript.md b/server/sonar-docs/src/pages/analysis/languages/javascript.md new file mode 100644 index 00000000000..323cbc0823d --- /dev/null +++ b/server/sonar-docs/src/pages/analysis/languages/javascript.md @@ -0,0 +1,116 @@ +--- +title: JavaScript +url: /analysis/languages/javascript/ +--- + +<!-- static --> +[[info]] +| <iframe src="http://update.sonarsource.org/plugins/javascript-confluence-include.html" height="125px">Your browser does not support iframes.</iframe> +<!-- /static --> + + +## Prerequisites + +In order to analyze JavaScript code, you need to have Node.js >= 6 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. + + 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 --> diff --git a/server/sonar-docs/src/pages/analysis/languages/kotlin.md b/server/sonar-docs/src/pages/analysis/languages/kotlin.md new file mode 100644 index 00000000000..e97ed8d08fe --- /dev/null +++ b/server/sonar-docs/src/pages/analysis/languages/kotlin.md @@ -0,0 +1,18 @@ +--- +title: Kotlin +url: /analysis/languages/kotlin/ +--- + +<!-- static --> +[[info]] +| <iframe src="http://update.sonarsource.org/plugins/kotlin-confluence-include.html" height="125px">Your browser does not support iframes.</iframe> +<!-- /static --> + + +## 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) diff --git a/server/sonar-docs/src/pages/analysis/languages/overview.md b/server/sonar-docs/src/pages/analysis/languages/overview.md new file mode 100644 index 00000000000..6b5efc2a3a3 --- /dev/null +++ b/server/sonar-docs/src/pages/analysis/languages/overview.md @@ -0,0 +1,42 @@ +--- +title: Overview +url: /analysis/languages/overview/ +--- + +SonarQube allows to analyze different languages depending on the Edition you are running. + +| Language | Community Edition | Developer Edition | Enterprise Edition and Data Center Edtion | +| ------------------------------------ | ---------------------- | ---------------------- | ----------------------------------------- | +| [ABAP](/analysis/languages/abap/) | |  |  | +| [Apex](/analysis/languages/apex/) | | |  | +| [C#](/analysis/languages/csharp/) |  |  |  | +| [C](/analysis/languages/cfamily/) | |  |  | +| [C++](/analysis/languages/cfamily/) | |  |  | +| [COBOL](/analysis/languages/cobol/) | | |  | +| [CSS](/analysis/languages/css/) |  |  |  | +| [Flex](/analysis/languages/flex/) |  |  |  | +| [Go](/analysis/languages/go/) |  |  |  | +| [Java](/analysis/languages/java/) |  |  |  | +| [JavaScript](/analysis/languages/javascript/) |  |  |  | +| [Kotlin](/analysis/languages/kotlin/) |  |  |  | +| [Objective-C](/analysis/languages/cfamily/) | |  |  | +| [PHP](/analysis/languages/php/) |  |  |  | +| [PLI](/analysis/languages/pli/) | | |  | +| [PLSQL](/analysis/languages/plsql/) | |  |  | +| [Python](/analysis/languages/python/) |  |  |  | +| [RPG](/analysis/languages/rpg/) | | |  | +| [Ruby](/analysis/languages/ruby/) |  |  |  | +| [Scala](/analysis/languages/scala/) |  |  |  | +| [Swift](/analysis/languages/swift/) | |  |  | +| [TypeScript](/analysis/languages/typescript/) |  |  |  | +| [TSQL](/analysis/languages/tsql/) | |  |  | +| [Visual Basic](/analysis/languages/vb/) |  |  |  | +| [VB6](/analysis/languages/vb6/) | | |  | +| [HTML](/analysis/languages/html/) |  |  |  | +| [XML](/analysis/languages/xml/) |  |  |  | + +In this section you will find the documentation related to language analyzers made and supported by SonarSource. + +[[warning]] +| This documentation is not updated automatically when you upgrade a given analyzer. It's required to upgrade SonarQube to get the latest version of analyzers's documentation. This will be improved in the future. + diff --git a/server/sonar-docs/src/pages/analysis/languages/php.md b/server/sonar-docs/src/pages/analysis/languages/php.md new file mode 100644 index 00000000000..a35bddcf3fd --- /dev/null +++ b/server/sonar-docs/src/pages/analysis/languages/php.md @@ -0,0 +1,94 @@ +--- +title: PHP +url: /analysis/languages/php/ +--- + +<!-- static --> +[[info]] +| <iframe src="http://update.sonarsource.org/plugins/php-confluence-include.html" height="125px">Your browser does not support iframes.</iframe> +<!-- /static --> + + +## 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. + + 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 --> diff --git a/server/sonar-docs/src/pages/analysis/languages/pli.md b/server/sonar-docs/src/pages/analysis/languages/pli.md new file mode 100644 index 00000000000..b27b91b4811 --- /dev/null +++ b/server/sonar-docs/src/pages/analysis/languages/pli.md @@ -0,0 +1,68 @@ +--- +title: PLI +url: /analysis/languages/pli/ +--- + +_PL/I is available as part of [Enterprise Edition](https://redirect.sonarsource.com/editions/enterprise.html) and [above](https://redirect.sonarsource.com/editions/editions.html)._ + +<!-- static --> + +[[info]] +| <iframe src="http://update.sonarsource.org/plugins/pli-confluence-include.html" height="125px">Your browser does not support iframes.</iframe> + +<!-- /static --> + +## 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 -->
\ No newline at end of file diff --git a/server/sonar-docs/src/pages/analysis/languages/plsql.md b/server/sonar-docs/src/pages/analysis/languages/plsql.md new file mode 100644 index 00000000000..cd225f3aee4 --- /dev/null +++ b/server/sonar-docs/src/pages/analysis/languages/plsql.md @@ -0,0 +1,43 @@ +--- +title: PL/SQL +url: /analysis/languages/plsql/ +--- + +<!-- static --> +[[info]] +| <iframe src="http://update.sonarsource.org/plugins/plsql-confluence-include.html" height="125px">Your browser does not support iframes.</iframe> +<!-- /static --> + + +## 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 --> + diff --git a/server/sonar-docs/src/pages/analysis/languages/python.md b/server/sonar-docs/src/pages/analysis/languages/python.md new file mode 100644 index 00000000000..f6bd20f8bc2 --- /dev/null +++ b/server/sonar-docs/src/pages/analysis/languages/python.md @@ -0,0 +1,32 @@ +--- +title: Python +url: /analysis/languages/python/ +--- + +<!-- static --> +[[info]] +| <iframe src="http://update.sonarsource.org/plugins/python-confluence-include.html" height="125px">Your browser does not support iframes.</iframe> +<!-- /static --> + + +## 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 used to augment Python analysis. To include Pylint issues, first generate an issues report: +``` +pylint <module_or_package> -r n --msg-template="{path}:{line}: [{msg_id}({symbol}), {obj}] {msg}" > <report_file> +``` +Then pass it in to analysis with the `sonar.python.pylint.reportPath` property. + +The analyzer will execute Pylint for you if you haven't specified the path to a Pylint report. The path to your installation of `pylint` can be tuned using the `sonar.python.pylint` property, and non-default a properties file can be specified with `sonar.python.pylint_config`. + + +## 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/)) diff --git a/server/sonar-docs/src/pages/analysis/languages/rpg.md b/server/sonar-docs/src/pages/analysis/languages/rpg.md new file mode 100644 index 00000000000..3704f84d803 --- /dev/null +++ b/server/sonar-docs/src/pages/analysis/languages/rpg.md @@ -0,0 +1,95 @@ +--- +title: RPG +url: /analysis/languages/rpg/ +--- + +_RPG is available as part of [Enterprise Edition](https://redirect.sonarsource.com/editions/enterprise.html) and [above](https://redirect.sonarsource.com/editions/editions.html)._ + +<!-- static --> + +[[info]] +| <iframe src="http://update.sonarsource.org/plugins/rpg-confluence-include.html" height="125px">Your browser does not support iframes.</iframe> + +<!-- /static --> + +## 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. diff --git a/server/sonar-docs/src/pages/analysis/languages/ruby.md b/server/sonar-docs/src/pages/analysis/languages/ruby.md new file mode 100644 index 00000000000..60e8e3faa91 --- /dev/null +++ b/server/sonar-docs/src/pages/analysis/languages/ruby.md @@ -0,0 +1,18 @@ +--- +title: Ruby +url: /analysis/languages/ruby/ +--- + +<!-- static --> +[[info]] +| <iframe src="http://update.sonarsource.org/plugins/ruby-confluence-include.html" height="125px">Your browser does not support iframes.</iframe> +<!-- /static --> + + +## 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) diff --git a/server/sonar-docs/src/pages/analysis/languages/scala.md b/server/sonar-docs/src/pages/analysis/languages/scala.md new file mode 100644 index 00000000000..5dbfdff8bce --- /dev/null +++ b/server/sonar-docs/src/pages/analysis/languages/scala.md @@ -0,0 +1,18 @@ +--- +title: Scala +url: /analysis/languages/scala/ +--- + +<!-- static --> +[[info]] +| <iframe src="http://update.sonarsource.org/plugins/sonarscala-confluence-include.html" height="125px">Your browser does not support iframes.</iframe> +<!-- /static --> + + +## 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) diff --git a/server/sonar-docs/src/pages/analysis/languages/swift.md b/server/sonar-docs/src/pages/analysis/languages/swift.md new file mode 100644 index 00000000000..7314c3d561b --- /dev/null +++ b/server/sonar-docs/src/pages/analysis/languages/swift.md @@ -0,0 +1,18 @@ +--- +title: Swift +url: /analysis/languages/swift/ +--- + +<!-- static --> +[[info]] +| <iframe src="http://update.sonarsource.org/plugins/swift-confluence-include.html" height="125px">Your browser does not support iframes.</iframe> +<!-- /static --> + + +## 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) diff --git a/server/sonar-docs/src/pages/analysis/languages/tsql.md b/server/sonar-docs/src/pages/analysis/languages/tsql.md new file mode 100644 index 00000000000..068f6f6a8ff --- /dev/null +++ b/server/sonar-docs/src/pages/analysis/languages/tsql.md @@ -0,0 +1,18 @@ +--- +title: T-SQL +url: /analysis/languages/tsql/ +--- + +<!-- static --> +[[info]] +| <iframe src="http://update.sonarsource.org/plugins/tsql-confluence-include.html" height="125px">Your browser does not support iframes.</iframe> +<!-- /static --> + + +## 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. + diff --git a/server/sonar-docs/src/pages/analysis/languages/typescript.md b/server/sonar-docs/src/pages/analysis/languages/typescript.md new file mode 100644 index 00000000000..f134104690d --- /dev/null +++ b/server/sonar-docs/src/pages/analysis/languages/typescript.md @@ -0,0 +1,41 @@ +--- +title: TypeScript +url: /analysis/languages/typescript/ +--- + +<!-- static --> +[[info]] +| <iframe src="http://update.sonarsource.org/plugins/typescript-confluence-include.html" height="125px">Your browser does not support iframes.</iframe> +<!-- /static --> + + +## Prerequisites + +In order to analyze TypeScript code, you need to have Node.js >= 6 installed on the machine running the scan. Set property `sonar.typescript.node` to an absolute path to Node.js executable, if standard `node` is not available. + +Also make sure to have [TypeScript](https://www.npmjs.com/package/typescript) as a project dependency or dev dependency. If it's not the case, add it: +``` +cd <your-project-folder> +npm install -D typescript +``` +If you can't have TypeScript as a project dependency you can set your `NODE_PATH` variable to point to your globally installed TypeScript (but this is generally discouraged by the Node.js documentation). + +## Language-Specific Properties + +Discover and update the TypeScript-specific properties in: **<!-- sonarcloud -->Project <!-- /sonarcloud -->[Administration > General Settings > TypeScript](/#sonarqube-admin#/admin/settings?category=typescript)** + +## Supported Frameworks and Versions +* TypeScript >= 2.2 + +## Rule Profiles + +There are 2 built-in rule profiles for TypeScript: `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 TS development context. +* `Sonar way Recommended` contains all rules from `Sonar way`, plus more rules that mandate high code readability and long-term project evolution. + +## Related Pages + +* [Test Coverage & Execution](/analysis/coverage/) (LCOV format) +* [Importing External Issues](/analysis/external-issues/) (TSLint) +* [SonarTS Plugin for TSLint](https://www.npmjs.com/package/tslint-sonarts) +* [Sample TypeScript Project](https://github.com/SonarSource/SonarTS-example/) diff --git a/server/sonar-docs/src/pages/analysis/languages/vb.md b/server/sonar-docs/src/pages/analysis/languages/vb.md new file mode 100644 index 00000000000..40d52549451 --- /dev/null +++ b/server/sonar-docs/src/pages/analysis/languages/vb.md @@ -0,0 +1,22 @@ +--- +title: VB.NET +url: /analysis/languages/vb/ +--- + +<!-- static --> +[[info]] +| <iframe src="http://update.sonarsource.org/plugins/vbnet-confluence-include.html" height="125px">Your browser does not support iframes.</iframe> +<!-- /static --> + + +## 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)** + +## 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, NCover 3) diff --git a/server/sonar-docs/src/pages/analysis/languages/vb6.md b/server/sonar-docs/src/pages/analysis/languages/vb6.md new file mode 100644 index 00000000000..9d24936a5a4 --- /dev/null +++ b/server/sonar-docs/src/pages/analysis/languages/vb6.md @@ -0,0 +1,21 @@ +--- +title: VB6 +url: /analysis/languages/vb6/ +--- + +<!-- sonarqube --> + +_VB6 analysis is available as part of the [Enterprise Edition](https://redirect.sonarsource.com/editions/enterprise.html) and [above](https://redirect.sonarsource.com/editions/editions.html)._ + +<!-- /sonarqube --> + +<!-- static --> + +[[info]] +| <iframe src="http://update.sonarsource.org/plugins/vb-confluence-include.html" height="125px">Your browser does not support iframes.</iframe> + +<!-- /static --> + +## 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)**. diff --git a/server/sonar-docs/src/pages/analysis/languages/xml.md b/server/sonar-docs/src/pages/analysis/languages/xml.md new file mode 100644 index 00000000000..622d49231d3 --- /dev/null +++ b/server/sonar-docs/src/pages/analysis/languages/xml.md @@ -0,0 +1,19 @@ +--- +title: XML +url: /analysis/languages/xml/ +--- + +<!-- static --> +[[info]] +| <iframe src="http://update.sonarsource.org/plugins/xml-confluence-include.html" height="125px">Your browser does not support iframes.</iframe> +<!-- /static --> + + +## 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 --> diff --git a/server/sonar-docs/src/pages/analysis/overview.md b/server/sonar-docs/src/pages/analysis/overview.md index 16a16c6c799..e02f6425471 100644 --- a/server/sonar-docs/src/pages/analysis/overview.md +++ b/server/sonar-docs/src/pages/analysis/overview.md @@ -16,11 +16,11 @@ Find the key of your organization, you will need it at later stages. It can be f ## Run analysis SonarCloud currently does not trigger analyses automatically - this feature will come in a near future. Currently, it's up to you to launch them inside your existing CI scripts using the available scanners: -* Gradle - [SonarScanner for Gradle](https://redirect.sonarsource.com/doc/gradle.html) -* MSBuild - [SonarScanner for MSBuild](https://redirect.sonarsource.com/doc/install-configure-scanner-msbuild.html) -* Maven - use the [SonarScanner for Maven](https://redirect.sonarsource.com/doc/install-configure-scanner-maven.html) -* Ant - [SonarScanner for Ant](https://redirect.sonarsource.com/doc/install-configure-scanner-ant.html) -* anything else (CLI) - [SonarScanner](https://redirect.sonarsource.com/doc/install-configure-scanner.html) +* Gradle - [SonarScanner for Gradle](/scan/sonarscanner-for-gradle/) +* MSBuild - [SonarScanner for MSBuild](/scan/sonarscanner-for-msbuild/) +* Maven - use the [SonarScanner for Maven](/scan/sonarscanner-for-maven/) +* Ant - [SonarScanner for Ant](/scan/sonarscanner-for-ant/) +* anything else (CLI) - [SonarScanner](/scan/sonarscanner/) After creating a project, the tutorial available on its homepage will guide you to find how to trigger an analysis. @@ -33,7 +33,7 @@ After creating a project, the tutorial available on its homepage will guide you <!-- /sonarcloud --> <!-- sonarqube --> -Once the SonarQube platform has been installed, you're ready to install an analyzer and begin creating projects. To do that, you must install and configure the scanner that is most appropriate for your needs. Do you build with: +Once the SonarQube platform has been installed, you're ready to install a scanner and begin creating projects. To do that, you must install and configure the scanner that is most appropriate for your needs. Do you build with: * Gradle - [SonarScanner for Gradle](https://redirect.sonarsource.com/doc/gradle.html) * MSBuild - [SonarScanner for MSBuild](https://redirect.sonarsource.com/doc/install-configure-scanner-msbuild.html) @@ -46,7 +46,7 @@ Once the SonarQube platform has been installed, you're ready to install an analy **Note** that we do not recommend running an antivirus scanner on the machine where a SonarQube analysis runs, it could result in unpredictable behavior. -A project is created in the platform automatically on its first analysis. However, if you need to set some configuration on your project before its first analysis, you have the option of provisioning it via Administration options. +A project is created in the platform automatically on its first analysis. However, if you need to set some configuration on your project before its first analysis, you have the option of provisioning it via Administration options or the **+** menu item. <!-- /sonarqube --> ## What does analysis produce? diff --git a/server/sonar-docs/src/pages/extend/adding-coding-rules.md b/server/sonar-docs/src/pages/extend/adding-coding-rules.md index 7f418572358..ed8bcb07b01 100644 --- a/server/sonar-docs/src/pages/extend/adding-coding-rules.md +++ b/server/sonar-docs/src/pages/extend/adding-coding-rules.md @@ -18,7 +18,7 @@ Languages not listed here don't support custom rules |XPath 1.0|Java|Other ---|---|---|--- -C#| - | - | [Importing Issues from Third-Party Roslyn Analyzers (C#, VB.NET)](https://docs.sonarqube.org/pages/viewpage.action?pageId=11640944) +C#| - | - | [Importing Issues from Third-Party Roslyn Analyzers (C#, VB.NET)](/analysis/external-issues/) COBOL|  | - | - Flex| | - | - Java | - |  | - @@ -27,7 +27,7 @@ PHP | - | | - PL/SQL |  | - | - PL/I |  | - | - RPG | - | | - -VB.NET| - | - | [Importing Issues from Third-Party Roslyn Analyzers (C#, VB.NET)](https://docs.sonarqube.org/pages/viewpage.action?pageId=11640944) +VB.NET| - | - | [Importing Issues from Third-Party Roslyn Analyzers (C#, VB.NET)](/analysis/external-issues/) XML |  | - | - @@ -43,11 +43,11 @@ Writing coding rules in Java is a six-step process: See the following pages to see samples and details about how to create coding rules -* [for COBOL](https://docs.sonarqube.org/display/PLUG/Custom+Rules+for+SonarCOBOL) -* [for Java](https://docs.sonarqube.org/display/PLUG/Custom+Rules+for+Java) -* [for JavaScript](https://docs.sonarqube.org/display/PLUG/Custom+Rules+for+SonarJS) -* [for PHP](https://docs.sonarqube.org/display/PLUG/Custom+Rules+for+PHP) -* [for RPG](https://docs.sonarqube.org/display/PLUG/Custom+Rules+for+RPG) +* [for COBOL](/analysis/languages/cobol/) +* [for Java](/analysis/languages/java/) +* [for JavaScript](/analysis/languages/javascript/) +* [for PHP](/analysis/languages/php/) +* [for RPG](/analysis/languages/rpg/) ## Adding coding rules using XPATH diff --git a/server/sonar-docs/src/pages/instance-administration/marketplace.md b/server/sonar-docs/src/pages/instance-administration/marketplace.md index 1de5e2723a2..1940e3ac066 100644 --- a/server/sonar-docs/src/pages/instance-administration/marketplace.md +++ b/server/sonar-docs/src/pages/instance-administration/marketplace.md @@ -36,9 +36,9 @@ Restarting SonarQube can be done manually from the command line by running `sona ## Manual Updates If your server has no access to the internet, you won't be able to rely on the Marketplace for plugins, and will have to handle plugin installations and upgrades manually. -To see what plugins are available and which version of a plugin is appropriate for your server, use the [plugin version matrix](https://redirect.sonarsource.com/doc/plugin-version-matrix.html), which is kept up to date with plugin availability and compatibility. +To see what plugins are available and which version of a plugin is appropriate for your server, use the [plugin version matrix](/instance-administration/plugin-version-matrix/), which is kept up to date with current plugin availability and compatibility. -To install a plugin, simply download it using the manual download link on the plugin documentation page, place it in _$SONARQUBE_HOME/extensions/downloads_, and restart the server. +To install a plugin, simply download it using the manual download link on the plugin documentation page, place it in _$SONARQUBE-HOME/extensions/downloads_, and restart the server. ## Which URLs does the Marketplace connect to? The SonarQube Marketplace connects to https://update.sonarsource.org/ to get the list of plugins. Most of the referenced plugins are downloaded from: diff --git a/server/sonar-docs/src/pages/instance-administration/plugin-version-matrix.md b/server/sonar-docs/src/pages/instance-administration/plugin-version-matrix.md new file mode 100644 index 00000000000..3e2672808ca --- /dev/null +++ b/server/sonar-docs/src/pages/instance-administration/plugin-version-matrix.md @@ -0,0 +1,11 @@ +--- +title: Plugin Version Matrix +url: /instance-administration/plugin-version-matrix/ +--- + + + = Supported by SonarSource + = Not compatible + +<iframe src="https://update.sonarsource.org/plugins/compatibility-matrix.html" height="3100">Your browser does not support iframes.</iframe> + diff --git a/server/sonar-docs/src/pages/instance-administration/system-info.md b/server/sonar-docs/src/pages/instance-administration/system-info.md index c97287949e9..b3d78dd0a54 100644 --- a/server/sonar-docs/src/pages/instance-administration/system-info.md +++ b/server/sonar-docs/src/pages/instance-administration/system-info.md @@ -60,7 +60,7 @@ If you're on a commercial edition and using Branch or PR analysis, rest assured The best approach there is to query the database. The actual query varies based on the version of SonarQube and the database engine. Two queries are provided: * one query that counts LOCs across *all* projects -& one query that filters out project branches (i.e. projects analysed with the `sonar.branch` parameter). However, this query is accurate only if projects with branches are also analysed once without sonar.branch. +& one query that filters out project branches (i.e. projects analyzed with the `sonar.branch` parameter). However, this query is accurate only if projects with branches are also analyzed once without sonar.branch. **SonarQube LTS v5.6.x** diff --git a/server/sonar-docs/src/pages/project-administration/narrowing-the-focus.md b/server/sonar-docs/src/pages/project-administration/narrowing-the-focus.md index 59aa1586c2c..9154ecd31de 100644 --- a/server/sonar-docs/src/pages/project-administration/narrowing-the-focus.md +++ b/server/sonar-docs/src/pages/project-administration/narrowing-the-focus.md @@ -24,7 +24,7 @@ Set the [sonar.sources](/analysis/analysis-parameters/) property to limit the sc Most language plugins offer a way to restrict the scope of analysis to files matching a set of extensions. Go to **Administration > General Settings > [Language]** to set the File suffixes property. ### Choosing Files -Your first line of defence having a well-defined set of files in your analysis is your `sonar.sources` value. For projects built and analysed with Maven, Gradle, or MSBuild, this value is defined automatically with a generally thorough, yet sane value. For other projects, you want to make sure `sonar.sources` is set to your project _sub-directory_ that actually contains your source files. Setting it to `.` will cast a wider net than most people intend. +Your first line of defence having a well-defined set of files in your analysis is your `sonar.sources` value. For projects built and analyzed with Maven, Gradle, or MSBuild, this value is defined automatically with a generally thorough, yet sane value. For other projects, you want to make sure `sonar.sources` is set to your project _sub-directory_ that actually contains your source files. Setting it to `.` will cast a wider net than most people intend.  diff --git a/server/sonar-docs/src/pages/scan/sonarscanner-for-azure-devops.md b/server/sonar-docs/src/pages/scan/sonarscanner-for-azure-devops.md index 4e6127ac2e2..cabb21d8306 100644 --- a/server/sonar-docs/src/pages/scan/sonarscanner-for-azure-devops.md +++ b/server/sonar-docs/src/pages/scan/sonarscanner-for-azure-devops.md @@ -8,7 +8,7 @@ url: /scan/sonarscanner-for-azure-devops/ | By [SonarSource](https://www.sonarsource.com/) – GNU LGPL 3 – [Issue Tracker](https://jira.sonarsource.com/browse/VSTS) – [Source](https://github.com/SonarSource/sonar-scanner-vsts) | **SonarScanner for Azure DevOps** -The <!-- sonarqube -->[SonarQube](https://marketplace.visualstudio.com/items?itemName=SonarSource.sonarqube)<!-- /sonarqube --> <!-- sonarcloud -->[SonarCloud](https://marketplace.visualstudio.com/items?itemName=SonarSource.sonarcloud)<!-- /sonarcloud --> extension for Azure DevOps <!-- sonarqube -->Server<!-- /sonarqube --> makes it easy to integrate analysis into your build pipeline. The extension allows the analysis of all languages supported by {instance}. +The <!-- sonarqube -->[SonarQube](https://marketplace.visualstudio.com/items?itemName=SonarSource.sonarqube)<!-- /sonarqube --> <!-- sonarcloud -->[SonarCloud](https://marketplace.visualstudio.com/items?itemName=SonarSource.sonarcloud)<!-- /sonarcloud --> extension for Azure DevOps <!-- sonarqube -->Server<!-- /sonarqube --> makes it easy to integrate analysis into your build pipeline. The extension allows the analysis of all languages supported by {instance}. <!-- sonarcloud --> Microsoft has published a [dedicated lab](https://aka.ms/sonarcloudlab) describing how to integrate Azure DevOps Pipelines and SonarCloud. The lab includes setting up a Branch Policy in Azure DevOps to block a Pull Request from being submitted if the changed code does not meet the quality bar. @@ -58,7 +58,7 @@ Each extension provides three tasks you will use in your build definitions to an When creating a build definition you can filter the list of available tasks by typing "Sonar" to display only the relevant tasks. -## Analysing a .NET solution +## Analyzing a .NET solution 1. In your build definition, add: * At least **Prepare Analysis Configuration** task and **Run Code Analysis** task * Optionally **Publish Quality Gate Result** task @@ -80,20 +80,45 @@ When creating a build definition you can filter the list of available tasks by t Once all this is done, you can trigger a build. -## Analysing a Java project with Maven or Gradle +## Analyzing a Java project with Maven or Gradle 1. In your build definition, add: * At least **Prepare Analysis Configuration** task - * Optionaly **Publish Quality Gate Result** task + * Optionally **Publish Quality Gate Result** task 1. Reorder the tasks to respect the following order: * **Prepare Analysis Configuration** task before the **Maven** or **Gradle** task. * **Publish Quality Gate Result** task after the **Maven** or **Gradle** task. -1. Click on the Prepare Analysis Configuration build step to configure it: +1. Click on the **Prepare Analysis Configuration** task to configure it: * Select the **SonarQube Server** * Select **Integrate with Maven or Gradle** 1. On the Maven or Gradle task, in **Code Analysis**, check **Run SonarQube or SonarCloud Analysis** Once all this is done, you can trigger a build. +## Analyzing a Visual C++ project +1. Make **SonarQube Build Wrapper** available on the build agent + * Download and unzip **SonarQube Build Wrapper** on the build agent (see *Prerequisites* section of *C/C++/Objective-C* page). For the Microsoft-hosted build agent you will need to do it every time (as part of build definition), e.g. you can add **PowerShell script** task doing that. For the self-hosted build agent you can do the same either every build or only once (as part of manual setup of build agent). Example of PowerShell commands: + ``` + Invoke-WebRequest -Uri '<sonarqube or sonarcloud url>/static/cpp/build-wrapper-win-x86.zip' -OutFile 'build-wrapper.zip' + Expand-Archive -Path 'build-wrapper.zip' -DestinationPath '.' + ``` +1. In your build definition, add: + * At least **Prepare Analysis Configuration** task, **Run Code Analysis** task and the **Command Line** task + * Optionally **Publish Quality Gate Result** task +1. Reorder the tasks to respect the following order: + * **Prepare Analysis Configuration** task before **Command Line** task. + * **Run Code Analysis** task after the **Command Line** task. + * **Publish Quality Gate Result** task after the **Run Code Analysis** task +1. On the **Command Line** task + * Run **SonarQube Build Wrapper** executable. Pass in as the arguments (1) the output directory to which the Build Wrapper should write its results and (2) the command that runs the compilation of your project, e.g. + ``` + path/to/build-wrapper-win-x86-64.exe --out-dir <output directory> MSBuild.exe /t:Rebuild + ``` +1. Click on the **Prepare Analysis Configuration** task to configure it: + * Select the **SonarQube Server** + * In *Additional Properties* in the *Advanced* section, add the property `sonar.cfamily.build-wrapper-output` with the value of the directory you specified: `sonar.cfamily.build-wrapper-output=<output directory>` + +Once all this is done, you can trigger a build. + ## Analysing other project types If you are not developing a .NET application or a Java project, here is the standard way to trigger an analysis: @@ -104,7 +129,7 @@ If you are not developing a .NET application or a Java project, here is the stan 1. **Prepare Analysis Configuration** 2. **Run Code Analysis** 3. **Publish Quality Gate Result** -1. Click on the Prepare Analysis Configuration build step to configure it: +1. Click on the **Prepare Analysis Configuration** task to configure it: * Select the **SonarQube Server** * Select **Use standalone scanner** * Then: diff --git a/server/sonar-docs/src/pages/sonarcloud/integrations/bitbucketcloud.md b/server/sonar-docs/src/pages/sonarcloud/integrations/bitbucketcloud.md index bb14da54c62..b19cdb62fdc 100644 --- a/server/sonar-docs/src/pages/sonarcloud/integrations/bitbucketcloud.md +++ b/server/sonar-docs/src/pages/sonarcloud/integrations/bitbucketcloud.md @@ -49,7 +49,7 @@ If you want to see this widget, you can go to the "Settings > SonarCloud" page o ## FAQ **Do you have sample projects on Bitbucket Cloud?** -You can take a look at these various projects: [Sample projects analysed on SonarCloud](https://bitbucket.org/account/user/sonarsource/projects/SAMPLES) +You can take a look at these various projects: [Sample projects analyzed on SonarCloud](https://bitbucket.org/account/user/sonarsource/projects/SAMPLES) **I don't see the widget with quality information whereas I configured everything** Make sure that your browser is not using some extensions like AdBlocks. They tend to break the integration of third-party applications in BitBucket Cloud. diff --git a/server/sonar-docs/src/pages/user-guide/rules.md b/server/sonar-docs/src/pages/user-guide/rules.md index be8ee14f049..7c921459840 100644 --- a/server/sonar-docs/src/pages/user-guide/rules.md +++ b/server/sonar-docs/src/pages/user-guide/rules.md @@ -79,7 +79,7 @@ Note that when deleting a custom rule, it is not physically removed from the {in ## Extending Coding Rules -Custom coding rules can be added. See [Adding Coding Rules](https://docs.sonarqube.org/display/DEV/Adding+Coding+Rules) for detailed information and tutorials. +Custom coding rules can be added. See [Adding Coding Rules](/extend/adding-coding-rules/) for detailed information and tutorials. <!-- /sonarqube --> ## Rule Types and Severities diff --git a/server/sonar-docs/static/SonarCloudNavigationTree.json b/server/sonar-docs/static/SonarCloudNavigationTree.json index 50ad2fe97ce..6e6f8d79ca4 100644 --- a/server/sonar-docs/static/SonarCloudNavigationTree.json +++ b/server/sonar-docs/static/SonarCloudNavigationTree.json @@ -8,6 +8,33 @@ "children": [ "/analysis/overview/", "/analysis/analysis-parameters/", + { + "title": "Languages", + "children": [ + "/analysis/languages/abap/", + "/analysis/languages/apex/", + "/analysis/languages/csharp/", + "/analysis/languages/cfamily/", + "/analysis/languages/cobol/", + "/analysis/languages/css/", + "/analysis/languages/flex/", + "/analysis/languages/go/", + "/analysis/languages/html/", + "/analysis/languages/java/", + "/analysis/languages/javascript/", + "/analysis/languages/kotlin/", + "/analysis/languages/php/", + "/analysis/languages/plsql/", + "/analysis/languages/python/", + "/analysis/languages/ruby/", + "/analysis/languages/scala/", + "/analysis/languages/swift/", + "/analysis/languages/tsql/", + "/analysis/languages/typescript/", + "/analysis/languages/vb/", + "/analysis/languages/xml/" + ] + }, "/analysis/coverage/", "/analysis/external-issues/", "/analysis/background-tasks/", diff --git a/server/sonar-docs/static/SonarQubeNavigationTree.json b/server/sonar-docs/static/SonarQubeNavigationTree.json index ecf986a4f2c..dc6bafd000a 100644 --- a/server/sonar-docs/static/SonarQubeNavigationTree.json +++ b/server/sonar-docs/static/SonarQubeNavigationTree.json @@ -10,19 +10,38 @@ "title": "Analyzing Source Code", "children": [ "/analysis/overview/", + "/analysis/analysis-parameters/", { - "title": "Scanners", + "title": "Languages", "children": [ - "/scan/sonarscanner-for-msbuild/", - "/scan/sonarscanner-for-gradle/", - "/scan/sonarscanner-for-maven/", - "/scan/sonarscanner/", - "/scan/sonarscanner-for-ant/", - "/scan/sonarscanner-for-jenkins/", - "/scan/sonarscanner-for-azure-devops/" + "/analysis/languages/overview/", + "/analysis/languages/abap/", + "/analysis/languages/apex/", + "/analysis/languages/csharp/", + "/analysis/languages/cfamily/", + "/analysis/languages/cobol/", + "/analysis/languages/css/", + "/analysis/languages/flex/", + "/analysis/languages/go/", + "/analysis/languages/html/", + "/analysis/languages/java/", + "/analysis/languages/javascript/", + "/analysis/languages/kotlin/", + "/analysis/languages/php/", + "/analysis/languages/pli/", + "/analysis/languages/plsql/", + "/analysis/languages/python/", + "/analysis/languages/rpg/", + "/analysis/languages/ruby/", + "/analysis/languages/scala/", + "/analysis/languages/swift/", + "/analysis/languages/typescript/", + "/analysis/languages/tsql/", + "/analysis/languages/vb/", + "/analysis/languages/vb6/", + "/analysis/languages/xml/" ] }, - "/analysis/analysis-parameters/", "/analysis/coverage/", "/analysis/external-issues/", "/analysis/background-tasks/", diff --git a/server/sonar-docs/static/StaticNavigationTree.json b/server/sonar-docs/static/StaticNavigationTree.json index da5d0dfe9e6..d0202b53247 100644 --- a/server/sonar-docs/static/StaticNavigationTree.json +++ b/server/sonar-docs/static/StaticNavigationTree.json @@ -26,19 +26,38 @@ "title": "Analyzing Source Code", "children": [ "/analysis/overview/", + "/analysis/analysis-parameters/", { - "title": "Scanners", + "title": "Languages", "children": [ - "/scan/sonarscanner-for-msbuild/", - "/scan/sonarscanner-for-gradle/", - "/scan/sonarscanner-for-maven/", - "/scan/sonarscanner/", - "/scan/sonarscanner-for-ant/", - "/scan/sonarscanner-for-jenkins/", - "/scan/sonarscanner-for-azure-devops/" + "/analysis/languages/overview/", + "/analysis/languages/abap/", + "/analysis/languages/apex/", + "/analysis/languages/csharp/", + "/analysis/languages/cfamily/", + "/analysis/languages/cobol/", + "/analysis/languages/css/", + "/analysis/languages/flex/", + "/analysis/languages/go/", + "/analysis/languages/html/", + "/analysis/languages/java/", + "/analysis/languages/javascript/", + "/analysis/languages/kotlin/", + "/analysis/languages/php/", + "/analysis/languages/pli/", + "/analysis/languages/plsql/", + "/analysis/languages/python/", + "/analysis/languages/rpg/", + "/analysis/languages/ruby/", + "/analysis/languages/scala/", + "/analysis/languages/swift/", + "/analysis/languages/typescript/", + "/analysis/languages/tsql/", + "/analysis/languages/vb/", + "/analysis/languages/vb6/", + "/analysis/languages/xml/" ] }, - "/analysis/analysis-parameters/", "/analysis/coverage/", "/analysis/external-issues/", "/analysis/background-tasks/", @@ -102,6 +121,7 @@ "/instance-administration/github-application/", "/instance-administration/look-and-feel/", "/instance-administration/marketplace/", + "/instance-administration/plugin-version-matrix/", "/instance-administration/housekeeping/", "/instance-administration/notifications/", "/instance-administration/system-info/", |