mirrors/cdt
1
0
Fork 0
mirror of https://github.com/eclipse-cdt/cdt synced 2025-04-21 21:52:10 +02:00
Code Issues Wiki Activity

Bug 559674: Improve doc and javadoc

Browse source 
eliminate use of 'Language ID'
eliminate use of 'Language Setting'
eliminate use of 'Language Setting Provider' and 'lsp'

Change-Id: I7358ec99fde008d2b1a8c99fa294acac3469b20e
Signed-off-by: Martin Weber <fifteenknots505@gmail.com>
This commit is contained in:
Martin Weber 2020-05-28 22:37:10 +02:00 • committed by Alexander Fedorov
parent aa377d40c2
commit cfe6a49692
8 changed files with 48 additions and 69 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

14
cmake/org.eclipse.cdt.cmake.is.core.doc/doc/html/builtins-detection.xhtml
View file

@ -20,7 +20,7 @@ td {
<p>CDT CMake support can detect compiler-built-in include paths and preprocessor macros.<br/>
Unfortunately, it has no knowledge about the generated build system structure, the <code>compile_commads.json</code>
file generated by CMake only reports source-files. To avoid the cost of running the built-ins detector for
<strong>each</strong> source-file, CDT CMAke support assumes that compiler built-ins
<strong>each</strong> source-file, CDT CMake support assumes that compiler built-ins
are the same for each source-file in a CMake project. Therefore, detection is run just once
(on the first source file found per language) per Eclipse project.
</p>
@ -106,16 +106,6 @@ td {
</tr>
</tbody>
</table>
<p>
Please note that for performance reasons, compiler built-ins assumes that compiler built-ins
are the <strong>same for each source-file</strong> in a CMake project and built-ins detection is run only for the
first source-file.<br/>
In contrast, CMake has commands like <code>add_compile_options</code>, <code>target_compile_features</code> and
<code>target_compile_options</code> allowing you to specify the language standard and
non-standard system include paths on a
<strong>per-source-directory</strong> or <strong>per-artifact</strong> level.
Hence the syntax highlighting may not always exactly reflect the built-ins specified on that levels.
</p>
<p>Remarks:</p>
<ul style="list-style-type:none">
<li id="fw-help-gcc">[1] Help wanted! To implement this, the output of <code>gcc -E -P -dM -Wp,-v emty.c</code>
@ -126,6 +116,6 @@ td {
<h3>Compilers supported through separate plug-ins</h3>
<!-- extra compilers go here -->
<anchor id="extra_lsp_detection_participant_builtins_enhanced_list"/>
<anchor id="extra_detection_participant_builtins_enhanced_list"/>
</body>
</html>

27
cmake/org.eclipse.cdt.cmake.is.core.doc/doc/html/languageSettingsProviders.xhtml
View file

@ -2,10 +2,7 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
<head>
<title>Available Language Setting Providers</title>
<!--
TODO update this! We do not use Language Setting Providers in core build!
-->
<title>Available Compiler Support for the Indexer</title>
<style type="text/css">
table, th, td {
border: 1px solid black;
@ -17,23 +14,10 @@ th, td {
</head>
<body>
<h1>Preprocessor Include Paths, Macros</h1>
<P>Include paths and preprocessor macros for the CDT source code indexer are supplied by
<strong>Language Settings Providers</strong> using the
<a href="PLUGINS_ROOT/org.eclipse.cdt.doc.user/tasks/cdt_t_sd.htm">Scanner Discovery</a>
mechanism. The C/C++/CUDA editors use the indexer to improve syntax highlighting, allowing you to jump to
<P>The C/C++/CUDA editors use the CDT indexer to improve syntax highlighting, allowing you to jump to
macro definitions and to browse through include files.
</P>
<p>The CDT CMake support provides two <a href="PLUGINS_ROOT/org.eclipse.cdt.doc.user/concepts/cdt_c_scanner_discovery.htm">Language Settings Providers</a>:</p>
<h2>CMAKE_EXPORT_COMPILE_COMMANDS Parser</h2>
<p>This provider instructs CMake to generate a file that contains all the compiler command-lines
which will be executed when a project is build.<br/>
The provider will parse that file and feed any preprocessor include path, macro definition or
macro undefine that originates from your <em>CMakeLists.txt</em> files to the indexer.<br/>
Parsing is done rarely, since the internal cache is invalidated only when the
file`s time-stamp is newer, so it should be reasonably fast.
</p>
<p>The following table lists the compiler executables supported by the CMAKE_EXPORT_COMPILE_COMMANDS Parser.</p>
<p>The following table lists the compiler executables supported by the CDT CMake build integration.</p>
<table id="overview_table" style="border-collapse:collapse">
<thead>
<tr>
@ -117,9 +101,8 @@ th, td {
<!-- extra compilers go here -->
<anchor id="extra_detection_participant_list"/>
<h2>CMAKE_EXPORT_COMPILE_COMMANDS Compiler Built-ins</h2>
<p>This provider works similar to <q>CMAKE_EXPORT_COMPILE_COMMANDS Parser</q>, but invokes
the compiler with arguments to get the include paths and preprocessor macros
<h2>CDT CMake build integration Compiler Built-ins detection</h2>
<p>This feature also invokes tries to get the include paths and preprocessor macros
<strong>built-in to the compiler</strong>.<br/>
Note that this works only for compilers that supporting it.
See <a href="builtins-detection.xhtml">built-ins detection</a> for supported compilers.

4
cmake/org.eclipse.cdt.cmake.is.core/schema/participant.exsd
View file

@ -111,11 +111,11 @@ the Foobar company:
&lt;p&gt;
To provide online help that lists the supported compilers anlong with and the recognized arguments,
the extension point &lt;code&gt;org.eclipse.help.contentExtension&lt;/code&gt; can be used.&lt;br/&gt;
Plugin &lt;i&gt;de.marw.cdt.cmake.core&lt;/i&gt; provides predefined help-anchors that allow to integrate the online help:
Plugin &lt;i&gt;org.eclipse.cdt.cmake.is.core.doc&lt;/i&gt; provides predefined help-anchors that allow to integrate the online help:
&lt;ol&gt;
&lt;li&gt;&lt;i&gt;extra_detection_participant_list&lt;/i&gt; for the commandline parser,&lt;/li&gt;
&lt;li&gt;&lt;i&gt;extra_detection_participant_builtins_list&lt;/i&gt; and
&lt;i&gt;extra_lsp_detection_participant_builtins_enhanced_list&lt;/i&gt; for the compiler built-ins parser.&lt;/li&gt;
&lt;i&gt;extra_detection_participant_builtins_enhanced_list&lt;/i&gt; for the compiler built-ins parser.&lt;/li&gt;
&lt;/ol&gt;
Example file &lt;code&gt;help_content_extension.xml&lt;/code&gt;:
&lt;pre&gt;

5
cmake/org.eclipse.cdt.cmake.is.core/src/main/java/org/eclipse/cdt/cmake/is/core/package-info.java
View file

@ -8,7 +8,10 @@
*******************************************************************************/
/**
* Language Setting Providers
* Classes and interfaces to parse a file 'compile_commands.json' produced by
* cmake and to generate information about preprocessor symbols and include
* paths of the files being compiled in order to support the CDT indexer/ syntax
* highlighting.
*
* @author Martin Weber
*/

7
cmake/org.eclipse.cdt.cmake.is.core/src/main/java/org/eclipse/cdt/cmake/is/core/participant/DefaultToolCommandlineParser.java
View file

@ -35,13 +35,6 @@ public class DefaultToolCommandlineParser implements IToolCommandlineParser {
/**
* Constructs a new object with the given values.
* <p>
* NOTE: Concerning the {@code languageID} argument, please note that CDT
* expects "org.eclipse.cdt.core.gcc" for the C language and
* "org.eclipse.cdt.core.g++" for the C++ language. Some extension to CDT may
* recognize different language IDs, such as
* "com.nvidia.cuda.toolchain.language.cuda.cu"
* </p>
*
* @param responseFileArglet the parsers for the response-file
* command-line argument for the tool or

43
cmake/org.eclipse.cdt.cmake.is.core/src/main/java/org/eclipse/cdt/cmake/is/core/participant/IToolDetectionParticipant.java
View file

@ -12,15 +12,22 @@ package org.eclipse.cdt.cmake.is.core.participant;
import java.util.Optional;
/**
* Responsible to match the first argument (the tool command) of a command-line
* and to provide a parser for the tool-specific command-line arguments.
* Participates in generating {@link org.eclipse.cdt.core.parser.IScannerInfo}
* objects for the files being compiled in order to support the CDT indexer/
* syntax highlighting.<br>
* Generation of the {@code IScannerInfo} objects is done by analyzing a
* {@code compile_commands.json} file produced by cmake.
* <p>
* This interface is the expected interface for extensions provided for the
* {@code org.eclipse.cdt.cmake.is.core.detectionParticipant} extension point.
* </p>
*
* @author Martin Weber
*/
public interface IToolDetectionParticipant {
/**
* Gets the for the parser for the tool-specific command-line arguments.
* Gets the parser for the tool-specific command-line arguments.
*
* @return the parser, never {@code null}
*/
@ -37,14 +44,14 @@ public interface IToolDetectionParticipant {
/**
* Gets, whether the parser for the tool arguments can properly parse the
* specified command-line string. If so, the remaining arguments of the
* command-line are returned.
* specified command-line string.
*
* @param commandLine the command line to match
* @param matchBackslash whether to match on file system paths with backslashes
* in the compiler argument or to match an paths with
* forward slashes
* @return An empty {@code Optional} if the matcher did not match the tool name in the
* @return An empty {@code Optional} if the tool/compiler handled by this object
* does not match the first argument (the tool name) from the
* command-line string. Otherwise, if the tool name matches, a
* MatchResult holding the de-composed command-line is returned.
*/
@ -52,9 +59,8 @@ public interface IToolDetectionParticipant {
/**
* Gets, whether the parser for the tool arguments can properly parse the
* specified command-line string. If so, the remaining arguments of the
* command-line are returned. This is time-consuming, since it creates a Matcher
* object on each invocation.
* specified command-line string. This may be time-consuming, since it creates a
* Matcher object on each invocation.
*
* @param commandLine the command-line to match
* @param matchBackslash whether to match on file system paths with backslashes
@ -62,7 +68,8 @@ public interface IToolDetectionParticipant {
* forward slashes
* @param versionRegex a regular expression that matches the version string in
* the name of the tool to detect.
* @return An empty {@code Optional} if the matcher did not match the tool name in the
* @return An empty {@code Optional} if the tool/compiler handled by this object
* does not match the first argument (the tool name) from the
* command-line string. Otherwise, if the tool name matches, a
* MatchResult holding the de-composed command-line is returned.
*/
@ -70,14 +77,14 @@ public interface IToolDetectionParticipant {
/**
* Gets, whether the parser for the tool arguments can properly parse the
* specified command-line string. If so, the remaining arguments of the
* command-line are returned.
* specified command-line string.
*
* @param commandLine the command-line to match
* @param matchBackslash whether to match on file system paths with backslashes
* in the compiler argument or to match an paths with
* forward slashes
* @return An empty {@code Optional} if the matcher did not match the tool name in the
* @return An empty {@code Optional} if the tool/compiler handled by this object
* does not match the first argument (the tool name) from the
* command-line string. Otherwise, if the tool name matches, a
* MatchResult holding the de-composed command-line is returned.
*/
@ -85,9 +92,8 @@ public interface IToolDetectionParticipant {
/**
* Gets, whether the parser for the tool arguments can properly parse the
* specified command-line string. If so, the remaining arguments of the
* command-line are returned. This is time-consuming, since it creates a Matcher
* object on each invocation.
* specified command-line string. This may be time-consuming, since it creates a
* Matcher object on each invocation.
*
* @param commandLine the command-line to match
* @param matchBackslash whether to match on file system paths with backslashes
@ -95,7 +101,8 @@ public interface IToolDetectionParticipant {
* forward slashes
* @param versionRegex a regular expression that matches the version string in
* the name of the tool to detect.
* @return An empty {@code Optional} if the matcher did not match the tool name in the
* @return An empty {@code Optional} if the tool/compiler handled by this object
* does not match the first argument (the tool name) from the
* command-line string. Otherwise, if the tool name matches, a
* MatchResult holding the de-composed command-line is returned.
*/
@ -111,7 +118,7 @@ public interface IToolDetectionParticipant {
/**
* @param command the command from the command-line, without the argument
* string. . If the command contains space characters, the
* string. If the command contains space characters, the
* surrounding quotes must have been removed,
* @param arguments the remaining arguments from the command-line, without the
* command

7
cmake/org.eclipse.cdt.cmake.is.core/src/main/java/org/eclipse/cdt/cmake/is/core/internal/package-info.java → cmake/org.eclipse.cdt.cmake.is.core/src/main/java/org/eclipse/cdt/cmake/is/core/participant/package-info.java
View file

@ -8,8 +8,11 @@
*******************************************************************************/
/**
* Language Setting Providers
* Classes and interfaces allowing for third-party compiler vendors so they can
* provide a plugin that understands their compiler specific command-line
* options and participates in command-line analysis in order to support the CDT
* indexer/ syntax highlighting.
*
* @author Martin Weber
*/
package org.eclipse.cdt.cmake.is.core.internal;
package org.eclipse.cdt.cmake.is.core.participant;

2
cmake/org.eclipse.cdt.cmake.is.nvidia/help_content_extension.xml
View file

@ -5,5 +5,5 @@
<contribution content="doc/compiler.xhtml#builtins"
path="/de.marw.cdt.cmake.core/doc/html/builtins-detection.xhtml#extra_detection_participant_builtins_list"/>
<contribution content="doc/compiler.xhtml#builtins_enhanced"
path="/de.marw.cdt.cmake.core/doc/html/builtins-detection.xhtml#extra_lsp_detection_participant_builtins_enhanced_list"/>
path="/de.marw.cdt.cmake.core/doc/html/builtins-detection.xhtml#extra_detection_participant_builtins_enhanced_list"/>
</contentExtension>