xpybuild.targets.custom

Contains xpybuild.targets.custom.CustomCommand (and similar classes) for executing an arbitrary command line to produce a file or directory of output.

Custom

class xpybuild.targets.custom.Custom(target, deps, fn, cleanfn=None)[source]

Bases: xpybuild.basetarget.BaseTarget

Deprecated

Use CustomCommand instead, or a dedicated BaseTarget subclass.

A custom target that builds a single file or directory of content by executing an arbitrary python functor.

Functor must take: (target path, [dependency paths], context)

Tip: don’t forget to ensure the target path’s parent dir exists using fileutils.mkdir.

Parameters

  • target – The target file/directory that will be built

  • deps – The list of dependencies of this target (paths, pathsets or lists)

  • fn – The functor used to build this target

  • cleanfn – The functor used to clean this target (optional, defaults to removing the target file/dir)

ResolvePath

class xpybuild.targets.custom.ResolvePath(path)[source]

Bases: object

Deprecated

Use a PathSet (possibly with the joinPaths property functor) instead of this class.

A wrapper around a string in a command line that indicates it is a path an should be resolved (expanded, normalized, possibly made relative to the target dir) when the command is executed.

If the specified path resolves to more than one item then an exception is thrown unless the pathsep argument is specified.

Parameters

path – The path to expand, which is a string.

resolve(context, baseDir)[source]

Resolves the path using the specified context and baseDir

CustomCommand

class xpybuild.targets.custom.CustomCommand(target, command=None, dependencies=[], cwd=None, redirectStdOutToTarget=False, env=None, stdout=None, stderr=None, commands=None)[source]

Bases: xpybuild.basetarget.BaseTarget

A custom target that builds a single file or directory of content by running one or more command line processes.

The command line must not reference any generated paths unless they are explicitly listed in deps.

Supported target options include:

  • .option("process.timeout") to control the maximum number of seconds the command can

    run before being cancelled.

  • .option("common.processOutputEncodingDecider") to determine the encoding

    used for reading stdout/err (see xpybuild.utils.process.defaultProcessOutputEncodingDecider).

  • .option("CustomCommand.outputHandlerFactory") to replace the default behaviour

    for detecting errors (which is just based on zero/non-zero exit code) and logging stdout/err with a custom xpybuild.utils.outputhandler.ProcessOutputHandler. The additional options described on ProcessOutputHandler can also be used with this target.

Parameters

  • target – the file or directory to be built. Will be cleaned, and its parent dir created, before target runs.

  • dependencies – an optional list of dependencies; it is essential that ALL dependencies required by this command and generated by the build processare explicitly listed here, in addition to any files/directories used by this command that might change between builds.

  • command (list[obj]|Callable->list) –

    A list of command line arguments to execute one process.

    (see also the commands parameter which can be used to execute multiple processes).

    Alternatively, the list can be constructed dynamically by passing a function with signature (resolvedTargetDirPath: str, resolvedDepsList: list, context: xpybuild.buildcontext.BuildContext) -> list (where resolvedDepsList is an ordered, flattened list of resolved paths from deps).

    Each argument in the list of arguments may be:

    • a string (which will be run through expandPropertyValues prior to execution);

      must not be used for representing arguments that are paths

    • a PathSet (which must resolve to exactly one path - see joinPaths

      property functor if multiple paths are required). Any PathSets used in the arguments should usually be explicitly listed in dependencies too, especially if they are generated by another part of this build.

    • a property functor such as joinPaths (useful for constructing

      Java classpaths), basename, etc

    • an arbitrary function taking a single context argument

    • CustomCommand.TARGET - a special value that is resolved to the

      output path of this target

    • CustomCommand.DEPENDENCIES - a special value that is resolved to

      a list of this target’s dependencies

    • [deprecated] a ResolvePath(path) object, indicating a path that should be

      resolved and resolved at execution time (this is equivalent to using a PathSet, which is probably a better approach).

    Command lines MUST NOT depend in any way on the current source or output directory, always use a PathSet wrapper around such paths.

  • commands (list[list[obj]]) –

    A list of commands to run to generate this target, each of which is itself

    represented as a list of command line arguments (as described above under command).

    Note that you must specify either command= or commands= but not both.

    Commands listed here are executed in sequence. Unless you have multiple commands that need to write to the same large output directory it is usually better to use separate CustomCommand or CustomCommandWithCopy instances so they can execute in parallel for a faster build.

    This parameter was added in version 4.0.

  • cwd – the working directory to run it from (almost always this should be left blank, meaning use output dir)

  • env – a dictionary of environment overrides, or a function that returns one given a context. Values in the dictionary will be expanded using the same rules as for the command (see above). Consider using xpybuild.propertysupport.joinPaths for environment variables containing a list of paths.

  • redirectStdOutToTarget – usually, any stdout is treated as logging and the command is assumed to create the target file itself, but set this to True for commands where the target file contents are generated by the stdout of the command being executed.

  • stdout – usually a unique name is auto-generated for this target and suffixed with .out, but set this parameter if you need to send output to a specific location. Ignored if the CustomCommand.outputHandlerFactory option is set.

  • stderr – usually a unique name is auto-generated this target and suffixed with .err, but set this parameter if you need to send output to a specific location. Ignored if the CustomCommand.outputHandlerFactory option is set.

TARGET

A special value that can be used in the command argument and is resolved to the output path of this target.

DEPENDENCIES

A special value that can be used in the command argument and is resolved to a list of this target’s dependencies.

CustomCommandWithCopy

class xpybuild.targets.custom.CustomCommandWithCopy(target, command=None, dependencies=[], copySrc=None, cwd=None, redirectStdOutToTarget=False, env=None, commands=None, **kwargs)[source]

Bases: xpybuild.targets.custom.CustomCommand, xpybuild.targets.copy.Copy

A custom target that builds a directory of content by running a specified command line process, but unlike the normal CustomCommand also copies one or more files into the output directory before running the specified command.

For advanced cases only - usually it’s best to find a way to explicitly separate the target input and output and use a normal CustomCommand - but this target exists for badly written tools that are only able to do in-place modifications on a directory.

Parameters

  • target – the target that will be generated by copying and then running the specified commands.

  • command – see CustomCommand for details

  • commands – see CustomCommand for details

  • dependencies – an explicit list of any dependencies other than copySrc) that are required by the command, including static resources and other targets generated by the build. Specifying this accurately is ESSENTIAL for reliable building.