#include <driver.h>

Inheritance diagram for hilti::Driver:

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

Driver &	operator= (const Driver &)=delete

Driver &	operator= (Driver &&) noexcept=delete

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

void	registerUnit (const std::shared_ptr< Unit > &unit)

Unit *	lookupUnit (const declaration::module::UID &uid) const

void	updateProcessExtension (const declaration::module::UID &uid, const hilti::rt::filesystem::path &ext)

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

Result< Nothing >	addInput (declaration::module::UID uid)

bool	hasInputs () const

const auto &	driverOptions () const

const auto &	hiltiOptions () const

void	setDriverOptions (driver::Options options)

void	setCompilerOptions (hilti::Options options)

Result< Nothing >	initialize ()

Result< Nothing >	compile ()

const auto &	context () const

auto *	builder () const

const auto &	options () const

Result< Nothing >	initRuntime ()

Result< Nothing >	executeMain ()

Result< Nothing >	finishRuntime ()

void	fatalError (const std::string &msg)

void	fatalError (const hilti::result::Error &error)

Result< Nothing >	run ()

Protected Member Functions
void	usage ()

Result< Nothing >	compileUnits ()

Result< Nothing >	codegenUnits ()

Result< Nothing >	linkUnits ()

Result< Nothing >	outputUnits ()

Result< Nothing >	jitUnits ()

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< Nothing >	openInput (std::ifstream &in, const hilti::rt::filesystem::path &p)

Result< Nothing >	writeOutput (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::unique_ptr< Builder >	createBuilder (ASTContext *ctx) const

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 (const Plugin &plugin, ASTRoot *root)

virtual bool	hookNewASTPostCompilation (const Plugin &plugin, ASTRoot *root)

virtual Result< Nothing >	hookCompilationFinished (ASTRoot *root)

virtual void	hookInitRuntime ()

virtual void	hookFinishRuntime ()

Friends
class	ASTContext

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

name	descriptive 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

name	descriptive name for the tool using the driver, which will be used in usage and error messages.
argv0	the 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 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

path	source code to compile

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

◆ addInput() [2/2]

Result< Nothing > Driver::addInput ( declaration::module::UID uid )

Schedules an already existing module for compilation. This is useful when input modules are generated in-memory on the fly. The module must have already been added to the AST. It will now be registered as a source unit for full processing (compilation to C++; JIT) just as any on-disk source files added with addInput(<path>).

Parameters

uid	UID of the existing module

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

msg	error message
p	file to associate with the error, empty for none

Returns: error with an appropriately set message

◆ builder()

auto* hilti::Driver::builder ( ) const

inline

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

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

◆ createBuilder()

std::unique_ptr< Builder > Driver::createBuilder ( ASTContext * ctx ) const

protectedvirtual

Instantiates a new builder tied to a given context. Derived class can override this to create a builder own their own type (as long as that's derived from hilti::Builder).

Parameters

ctx	context to create builder for

Returns: new builder instance

Reimplemented in spicy::Driver.

◆ 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

msg	error message
p	file 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

◆ fatalError() [1/2]

void Driver::fatalError ( const hilti::result::Error & error )

Reports the given error and stops execution.

Parameters

error the error to report

◆ fatalError() [2/2]

void Driver::fatalError ( const std::string & msg )

Reports the given message and stops execution.

Parameters

msg	the 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 code file is being added as an input file.

◆ hookAddInput() [2/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.

◆ 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 ( ASTRoot * root )

inlineprotectedvirtual

Hook for derived classes to execute custom code when the AST has been fully processed and transformed to its final state.

◆ 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 bool hilti::Driver::hookNewASTPostCompilation	(	const Plugin &	plugin,
		ASTRoot *	root
	)

inlineprotectedvirtual

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

The hook may modify the AST further, including adding new modules. If it does indicate so with its return value, AST processing will start over again to fully resolve the modified AST. Once that's done, this hook will execute again. Note, however, that the hook cannot add anything to the AST that depends on previous plugins, as they won't execute again.

Parameters

plugin	the plugin that has processed the AST
root	the AST that has been processed

Returns: true if the AST has been modified and needs to be reprocessed

◆ hookNewASTPreCompilation()

virtual void hilti::Driver::hookNewASTPreCompilation	(	const Plugin &	plugin,
		ASTRoot *	root
	)

inlineprotectedvirtual

Hook for derived classes to execute custom code when an HILTI AST has been initially set up for processing by a plugin. This hook will run before the AST has been processed any further by that plugin.

◆ 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

◆ lookupUnit()

Unit* hilti::Driver::lookupUnit ( const declaration::module::UID & uid ) const

inline

Looks up a previously registered by its UID.

Parameters

uid	UID to look up

Returns: pointer to unit, or null if not found

◆ openInput()

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

protected

Helper function to open a file for reading.

Parameters

in	input stream to open with file with
p	input 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

p	output file
binary	true to open in binary mode
append	true 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,argv command 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

e	exception 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

p	input file

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

◆ registerUnit()

void hilti::Driver::registerUnit ( const std::shared_ptr< Unit > & unit )

inline

Registers a unit with the driver for compilation. If a unit with the same UID is already known, this is a no-op.

Parameters

unit	unit to register

◆ 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

options the options

◆ setDriverOptions()

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

Sets the driver's options and arguments.

Parameters

options the options

◆ updateProcessExtension()

void Driver::updateProcessExtension	(	const declaration::module::UID &	uid,
		const hilti::rt::filesystem::path &	ext
	)

Changes the process extension of an existing unit.

This also updates the unit's module by changing its UID accordingly.

Parameters

uid	UID of the unit to change, which must correspond to a known unit
ext	new process extension; no other unit of the same name must exist yet with that extension

◆ 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

in	stream to read data to write from
p	output 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

in	stream to read from
name_hint	a string to include into the temporary file's name
extension	extension 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:

/home/docs/checkouts/readthedocs.org/user_builds/spicy-docs/checkouts/v1.14.0/hilti/toolchain/include/compiler/driver.h
/home/docs/checkouts/readthedocs.org/user_builds/spicy-docs/checkouts/v1.14.0/hilti/toolchain/src/compiler/driver.cc

Public Member Functions

Protected Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Driver() [1/2]

◆ Driver() [2/2]

Member Function Documentation

◆ addInput() [1/2]

◆ addInput() [2/2]

◆ augmentError()

◆ builder()

◆ codegenUnits()

◆ compile()

◆ compileUnits()

◆ context()

◆ createBuilder()

◆ driverOptions()

◆ dumpUnit()

◆ error()

◆ executeMain()

◆ fatalError() [1/2]

◆ fatalError() [2/2]

◆ finishRuntime()

◆ hasInputs()

◆ hiltiOptions()

◆ hookAddCommandLineOptions()

◆ hookAddInput() [1/2]

◆ hookAddInput() [2/2]

◆ hookAugmentUsage()

◆ hookCompilationFinished()

◆ hookFinishRuntime()

◆ hookInitRuntime()

◆ hookNewASTPostCompilation()

◆ hookNewASTPreCompilation()

◆ hookProcessCommandLineOption()

◆ initialize()

◆ initRuntime()

◆ jitUnits()

◆ linkUnits()

◆ lookupUnit()

◆ openInput()

◆ openOutput()

◆ options()

◆ outputUnits()

◆ parseOptions()

◆ printHiltiException()

◆ readInput()

◆ registerUnit()

◆ run()

◆ setCompilerOptions()

◆ setDriverOptions()

◆ updateProcessExtension()

◆ usage()

◆ writeOutput()

◆ writeToTemp()