xpybuild.basetarget

Contains xpybuild.basetarget.BaseTarget which contains methods such as basetarget.BaseTarget.option, basetarget.BaseTarget.tags for configuring the target instances in your build files, and is also the base class for defining new targets.

BaseTarget

class xpybuild.basetarget.BaseTarget(name, dependencies)

Bases: xpybuild.utils.functors.Composable

The base class for all targets.

Configuring targets in your build files

The following methods can be used to configure any target instance you add to a build file:

option(key, value)	Called by build file authors to configure this target instance with an override for an option value.
tags(*tags)	Called by build file authors to append one or more tags to this target to make groups of related targets easier to build (or just to provide a shorter alias for the target on the command line).
clearTags()	Called by build file authors to removes all tags other than all from this target.
disableInFullBuild()	Called by build file authors to configure this target to not build in all mode, so that it will only be built if the target name or tag is specified on the command line (or if pulled in by a dependency).
priority(priority)	Called by build file authors to configure the priority of this target to encourage it (and its dependencies) to be built earlier in the process.

Implementing a new target class

If you are subclassing BaseTarget to create a new target class, you must implement run.

In rare occasions you may also wish to override clean. The following methods are available for use by target subclasses, either at construction time (__init__) or at build time (during run or clean):

registerImplicitInputOption(optionKey)	Target classes can call this from their __init__() to add the resolved value of the specified option(s) as ‘implicit inputs’ of this target.
registerImplicitInput(item)	Target classes can call this from their __init__() to add the specified string line(s) as ‘implicit inputs’ of this target.
getOption(key[, errorIfNone, errorIfEmptyString])	Target classes can call this during run or clean to get the resolved value of a specified option for this target, with optional checking to give a friendly error message if the value is an empty string or None.
openFile(context, path[, mode])	Target classes can call this from their run implementation to open a specified file, using an encoding specified by the common.fileEncodingDecider option (unless explicitly provided by encoding=).
targetNameToUniqueId(name)	Convert a target name (containing unexpanded property values) into a convenient unique identifier.

This class provides several read-only attributes for use by subclasses.

Variables

• name (str) – The canonical name for the target (containing unsubstituted properties).

• path (str) – The resolved name with all properties variables expanded. This field is set only once the target is running or checking up-to-dateness but not during initialization phase when targets are initially constructed.

• options (dict) – A dict of the resolved options for this target. Can only be used once target is running or checking up-to-dateness but not during the initialization phase. See also getOption().

• workDir (str) – A unique dedicated directory where this target can write temporary/working files.

Arguments for the BaseTarget __init__ constructor

Parameters

• name – This target instance’s unique name, which is the file or directory path which is created as a result of running this target. The target name may contain ${...} properties (e.g. ${OUTPUT_DIR}/myoutputfile), and must use only forward slashes /. If the target builds a directory it must end with a forward slash.

• dependencies – The dependencies, which may need to be flattened/expanded by the build system; may be any combination of strings, xpybuild.pathsets` and lists, and may also contain unexpanded variables.

BaseTarget methods

run(context: xpybuild.buildcontext.BuildContext)

Called by xpybuild to request to target to run its build (all targets must implement this).

This method is only called when up-to-date checking shows that the target must be built. It’s possible that execution will show that the target did not really need to execute, in which case False should be returned.

clean(context: xpybuild.buildcontext.BuildContext)

Called by xpybuild when the target should be deleted (can be overridden if needed).

The default implementation will simply delete the target, and any target workdir, but can be overridden to delete additional temporary files if needed (shouldn’t be).

registerImplicitInputOption(optionKey)

Target classes can call this from their __init__() to add the resolved value of the specified option(s) as ‘implicit inputs’ of this target.

This list will be written to disk after the target builds successfully, and compared with its recorded value when subsequently checking the up-to-date-ness of the target. This allows xpybuild to detect when the target should be rebuilt as a result of a change in options or property values (e.g. build number, release/debug mode etc), even if no dependencies have changed.

Call this from the target’s constructor, for each option that this target is affected by, or with a callable that dynamically selects from the defined options, e.g. based on a prefix.

Parameters

optionKey –

the name of an option (as a string), or a callable that accepts an optionKey and dynamically decides which options to include, returning True if it should be included. For example:

self.registerImplicitInputOption(lambda optionKey: optionKey.startswith(('java.', 'javac.')))

registerImplicitInput(item)

Target classes can call this from their __init__() to add the specified string line(s) as ‘implicit inputs’ of this target.

This list will be written to disk after the target builds successfully, and compared with its recorded value when subsequently checking the up-to-date-ness of the target. This allows xpybuild to detect when the target should be rebuilt as a result of a change in options or property values (e.g. build number, release/debug mode etc), even if no dependencies have changed.

Call this from the target’s constructor.

Parameters

item –

The item to be added to the implicit inputs.

This can be either:

• a string, which may contain substitution variables, e.g. myparameter="${someprop}", and will converted to a string using buildcontext.BuildContext.expandPropertyValues, or

• a callable to be invoked during up-to-dateness checking, that accepts a context parameter and returns a string or list of strings; any None items in the list are ignored.

getHashableImplicitInputs(context)

(deprecated) Target classes can implement this to add the string line(s) as ‘implicit inputs’ of this target.

Deprecated

The registerImplicitInput or registerImplicitInputOption methods should be called instead of overriding this method.

The default implementation returns nothing, unless registerImplicitInput or registerImplicitInputOption have been called (in which case only the resolved paths of the file/directory dependencies will be used).

disableInFullBuild()

Called by build file authors to configure this target to not build in all mode, so that it will only be built if the target name or tag is specified on the command line (or if pulled in by a dependency).

This is useful for targets that perform operations such as configuring developer IDEs which would not be needed in the main build, or for expensive parts of the build that are often not needed such as generation of installers.

See also tag.

clearTags()

Called by build file authors to removes all tags other than all from this target.

See tag.

getOption(key, errorIfNone=True, errorIfEmptyString=True)

Target classes can call this during run or clean to get the resolved value of a specified option for this target, with optional checking to give a friendly error message if the value is an empty string or None.

This is a high-level alternative to reading directly from self.options.

This method cannot be used while the build files are still being loaded, only during the execution of the targets.

option(key, value)

Called by build file authors to configure this target instance with an override for an option value.

This allows target-specific overriding of options. If no override is provided, the value set in xpybuild.propertysupport.setGlobalOption for the whole build is used, or if that was not set then the default when the option was defined.

Use self.options or getOption to get resolved option values when implementing a target class.

Parameters

• key (str|xpybuild.propertysupport.Option) – The name of a previously-defined option. Usually this is a string literal, but you cna also use the xpybuild.propertysupport.Option instance if you prefer.

• value – The value. If the value is a string and contains any property values these will be expanded before the option value is passed to the target.

openFile(context: xpybuild.buildcontext.BuildContext, path: str, mode='r', **kwargs)

Target classes can call this from their run implementation to open a specified file, using an encoding specified by the common.fileEncodingDecider option (unless explicitly provided by encoding=).

Parameters

• context – The context that was passed to run().

• path – The full absolute path to be opened.

• mode – The file mode.

• kwargs – Any additional arguments for the io.open() method can be specified here.

tags(*tags: str)

Called by build file authors to append one or more tags to this target to make groups of related targets easier to build (or just to provide a shorter alias for the target on the command line).

Parameters

tags – The tag, tags or list of tags to add to the target.

>>> BaseTarget('a',[]).tags('abc').getTags()
<using test initialization context> <using test initialization context> ['abc', 'full']
>>> BaseTarget('a',[]).tags(['abc', 'def']).getTags()
<using test initialization context> <using test initialization context> ['abc', 'def', 'full']
>>> BaseTarget('a',[]).tags('abc', 'def').tags('ghi').getTags()
<using test initialization context> <using test initialization context> <using test initialization context> ['ghi', 'abc', 'def', 'full']

priority(priority: float)

Called by build file authors to configure the priority of this target to encourage it (and its dependencies) to be built earlier in the process.

The default priority is 0.0

Parameters

priority – a float representing the priority. Higher numbers will be built first where possible. Cannot be negative.

static targetNameToUniqueId(name: str) → str

Convert a target name (containing unexpanded property values) into a convenient unique identifier.

The resulting identifier is not an absolute path, and (unless very long) does not contain any directory elements. This id is suitable for temporary filenames and directories etc

class Options

Bases: object

Options for customizing the behaviour of all targets. To set an option on a specific target call xpybuild.basetarget.BaseTarget.option or to se a global default use xpybuild.propertysupport.setGlobalOption.

failureRetries = Option "Target.failureRetries" (default: 0)

The “Target.failureRetries” option can be set on any target (or globally), and specifies how many times to retry the target’s build if it fails. The default is 0, which is recommended for normal developer builds.

There is an exponentially increasing backoff pause between each attempt - first 15s, then 30s, then 60s etc.

See xpybuild.buildcommon.registerBuildLoadPostProcessor which can be used to customize this option for targets based on user-defined criteria such as target type.