Vuo
0.9.0
|
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.
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:
Executables and dynamic libraries created by VuoCompiler link to Vuo.framework, so they can't be distributed without it. Currently, these executables and dynamic libraries contain an absolute path to Vuo.framework, so they can't easily be distributed at all; this will be improved in later versions of Vuo.
Public Member Functions | |
~VuoCompiler (void) | |
Destructor. | |
void | setLicense (string licenseContent, string licenseSignature) |
Initializes the premium node loader with the license information provided. | |
void | compileComposition (VuoCompilerComposition *composition, string outputPath) |
Compiles a composition to LLVM bitcode. | |
void | compileComposition (string inputPath, string outputPath) |
Compiles a composition, read from file, to LLVM bitcode. | |
void | compileCompositionString (const string &compositionString, string outputPath) |
Compiles the composition, read from a string, to LLVM bitcode. | |
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, 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) |
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. | |
VuoNode * | createNode (VuoCompilerNodeClass *nodeClass, string title="", double x=0, double y=0) |
Instantiates a node for the given node class. | |
VuoCompilerNodeClass * | getNodeClass (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. | |
VuoCompilerType * | getType (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. | |
VuoNodeSet * | getNodeSetForName (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 | addPreferredLibrarySearchPath (const string &path) |
Adds a preferred library search path to use when linking a composition. | |
void | clearPreferredLibrarySearchPaths () |
Clears the list of preferred library paths. | |
void | addFrameworkSearchPath (const string &path) |
Adds a Mac OS X framework search path to use when linking a composition. | |
void | addPreferredFrameworkSearchPath (const string &path) |
Adds a preferred Mac OS X 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. | |
void | setClangPath (const string &clangPath) |
Sets the path to the clang binary. | |
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 string | getUserModulesPath () |
Returns the filesystem path to the user-specific Vuo Modules folder. | |
static string | getSystemModulesPath () |
Returns the filesystem path to the system-wide Vuo Modules folder. | |
static void | preserveOriginalFileName (string &fileContents, string originalFileName) |
Saves originalFileName into fileContents so that, when fileContents is written to some other file path, originalFileName will still be the name that shows up in compile errors/warnings and in the FILE macro. | |
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 VuoRunner * | newSeparateProcessRunnerFromCompositionFile (string compositionFilePath) |
Creates a runner object that can run the composition in file compositionFilePath in a new process. | |
static VuoRunner * | newSeparateProcessRunnerFromCompositionString (string composition, string workingDirectory) |
Creates a runner object that can run the composition in string composition in a new process. | |
static VuoRunner * | newCurrentProcessRunnerFromCompositionFile (string compositionFilePath) |
Creates a runner object that can run the composition in file compositionFilePath in this process. | |
static VuoRunner * | newCurrentProcessRunnerFromCompositionString (string composition, string workingDirectory) |
Creates a runner object that can run the composition in string composition in this process. | |
Protected Member Functions | |
void | addModuleSearchPath (string path) |
Adds a module search path (for node classes, types, and libraries) to use when linking a composition. | |
Friends | |
class | TestVuoCompilerBitcodeGenerator |
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. | |
VuoCompiler::~VuoCompiler | ( | void | ) |
Destructor.
void VuoCompiler::addFrameworkSearchPath | ( | const string & | path | ) |
Adds a Mac OS X 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.
|
protected |
Adds a module search path (for node classes, types, and libraries) to use when linking a composition.
void VuoCompiler::addPreferredFrameworkSearchPath | ( | const string & | path | ) |
Adds a preferred Mac OS X framework search path to use when linking a composition.
Preferred paths will be searched before any other framework paths.
void VuoCompiler::addPreferredLibrarySearchPath | ( | const string & | path | ) |
Adds a preferred library search path to use when linking a composition.
Preferred paths will be searched before any other library paths.
void VuoCompiler::clearPreferredLibrarySearchPaths | ( | void | ) |
Clears the list of preferred library paths.
void VuoCompiler::compileComposition | ( | VuoCompilerComposition * | composition, |
string | outputPath | ||
) |
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.
composition | The composition to compile. |
outputPath | The file in which to save the compiled LLVM bitcode. |
std::exception | The composition is invalid. |
void VuoCompiler::compileComposition | ( | string | inputPath, |
string | outputPath | ||
) |
Compiles a composition, read from file, to LLVM bitcode.
inputPath | The .vuo file containing the composition. |
outputPath | The file in which to save the compiled LLVM bitcode. |
std::exception | The composition is invalid. |
void VuoCompiler::compileCompositionString | ( | const string & | compositionString, |
string | outputPath | ||
) |
Compiles the composition, read from a string, to LLVM bitcode.
compositionString | A string containing the composition. |
outputPath | The file in which to save the compiled LLVM bitcode. |
std::exception | The composition is invalid. |
void VuoCompiler::compileModule | ( | string | inputPath, |
string | outputPath | ||
) |
Compiles a node class, port type, or library module to LLVM bitcode.
inputPath | The file to compile, containing a C implementation of the node class, port type, or library module. |
outputPath | The 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.
inputPath | The file to compile, containing a C implementation of the node class, port type, or library module. |
outputPath | The file in which to save the compiled LLVM bitcode. |
includePaths | Directories 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).
nodeClass | The node class from which to create the node. |
title | The node's title. |
x | The node's x-coordinate within the composition. |
y | The node's y-coordinate within the composition. |
|
static |
Calls the destructor for module, using the LLVM global context thread-safely.
This function may be called on any dispatch queue except llvmQueue
.
string VuoCompiler::getCompositionLoaderPath | ( | void | ) |
Returns the path to the VuoCompositionLoader executable.
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.
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.
|
static |
Returns the filesystem path to the system-wide Vuo Modules folder.
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.
|
static |
Returns the filesystem path to the user-specific Vuo Modules folder.
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.
compiledCompositionPath | Path to the compiled composition (an LLVM bitcode file). |
linkedCompositionPath | Path where the resulting dynamic library for the composition should be placed. |
newLinkedResourcePath | Path 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. |
alreadyLinkedResourcePaths | Paths 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. |
alreadyLinkedResources | Names 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. |
std::runtime_error | At least one of the dependencies is incompatible with the targets for building the composition. |
VuoCompilerException | The linker encountered errors and failed. The values of newLinkedResourcePath, alreadyLinkedResourcePaths, and alreadyLinkedResources are unchanged. |
void VuoCompiler::linkCompositionToCreateDynamicLibrary | ( | string | inputPath, |
string | outputPath | ||
) |
Turns a compiled composition into a dynamic library by linking in all of its dependencies.
inputPath | Path to the compiled composition (an LLVM bitcode file). |
outputPath | Path where the resulting dynamic library should be placed. |
std::runtime_error | At least one of the dependencies is incompatible with the targets for building the composition. |
void VuoCompiler::linkCompositionToCreateExecutable | ( | string | inputPath, |
string | outputPath, | ||
bool | isApp = false , |
||
string | rPath = "" |
||
) |
Turns a compiled composition into an executable by linking in all of its dependencies and adding a main function.
inputPath | Path to the compiled composition (an LLVM bitcode file). |
outputPath | Path where the resulting executable should be placed. |
isApp | If 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. |
rPath | An optional -rpath argument to be passed to clang. |
std::runtime_error | At least one of the dependencies is incompatible with the targets for building the composition. |
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.
format | The format for printing the node classes.
|
|
static |
Creates a runner object that can run the composition in file compositionFilePath in this process.
std::exception | The composition is invalid. |
|
static |
Creates a runner object that can run the composition in string composition in this process.
composition | A serialized composition. |
workingDirectory | The directory used by nodes in the composition to resolve relative paths. |
std::exception | The composition is invalid. |
|
static |
Creates a runner object that can run the composition in file compositionFilePath in a new process.
std::exception | The composition is invalid. |
|
static |
Creates a runner object that can run the composition in string composition in a new process.
composition | A serialized composition. |
workingDirectory | The directory used by nodes in the composition to resolve relative paths. |
std::exception | The composition is invalid. |
|
static |
Saves originalFileName into fileContents so that, when fileContents is written to some other file path, originalFileName will still be the name that shows up in compile errors/warnings and in the FILE
macro.
This function inserts a preprocessor directive at the beginning of fileContents. Any modifications to fileContents after this function is called should keep the preprocessor directive on the first line.
void VuoCompiler::print | ( | void | ) |
Prints info about this compiler, for debugging.
|
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::setClangPath | ( | const string & | clangPath | ) |
Sets the path to the clang binary.
void VuoCompiler::setLicense | ( | string | licenseContent, |
string | licenseSignature | ||
) |
Initializes the premium node loader with the license information provided.
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.
|
friend |
TestCompositionExecution needs to add a search path for its own private nodes.
|
friend |
TestVuoCompiler needs to add a search path for its own private nodes/types.