clang API Documentation

Classes | Public Types | Public Member Functions | Static Public Member Functions | Friends
clang::HeaderSearch Class Reference

Encapsulates the information needed to find the file referenced by a #include or #include_next, (sub-)framework lookup, etc. More...

#include <HeaderSearch.h>

List of all members.

Classes

struct  FrameworkCacheEntry
 This structure is used to record entries in our framework cache.
struct  LookupFileCacheInfo
 Keeps track of each lookup performed by LookupFile.

Public Types

typedef std::vector
< DirectoryLookup >
::const_iterator 
search_dir_iterator

Public Member Functions

 HeaderSearch (IntrusiveRefCntPtr< HeaderSearchOptions > HSOpts, SourceManager &SourceMgr, DiagnosticsEngine &Diags, const LangOptions &LangOpts, const TargetInfo *Target)
 ~HeaderSearch ()
HeaderSearchOptionsgetHeaderSearchOpts () const
 Retrieve the header-search options with which this header search was initialized.
FileManagergetFileMgr () const
void SetSearchPaths (const std::vector< DirectoryLookup > &dirs, unsigned angledDirIdx, unsigned systemDirIdx, bool noCurDirSearch)
 Interface for setting the file search paths.
void AddSearchPath (const DirectoryLookup &dir, bool isAngled)
 Add an additional search path.
void SetSystemHeaderPrefixes (ArrayRef< std::pair< std::string, bool > > P)
 Set the list of system header prefixes.
bool HasIncludeAliasMap () const
 Checks whether the map exists or not.
void AddIncludeAlias (StringRef Source, StringRef Dest)
 Map the source include name to the dest include name.
StringRef MapHeaderToIncludeAlias (StringRef Source)
void setModuleCachePath (StringRef CachePath)
 Set the path to the module cache.
StringRef getModuleCachePath () const
 Retrieve the path to the module cache.
void setDirectoryHasModuleMap (const DirectoryEntry *Dir)
 Consider modules when including files from this directory.
void ClearFileInfo ()
 Forget everything we know about headers so far.
void SetExternalLookup (ExternalIdentifierLookup *EIL)
ExternalIdentifierLookupgetExternalLookup () const
void SetExternalSource (ExternalHeaderFileInfoSource *ES)
 Set the external source of header information.
void setTarget (const TargetInfo &Target)
 Set the target information for the header search, if not already known.
const FileEntryLookupFile (StringRef Filename, SourceLocation IncludeLoc, bool isAngled, const DirectoryLookup *FromDir, const DirectoryLookup *&CurDir, ArrayRef< std::pair< const FileEntry *, const DirectoryEntry * >> Includers, SmallVectorImpl< char > *SearchPath, SmallVectorImpl< char > *RelativePath, ModuleMap::KnownHeader *SuggestedModule, bool SkipCache=false)
 Given a "foo" or <foo> reference, look up the indicated file, return null on failure.
const FileEntryLookupSubframeworkHeader (StringRef Filename, const FileEntry *RelativeFileEnt, SmallVectorImpl< char > *SearchPath, SmallVectorImpl< char > *RelativePath, ModuleMap::KnownHeader *SuggestedModule)
 Look up a subframework for the specified #include file.
FrameworkCacheEntry & LookupFrameworkCache (StringRef FWName)
 Look up the specified framework name in our framework cache.
bool ShouldEnterIncludeFile (const FileEntry *File, bool isImport)
 Mark the specified file as a target of of a #include, #include_next, or #import directive.
SrcMgr::CharacteristicKind getFileDirFlavor (const FileEntry *File)
 Return whether the specified file is a normal header, a system header, or a C++ friendly system header.
void MarkFileIncludeOnce (const FileEntry *File)
 Mark the specified file as a "once only" file, e.g. due to #pragma once.
void MarkFileSystemHeader (const FileEntry *File)
 Mark the specified file as a system header, e.g. due to #pragma GCC system_header.
void MarkFileModuleHeader (const FileEntry *File, ModuleMap::ModuleHeaderRole Role, bool IsCompiledModuleHeader)
 Mark the specified file as part of a module.
void IncrementIncludeCount (const FileEntry *File)
 Increment the count for the number of times the specified FileEntry has been entered.
void SetFileControllingMacro (const FileEntry *File, const IdentifierInfo *ControllingMacro)
 Mark the specified file as having a controlling macro.
bool FirstTimeLexingFile (const FileEntry *File)
 Return true if this is the first time encountering this header.
bool isFileMultipleIncludeGuarded (const FileEntry *File)
 Determine whether this file is intended to be safe from multiple inclusions, e.g., it has #pragma once or a controlling macro.
const HeaderMapCreateHeaderMap (const FileEntry *FE)
bool enabledModules () const
 Returns true if modules are enabled.
std::string getModuleFileName (Module *Module)
 Retrieve the name of the module file that should be used to load the given module.
std::string getModuleFileName (StringRef ModuleName, StringRef ModuleMapPath)
 Retrieve the name of the module file that should be used to load a module with the given name.
ModulelookupModule (StringRef ModuleName, bool AllowSearch=true)
 Lookup a module Search for a module with the given name.
const FileEntrylookupModuleMapFile (const DirectoryEntry *Dir, bool IsFramework)
 Try to find a module map file in the given directory, returning nullptr if none is found.
void IncrementFrameworkLookupCount ()
bool hasModuleMap (StringRef Filename, const DirectoryEntry *Root, bool IsSystem)
 Determine whether there is a module map that may map the header with the given file name to a (sub)module. Always returns false if modules are disabled.
ModuleMap::KnownHeader findModuleForHeader (const FileEntry *File) const
 Retrieve the module that corresponds to the given file, if any.
bool loadModuleMapFile (const FileEntry *File, bool IsSystem)
 Read the contents of the given module map file.
void collectAllModules (SmallVectorImpl< Module * > &Modules)
 Collect the set of all known, top-level modules.
void loadTopLevelSystemModules ()
 Load all known, top-level system modules.
ModuleMapgetModuleMap ()
 Retrieve the module map.
unsigned header_file_size () const
bool tryGetFileInfo (const FileEntry *FE, HeaderFileInfo &Result) const
 Get a HeaderFileInfo structure for the specified FileEntry, if one exists.
search_dir_iterator search_dir_begin () const
search_dir_iterator search_dir_end () const
unsigned search_dir_size () const
search_dir_iterator quoted_dir_begin () const
search_dir_iterator quoted_dir_end () const
search_dir_iterator angled_dir_begin () const
search_dir_iterator angled_dir_end () const
search_dir_iterator system_dir_begin () const
search_dir_iterator system_dir_end () const
StringRef getUniqueFrameworkName (StringRef Framework)
 Retrieve a uniqued framework name.
void PrintStats ()
size_t getTotalMemory () const

Static Public Member Functions

static std::string NormalizeDashIncludePath (StringRef File, FileManager &FileMgr)

Friends

class DirectoryLookup

Detailed Description

Encapsulates the information needed to find the file referenced by a #include or #include_next, (sub-)framework lookup, etc.

Definition at line 149 of file HeaderSearch.h.


Member Typedef Documentation

typedef std::vector<DirectoryLookup>::const_iterator clang::HeaderSearch::search_dir_iterator

Definition at line 594 of file HeaderSearch.h.


Constructor & Destructor Documentation

HeaderSearch::HeaderSearch ( IntrusiveRefCntPtr< HeaderSearchOptions HSOpts,
SourceManager SourceMgr,
DiagnosticsEngine Diags,
const LangOptions LangOpts,
const TargetInfo Target 
)

Definition at line 48 of file HeaderSearch.cpp.

Definition at line 67 of file HeaderSearch.cpp.


Member Function Documentation

void clang::HeaderSearch::AddIncludeAlias ( StringRef  Source,
StringRef  Dest 
) [inline]

Map the source include name to the dest include name.

The Source should include the angle brackets or quotes, the dest should not. This allows for distinction between <> and "" headers.

Definition at line 309 of file HeaderSearch.h.

Referenced by clang::Preprocessor::HandlePragmaIncludeAlias().

void clang::HeaderSearch::AddSearchPath ( const DirectoryLookup dir,
bool  isAngled 
) [inline]

Add an additional search path.

Definition at line 289 of file HeaderSearch.h.

Definition at line 606 of file HeaderSearch.h.

Definition at line 609 of file HeaderSearch.h.

Forget everything we know about headers so far.

Definition at line 343 of file HeaderSearch.h.

void HeaderSearch::collectAllModules ( SmallVectorImpl< Module * > &  Modules)

Collect the set of all known, top-level modules.

Parameters:
ModulesWill be filled with the set of known, top-level modules.

Definition at line 1245 of file HeaderSearch.cpp.

References clang::FileManager::getDirectory(), loadModuleMapFile(), clang::ModuleMap::module_begin(), and clang::ModuleMap::module_end().

CreateHeaderMap - This method returns a HeaderMap for the specified FileEntry, uniquing them through the 'HeaderMaps' datastructure.

Definition at line 97 of file HeaderSearch.cpp.

References clang::HeaderMap::Create().

Returns true if modules are enabled.

Definition at line 482 of file HeaderSearch.h.

Referenced by hasModuleMap().

Retrieve the module that corresponds to the given file, if any.

Parameters:
FileThe header that we wish to map to a module.

Definition at line 1110 of file HeaderSearch.cpp.

References clang::ModuleMap::findModuleForHeader().

Referenced by getFileAndSuggestModule(), clang::VerifyDiagnosticConsumer::HandleDiagnostic(), and LookupSubframeworkHeader().

Return true if this is the first time encountering this header.

Definition at line 466 of file HeaderSearch.h.

References clang::HeaderFileInfo::NumIncludes.

Referenced by clang::Preprocessor::HandleEndOfFile().

Definition at line 351 of file HeaderSearch.h.

Return whether the specified file is a normal header, a system header, or a C++ friendly system header.

Definition at line 427 of file HeaderSearch.h.

References clang::HeaderFileInfo::DirInfo.

Retrieve the header-search options with which this header search was initialized.

Definition at line 271 of file HeaderSearch.h.

Referenced by clang::CompilerInstance::createPCHExternalASTSource().

StringRef clang::HeaderSearch::getModuleCachePath ( ) const [inline]

Retrieve the path to the module cache.

Definition at line 335 of file HeaderSearch.h.

Referenced by clang::FrontendAction::Execute().

std::string HeaderSearch::getModuleFileName ( Module Module)

Retrieve the name of the module file that should be used to load the given module.

Parameters:
ModuleThe module whose module file name will be returned.
Returns:
The name of the module file that corresponds to this module, or an empty string if this module does not correspond to any module file.

Definition at line 116 of file HeaderSearch.cpp.

References getModuleMap(), clang::ModuleMap::getModuleMapFileForUniquing(), clang::FileEntry::getName(), and clang::Module::Name.

Referenced by clang::GenerateModuleAction::ComputeASTConsumerArguments().

std::string HeaderSearch::getModuleFileName ( StringRef  ModuleName,
StringRef  ModuleMapPath 
)

Retrieve the name of the module file that should be used to load a module with the given name.

Parameters:
ModuleNameThe module whose module file name will be returned.
ModuleMapPathA path that when combined with ModuleName uniquely identifies this module. See Module::ModuleMap.
Returns:
The name of the module file that corresponds to this module, or an empty string if this module does not correspond to any module file.

Definition at line 122 of file HeaderSearch.cpp.

Definition at line 1052 of file HeaderSearch.cpp.

StringRef HeaderSearch::getUniqueFrameworkName ( StringRef  Framework)

Retrieve a uniqued framework name.

Definition at line 1060 of file HeaderSearch.cpp.

Referenced by LookupFile().

Checks whether the map exists or not.

Definition at line 303 of file HeaderSearch.h.

bool HeaderSearch::hasModuleMap ( StringRef  Filename,
const DirectoryEntry Root,
bool  IsSystem 
)

Determine whether there is a module map that may map the header with the given file name to a (sub)module. Always returns false if modules are disabled.

Parameters:
FilenameThe name of the file.
RootThe "root" directory, at which we should stop looking for module maps.
IsSystemWhether the directories we're looking at are system header directories.

Definition at line 1064 of file HeaderSearch.cpp.

References enabledModules(), clang::FileManager::getDirectory(), and loadModuleMapFile().

Referenced by getFileAndSuggestModule().

Definition at line 587 of file HeaderSearch.h.

Definition at line 521 of file HeaderSearch.h.

void clang::HeaderSearch::IncrementIncludeCount ( const FileEntry File) [inline]

Increment the count for the number of times the specified FileEntry has been entered.

Definition at line 452 of file HeaderSearch.h.

References clang::HeaderFileInfo::NumIncludes.

Referenced by clang::Preprocessor::EnterMainSourceFile().

Determine whether this file is intended to be safe from multiple inclusions, e.g., it has #pragma once or a controlling macro.

This routine does not consider the effect of #import

Definition at line 990 of file HeaderSearch.cpp.

References clang::HeaderFileInfo::ControllingMacro, clang::HeaderFileInfo::ControllingMacroID, clang::ExternalHeaderFileInfoSource::GetHeaderFileInfo(), clang::FileEntry::getUID(), clang::HeaderFileInfo::isImport, clang::HeaderFileInfo::isPragmaOnce, mergeHeaderFileInfo(), and clang::HeaderFileInfo::Resolved.

bool HeaderSearch::loadModuleMapFile ( const FileEntry File,
bool  IsSystem 
)

Read the contents of the given module map file.

Parameters:
FileThe module map file.
IsSystemWhether this file is in a system header directory.
Returns:
true if an error occurred, false otherwise.

Definition at line 1133 of file HeaderSearch.cpp.

Referenced by clang::GenerateModuleAction::BeginSourceFileAction(), collectAllModules(), hasModuleMap(), loadTopLevelSystemModules(), LookupFile(), and lookupModule().

Load all known, top-level system modules.

Definition at line 1294 of file HeaderSearch.cpp.

References loadModuleMapFile().

const FileEntry * HeaderSearch::LookupFile ( StringRef  Filename,
SourceLocation  IncludeLoc,
bool  isAngled,
const DirectoryLookup FromDir,
const DirectoryLookup *&  CurDir,
ArrayRef< std::pair< const FileEntry *, const DirectoryEntry * >>  Includers,
SmallVectorImpl< char > *  SearchPath,
SmallVectorImpl< char > *  RelativePath,
ModuleMap::KnownHeader SuggestedModule,
bool  SkipCache = false 
)

Given a "foo" or <foo> reference, look up the indicated file, return null on failure.

Returns:
If successful, this returns 'UsedDir', the DirectoryLookup member the file was found in, or null if not applicable.
Parameters:
IncludeLocUsed for diagnostics if valid.
isAngledindicates whether the file reference is a <> reference.
CurDirIf non-null, the file was found in the specified directory search location. This is used to implement #include_next.
IncludersIndicates where the #including file(s) are, in case relative searches are needed. In reverse order of inclusion.
SearchPathIf non-null, will be set to the search path relative to which the file was found. If the include path is absolute, SearchPath will be set to an empty string.
RelativePathIf non-null, will be set to the path relative to SearchPath at which the file was found. This only differs from the Filename for framework includes.
SuggestedModuleIf non-null, and the file found is semantically part of a known module, this will be set to the module that should be imported instead of preprocessing/parsing the file found.

LookupFile - Given a "foo" or <foo> reference, look up the indicated file, return null on failure. isAngled indicates whether the file reference is for system #include's or not (i.e. using <> instead of ""). Includers, if non-empty, indicates where the #including file(s) are, in case a relative search is needed. Microsoft mode will pass all #including files.

Definition at line 566 of file HeaderSearch.cpp.

References clang::SrcMgr::C_System, clang::SrcMgr::C_User, checkMSVCHeaderSearch(), copyString(), clang::HeaderFileInfo::DirInfo, clang::HeaderFileInfo::Framework, clang::DirectoryLookup::getDirCharacteristic(), clang::FileManager::getFile(), getFileAndSuggestModule(), clang::FileEntry::getName(), getUniqueFrameworkName(), clang::HeaderFileInfo::IndexHeaderMapHeader, clang::DiagnosticsEngine::isIgnored(), clang::DirectoryLookup::isIndexHeaderMap(), and loadModuleMapFile().

Referenced by clang::Preprocessor::LookupFile().

FrameworkCacheEntry& clang::HeaderSearch::LookupFrameworkCache ( StringRef  FWName) [inline]

Look up the specified framework name in our framework cache.

Returns:
The DirectoryEntry it is in if we know, null otherwise.

Definition at line 413 of file HeaderSearch.h.

Module * HeaderSearch::lookupModule ( StringRef  ModuleName,
bool  AllowSearch = true 
)

Lookup a module Search for a module with the given name.

Parameters:
ModuleNameThe name of the module we're looking for.
AllowSearchWhether we are allowed to search in the various search directories to produce a module definition. If not, this lookup will only return an already-known module.
Returns:
The module with the given name.

Definition at line 149 of file HeaderSearch.cpp.

References clang::SrcMgr::C_User, clang::ModuleMap::findModule(), clang::FileManager::getDirectory(), and loadModuleMapFile().

Referenced by clang::GenerateModuleAction::BeginSourceFileAction(), and clang::Preprocessor::getCurrentModule().

const FileEntry * HeaderSearch::lookupModuleMapFile ( const DirectoryEntry Dir,
bool  IsFramework 
)

Try to find a module map file in the given directory, returning nullptr if none is found.

Definition at line 1174 of file HeaderSearch.cpp.

References clang::FileManager::getFile(), and clang::DirectoryEntry::getName().

Referenced by clang::ModuleMap::inferFrameworkModule().

const FileEntry * HeaderSearch::LookupSubframeworkHeader ( StringRef  Filename,
const FileEntry ContextFileEnt,
SmallVectorImpl< char > *  SearchPath,
SmallVectorImpl< char > *  RelativePath,
ModuleMap::KnownHeader SuggestedModule 
)

Look up a subframework for the specified #include file.

For example, if #include'ing <HIToolbox/HIToolbox.h> from within ".../Carbon.framework/Headers/Carbon.h", check to see if HIToolbox is a subframework within Carbon.framework. If so, return the FileEntry for the designated file, otherwise return null.

LookupSubframeworkHeader - Look up a subframework for the specified #include file. For example, if #include'ing <HIToolbox/HIToolbox.h> from within ".../Carbon.framework/Headers/Carbon.h", check to see if HIToolbox is a subframework within Carbon.framework. If so, return the FileEntry for the designated file, otherwise return null.

Definition at line 820 of file HeaderSearch.cpp.

References clang::HeaderFileInfo::DirInfo, findModuleForHeader(), clang::FileManager::getDirectory(), clang::FileManager::getFile(), clang::DirectoryEntry::getName(), clang::FileEntry::getName(), and getTopFrameworkDir().

Referenced by clang::Preprocessor::LookupFile().

StringRef clang::HeaderSearch::MapHeaderToIncludeAlias ( StringRef  Source) [inline]

MapHeaderToIncludeAlias - Maps one header file name to a different header file name, for use with the include_alias pragma. Note that the source file name should include the angle brackets or quotes. Returns StringRef as null if the header cannot be mapped.

Definition at line 319 of file HeaderSearch.h.

void clang::HeaderSearch::MarkFileIncludeOnce ( const FileEntry File) [inline]

Mark the specified file as a "once only" file, e.g. due to #pragma once.

Definition at line 433 of file HeaderSearch.h.

References clang::HeaderFileInfo::isImport, and clang::HeaderFileInfo::isPragmaOnce.

Referenced by clang::Preprocessor::HandlePragmaOnce().

void HeaderSearch::MarkFileModuleHeader ( const FileEntry File,
ModuleMap::ModuleHeaderRole  Role,
bool  IsCompiledModuleHeader 
)
void clang::HeaderSearch::MarkFileSystemHeader ( const FileEntry File) [inline]

Mark the specified file as a system header, e.g. due to #pragma GCC system_header.

Definition at line 441 of file HeaderSearch.h.

References clang::SrcMgr::C_System, and clang::HeaderFileInfo::DirInfo.

Referenced by clang::Preprocessor::HandlePragmaSystemHeader().

static std::string clang::HeaderSearch::NormalizeDashIncludePath ( StringRef  File,
FileManager FileMgr 
) [static]

Definition at line 73 of file HeaderSearch.cpp.

Referenced by clang::FrontendAction::EndSourceFile().

Definition at line 599 of file HeaderSearch.h.

Definition at line 602 of file HeaderSearch.h.

Definition at line 595 of file HeaderSearch.h.

Definition at line 596 of file HeaderSearch.h.

Definition at line 597 of file HeaderSearch.h.

Consider modules when including files from this directory.

Definition at line 338 of file HeaderSearch.h.

Definition at line 347 of file HeaderSearch.h.

Set the external source of header information.

Definition at line 356 of file HeaderSearch.h.

void clang::HeaderSearch::SetFileControllingMacro ( const FileEntry File,
const IdentifierInfo ControllingMacro 
) [inline]

Mark the specified file as having a controlling macro.

This is used by the multiple-include optimization to eliminate no-op #includes.

Definition at line 460 of file HeaderSearch.h.

References clang::HeaderFileInfo::ControllingMacro.

Referenced by clang::Preprocessor::HandleEndOfFile().

void clang::HeaderSearch::setModuleCachePath ( StringRef  CachePath) [inline]

Set the path to the module cache.

Definition at line 330 of file HeaderSearch.h.

void clang::HeaderSearch::SetSearchPaths ( const std::vector< DirectoryLookup > &  dirs,
unsigned  angledDirIdx,
unsigned  systemDirIdx,
bool  noCurDirSearch 
) [inline]

Interface for setting the file search paths.

Definition at line 276 of file HeaderSearch.h.

void clang::HeaderSearch::SetSystemHeaderPrefixes ( ArrayRef< std::pair< std::string, bool > >  P) [inline]

Set the list of system header prefixes.

Definition at line 298 of file HeaderSearch.h.

References P.

void HeaderSearch::setTarget ( const TargetInfo Target)

Set the target information for the header search, if not already known.

Definition at line 531 of file HeaderSearch.cpp.

References clang::ModuleMap::setTarget().

Referenced by clang::Preprocessor::Initialize().

bool HeaderSearch::ShouldEnterIncludeFile ( const FileEntry File,
bool  isImport 
)

Mark the specified file as a target of of a #include, #include_next, or #import directive.

Returns:
false if #including the file will have no effect or true if we should include it.

Definition at line 1016 of file HeaderSearch.cpp.

References clang::HeaderFileInfo::getControllingMacro(), clang::HeaderFileInfo::isImport, and clang::HeaderFileInfo::NumIncludes.

Definition at line 613 of file HeaderSearch.h.

Definition at line 616 of file HeaderSearch.h.

bool HeaderSearch::tryGetFileInfo ( const FileEntry FE,
HeaderFileInfo Result 
) const

Get a HeaderFileInfo structure for the specified FileEntry, if one exists.

Definition at line 979 of file HeaderSearch.cpp.

References clang::FileEntry::getUID(), and clang::HeaderFileInfo::IsValid.


Friends And Related Function Documentation

friend class DirectoryLookup [friend]

Definition at line 261 of file HeaderSearch.h.


The documentation for this class was generated from the following files: