The routines in this group provide the ability to create and destroy translation units from files, either by parsing the contents of the files or by reading in a serialized representation of a translation unit. More...
clang_saveTranslationUnit() . More... -emit-ast). command_line_args including argv[0]. The routines in this group provide the ability to create and destroy translation units from files, either by parsing the contents of the files or by reading in a serialized representation of a translation unit.
The memory usage of a CXTranslationUnit, broken into categories.
Describes the kind of error that occurred (if any) in a call to clang_saveTranslationUnit() .
| Enumerator | |
|---|---|
| CXSaveError_None | Indicates that no error occurred while saving a translation unit. |
| CXSaveError_Unknown | Indicates that an unknown error occurred while attempting to save the file. This error typically indicates that file I/O failed when attempting to write the file. |
| CXSaveError_TranslationErrors | Indicates that errors during translation prevented this attempt to save the translation unit. Errors that prevent the translation unit from being saved can be extracted using |
| CXSaveError_InvalidTU | Indicates that the translation unit to be saved was somehow invalid (e.g., NULL). |
Flags that control how translation units are saved.
The enumerators in this enumeration type are meant to be bitwise ORed together to specify which options should be used when saving the translation unit.
| Enumerator | |
|---|---|
| CXSaveTranslationUnit_None | Used to indicate that no special saving options are needed. |
Flags that control the creation of translation units.
The enumerators in this enumeration type are meant to be bitwise ORed together to specify which options should be used when constructing the translation unit.
| Enumerator | |
|---|---|
| CXTranslationUnit_None | Used to indicate that no special translation-unit options are needed. |
| CXTranslationUnit_DetailedPreprocessingRecord | Used to indicate that the parser should construct a "detailed" preprocessing record, including all macro definitions and instantiations. Constructing a detailed preprocessing record requires more memory and time to parse, since the information contained in the record is usually not retained. However, it can be useful for applications that require more detailed information about the behavior of the preprocessor. |
| CXTranslationUnit_Incomplete | Used to indicate that the translation unit is incomplete. When a translation unit is considered "incomplete", semantic analysis that is typically performed at the end of the translation unit will be suppressed. For example, this suppresses the completion of tentative declarations in C and of instantiation of implicitly-instantiation function templates in C++. This option is typically used when parsing a header with the intent of producing a precompiled header. |
| CXTranslationUnit_PrecompiledPreamble | Used to indicate that the translation unit should be built with an implicit precompiled header for the preamble. An implicit precompiled header is used as an optimization when a particular translation unit is likely to be reparsed many times when the sources aren't changing that often. In this case, an implicit precompiled header will be built containing all of the initial includes at the top of the main file (what we refer to as the "preamble" of the file). In subsequent parses, if the preamble or the files in it have not changed, |
| CXTranslationUnit_CacheCompletionResults | Used to indicate that the translation unit should cache some code-completion results with each reparse of the source file. Caching of code-completion results is a performance optimization that introduces some overhead to reparsing but improves the performance of code-completion operations. |
| CXTranslationUnit_ForSerialization | Used to indicate that the translation unit will be serialized with This option is typically used when parsing a header with the intent of producing a precompiled header. |
| CXTranslationUnit_CXXChainedPCH | DEPRECATED: Enabled chained precompiled preambles in C++. Note: this is a temporary option that is available only while we are testing C++ precompiled preamble support. It is deprecated. |
| CXTranslationUnit_SkipFunctionBodies | Used to indicate that function/method bodies should be skipped while parsing. This option can be used to search for declarations/definitions while ignoring the usages. |
| CXTranslationUnit_IncludeBriefCommentsInCodeCompletion | Used to indicate that brief documentation comments should be included into the set of code completions returned from this translation unit. |
| CXTranslationUnit_CreatePreambleOnFirstParse | Used to indicate that the precompiled preamble should be created on the first parse. Otherwise it will be created on the first reparse. This trades runtime on the first parse (serializing the preamble takes time) for reduced runtime on the second parse (can now reuse the preamble). |
| CXTranslationUnit_KeepGoing | Do not stop processing when fatal errors are encountered. When fatal errors are encountered while parsing a translation unit, semantic analysis is typically stopped early when compiling code. A common source for fatal errors are unresolvable include files. For the purposes of an IDE, this is undesirable behavior and as much information as possible should be reported. Use this flag to enable this behavior. |
| CXTranslationUnit_SingleFileParse | Sets the preprocessor in a mode for parsing a single file only. |
| CXTranslationUnit_LimitSkipFunctionBodiesToPreamble | Used in combination with CXTranslationUnit_SkipFunctionBodies to constrain the skipping of function bodies to the preamble. The function bodies of the main file are not skipped. |
| CXTranslationUnit_IncludeAttributedTypes | Used to indicate that attributed types should be included in CXType. |
| CXTranslationUnit_VisitImplicitAttributes | Used to indicate that implicit attributes should be visited. |
| CXTranslationUnit_IgnoreNonErrorsFromIncludedFiles | Used to indicate that non-errors from included files should be ignored. If set, clang_getDiagnosticSetFromTU() will not report e.g. warnings from included files anymore. This speeds up clang_getDiagnosticSetFromTU() for the case where these warnings are not of interest, as for an IDE for example, which typically shows only the diagnostics in the main file. |
| CXTranslationUnit_RetainExcludedConditionalBlocks | Tells the preprocessor not to skip excluded conditional blocks. |
Categorizes how memory is being used by a translation unit.
Same as clang_createTranslationUnit2, but returns the CXTranslationUnit instead of an error code.
In case of an error this routine returns a NULL CXTranslationUnit , without further detailed error codes.
References CINDEX_LINKAGE.
Create a translation unit from an AST file (-emit-ast).
CXTranslationUnit .Return the CXTranslationUnit for a given source file and the provided command line arguments one would pass to the compiler.
Note: The 'source_filename' argument is optional. If the caller provides a NULL pointer, the name of the source file is expected to reside in the specified command line arguments.
Note: When encountered in 'clang_command_line_args', the following options are ignored:
'-c' '-emit-ast' '-fsyntax-only' '-o <output file>' (both '-o' and '<output file>' are ignored)
clang_command_line_args.clang_command_line_args.clang executable if it were being invoked out-of-process. These command-line options will be parsed and will affect how the translation unit is parsed. Note that the following options are ignored: '-c', '-emit-ast', '-fsyntax-only' (which is the default), and '-o <output file>'.unsaved_files.References CINDEX_LINKAGE.
Returns the set of flags that is suitable for parsing a translation unit that is being edited.
The set of flags returned provide options for clang_parseTranslationUnit() to indicate that the translation unit is likely to be reparsed many times, either explicitly (via clang_reparseTranslationUnit() ) or implicitly (e.g., by code completion (clang_codeCompletionAt())). The returned flag set contains an unspecified set of optimizations (e.g., the precompiled preamble) geared toward improving the performance of these routines. The set of optimizations enabled may change from one version to the next.
References CINDEX_LINKAGE.
Returns the set of flags that is suitable for reparsing a translation unit.
The set of flags returned provide options for clang_reparseTranslationUnit() by default. The returned flag set contains an unspecified set of optimizations geared toward common uses of reparsing. The set of optimizations enabled may change from one version to the next.
References CINDEX_LINKAGE.
Returns the set of flags that is suitable for saving a translation unit.
The set of flags returned provide options for clang_saveTranslationUnit() by default. The returned flag set contains an unspecified set of options that save translation units with the most commonly-requested data.
References CINDEX_LINKAGE.
References CINDEX_LINKAGE.
Destroy the specified CXTranslationUnit object.
References CINDEX_LINKAGE.
Return the memory usage of a translation unit.
This object should be released with clang_disposeCXTUResourceUsage().
Get the original translation unit source file name.
Get target information for this translation unit.
The CXTargetInfo object cannot outlive the CXTranslationUnit object.
Returns the human-readable null-terminated C string that represents the name of the memory category.
This string should never be freed.
Same as clang_parseTranslationUnit2, but returns the CXTranslationUnit instead of an error code.
In case of an error this routine returns a NULL CXTranslationUnit , without further detailed error codes.
References CINDEX_LINKAGE.
Parse the given source file and the translation unit corresponding to that file.
This routine is the main entry point for the Clang C API, providing the ability to parse a source file into a translation unit that can then be queried by other functions in the API. This routine accepts a set of command-line arguments so that the compilation can be configured in the same way that the compiler is configured on the command line.
command_line_args.clang executable if it were being invoked out-of-process. These command-line options will be parsed and will affect how the translation unit is parsed. Note that the following options are ignored: '-c', '-emit-ast', '-fsyntax-only' (which is the default), and '-o <output file>'.command_line_args.unsaved_files.CXTranslationUnit , describing the parsed code and containing any diagnostics produced by the compiler.References CINDEX_LINKAGE.
Same as clang_parseTranslationUnit2 but requires a full command line for command_line_args including argv[0].
This is useful if the standard library paths are relative to the binary.
References CINDEX_LINKAGE.
Reparse the source files that produced this translation unit.
This routine can be used to re-parse the source files that originally created the given translation unit, for example because those source files have changed (either on disk or as passed via unsaved_files). The source code will be reparsed with the same command-line options as it was originally parsed.
Reparsing a translation unit invalidates all cursors and source locations that refer into that translation unit. This makes reparsing a translation unit semantically equivalent to destroying the translation unit and then creating a new translation unit with the same command-line arguments. However, it may be more efficient to reparse a translation unit using this routine.
clang_createTranslationUnitFromSourceFile() .unsaved_files.clang_defaultReparseOptions() produces a default set of options recommended for most uses, based on the translation unit.TU is clang_disposeTranslationUnit(TU). The error codes returned by this routine are described by the CXErrorCode enum. Saves a translation unit into a serialized representation of that translation unit on disk.
Any translation unit that was parsed without error can be saved into a file. The translation unit can then be deserialized into a new CXTranslationUnit with clang_createTranslationUnit() or, if it is an incomplete translation unit that corresponds to a header, used as a precompiled header when parsing other translation units.
References CINDEX_LINKAGE.
Suspend a translation unit in order to free memory associated with it.
A suspended translation unit uses significantly less memory but on the other side does not support any other calls than clang_reparseTranslationUnit to resume it or clang_disposeTranslationUnit to dispose it completely.
References CINDEX_LINKAGE.
Destroy the CXTargetInfo object.
References CINDEX_LINKAGE.
Get the pointer width of the target in bits.
Returns -1 in case of error.
References CINDEX_LINKAGE.
Get the normalized target triple as a string.
Returns the empty string in case of any error.
References CINDEX_LINKAGE.