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 (const std::shared_ptr< Unit > &u)
 
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 ()
 
const auto & context () const
 
const auto & options () 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 (int opt, const char *optarg)
 
virtual std::string hookAugmentUsage ()
 
virtual void hookAddInput (std::shared_ptr< Unit > unit)
 
virtual void hookAddInput (const hilti::rt::filesystem::path &path)
 
virtual void hookNewASTPreCompilation (std::shared_ptr< Unit > unit)
 
virtual void hookNewASTPostCompilation (std::shared_ptr< Unit > unit)
 
virtual Result< NothinghookCompilationFinished (const Plugin &plugin)
 
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 executable, 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 ( const std::shared_ptr< Unit > &  u)

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

The hookAddInput() and hookNewASTPreCompilation() hooks will be called immediately for the new module.

Parameters
uunit to schedule for compilation
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 source file for compilation. The file will be parsed immediately, and then compiled later when compile() is called. If the same source unit has been added previously, this method will have no effect.

The hookAddInput() and hookNewASTPreCompilation() hooks will be called immediately for the new module.

Parameters
pathsource code 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 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

◆ codegenUnits()

Result<Nothing> hilti::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()

const 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 ( std::shared_ptr< Unit unit)
inlineprotectedvirtual

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

◆ hookAddInput() [2/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 code file 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 ( const Plugin plugin)
inlineprotectedvirtual

Hook for derived classes to execute custom code when all input files have been fully processes by a plugin. If the hook returns 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. This hook will execute again once all new inputs have likewise been compiled. The new files, however, must not need processing by any plugin that has already completed compilation previously.

Parameters
pluginplugin that has finished now

◆ 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 ( std::shared_ptr< Unit unit)
inlineprotectedvirtual

Hook for derived classes to execute custom code when a code unit has been finalized. This hook will run after the AST has been be fully processed by the suitable plugin, but before it's being transformed.

◆ hookNewASTPreCompilation()

virtual void hilti::Driver::hookNewASTPreCompilation ( std::shared_ptr< Unit unit)
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 ( int  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

◆ options()

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

Shortcut to return the current context's options.

◆ 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 output 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

◆ 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: