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/> <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> 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 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 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. (on the first source file found per language) per Eclipse project.
</p> </p>
@ -106,16 +106,6 @@ td {
</tr> </tr>
</tbody> </tbody>
</table> </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> <p>Remarks:</p>
<ul style="list-style-type:none"> <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> <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> <h3>Compilers supported through separate plug-ins</h3>
<!-- extra compilers go here --> <!-- extra compilers go here -->
<anchor id="extra_lsp_detection_participant_builtins_enhanced_list"/> <anchor id="extra_detection_participant_builtins_enhanced_list"/>
</body> </body>
</html> </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"> <!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"> <html xmlns="http://www.w3.org/1999/xhtml" lang="en">
<head> <head>
<title>Available Language Setting Providers</title> <title>Available Compiler Support for the Indexer</title>
<!--
TODO update this! We do not use Language Setting Providers in core build!
-->
<style type="text/css"> <style type="text/css">
table, th, td { table, th, td {
border: 1px solid black; border: 1px solid black;
@ -17,23 +14,10 @@ th, td {
</head> </head>
<body> <body>
<h1>Preprocessor Include Paths, Macros</h1> <h1>Preprocessor Include Paths, Macros</h1>
<P>Include paths and preprocessor macros for the CDT source code indexer are supplied by <P>The C/C++/CUDA editors use the CDT indexer to improve syntax highlighting, allowing you to jump to
<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
macro definitions and to browse through include files. macro definitions and to browse through include files.
</P> </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> <p>The following table lists the compiler executables supported by the CDT CMake build integration.</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>
<table id="overview_table" style="border-collapse:collapse"> <table id="overview_table" style="border-collapse:collapse">
<thead> <thead>
<tr> <tr>
@ -117,9 +101,8 @@ th, td {
<!-- extra compilers go here --> <!-- extra compilers go here -->
<anchor id="extra_detection_participant_list"/> <anchor id="extra_detection_participant_list"/>
<h2>CMAKE_EXPORT_COMPILE_COMMANDS Compiler Built-ins</h2> <h2>CDT CMake build integration Compiler Built-ins detection</h2>
<p>This provider works similar to <q>CMAKE_EXPORT_COMPILE_COMMANDS Parser</q>, but invokes <p>This feature also invokes tries to get the include paths and preprocessor macros
the compiler with arguments to get the include paths and preprocessor macros
<strong>built-in to the compiler</strong>.<br/> <strong>built-in to the compiler</strong>.<br/>
Note that this works only for compilers that supporting it. Note that this works only for compilers that supporting it.
See <a href="builtins-detection.xhtml">built-ins detection</a> for supported compilers. 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; &lt;p&gt;
To provide online help that lists the supported compilers anlong with and the recognized arguments, 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; 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;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_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;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; &lt;/ol&gt;
Example file &lt;code&gt;help_content_extension.xml&lt;/code&gt;: Example file &lt;code&gt;help_content_extension.xml&lt;/code&gt;:
&lt;pre&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 * @author Martin Weber
*/ */

15
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. * 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 * @param responseFileArglet the parsers for the response-file
* command-line argument for the tool or * command-line argument for the tool or
@ -114,10 +107,10 @@ public class DefaultToolCommandlineParser implements IToolCommandlineParser {
private final IPath cwd; private final IPath cwd;
/** /**
* @param cwd the current working directory of the compiler at the time of its * @param cwd the current working directory of the compiler at the time of its
* invocation * invocation
* *
* @throws NullPointerException if any of the arguments is {@code null} * @throws NullPointerException if any of the arguments is {@code null}
*/ */
public ParserHandler(IPath cwd) { public ParserHandler(IPath cwd) {
this.cwd = Objects.requireNonNull(cwd, "cwd"); //$NON-NLS-1$ this.cwd = Objects.requireNonNull(cwd, "cwd"); //$NON-NLS-1$

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; import java.util.Optional;
/** /**
* Responsible to match the first argument (the tool command) of a command-line * Participates in generating {@link org.eclipse.cdt.core.parser.IScannerInfo}
* and to provide a parser for the tool-specific command-line arguments. * 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 * @author Martin Weber
*/ */
public interface IToolDetectionParticipant { 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} * @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 * Gets, whether the parser for the tool arguments can properly parse the
* specified command-line string. If so, the remaining arguments of the * specified command-line string.
* command-line are returned.
* *
* @param commandLine the command line to match * @param commandLine the command line to match
* @param matchBackslash whether to match on file system paths with backslashes * @param matchBackslash whether to match on file system paths with backslashes
* in the compiler argument or to match an paths with * in the compiler argument or to match an paths with
* forward slashes * 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 * command-line string. Otherwise, if the tool name matches, a
* MatchResult holding the de-composed command-line is returned. * 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 * Gets, whether the parser for the tool arguments can properly parse the
* specified command-line string. If so, the remaining arguments of the * specified command-line string. This may be time-consuming, since it creates a
* command-line are returned. This is time-consuming, since it creates a Matcher * Matcher object on each invocation.
* object on each invocation.
* *
* @param commandLine the command-line to match * @param commandLine the command-line to match
* @param matchBackslash whether to match on file system paths with backslashes * @param matchBackslash whether to match on file system paths with backslashes
@ -62,7 +68,8 @@ public interface IToolDetectionParticipant {
* forward slashes * forward slashes
* @param versionRegex a regular expression that matches the version string in * @param versionRegex a regular expression that matches the version string in
* the name of the tool to detect. * 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 * command-line string. Otherwise, if the tool name matches, a
* MatchResult holding the de-composed command-line is returned. * 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 * Gets, whether the parser for the tool arguments can properly parse the
* specified command-line string. If so, the remaining arguments of the * specified command-line string.
* command-line are returned.
* *
* @param commandLine the command-line to match * @param commandLine the command-line to match
* @param matchBackslash whether to match on file system paths with backslashes * @param matchBackslash whether to match on file system paths with backslashes
* in the compiler argument or to match an paths with * in the compiler argument or to match an paths with
* forward slashes * 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 * command-line string. Otherwise, if the tool name matches, a
* MatchResult holding the de-composed command-line is returned. * 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 * Gets, whether the parser for the tool arguments can properly parse the
* specified command-line string. If so, the remaining arguments of the * specified command-line string. This may be time-consuming, since it creates a
* command-line are returned. This is time-consuming, since it creates a Matcher * Matcher object on each invocation.
* object on each invocation.
* *
* @param commandLine the command-line to match * @param commandLine the command-line to match
* @param matchBackslash whether to match on file system paths with backslashes * @param matchBackslash whether to match on file system paths with backslashes
@ -95,7 +101,8 @@ public interface IToolDetectionParticipant {
* forward slashes * forward slashes
* @param versionRegex a regular expression that matches the version string in * @param versionRegex a regular expression that matches the version string in
* the name of the tool to detect. * 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 * command-line string. Otherwise, if the tool name matches, a
* MatchResult holding the de-composed command-line is returned. * 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 * @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, * surrounding quotes must have been removed,
* @param arguments the remaining arguments from the command-line, without the * @param arguments the remaining arguments from the command-line, without the
* command * 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 * @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" <contribution content="doc/compiler.xhtml#builtins"
path="/de.marw.cdt.cmake.core/doc/html/builtins-detection.xhtml#extra_detection_participant_builtins_list"/> path="/de.marw.cdt.cmake.core/doc/html/builtins-detection.xhtml#extra_detection_participant_builtins_list"/>
<contribution content="doc/compiler.xhtml#builtins_enhanced" <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> </contentExtension>