Package org.bytedeco.javacpp.tools

Class Builder

  • public class Builder
extends java.lang.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 Summary

      Fields 
      Modifier and Type Field Description
      (package private) java.lang.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) java.util.Collection<java.lang.String> compilerOptions
      Contains additional command line options from the user for the native compiler.
      (package private) java.io.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) java.lang.String encoding
      The name of the character encoding used for input files as well as output files.
      (package private) java.util.Map<java.lang.String,​java.lang.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) java.lang.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) java.io.File outputDirectory
      The directory where the generated files and compiled shared libraries get written to.
      (package private) java.lang.String outputName
      The name of the output generated source file or shared library.
      (package private) java.util.Properties properties
      Accumulates the various properties loaded from resources, files, command line options, etc.
      (package private) java.io.File workingDirectory
      User specified working directory to execute build subprocesses under.

    • Constructor Summary

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

    • Field Detail

      • logger

        final Logger logger
        Logger where to send debug, info, warning, and error messages.

      • encoding

        java.lang.String encoding
        The name of the character encoding used for input files as well as output files.

      • outputDirectory

        java.io.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

        java.lang.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

        java.io.File configDirectory
        The name of the directory where to output config files for GraalVM native-image, if not null.

      • jarPrefix

        java.lang.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

        java.util.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

        java.lang.String[] buildCommand
        A system command for ProcessBuilder to execute for the build, instead of JavaCPP itself.

      • workingDirectory

        java.io.File workingDirectory
        User specified working directory to execute build subprocesses under.

      • environmentVariables

        java.util.Map<java.lang.String,​java.lang.String> environmentVariables
        User specified environment variables to pass to the native compiler.

      • compilerOptions

        java.util.Collection<java.lang.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 java.io.IOException
        Deletes outputDirectory if clean is true.
        Throws:
        java.io.IOException

      • parse

        java.io.File[] parse​(java.lang.String[] classPath,
                     java.lang.Class cls)
              throws java.io.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:
        java.io.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​(java.lang.String[] sourceFilenames,
            java.lang.String outputFilename,
            ClassProperties properties,
            java.io.File workingDirectory)
     throws java.io.IOException,
            java.lang.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:
        java.io.IOException
        java.lang.InterruptedException

      • getOutputPath

        java.io.File getOutputPath​(java.lang.Class[] classes,
                           java.lang.String[] sourcePrefixes)
                    throws java.io.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:
        java.io.IOException

      • generateAndCompile

        java.io.File[] generateAndCompile​(java.lang.Class[] classes,
                                  java.lang.String outputName,
                                  boolean first,
                                  boolean last)
                           throws java.io.IOException,
                                  java.lang.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:
        java.io.IOException
        java.lang.InterruptedException

      • createJar

        void createJar​(java.io.File jarFile,
               java.lang.String[] classPath,
               java.io.File... files)
        throws java.io.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:
        java.io.IOException

      • classPaths

        public Builder classPaths​(java.lang.String classPaths)
        Splits argument with File.pathSeparator and appends result to paths of the classScanner.

      • classPaths

        public Builder classPaths​(java.lang.String... classPaths)
        Appends argument to the paths of the classScanner.

      • encoding

        public Builder encoding​(java.lang.String encoding)
        Sets the encoding field to the argument.

      • outputDirectory

        public Builder outputDirectory​(java.lang.String outputDirectory)
        Sets the outputDirectory field to the argument.

      • outputDirectory

        public Builder outputDirectory​(java.io.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​(java.lang.String outputName)
        Sets the outputName field to the argument.

      • configDirectory

        public Builder configDirectory​(java.lang.String configDirectory)
        Sets the configDirectory field to the argument.

      • configDirectory

        public Builder configDirectory​(java.io.File configDirectory)
        Sets the configDirectory field to the argument.

      • jarPrefix

        public Builder jarPrefix​(java.lang.String jarPrefix)
        Sets the jarPrefix field to the argument.

      • properties

        public Builder properties​(java.lang.String platform)
        Sets the properties field to the ones loaded from resources for the specified platform.

      • properties

        public Builder properties​(java.util.Properties properties)
        Adds all the properties of the argument to the properties field.

      • propertyFile

        public Builder propertyFile​(java.lang.String filename)
                     throws java.io.IOException
        Sets the properties field to the ones loaded from the specified file.
        Throws:
        java.io.IOException

      • propertyFile

        public Builder propertyFile​(java.io.File propertyFile)
                     throws java.io.IOException
        Sets the properties field to the ones loaded from the specified file.
        Throws:
        java.io.IOException

      • property

        public Builder property​(java.lang.String keyValue)
        Sets a property of the properties field, in either "key=value" or "key:value" format.

      • property

        public Builder property​(java.lang.String key,
                        java.lang.String value)
        Sets a key/value pair property of the properties field.

      • getProperties

        public java.util.Properties getProperties()
        Returns properties.

      • getProperty

        public java.lang.String getProperty​(java.lang.String key)
        Returns properties.getProperty(key).

      • addProperty

        public Builder addProperty​(java.lang.String key,
                           java.lang.String... values)
        Adds values to a given property key, seperating them with "platform.path.separator".

      • classesOrPackages

        public Builder classesOrPackages​(java.lang.String... classesOrPackages)
                          throws java.io.IOException,
                                 java.lang.ClassNotFoundException,
                                 java.lang.NoClassDefFoundError
        Requests the classScanner to add a class or all classes from a package. A null argument indicates the unnamed package.
        Throws:
        java.io.IOException
        java.lang.ClassNotFoundException
        java.lang.NoClassDefFoundError

      • buildCommand

        public Builder buildCommand​(java.lang.String[] buildCommand)
        Sets the buildCommand field to the argument.

      • workingDirectory

        public Builder workingDirectory​(java.lang.String workingDirectory)
        Sets the workingDirectory field to the argument.

      • workingDirectory

        public Builder workingDirectory​(java.io.File workingDirectory)
        Sets the workingDirectory field to the argument.

      • environmentVariables

        public Builder environmentVariables​(java.util.Map<java.lang.String,​java.lang.String> environmentVariables)
        Sets the environmentVariables field to the argument.

      • compilerOptions

        public Builder compilerOptions​(java.lang.String... options)
        Appends arguments to the compilerOptions field.

      • build

        public java.io.File[] build()
                     throws java.io.IOException,
                            java.lang.InterruptedException,
                            ParserException
        Starts the build process and returns an array of File produced.
        Returns:
        the array of File produced
        Throws:
        java.io.IOException
        java.lang.InterruptedException
        ParserException

      • printHelp

        public static void printHelp()
        Simply prints out to the display the command line usage.

      • main

        public static void main​(java.lang.String[] args)
                 throws java.lang.Exception
        The terminal shell interface to the Builder.
        Parameters:
        args - an array of arguments as described by printHelp()
        Throws:
        java.lang.Exception