Spicy
Public Member Functions | Static Public Member Functions | List of all members
hilti::Unit Class Reference

#include <unit.h>

Public Member Functions

NodeRef module ()
 
auto id () const
 
auto path () const
 
Result< Nothingcompile ()
 
Result< Nothingcodegen ()
 
Result< Nothingprint (std::ostream &out) const
 
Result< NothingcreatePrototypes (std::ostream &out)
 
Result< CxxCodecxxCode () const
 
Result< context::ModuleIndeximport (const ID &id, const hilti::rt::filesystem::path &ext, std::optional< ID > scope={}, std::vector< hilti::rt::filesystem::path > search_dirs={})
 
Result< context::ModuleIndeximport (const hilti::rt::filesystem::path &path)
 
Nodeimported (const ID &id) const
 
std::set< context::ModuleIndexallImported (bool code_only=false) const
 
Result< bool > requiresCompilation (const ID &id)
 
Result< linker::MetaDatalinkerMetaData () const
 
bool isCompiledHILTI () const
 
std::shared_ptr< Contextcontext () const
 
const Optionsoptions () const
 

Static Public Member Functions

static Result< UnitfromModule (const std::shared_ptr< Context > &context, hilti::Module &&module, const hilti::rt::filesystem::path &path="")
 
static Result< UnitfromSource (const std::shared_ptr< Context > &context, const hilti::rt::filesystem::path &path)
 
static Result< UnitfromCache (const std::shared_ptr< Context > &context, const hilti::ID &id)
 
static Result< UnitfromCache (const std::shared_ptr< Context > &context, const hilti::rt::filesystem::path &path)
 
static Result< UnitfromCXX (std::shared_ptr< Context > context, detail::cxx::Unit cxx, const hilti::rt::filesystem::path &path="")
 
static Result< Unitlink (const std::shared_ptr< Context > &context, const std::vector< linker::MetaData > &mds)
 
static std::pair< bool, std::optional< linker::MetaData > > readLinkerMetaData (std::istream &input, const hilti::rt::filesystem::path &path="<input stream>")
 

Detailed Description

Container for a single HILTI code module. For each HILTI source file, one compiler unit gets instantiated. That unit then drives the process to compile module comp into C++ code. While that's in progress, the unit maintains state about the process, such as a cache of all external modules imported by the one that's being compiled.

Member Function Documentation

◆ allImported()

std::set< context::ModuleIndex > Unit::allImported ( bool  code_only = false) const

Returns set of all imported modules so far.

Parameters
code_onlyif true include only dependencies that require independent compilation themselves

◆ codegen()

Result< Nothing > Unit::codegen ( )

Triggers generation of C++ code from the compiled AST.

◆ compile()

Result< Nothing > Unit::compile ( )

Compiles the unit's module AST into its final internal representation.

Returns
set if successful, or an appropriate error result

◆ context()

std::shared_ptr<Context> hilti::Unit::context ( ) const
inline

Returns the compiler context in use.

◆ createPrototypes()

Result< Nothing > Unit::createPrototypes ( std::ostream &  out)

Prints out C++ prototypes that host applications can use to interface with the generated C++ code. Must be called only after compile() was successful.

Parameters
outstream to print the code to
Returns
set if successful, or an appropriate error result

◆ cxxCode()

Result< CxxCode > Unit::cxxCode ( ) const

Returns the generated C++ code. Must be called only after compile() was successful.

Returns
code wrapped into the JIT's container class

◆ fromCache() [1/2]

Result< Unit > Unit::fromCache ( const std::shared_ptr< Context > &  context,
const hilti::ID id 
)
static

Factory method that instantiates a unit from an existing HILTI module already cached by the global context.

Parameters
contextglobal compiler context
idID of the cached module
Returns
instantiated unit, or an appropriate error result if operation failed

◆ fromCache() [2/2]

Result< Unit > Unit::fromCache ( const std::shared_ptr< Context > &  context,
const hilti::rt::filesystem::path &  path 
)
static

Factory method that instantiates a unit from an existing HILTI module already cached by the global context.

Parameters
contextglobal compiler context
pathpath of the cached module
Returns
instantiated unit, or an appropriate error result if operation failed

◆ fromCXX()

Result< Unit > Unit::fromCXX ( std::shared_ptr< Context context,
detail::cxx::Unit  cxx,
const hilti::rt::filesystem::path &  path = "" 
)
static

Factory method that instantiates a unit from existing C++ source code that's to compiled.

Parameters
contextglobal compiler context
pathpath associated with the C++ code, if any
Returns
instantiated unit, or an appropriate error result if operation failed

◆ fromModule()

Result< Unit > Unit::fromModule ( const std::shared_ptr< Context > &  context,
hilti::Module &&  module,
const hilti::rt::filesystem::path &  path = "" 
)
static

Factory method that instantiates a unit from an existing HILTI module that's be compiled.

This method also caches the module with the global context. Note that the module's ID or path must not exist with the context yet.

Parameters
contextglobal compiler context
moduleHILTI module to compile, of which the unit will take ownership
pathpath associated with the module, if any
Returns
instantiated unit, or an appropriate error result if operation failed

◆ fromSource()

Result< Unit > Unit::fromSource ( const std::shared_ptr< Context > &  context,
const hilti::rt::filesystem::path &  path 
)
static

Factory method that instantiates a unit from an existing source file that it will parse.

This method also caches the module with the global context. Note that the module's ID or path must not exist with the context yet.

Parameters
contextglobal compiler context
pathpath to parse the module from
Returns
instantiated unit, or an appropriate error result if operation failed

◆ id()

auto hilti::Unit::id ( ) const
inline

Returns the ID of the unit's top-level module (i.e., the one being compiled).

◆ import() [1/2]

Result< ModuleIndex > Unit::import ( const ID id,
const hilti::rt::filesystem::path &  ext,
std::optional< ID scope = {},
std::vector< hilti::rt::filesystem::path >  search_dirs = {} 
)

Makes an external HILTI module available to the one this unit is compiling. Essentially, this implements the HITLI's import statement. Importing another module means that the compiled module will know how to access the other one's functionality. However, that external module will still need to be compiled itself as well; and then all the compiled modules need to be linked together.

This version of the import method imports by module ID: it searches Configuration::hilti_library_paths for a file with a corresponding name and extension.

Parameters
idID of module to import
extfile name extension to search; .hlt is HILTI's standard extension, but plugins can add support for other extensions as well
scopeif given, qualifies the ID with a path prefix to find the module (e.g., a scope of a.b.c will search the module in <search path>/a/b/c/<name>.)
dirsadditional directories to search first
Returns
the modules' cache index if successful,or an appropriate error result if not

◆ import() [2/2]

Result< ModuleIndex > Unit::import ( const hilti::rt::filesystem::path &  path)

Makes an external HILTI module available to the one this unit is compiling. See import(const ID, const hilti::rt::filesystem::path) for more details on importing.

This version of the import method imports directly from a given file.

Parameters
pathto the file to import
Returns
the modules' cache index if successful,or an appropriate error result if not

◆ imported()

Node & Unit::imported ( const ID id) const

Returns the AST for an imported module.

Parameters
idmodule ID
Returns
Reference to the root node of the imported module's AST
Exceptions
<tt>std::out_of_range</tt>if no module of that name has been imported yet

◆ isCompiledHILTI()

bool hilti::Unit::isCompiledHILTI ( ) const
inline

Returns true if this unit has been compiled from HILTI source. This is usually the case, but we also represent HILTI's linker output as a unit and there's no corresponding HILTI source code for that.

◆ link()

Result< Unit > Unit::link ( const std::shared_ptr< Context > &  context,
const std::vector< linker::MetaData > &  mds 
)
static

Entry point for the HILTI linker, The linker combines meta data from several compiled HILTI modules and creates an additional unit from it, with its C++ code representing logic the HILTI runtime library will draw upon.

Parameters
contextcompiler context to use
mdsset of meta data from modules to be linked together
Returns
a unit representing additional C++ code that the modules need to function

◆ linkerMetaData()

Result<linker::MetaData> hilti::Unit::linkerMetaData ( ) const
inline

Returns the unit's meta data for the internal HILTI linker.

Returns
meta data, or an error if no code has been compiled yet

◆ module()

NodeRef hilti::Unit::module ( )
inline

Returns the root node of the module AST's.

◆ options()

const Options& hilti::Unit::options ( ) const
inline

Returns the compiler options in use.

◆ path()

auto hilti::Unit::path ( ) const
inline

Returns the path associated with the unit's top-level module (i.e., the one being compiled).

◆ print()

Result< Nothing > Unit::print ( std::ostream &  out) const

Prints out a HILTI module by recreating its code from the internal AST. Must be called only after compile() was successful.

Parameters
outstream to print the code to
Returns
set if successful, or an appropriate error result

◆ readLinkerMetaData()

std::pair< bool, std::optional< linker::MetaData > > Unit::readLinkerMetaData ( std::istream &  input,
const hilti::rt::filesystem::path &  path = "<input stream>" 
)
static

Reads linker meta from a file. This expects the file to contain linker meta somewhere inside a appropriately marked block bracketed by C-style comments. When printing the generated C++ code for a compiled HILTI module, it will include that block. In other words, you can just save the C++ and reread the meta data with this method.

Parameters
inputstream to read from
pathfile associated with the stream, for logging and error reporting
Returns
If the input had valid meta data, the 1st element is true and the second contains it. If the input was valid but had no meta data included, the 1st element is true while the 2nd remains unset. If there was an error reading the input, the 1st element is false and the 2nd undefined.

◆ requiresCompilation()

Result<bool> hilti::Unit::requiresCompilation ( const ID id)
inline

Returns true if an imported module provides code that needs independent compilation to resolve references at link-time.

Returns
a boolean that true if the module provides code for compilation, or an error value if no such module is known.

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