Builder (JavaCPP 1.5.11 API)

java.lang.Object
- org.bytedeco.javacpp.tools.Builder

```
public class Builder
extends Object
```
The Builder is responsible for coordinating efforts between the Parser, the Generator, and the native compiler. It contains the main() method, and basically takes care of the tasks one would expect from a command line build tool, but can also be used programmatically by setting its properties and calling build().

Author:

Samuel Audet

Field Summary

Fields
Modifier and Type	Field and Description
`(package private) String[]`	`buildCommand` A system command for `ProcessBuilder` to execute for the build, instead of JavaCPP itself.
`(package private) ClassScanner`	`classScanner` The instance of the `ClassScanner` that fills up a `Collection` of `Class` objects to process.
`(package private) boolean`	`clean` If true, deletes all files from `outputDirectory` before writing anything in it.
`(package private) CommandExecutor`	`commandExecutor` An alternative CommandExecutor to use to execute commands.
`(package private) boolean`	`compile` If true, compiles the generated source file to a shared library and deletes source.
`(package private) Collection<String>`	`compilerOptions` Contains additional command line options from the user for the native compiler.
`(package private) File`	`configDirectory` The name of the directory where to output config files for GraalVM native-image, if not `null`.
`(package private) boolean`	`copyLibs` If true, also copies to the output directory dependent shared libraries (link and preload).
`(package private) boolean`	`copyResources` If true, also copies to the output directory resources listed in properties.
`(package private) boolean`	`deleteJniFiles` If true, preserves the generated C++ JNI files after compilation.
`(package private) String`	`encoding` The name of the character encoding used for input files as well as output files.
`(package private) Map<String,String>`	`environmentVariables` User specified environment variables to pass to the native compiler.
`(package private) boolean`	`generate` If true, attempts to generate C++ JNI files, but if false, only attempts to parse header files.
`(package private) boolean`	`header` If true, also generates C++ header files containing declarations of callback functions.
`(package private) String`	`jarPrefix` The name of the JAR file to create, if not `null`.
`(package private) Logger`	`logger` Logger where to send debug, info, warning, and error messages.
`(package private) File`	`outputDirectory` The directory where the generated files and compiled shared libraries get written to.
`(package private) String`	`outputName` The name of the output generated source file or shared library.
`(package private) Properties`	`properties` Accumulates the various properties loaded from resources, files, command line options, etc.
`(package private) File`	`workingDirectory` User specified working directory to execute build subprocesses under.

Constructor Summary

Constructors
Constructor and Description

Builder()
Default constructor that simply initializes everything.

Builder(Logger logger)
Constructor that simply initializes everything.

Constructors
Constructor and Description
`Builder()` Default constructor that simply initializes everything.
`Builder(Logger logger)` Constructor that simply initializes everything.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Builder`	`addProperty(String key, String... values)` Adds values to a given property key, seperating them with "platform.path.separator".
`File[]`	`build()` Starts the build process and returns an array of `File` produced.
`Builder`	`buildCommand(String[] buildCommand)` Sets the `buildCommand` field to the argument.
`Builder`	`classesOrPackages(String... classesOrPackages)` Requests the `classScanner` to add a class or all classes from a package.
`Builder`	`classPaths(String... classPaths)` Appends argument to the paths of the `classScanner`.
`Builder`	`classPaths(String classPaths)` Splits argument with `File.pathSeparator` and appends result to paths of the `classScanner`.
`Builder`	`clean(boolean clean)` Sets the `clean` field to the argument.
`(package private) void`	`cleanOutputDirectory()` Deletes `outputDirectory` if `clean` is true.
`Builder`	`commandExecutor(CommandExecutor commandExecutor)` Sets the `commandExecutor` field to the argument.
`Builder`	`compile(boolean compile)` Sets the `compile` field to the argument.
`(package private) int`	`compile(String[] sourceFilenames, String outputFilename, ClassProperties properties, File workingDirectory)` Launches and waits for the native compiler to produce a native shared library.
`Builder`	`compilerOptions(String... options)` Appends arguments to the `compilerOptions` field.
`Builder`	`configDirectory(File configDirectory)` Sets the `configDirectory` field to the argument.
`Builder`	`configDirectory(String configDirectory)` Sets the `configDirectory` field to the argument.
`Builder`	`copyLibs(boolean copyLibs)` Sets the `copyLibs` field to the argument.
`Builder`	`copyResources(boolean copyResources)` Sets the `copyResources` field to the argument.
`(package private) void`	`createJar(File jarFile, String[] classPath, File... files)` Stores all the files in the given JAR file.
`Builder`	`deleteJniFiles(boolean deleteJniFiles)` Sets the `deleteJniFiles` field to the argument.
`Builder`	`encoding(String encoding)` Sets the `encoding` field to the argument.
`Builder`	`environmentVariables(Map<String,String> environmentVariables)` Sets the `environmentVariables` field to the argument.
`Builder`	`generate(boolean generate)` Sets the `generate` field to the argument.
`(package private) File[]`	`generateAndCompile(Class[] classes, String outputName, boolean first, boolean last)` Generates C++ source files for classes, and compiles everything in one shared library when `compile == true`.
`(package private) File`	`getOutputPath(Class[] classes, String[] sourcePrefixes)` Creates and returns the directory where output files should be placed.
`Properties`	`getProperties()` Returns `properties`.
`String`	`getProperty(String key)` Returns `properties.getProperty(key)`.
`Builder`	`header(boolean header)` Sets the `header` field to the argument.
`(package private) void`	`includeJavaPaths(ClassProperties properties, boolean header)` Tries to find automatically include paths for `jni.h` and `jni_md.h`, as well as the link and library paths for the `jvm` library.
`Builder`	`jarPrefix(String jarPrefix)` Sets the `jarPrefix` field to the argument.
`static void`	`main(String[] args)` The terminal shell interface to the Builder.
`Builder`	`outputDirectory(File outputDirectory)` Sets the `outputDirectory` field to the argument.
`Builder`	`outputDirectory(String outputDirectory)` Sets the `outputDirectory` field to the argument.
`Builder`	`outputName(String outputName)` Sets the `outputName` field to the argument.
`(package private) File[]`	`parse(String[] classPath, Class cls)` Calls `Parser.parse(File, String[], Class)` after creating an instance of the Class.
`static void`	`printHelp()` Simply prints out to the display the command line usage.
`Builder`	`properties(Properties properties)` Adds all the properties of the argument to the `properties` field.
`Builder`	`properties(String platform)` Sets the `properties` field to the ones loaded from resources for the specified platform.
`Builder`	`property(String keyValue)` Sets a property of the `properties` field, in either "key=value" or "key:value" format.
`Builder`	`property(String key, String value)` Sets a key/value pair property of the `properties` field.
`Builder`	`propertyFile(File propertyFile)` Sets the `properties` field to the ones loaded from the specified file.
`Builder`	`propertyFile(String filename)` Sets the `properties` field to the ones loaded from the specified file.
`Builder`	`workingDirectory(File workingDirectory)` Sets the `workingDirectory` field to the argument.
`Builder`	`workingDirectory(String workingDirectory)` Sets the `workingDirectory` field to the argument.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - logger
```
final Logger logger
```
    Logger where to send debug, info, warning, and error messages.
  - encoding
```
String encoding
```
    The name of the character encoding used for input files as well as output files.
  - outputDirectory
```
File outputDirectory
```
    The directory where the generated files and compiled shared libraries get written to. By default they are placed in the same directory as the .class file.
  - outputName
```
String outputName
```
    The name of the output generated source file or shared library. This enables single- file output mode. By default, the top-level enclosing classes get one file each.
  - configDirectory
```
File configDirectory
```
    The name of the directory where to output config files for GraalVM native-image, if not null.
  - jarPrefix
```
String jarPrefix
```
    The name of the JAR file to create, if not null.
  - clean
```
boolean clean
```
    If true, deletes all files from outputDirectory before writing anything in it.
  - generate
```
boolean generate
```
    If true, attempts to generate C++ JNI files, but if false, only attempts to parse header files.
  - compile
```
boolean compile
```
    If true, compiles the generated source file to a shared library and deletes source.
  - deleteJniFiles
```
boolean deleteJniFiles
```
    If true, preserves the generated C++ JNI files after compilation.
  - header
```
boolean header
```
    If true, also generates C++ header files containing declarations of callback functions.
  - copyLibs
```
boolean copyLibs
```
    If true, also copies to the output directory dependent shared libraries (link and preload).
  - copyResources
```
boolean copyResources
```
    If true, also copies to the output directory resources listed in properties.
  - properties
```
Properties properties
```
    Accumulates the various properties loaded from resources, files, command line options, etc.
  - classScanner
```
ClassScanner classScanner
```
    The instance of the ClassScanner that fills up a Collection of Class objects to process.
  - buildCommand
```
String[] buildCommand
```
    A system command for ProcessBuilder to execute for the build, instead of JavaCPP itself.
  - workingDirectory
```
File workingDirectory
```
    User specified working directory to execute build subprocesses under.
  - environmentVariables
```
Map<String,String> environmentVariables
```
    User specified environment variables to pass to the native compiler.
  - compilerOptions
```
Collection<String> compilerOptions
```
    Contains additional command line options from the user for the native compiler.
  - commandExecutor
```
CommandExecutor commandExecutor
```
    An alternative CommandExecutor to use to execute commands.
- Constructor Detail
  - Builder
```
public Builder()
```
    Default constructor that simply initializes everything.
  - Builder
```
public Builder(Logger logger)
```
    Constructor that simply initializes everything.
    
    Parameters:
    
    logger - where to send messages
- Method Detail
  - cleanOutputDirectory
```
void cleanOutputDirectory()
                   throws IOException
```
    Deletes outputDirectory if clean is true.
    
    Throws:
    
    IOException
  - parse
```
File[] parse(String[] classPath,
             Class cls)
      throws IOException,
             ParserException
```
    Calls Parser.parse(File, String[], Class) after creating an instance of the Class.
    
    Parameters:
    
    classPath - an array of paths to try to load header files from
    
    cls - The class annotated with Properties and implementing InfoMapper
    
    Returns:
    
    the target File produced
    
    Throws:
    
    IOException - on Java target file writing error
    
    ParserException - on C/C++ header file parsing error
  - includeJavaPaths
```
void includeJavaPaths(ClassProperties properties,
                      boolean header)
```
    Tries to find automatically include paths for jni.h and jni_md.h, as well as the link and library paths for the jvm library.
    
    Parameters:
    
    properties - the Properties containing the paths to update
    
    header - to request support for exporting callbacks via generated header file
  - compile
```
int compile(String[] sourceFilenames,
            String outputFilename,
            ClassProperties properties,
            File workingDirectory)
     throws IOException,
            InterruptedException
```
    Launches and waits for the native compiler to produce a native shared library.
    
    Parameters:
    
    sourceFilenames - the C++ source filenames
    
    outputFilename - the output filename of the shared library
    
    properties - the Properties detailing the compiler options to use
    
    Returns:
    
    the result of Process.waitFor()
    
    Throws:
    
    IOException
    
    InterruptedException
  - getOutputPath
```
File getOutputPath(Class[] classes,
                   String[] sourcePrefixes)
            throws IOException
```
    Creates and returns the directory where output files should be placed. Uses outputDirectory as is when available, but falls back on the longest common path to the classes as well as the platform specific library path when available, or the platform name itself and the user provided extension when not.
    
    Parameters:
    
    classes - from which to derive the output path
    
    sourcePrefixes - returned, 2 strings without platform names, one from our class loader, the other from the common path of the classes
    
    Returns:
    
    directory where binary files should be written to
    
    Throws:
    
    IOException
  - generateAndCompile
```
File[] generateAndCompile(Class[] classes,
                          String outputName,
                          boolean first,
                          boolean last)
                   throws IOException,
                          InterruptedException
```
    Generates C++ source files for classes, and compiles everything in one shared library when compile == true.
    
    Parameters:
    
    classes - the Class objects as input to Generator
    
    outputName - the output name of the shared library
    
    first - of the batch, so generate jnijavacpp.cpp
    
    last - of the batch, so delete jnijavacpp.cpp
    
    Returns:
    
    the actual File generated, either the compiled library or its source
    
    Throws:
    
    IOException
    
    InterruptedException
  - createJar
```
void createJar(File jarFile,
               String[] classPath,
               File... files)
        throws IOException
```
    Stores all the files in the given JAR file. Also attempts to root the paths of the filenames to each element of a list of classpaths.
    
    Parameters:
    
    jarFile - the JAR file to create
    
    classPath - an array of paths to try to use as root for classes
    
    files - a list of files to store in the JAR file
    
    Throws:
    
    IOException
  - classPaths
```
public Builder classPaths(String classPaths)
```
    Splits argument with File.pathSeparator and appends result to paths of the classScanner.
  - classPaths
```
public Builder classPaths(String... classPaths)
```
    Appends argument to the paths of the classScanner.
  - encoding
```
public Builder encoding(String encoding)
```
    Sets the encoding field to the argument.
  - outputDirectory
```
public Builder outputDirectory(String outputDirectory)
```
    Sets the outputDirectory field to the argument.
  - outputDirectory
```
public Builder outputDirectory(File outputDirectory)
```
    Sets the outputDirectory field to the argument.
  - clean
```
public Builder clean(boolean clean)
```
    Sets the clean field to the argument.
  - generate
```
public Builder generate(boolean generate)
```
    Sets the generate field to the argument.
  - compile
```
public Builder compile(boolean compile)
```
    Sets the compile field to the argument.
  - deleteJniFiles
```
public Builder deleteJniFiles(boolean deleteJniFiles)
```
    Sets the deleteJniFiles field to the argument.
  - header
```
public Builder header(boolean header)
```
    Sets the header field to the argument.
  - copyLibs
```
public Builder copyLibs(boolean copyLibs)
```
    Sets the copyLibs field to the argument.
  - copyResources
```
public Builder copyResources(boolean copyResources)
```
    Sets the copyResources field to the argument.
  - outputName
```
public Builder outputName(String outputName)
```
    Sets the outputName field to the argument.
  - configDirectory
```
public Builder configDirectory(String configDirectory)
```
    Sets the configDirectory field to the argument.
  - configDirectory
```
public Builder configDirectory(File configDirectory)
```
    Sets the configDirectory field to the argument.
  - jarPrefix
```
public Builder jarPrefix(String jarPrefix)
```
    Sets the jarPrefix field to the argument.
  - properties
```
public Builder properties(String platform)
```
    Sets the properties field to the ones loaded from resources for the specified platform.
  - properties
```
public Builder properties(Properties properties)
```
    Adds all the properties of the argument to the properties field.
  - propertyFile
```
public Builder propertyFile(String filename)
                     throws IOException
```
    Sets the properties field to the ones loaded from the specified file.
    
    Throws:
    
    IOException
  - propertyFile
```
public Builder propertyFile(File propertyFile)
                     throws IOException
```
    Sets the properties field to the ones loaded from the specified file.
    
    Throws:
    
    IOException
  - property
```
public Builder property(String keyValue)
```
    Sets a property of the properties field, in either "key=value" or "key:value" format.
  - property
```
public Builder property(String key,
                        String value)
```
    Sets a key/value pair property of the properties field.
  - getProperties
```
public Properties getProperties()
```
    Returns properties.
  - getProperty
```
public String getProperty(String key)
```
    Returns properties.getProperty(key).
  - addProperty
```
public Builder addProperty(String key,
                           String... values)
```
    Adds values to a given property key, seperating them with "platform.path.separator".
  - classesOrPackages
```
public Builder classesOrPackages(String... classesOrPackages)
                          throws IOException,
                                 ClassNotFoundException,
                                 NoClassDefFoundError
```
    Requests the classScanner to add a class or all classes from a package. A null argument indicates the unnamed package.
    
    Throws:
    
    IOException
    
    ClassNotFoundException
    
    NoClassDefFoundError
  - buildCommand
```
public Builder buildCommand(String[] buildCommand)
```
    Sets the buildCommand field to the argument.
  - workingDirectory
```
public Builder workingDirectory(String workingDirectory)
```
    Sets the workingDirectory field to the argument.
  - workingDirectory
```
public Builder workingDirectory(File workingDirectory)
```
    Sets the workingDirectory field to the argument.
  - environmentVariables
```
public Builder environmentVariables(Map<String,String> environmentVariables)
```
    Sets the environmentVariables field to the argument.
  - compilerOptions
```
public Builder compilerOptions(String... options)
```
    Appends arguments to the compilerOptions field.
  - commandExecutor
```
public Builder commandExecutor(CommandExecutor commandExecutor)
```
    Sets the commandExecutor field to the argument.
  - build
```
public File[] build()
             throws IOException,
                    InterruptedException,
                    ParserException
```
    Starts the build process and returns an array of File produced.
    
    Returns:
    
    the array of File produced
    
    Throws:
    
    IOException
    
    InterruptedException
    
    ParserException
  - printHelp
```
public static void printHelp()
```
    Simply prints out to the display the command line usage.
  - main
```
public static void main(String[] args)
                 throws Exception
```
    The terminal shell interface to the Builder.
    
    Parameters:
    
    args - an array of arguments as described by printHelp()
    
    Throws:
    
    Exception

Class Builder

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

logger

encoding

outputDirectory

outputName

configDirectory

jarPrefix

clean

generate

compile

deleteJniFiles

header

copyLibs

copyResources

properties

classScanner

buildCommand

workingDirectory

environmentVariables

compilerOptions

commandExecutor

Constructor Detail

Builder

Builder

Method Detail

cleanOutputDirectory

parse

includeJavaPaths

compile

getOutputPath

generateAndCompile

createJar

classPaths

classPaths

encoding

outputDirectory

outputDirectory

clean

generate

compile

deleteJniFiles

header

copyLibs

copyResources

outputName

configDirectory

configDirectory

jarPrefix

properties

properties

propertyFile

propertyFile

property

property

getProperties

getProperty

addProperty

classesOrPackages

buildCommand

workingDirectory

workingDirectory

environmentVariables

compilerOptions

commandExecutor

build

printHelp

main