Class Builder

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().

  • Field Details

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

    • 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 Details

    • 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 Details

    • 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