mirror of
https://github.com/eclipse-cdt/cdt
synced 2025-04-21 21:52:10 +02:00
Bug 559674: Improve doc and javadoc
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
Alexander Fedorov
parent
aa377d40c2
commit
cfe6a49692
8 changed files with 48 additions and 69 deletions
|
|
@ -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>
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -111,11 +111,11 @@ the Foobar company:
|
|||
<p>
|
||||
To provide online help that lists the supported compilers anlong with and the recognized arguments,
|
||||
the extension point <code>org.eclipse.help.contentExtension</code> can be used.<br/>
|
||||
Plugin <i>de.marw.cdt.cmake.core</i> provides predefined help-anchors that allow to integrate the online help:
|
||||
Plugin <i>org.eclipse.cdt.cmake.is.core.doc</i> provides predefined help-anchors that allow to integrate the online help:
|
||||
<ol>
|
||||
<li><i>extra_detection_participant_list</i> for the commandline parser,</li>
|
||||
<li><i>extra_detection_participant_builtins_list</i> and
|
||||
<i>extra_lsp_detection_participant_builtins_enhanced_list</i> for the compiler built-ins parser.</li>
|
||||
<i>extra_detection_participant_builtins_enhanced_list</i> for the compiler built-ins parser.</li>
|
||||
</ol>
|
||||
Example file <code>help_content_extension.xml</code>:
|
||||
<pre>
|
||||
|
|
|
|||
|
|
@ -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
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -114,10 +107,10 @@ public class DefaultToolCommandlineParser implements IToolCommandlineParser {
|
|||
private final IPath cwd;
|
||||
|
||||
/**
|
||||
* @param cwd the current working directory of the compiler at the time of its
|
||||
* invocation
|
||||
*
|
||||
* @throws NullPointerException if any of the arguments is {@code null}
|
||||
* @param cwd the current working directory of the compiler at the time of its
|
||||
* invocation
|
||||
*
|
||||
* @throws NullPointerException if any of the arguments is {@code null}
|
||||
*/
|
||||
public ParserHandler(IPath cwd) {
|
||||
this.cwd = Objects.requireNonNull(cwd, "cwd"); //$NON-NLS-1$
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
@ -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>
|
||||
Loading…
Add table
Reference in a new issue