Package bm

Class Build

java.lang.Object
bm.Build
public class Build extends Object

Supportive wrapper to manage a build. Nothing here is required. This class merely helps to organize named targets, and update them according to a command line interface call. Ultimately Machine.update(Target) is called, which can also be done directly.

Typical Usage in a file called src/buma/Buma.java:

  1. Optionally call initLogging(OutputStream) for a reduced logging format.
  2. Call the Build(String, Path) constructor.
  3. Optionally call addBuildInspectionTargets(), a wrapper for addDependencyTreeTarget() and addTargetlisterTarget() which are nice defaults to get a quick overview about defined targets.
  4. Optionally run parseCmdline(String[]) on your main's argument list to get a list of targets (for later, see below) and a map of parameters key=value that may be used while creating the targets.
  5. Use add(String, Target) or addAlias(String, String, Target) to add targets.
  6. Call updateAll(List) with the list of requested targets returned by parseCmdline.
Nothing of the above is required. One can create a dependency graph of targets and feed the topmost target into Machine.update(Target) without even using this class.

NOTE:It is not necessary to register every target with the add* methods. In particular technical intermediate dependencies that need not be called from the command line need not be registered. By adding them as dependencies to other targets, they are linked into the dependency graph anyway.

  • Field Details

    • machine

      public final Machine machine
      The Machine we work with here.

  • Constructor Details

    • Build

      public Build(String defaultTarget, Path stateStore)
      Creates the wrapper and specifies a default target. Further add(Target) calls must make sure the default target actually exists.
      Parameters:
      defaultTarget - to update if the command does not specify one
      stateStore - path for the file to keep state hashes for targets

    • Build

      public Build(String defaultTarget, SupplyOrThrow<StateStore> stateStoreSupplier)
      Creates the wrapper and specifies a default target. Further add(Target) calls must make sure the default target actually exists.
      Parameters:
      defaultTarget - to update if the command does not specify one
      stateStoreSupplier - passed to Machine(SupplyOrThrow)

  • Method Details

    • getMachine

      public Machine getMachine()

    • updateAll

      public void updateAll(List<String> targets) throws BuildProblemException
      To be called with a list if target after after targets have been added. A typical build script may have code like 
       public static void main(String[] argv) {
   Build build = new Build(...);
   Cmdline cmdline = build.parseCmdline(argv);
   List targets = targetsAndProperties(argv);
   ...
   // add targets with build.add() or build.addAlias()
   ...
   build.updateAll(targets);
      Running targetsAndProperties early may be necessary if properties set on the command line are used during setup of the targets.
      Parameters:
      targets - list of targets to be updated
      Throws:
      BuildProblemException - as the need arises

    • targetsAndProperties

      @Deprecated public List<String> targetsAndProperties(String[] argv)
      Deprecated.
      Rather use parseCmdline(java.lang.String[]) to avoid confusion over the priority between system properties set with -Dkey=value as a JVM argument and key=value as a main method argument.
      Two types of command line arguments are handled. If the argument contains a '=', it is split at the '=' into key and value and the pair is entered into the system properties. Otherwise the argument is treated as a target name and returned in the result list. If there are no targets, the default target is added to the result list.

    • parseCmdline

      public Build.Cmdline parseCmdline(String[] argv)
      Two types of command line arguments are handled. If the argument contains a '=', it is split at the '=' into key and value and the pair is entered into the the map returned as part of the result. Otherwise the argument is treated as a target name and returned in the result's list.

      If there are no targets, the default target is added to the result list.

    • getTargets

      public List<Target> getTargets(String... targetNames) throws BuildProblemException
      Provides the Target objects for the given names.
      Parameters:
      targetNames - to look up
      Returns:
      a list of targets found
      Throws:
      BuildProblemException - if a requested name has no target registered

    • addBuildInspectionTargets

      public void addBuildInspectionTargets()
      Shortcut for calling addTargetlisterTarget() and addDependencyTreeTarget().

    • addTargetlisterTarget

      public Target addTargetlisterTarget()
      Adds a target with the name "targetlist" to print the list of targets we know about.

    • addDependencyTreeTarget

      public Target addDependencyTreeTarget()
      Adds a target with the name "dependencytree" to print a dependency tree in graphviz format.

    • add

      public <T extends Target> T add(T target)
      Adds a target without description.
      Type Parameters:
      T - the effective subclass of Target provided
      Parameters:
      target - to add
      Returns:
      the target provided

    • add

      public <T extends Target> T add(String description, T target)
      Adds a target with description.
      Type Parameters:
      T - the effective subclass of Target provided
      Parameters:
      description - shown in output for option -t or by descriptions()
      target - to add
      Returns:
      the target provided

    • addAlias

      public <T extends Target> T addAlias(String name, String description, T target)
      Adds a target under a different name with description.
      Type Parameters:
      T - the effective subclass of Target provided
      Parameters:
      name - to use instead of Target.getName()
      description - shown in output for option -t or by descriptions()
      target - to add
      Returns:
      the target provided

    • addAlias

      public <T extends Target> T addAlias(String name, T target)
      Calls addAlias(String, String, Target) with an empty description.

    • update

      public boolean update(String name) throws BuildProblemException
      Looks up the target name and calls a Machine instance with the target found.
      Parameters:
      name - of the target to update
      Returns:
      true if the target was valid and its update was initiated. If false is returned, an error message describing valid targets was printed already.
      Throws:
      BuildProblemException

    • descriptions

      public List<String> descriptions()

    • printDependencyTree

      public void printDependencyTree()
      Creates a digraph on stdout which can be understood by the dot program from graphviz.

    • topologicallySorted

      public List<Build.SortableTarget> topologicallySorted()

    • initLogging

      public static void initLogging(OutputStream out)
      Initialize logging with a simple plain format. If this method was called already, it is a NO-OP.

      Note: You may set the logging level with the environment variable BUMA_LOGLEVEL, for example as

      export BUMA_LOGLEVEL=FINEST

      in bash.