Spicy
Public Member Functions | Protected Member Functions | List of all members
hilti::Driver Class Reference

#include <driver.h>

Inheritance diagram for hilti::Driver:
spicy::Driver Spicyc SpicyDriver SpicyDump

Public Member Functions

 Driver (std::string name)
 
 Driver (std::string name, const hilti::rt::filesystem::path &argv0)
 
 Driver (const Driver &)=delete
 
 Driver (Driver &&) noexcept=delete
 
Driveroperator= (const Driver &)=delete
 
Driveroperator= (Driver &&) noexcept=delete
 
Result< NothingparseOptions (int argc, char **argv)
 
Result< NothingaddInput (hilti::Module &&m, const hilti::rt::filesystem::path &path="")
 
Result< NothingaddInput (const hilti::rt::filesystem::path &path)
 
bool hasInputs () const
 
const auto & driverOptions () const
 
const auto & hiltiOptions () const
 
void setDriverOptions (driver::Options options)
 
void setCompilerOptions (hilti::Options options)
 
Result< Nothinginitialize ()
 
Result< Nothingcompile ()
 
Result< NothingtransformUnits ()
 
auto context () const
 
Result< NothinginitRuntime ()
 
Result< NothingexecuteMain ()
 
Result< NothingfinishRuntime ()
 
Result< Nothingrun ()
 

Protected Member Functions

void usage ()
 
Result< NothingcompileUnits ()
 
Result< NothingcodegenUnits ()
 
Result< NothinglinkUnits ()
 
Result< NothingoutputUnits ()
 
Result< NothingjitUnits ()
 
result::Error error (std::string_view msg, const hilti::rt::filesystem::path &p="")
 
result::Error augmentError (const result::Error &err, const hilti::rt::filesystem::path &p="")
 
Result< std::ofstream > openOutput (const hilti::rt::filesystem::path &p, bool binary=false, bool append=false)
 
Result< NothingopenInput (std::ifstream &in, const hilti::rt::filesystem::path &p)
 
Result< NothingwriteOutput (std::ifstream &in, const hilti::rt::filesystem::path &p)
 
Result< std::stringstream > readInput (const hilti::rt::filesystem::path &p)
 
Result< hilti::rt::filesystem::path > writeToTemp (std::ifstream &in, const std::string &name_hint, const std::string &extension="tmp")
 
void dumpUnit (const Unit &unit)
 
void printHiltiException (const hilti::rt::Exception &e)
 
virtual std::string hookAddCommandLineOptions ()
 
virtual bool hookProcessCommandLineOption (char opt, const char *optarg)
 
virtual std::string hookAugmentUsage ()
 
virtual void hookAddInput (const hilti::rt::filesystem::path &path)
 
virtual void hookAddInput (const hilti::Module &m, const hilti::rt::filesystem::path &path)
 
virtual void hookNewASTPreCompilation (const ID &name, const std::optional< hilti::rt::filesystem::path > &path, const Node &root)
 
virtual void hookNewASTPostCompilation (const ID &name, const std::optional< hilti::rt::filesystem::path > &path, const Node &root)
 
virtual Result< NothinghookCompilationFinished ()
 
virtual void hookInitRuntime ()
 
virtual void hookFinishRuntime ()
 

Detailed Description

Compiler driver.

The driver is a high-level building block for writing command-line tools compiling HILTI source files (and more). hiltic is just a tiny wrapper around this class.

Classes can drive from the driver to expand its functionality, including for adding support for additional types of source files (e.g., Spicy code).

Constructor & Destructor Documentation

◆ Driver() [1/2]

Driver::Driver ( std::string  name)
explicit
Parameters
namedescriptive name for the tool using the driver, which will be used in usage and error messages.

◆ Driver() [2/2]

Driver::Driver ( std::string  name,
const hilti::rt::filesystem::path &  argv0 
)
Parameters
namedescriptive name for the tool using the driver, which will be used in usage and error messages.
argv0the current exectuable, which will change the path's that the global options instance returns if it's inside HILTI build directory.

Member Function Documentation

◆ addInput() [1/2]

Result< Nothing > Driver::addInput ( hilti::Module &&  m,
const hilti::rt::filesystem::path &  path = "" 
)

Schedules a HILTI module for compilation. The unit will take ownership and compile the module once compile() is called. If module of the same ID or path has been added previously, this will have no effect.

hookNewASTPreCompilation() hook will be called immediately for the new module.

Parameters
mHILTI module to schedule for compilation
pathpath associated with the module, if any
Returns
set if successful; otherwise the result provides an error message

◆ addInput() [2/2]

Result< Nothing > Driver::addInput ( const hilti::rt::filesystem::path &  path)

Schedules a HILTI source file for compilation. The file will be parsed immediately, and then compiled later when compile() is called. If the same file/module has been added previously, this method will have no effect.

hookNewASTPreCompilation() hook will be called immediately for the new module after it has been parsed.

Parameters
inputsource of HILTI module to compile
Returns
set if successful; otherwise the result provides an error message

◆ augmentError()

result::Error Driver::augmentError ( const result::Error err,
const hilti::rt::filesystem::path &  p = "" 
)
protected

Helper function to augment an result::Error with a message that includig driver name and, optionally, a file the error refers to.

Parameters
msgerror message
pfile to associate with the error, empty for none
Returns
error with an appropriately set message

◆ codegenUnits()

Result< Nothing > Driver::codegenUnits ( )
protected

Compiles all registered input files to C++ code.

This function can only be invoked after compileUnits.

Returns
set if successful; otherwise the result provides an error message

◆ compile()

Result< Nothing > Driver::compile ( )

Loads, compiles, and links the source files. This must be called only after driver and compiler options have been set. Internally, it chains the various *Modules() methods.

Returns
set if successful; otherwise the result provides an error message

◆ compileUnits()

Result< Nothing > Driver::compileUnits ( )
protected

Compiles all registered input files to HILTI code.

Returns
set if successful; otherwise the result provides an error message

◆ context()

auto hilti::Driver::context ( ) const
inline

Returns the current HILTI context. Valid only once compilation has started, otherwise null.

◆ driverOptions()

const auto& hilti::Driver::driverOptions ( ) const
inline

Returns the driver options currently in effect.

◆ dumpUnit()

void Driver::dumpUnit ( const Unit unit)
protected

Save a unit's final HILTI and C++ code to disk for debugging.

◆ error()

result::Error Driver::error ( std::string_view  msg,
const hilti::rt::filesystem::path &  p = "" 
)
protected

Helper function to create an result::Error with a message that including driver name and, optionally, a file the error refers to.

Parameters
msgerror message
pfile to associate with the error, empty for none
Returns
error with an appropriately set message

◆ executeMain()

Result< Nothing > Driver::executeMain ( )

Executes the hilti_main entry function in compiled code. This must be called only after initRuntime() has run already.

Returns
set if successful; otherwise the result provides an error message

◆ finishRuntime()

Result< Nothing > Driver::finishRuntime ( )

Shuts down HILT's runtime library after execution has concluded, cleaning up resources.

Returns
set if successful; otherwise the result provides an error message

◆ hasInputs()

bool hilti::Driver::hasInputs ( ) const
inline

Returns true if at least one input file has been added.

◆ hiltiOptions()

const auto& hilti::Driver::hiltiOptions ( ) const
inline

Returns the HILTI compiler options currently in effect.

◆ hookAddCommandLineOptions()

virtual std::string hilti::Driver::hookAddCommandLineOptions ( )
inlineprotectedvirtual

Hook for derived classes to add more options to the getopt() option string.

Reimplemented in spicy::Driver.

◆ hookAddInput() [1/2]

virtual void hilti::Driver::hookAddInput ( const hilti::rt::filesystem::path &  path)
inlineprotectedvirtual

Hook for derived classes to execute custom code when a new source path is being added as an input file.

◆ hookAddInput() [2/2]

virtual void hilti::Driver::hookAddInput ( const hilti::Module m,
const hilti::rt::filesystem::path &  path 
)
inlineprotectedvirtual

Hook for derived classes to execute custom code when a new AST module is being added as an input file.

◆ hookAugmentUsage()

virtual std::string hilti::Driver::hookAugmentUsage ( )
inlineprotectedvirtual

Hook for derived classes for adding content to the driver's usage message (--help).

Reimplemented in spicy::Driver.

◆ hookCompilationFinished()

virtual Result<Nothing> hilti::Driver::hookCompilationFinished ( )
inlineprotectedvirtual

Hook for derived classes to execute custom code when all input files have been compiled to HILTI & Spicy code (but not yet linked). If the hook return an error that will abort all further processing. The hook may add further inputs files through the add() methods, which will then be compiled next. If so, this hook will execute again once all new inputs have likewise been compiled.

◆ hookFinishRuntime()

virtual void hilti::Driver::hookFinishRuntime ( )
inlineprotectedvirtual

Hook for derived classes to execute custom code just before the HILTI runtime is being shut down.

Reimplemented in Spicyc.

◆ hookInitRuntime()

virtual void hilti::Driver::hookInitRuntime ( )
inlineprotectedvirtual

Hook for derived classes to execute custom code when the HILTI runtime has been initialized.

Reimplemented in Spicyc.

◆ hookNewASTPostCompilation()

virtual void hilti::Driver::hookNewASTPostCompilation ( const ID name,
const std::optional< hilti::rt::filesystem::path > &  path,
const Node root 
)
inlineprotectedvirtual

Hook for derived classes to execute custom code when a HILTI AST has been finalized. This hook will run after the AST has been compiled (and hence it'll be fully processed).

◆ hookNewASTPreCompilation()

virtual void hilti::Driver::hookNewASTPreCompilation ( const ID name,
const std::optional< hilti::rt::filesystem::path > &  path,
const Node root 
)
inlineprotectedvirtual

Hook for derived classes to execute custom code when an HILTI AST has been loaded. This hook will run before the AST has been compiled (and hence it'll be fully unprocessed).

◆ hookProcessCommandLineOption()

virtual bool hilti::Driver::hookProcessCommandLineOption ( char  opt,
const char *  optarg 
)
inlineprotectedvirtual

Hook for derived classes for parsing additional options.

Reimplemented in spicy::Driver.

◆ initialize()

Result< Nothing > Driver::initialize ( )

Initializes the compilation process. Must be called after options have been set, and before any inputs are added.

Returns
set if successful; otherwise the result provides an error message

◆ initRuntime()

Result< Nothing > Driver::initRuntime ( )

Initializes HILTI's runtime system to prepare for execution of compiled code. This will already trigger execution of all module-specific initialization code (initialization of globals; module-level statements). The method must be called only after compile() has run already.

Returns
set if successful; otherwise the result provides an error message

◆ jitUnits()

Result< Nothing > Driver::jitUnits ( )
protected

JIT all code compiled so far.

Returns
set if successful; otherwise the result provides an error message

◆ linkUnits()

Result< Nothing > Driver::linkUnits ( )
protected

Runs the HILTI-side linker on all available C++ code.

Returns
set if successful; otherwise the result provides an error message

◆ openInput()

Result< Nothing > Driver::openInput ( std::ifstream &  in,
const hilti::rt::filesystem::path &  p 
)
protected

Helper function to open a file for reading.

Parameters
ininput stream to open with file with
pinput file
Returns
set if successful, or an appropriate error result

◆ openOutput()

Result< std::ofstream > Driver::openOutput ( const hilti::rt::filesystem::path &  p,
bool  binary = false,
bool  append = false 
)
protected

Helper function to open a file for writing.

Parameters
poutput file
binarytrue to open in binary mode
appendtrue to append to existing file
Returns
set if successful, or an appropriate error result

◆ outputUnits()

Result< Nothing > Driver::outputUnits ( )
protected

Writes out generated code if requested by driver options.

Returns
set if successful; otherwise the result provides an error message

◆ parseOptions()

Result< Nothing > Driver::parseOptions ( int  argc,
char **  argv 
)

Frontend for parsing command line options into driver::Options and hilti::Options. See the outout ofhiltic –help` for a list.

setDriverOptions() and setCompilerOptions() provide alternative ways to set the options directly.

Parameters
argc,argvcommand line arguments to parse
Returns
set if successful; otherwise the result provides an error message

◆ printHiltiException()

void Driver::printHiltiException ( const hilti::rt::Exception e)
protected

Prints an uncaught HILTI exception to stderr.

Parameters
eexception to print

◆ readInput()

Result< std::stringstream > Driver::readInput ( const hilti::rt::filesystem::path &  p)
protected

Helper function to read data from an input file.

Parameters
pinput file
Returns
string stream with the file's data, or an appropriate error result

◆ run()

Result< Nothing > Driver::run ( )

Compile and executes all source files. This is a convenience wrapper around the stages of the process provided by other methods. It executes all of compile(), initRuntime(), executeMain(), and finishRuntime() in that order.

Returns
set if successful; otherwise the result provides an error message

◆ setCompilerOptions()

void Driver::setCompilerOptions ( hilti::Options  options)

Sets HILTI's compiler options.

Parameters
optionsthe options

◆ setDriverOptions()

void Driver::setDriverOptions ( driver::Options  options)

Sets the driver's options and arguments.

Parameters
optionsthe options

◆ transformUnits()

Result< Nothing > Driver::transformUnits ( )

Performs global transformations on the generated code.

◆ usage()

void Driver::usage ( )
protected

Prints a usage message to stderr. The message summarizes the options understood by parseOptions().

◆ writeOutput()

Result< Nothing > Driver::writeOutput ( std::ifstream &  in,
const hilti::rt::filesystem::path &  p 
)
protected

Helper function to write data into an output file.

Parameters
instream to read data to write from
poutput file
Returns
set if successful, or an appropriate error result

◆ writeToTemp()

Result< hilti::rt::filesystem::path > Driver::writeToTemp ( std::ifstream &  in,
const std::string &  name_hint,
const std::string &  extension = "tmp" 
)
protected

Copies an input stream into a temporary file on disk

Parameters
instream to read from
name_hinta string to include into the temporary file's name
extensionextension for the temporary file's name
Returns
the path to the temporary file, or an appropriate error result

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