Vuo  1.2.4
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Groups Pages
Classes | Public Types | Public Member Functions | Static Public Member Functions | Friends | List of all members
VuoCompiler Class Reference

Description

This class compiles node classes, types, and library modules.

It compiles and links compositions.

Node classes, types, library modules, and compositions are all compiled to LLVM bitcode. LLVM bitcode is one of the file formats used by the Clang compiler.

When a composition is linked, the compiled composition and all of its node classes, types, library modules, and other dependencies are combined to create one of the following: an executable, a dynamic library, or or separate dynamic libraries for the composition and its resources.

All VuoCompiler instances share a basic set of node classes, types, library modules, and other dependencies. Each VuoCompiler instance can add its own dependencies on top of that basic set.

The easiest way to compile, link, and run a composition is to use the VuoCompiler factory methods to create a VuoRunner that's ready to run the composition:

When building a composition, this class optimizes the build in different ways depending on the functions, and in some cases the arguments, that you use. Some functions for linking a composition accept an Optimization argument. The rest default to the "faster build" optimization (Optimization_FastBuild). The "faster build" optimization works by caching a library on the user's filesystem and reusing it each time a composition is linked. The caching takes a while, and may delay the building of the first composition. However, if you call prepareForFastBuild(), the caching can be done in advance.

If you plan to distribute an executable or dynamic library built from a composition, use either linkCompositionToCreateExecutable() or linkCompositionToCreateDynamicLibrary(), and choose the "smaller binary" optimization. If building an executable, pass an rpath (such as "@loader_path/../Frameworks") to enable the executable to find Vuo.framework. Since the executable or dynamic library links to Vuo.framework, you need to distribute it along with the build composition.

This can be used only in 64-bit applications, not 32-bit applications.

See Also
Developing Applications that Use Vuo

Classes

class  Environment
 A set of node classes, types, library modules, and search paths for other dependencies. More...
 

Public Types

enum  Optimization { Optimization_FastBuild, Optimization_FastBuildExistingCache, Optimization_SmallBinary }
 Options for optimizations when building a composition. More...
 

Public Member Functions

 VuoCompiler (void)
 Creates a compiler instance that can be used for compiling and linking.
 
 ~VuoCompiler (void)
 Destructor.
 
void setLicense (string licenseContent, string licenseSignature)
 Initializes the premium node loader with the license information provided.
 
void loadStoredLicense (bool showLicenseWarning)
 Initializes the premium node loader with the license information stored in the user's org.vuo.Editor settings file.
 
void loadStoredLicense (void)
 
map< string, VuoCompilerExceptionflushErrorsLoadingModules (void)
 Returns the exceptions that were encountered when loading modules (indexed by module file path), and clears the list of stored exceptions.
 
void compileComposition (VuoCompilerComposition *composition, string outputPath, bool isTopLevelComposition=true)
 Compiles a composition to LLVM bitcode.
 
void compileComposition (string inputPath, string outputPath, bool isTopLevelComposition)
 Compiles a composition, read from file, to LLVM bitcode.
 
void compileComposition (string inputPath, string outputPath)
 
void compileCompositionString (const string &compositionString, string outputPath, bool isTopLevelComposition=true)
 Compiles the composition, read from a string, to LLVM bitcode.
 
VuoCompilerNodeClassinstallSubcomposition (string compositionPath)
 Installs the composition as a node class in the user-specific Vuo Modules folder.
 
void compileModule (string inputPath, string outputPath)
 Compiles a node class, port type, or library module to LLVM bitcode.
 
void compileModule (string inputPath, string outputPath, const vector< string > &includeDirs)
 Compiles a node class, port type, or library module to LLVM bitcode.
 
void linkCompositionToCreateExecutable (string inputPath, string outputPath, Optimization optimization, bool isApp=false, string rPath="")
 Turns a compiled composition into an executable by linking in all of its dependencies and adding a main function.
 
void linkCompositionToCreateDynamicLibrary (string inputPath, string outputPath, Optimization optimization)
 Turns a compiled composition into a dynamic library by linking in all of its dependencies.
 
void linkCompositionToCreateDynamicLibraries (string compiledCompositionPath, string linkedCompositionPath, string &newLinkedResourcePath, vector< string > &alreadyLinkedResourcePaths, set< string > &alreadyLinkedResources)
 Creates one dynamic library for the composition by itself and, if needed, another dynamic library for the node classes and other resources that are dependencies of the composition.
 
void prepareForFastBuild (void)
 Asynchronously prepares the cache that enables compositions to build faster.
 
void setLoadAllModules (bool shouldLoadAllModules)
 Controls whether the VuoCompiler should load all node classes, types, and library modules from the module search paths the first time a module is needed.
 
void getDependenciesRecursively (const string &dependency, set< string > &compatibleDependencies, set< string > &incompatibleDependencies)
 Adds dependency and the names of all of its dependencies to compatibleDependencies and incompatibleDependencies.
 
VuoNodecreateNode (VuoCompilerNodeClass *nodeClass, string title="", double x=0, double y=0)
 Instantiates a node for the given node class.
 
VuoNodecreatePublishedInputNode (vector< VuoPublishedPort * > publishedInputPorts)
 Instantiates a node used during code generation to represent published input ports.
 
VuoNodecreatePublishedOutputNode (vector< VuoPublishedPort * > publishedOutputPorts)
 Instantiates a node used during code generation to represent published output ports.
 
VuoCompilerNodeClassgetNodeClass (const string &id)
 Looks up the VuoCompilerNodeClass for the node class specified by id.
 
map< string,
VuoCompilerNodeClass * > 
getNodeClasses (void)
 Returns a map linking a string representation of a node class's name to its VuoCompilerNodeClass instance.
 
VuoCompilerTypegetType (const string &id)
 Looks up the VuoCompilerType for the port type specified by id.
 
map< string, VuoCompilerType * > getTypes (void)
 Returns a map linking a string representation of a type's id to its VuoCompilerType instance.
 
VuoNodeSetgetNodeSetForName (const string &name)
 Looks up the VuoNodeSet with the given name.
 
void listNodeClasses (const string &format="")
 Prints a list of all loaded node classes to standard output.
 
void addHeaderSearchPath (const string &path)
 Adds a header search path to use when compiling a node class.
 
void addLibrarySearchPath (const string &path)
 Adds a library search path to use when linking a composition.
 
void addFrameworkSearchPath (const string &path)
 Adds a macOS framework search path to use when linking a composition.
 
void setTelemetry (const string &telemetry)
 Sets the telemetry option to use when compiling a composition.
 
void setTarget (const string &target)
 Sets the target triple to use when compiling or linking.
 
void setVerbose (bool isVerbose)
 Sets the verbosity to use when compiling or linking.
 
string getCompositionLoaderPath (void)
 Returns the path to the VuoCompositionLoader executable.
 
void print (void)
 Prints info about this compiler, for debugging.
 

Static Public Member Functions

static Module * readModuleFromBitcode (string inputPath)
 Returns the LLVM module read from inputPath (an LLVM bitcode file).
 
static void deleteModule (Module *module)
 Calls the destructor for module, using the LLVM global context thread-safely.
 
static set< string > getEncounteredPremiumModules ()
 Returns the set of premium module names that the compiler has attempted to load, whether or not the loads were successful.
 
static VuoRunnernewSeparateProcessRunnerFromCompositionFile (string compositionFilePath)
 Creates a runner object that can run the composition in file compositionFilePath in a new process.
 
static VuoRunnernewSeparateProcessRunnerFromCompositionString (string composition, string workingDirectory)
 Creates a runner object that can run the composition in string composition in a new process.
 
static VuoRunnernewCurrentProcessRunnerFromCompositionFile (string compositionFilePath)
 Creates a runner object that can run the composition in file compositionFilePath in this process.
 
static VuoRunnernewCurrentProcessRunnerFromCompositionString (string composition, string workingDirectory)
 Creates a runner object that can run the composition in string composition in this process.
 

Friends

class TestVuoCompiler
 TestVuoCompiler needs to add a search path for its own private nodes/types.
 
class TestCompositionExecution
 TestCompositionExecution needs to add a search path for its own private nodes.
 
class TestVuoCompilerModule
 
class TestVuoCompilerBitcodeGenerator
 
class TestCompilingAndLinking
 
class TestSubcompositions
 

Member Enumeration Documentation

Options for optimizations when building a composition.

Enumerator
Optimization_FastBuild 

Optimize for a fast build, at the expense of a binary that relies on a large cache library.

Optimization_FastBuildExistingCache 

Like Optimization_FastBuild, but skips ensuring that the cache library is up to date.

Optimization_SmallBinary 

Optimize for a small self-contained binary, at the expense of the build taking longer.

Constructor & Destructor Documentation

VuoCompiler::VuoCompiler ( void  )

Creates a compiler instance that can be used for compiling and linking.

VuoCompiler::~VuoCompiler ( void  )

Destructor.

Member Function Documentation

void VuoCompiler::addFrameworkSearchPath ( const string &  path)

Adds a macOS framework search path to use when linking a composition.

void VuoCompiler::addHeaderSearchPath ( const string &  path)

Adds a header search path to use when compiling a node class.

void VuoCompiler::addLibrarySearchPath ( const string &  path)

Adds a library search path to use when linking a composition.

void VuoCompiler::compileComposition ( VuoCompilerComposition composition,
string  outputPath,
bool  isTopLevelComposition = true 
)

Compiles a composition to LLVM bitcode.

If the composition contains generic nodes, then it may be modified to allow these generic nodes to be compiled. See reifyGenericPortTypes() for more information.

Parameters
compositionThe composition to compile.
outputPathThe file in which to save the compiled LLVM bitcode.
isTopLevelCompositionTrue if the composition is top-level, false if it's a subcomposition.
Exceptions
VuoCompilerExceptionThe composition is invalid.
void VuoCompiler::compileComposition ( string  inputPath,
string  outputPath,
bool  isTopLevelComposition 
)

Compiles a composition, read from file, to LLVM bitcode.

Parameters
inputPathThe .vuo file containing the composition.
outputPathThe file in which to save the compiled LLVM bitcode.
isTopLevelCompositionTrue if the composition is top-level, false if it's a subcomposition.
Exceptions
VuoCompilerExceptionThe composition is invalid.
void VuoCompiler::compileComposition ( string  inputPath,
string  outputPath 
)
void VuoCompiler::compileCompositionString ( const string &  compositionString,
string  outputPath,
bool  isTopLevelComposition = true 
)

Compiles the composition, read from a string, to LLVM bitcode.

Parameters
compositionStringA string containing the composition.
outputPathThe file in which to save the compiled LLVM bitcode.
isTopLevelCompositionTrue if the composition is top-level, false if it's a subcomposition.
Exceptions
VuoCompilerExceptionThe composition is invalid.
void VuoCompiler::compileModule ( string  inputPath,
string  outputPath 
)

Compiles a node class, port type, or library module to LLVM bitcode.

Parameters
inputPathThe file to compile, containing a C implementation of the node class, port type, or library module.
outputPathThe file in which to save the compiled LLVM bitcode.
void VuoCompiler::compileModule ( string  inputPath,
string  outputPath,
const vector< string > &  includePaths 
)

Compiles a node class, port type, or library module to LLVM bitcode.

Parameters
inputPathThe file to compile, containing a C implementation of the node class, port type, or library module.
outputPathThe file in which to save the compiled LLVM bitcode.
includePathsDirectories with header files to be included when compiling.
VuoNode * VuoCompiler::createNode ( VuoCompilerNodeClass nodeClass,
string  title = "",
double  x = 0,
double  y = 0 
)

Instantiates a node for the given node class.

If the node class is a generic template (e.g. vuo.data.hold), then the node is instantiated with the specialized version of the node class (e.g. vuo.data.hold.VuoGenericType1).

Parameters
nodeClassThe node class from which to create the node.
titleThe node's title.
xThe node's x-coordinate within the composition.
yThe node's y-coordinate within the composition.
VuoNode * VuoCompiler::createPublishedInputNode ( vector< VuoPublishedPort * >  publishedInputPorts)

Instantiates a node used during code generation to represent published input ports.

VuoNode * VuoCompiler::createPublishedOutputNode ( vector< VuoPublishedPort * >  publishedOutputPorts)

Instantiates a node used during code generation to represent published output ports.

void VuoCompiler::deleteModule ( Module *  module)
static

Calls the destructor for module, using the LLVM global context thread-safely.

This function may be called on any dispatch queue except llvmQueue.

map< string, VuoCompilerException > VuoCompiler::flushErrorsLoadingModules ( void  )

Returns the exceptions that were encountered when loading modules (indexed by module file path), and clears the list of stored exceptions.

string VuoCompiler::getCompositionLoaderPath ( void  )

Returns the path to the VuoCompositionLoader executable.

void VuoCompiler::getDependenciesRecursively ( const string &  dependency,
set< string > &  compatibleDependencies,
set< string > &  incompatibleDependencies 
)

Adds dependency and the names of all of its dependencies to compatibleDependencies and incompatibleDependencies.

Parameters
dependencyThe current dependency being searched for its dependencies.
[out]compatibleDependenciesThe dependencies found so far by calls to this function that are compatible with the targets for building the composition.
[out]incompatibleDependenciesThe dependencies that are incompatible with the targets for building the composition.
set< string > VuoCompiler::getEncounteredPremiumModules ( )
static

Returns the set of premium module names that the compiler has attempted to load, whether or not the loads were successful.

VuoCompilerNodeClass * VuoCompiler::getNodeClass ( const string &  id)

Looks up the VuoCompilerNodeClass for the node class specified by id.

The node class module is loaded or generated if it hasn't been already.

Example:
VuoCompiler *compiler = new VuoCompiler();
VuoCompilerNodeClass *nc = compiler->getNodeClass("vuo.math.add.VuoInteger");
[...]
delete compiler;
map< string, VuoCompilerNodeClass * > VuoCompiler::getNodeClasses ( void  )

Returns a map linking a string representation of a node class's name to its VuoCompilerNodeClass instance.

The node class modules are loaded if they haven't been already.

VuoNodeSet * VuoCompiler::getNodeSetForName ( const string &  name)

Looks up the VuoNodeSet with the given name.

The node class modules are loaded if they haven't been already.

VuoCompilerType * VuoCompiler::getType ( const string &  id)

Looks up the VuoCompilerType for the port type specified by id.

The port type module is loaded or generated if it haven't been already.

map< string, VuoCompilerType * > VuoCompiler::getTypes ( void  )

Returns a map linking a string representation of a type's id to its VuoCompilerType instance.

The type modules are loaded if they haven't been already.

VuoCompilerNodeClass * VuoCompiler::installSubcomposition ( string  compositionPath)

Installs the composition as a node class in the user-specific Vuo Modules folder.

The file at compositionPath is compiled as a node class. The compiled node class is placed in the cached Modules folder. That node class is returned.

Exceptions
VuoCompilerExceptionThe composition could not be compiled.
void VuoCompiler::linkCompositionToCreateDynamicLibraries ( string  compiledCompositionPath,
string  linkedCompositionPath,
string &  newLinkedResourcePath,
vector< string > &  alreadyLinkedResourcePaths,
set< string > &  alreadyLinkedResources 
)

Creates one dynamic library for the composition by itself and, if needed, another dynamic library for the node classes and other resources that are dependencies of the composition.

Parameters
compiledCompositionPathPath to the compiled composition (an LLVM bitcode file).
linkedCompositionPathPath where the resulting dynamic library for the composition should be placed.
newLinkedResourcePathPath where the resulting dynamic library for the composition's resources should be placed. The dynamic library is only created if this version of the composition requires resources that are not in alreadyLinkedResources. When this function returns, if the dynamic library was created, then this argument is the same as when it was passed in; otherwise, this argument is the empty string.
alreadyLinkedResourcePathsPaths where the resulting dynamic libraries for the composition's resources have been placed in previous calls to this function. When this function returns, if a dynamic library was created at newLinkedResourcePath, it will be the last element in this list.
alreadyLinkedResourcesNames of resources that have been linked into the composition in previous calls to this function. When this function returns, any new resources will have been added to this list.
Exceptions
VuoCompilerExceptionAt least one of the dependencies is incompatible with the targets for building the composition, or the linker encountered errors and failed. The values of newLinkedResourcePath, alreadyLinkedResourcePaths, and alreadyLinkedResources are unchanged.
void VuoCompiler::linkCompositionToCreateDynamicLibrary ( string  inputPath,
string  outputPath,
Optimization  optimization 
)

Turns a compiled composition into a dynamic library by linking in all of its dependencies.

Parameters
inputPathPath to the compiled composition (an LLVM bitcode file).
outputPathPath where the resulting dynamic library should be placed.
optimizationControls the time it takes to link the composition and the size and dependencies of the resulting dynamic library.
Exceptions
VuoCompilerExceptionAt least one of the dependencies is incompatible with the targets for building the composition, or the linker encountered errors and failed.
void VuoCompiler::linkCompositionToCreateExecutable ( string  inputPath,
string  outputPath,
Optimization  optimization,
bool  isApp = false,
string  rPath = "" 
)

Turns a compiled composition into an executable by linking in all of its dependencies and adding a main function.

Parameters
inputPathPath to the compiled composition (an LLVM bitcode file).
outputPathPath where the resulting executable should be placed.
optimizationControls the time it takes to link the composition and the size and dependencies of the resulting executable.
isAppIf true, the resulting executable can be added to an app bundle. If false, the resulting executable will be headless unless the composition contains a window.
rPathAn optional -rpath argument to be passed to clang.
Exceptions
VuoCompilerExceptionAt least one of the dependencies is incompatible with the targets for building the composition, or the linker encountered errors and failed.
void VuoCompiler::listNodeClasses ( const string &  format = "")

Prints a list of all loaded node classes to standard output.

The node class modules are loaded if they haven't been already.

Parameters
formatThe format for printing the node classes.
  • If "", prints each class name (e.g. vuo.math.count.VuoInteger), one per line.
  • If "dot", prints the declaration of a node as it would appear in a .vuo (DOT format) file, with a constant value set for each data+event input port and a comment listing metadata and port types for the node class.
void VuoCompiler::loadStoredLicense ( bool  showLicenseWarning)

Initializes the premium node loader with the license information stored in the user's org.vuo.Editor settings file.

void VuoCompiler::loadStoredLicense ( void  )
VuoRunner * VuoCompiler::newCurrentProcessRunnerFromCompositionFile ( string  compositionFilePath)
static

Creates a runner object that can run the composition in file compositionFilePath in this process.

Exceptions
VuoCompilerExceptionThe composition is invalid.
VuoRunner * VuoCompiler::newCurrentProcessRunnerFromCompositionString ( string  composition,
string  workingDirectory 
)
static

Creates a runner object that can run the composition in string composition in this process.

Parameters
compositionA serialized composition.
workingDirectoryThe directory used by nodes in the composition to resolve relative paths.
Exceptions
VuoCompilerExceptionThe composition is invalid.
VuoRunner * VuoCompiler::newSeparateProcessRunnerFromCompositionFile ( string  compositionFilePath)
static

Creates a runner object that can run the composition in file compositionFilePath in a new process.

Exceptions
VuoCompilerExceptionThe composition is invalid.
VuoRunner * VuoCompiler::newSeparateProcessRunnerFromCompositionString ( string  composition,
string  workingDirectory 
)
static

Creates a runner object that can run the composition in string composition in a new process.

Parameters
compositionA serialized composition.
workingDirectoryThe directory used by nodes in the composition to resolve relative paths.
Exceptions
VuoCompilerExceptionThe composition is invalid.
void VuoCompiler::prepareForFastBuild ( void  )

Asynchronously prepares the cache that enables compositions to build faster.

The first time a composition is built with the "faster build" optimization, it waits until the cache is prepared. Preparing the cache may take several seconds. By calling this function, the cache can be prepared in advance, so that there's no delay when building the first composition.

void VuoCompiler::print ( void  )

Prints info about this compiler, for debugging.

Module * VuoCompiler::readModuleFromBitcode ( string  inputPath)
static

Returns the LLVM module read from inputPath (an LLVM bitcode file).

This function may be called on any dispatch queue except llvmQueue.

void VuoCompiler::setLicense ( string  licenseContent,
string  licenseSignature 
)

Initializes the premium node loader with the license information provided.

This function should be called before attempting to load any premium moduless.

void VuoCompiler::setLoadAllModules ( bool  shouldLoadAllModules)

Controls whether the VuoCompiler should load all node classes, types, and library modules from the module search paths the first time a module is needed.

void VuoCompiler::setTarget ( const string &  target)

Sets the target triple to use when compiling or linking.

void VuoCompiler::setTelemetry ( const string &  telemetry)

Sets the telemetry option to use when compiling a composition.

Valid values are "on" and "console".

void VuoCompiler::setVerbose ( bool  isVerbose)

Sets the verbosity to use when compiling or linking.

If true, prints some debug info and passes the -v option to Clang.

Friends And Related Function Documentation

friend class TestCompositionExecution
friend

TestCompositionExecution needs to add a search path for its own private nodes.

friend class TestVuoCompiler
friend

TestVuoCompiler needs to add a search path for its own private nodes/types.


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