xpybuild.buildcontext¶

Contains the xpybuild.buildcontext.BuildContext class which targets use to resolve property values and paths during the build process, and the xpybuild.buildcontext.BuildInitializationContext which is can be used for accessing this information while the build files are being parsed.

The most useful methods are:

`BaseContext.getFullPath`(path, defaultDir[, …])	Expands any properties in the specified path, then removes trailing path separators, normalizes it for this platform and then makes it an absolute path if necessary, using the specified default directory.
`BaseContext.getPropertyValue`(name)	Get the value of the specified property or raise a BuildException if it doesn’t exist.
`BaseContext.expandListPropertyValue`(propertyName)	Get the list represented by the specified property or raise a BuildException if it doesn’t exist.
`BaseContext.expandPropertyValues`(string[, …])	Expand all `${PROP_NAME}` properties in the specified string.
`BaseContext.publishArtifact`(displayName, path)	Publishes the specified local path as an artifact, if supported by the configured output format.

BaseContext¶

class xpybuild.buildcontext.BaseContext(initialProperties=None)[source]¶

Bases: object

Common functionality needed during initialization and build phases.

Initializes a BaseContext object.

Parameters: initialProperties – a dictionary of initial property values; used by doc tests.

publishArtifact(displayName, path)[source]¶

Publishes the specified local path as an artifact, if supported by the configured output format.

For example this can be used to publish log and error output if a target fails.

Equivalent to calling utils.consoleformatter.publishArtifact

getPropertyValue(name)[source]¶

Get the value of the specified property or raise a BuildException if it doesn’t exist.

Parameters: name – the property name (without ${...}) to retrieve. Must be a string.
Returns: For Boolean properties this will be a python Boolean, for everything else it will be a string.

>>> BaseContext({'A':'b','BUILD_MODE':'release'}).getPropertyValue('BUILD_MODE')
'release'
>>> BaseContext({'A':False}).getPropertyValue('A')
False
>>> BaseContext({'A':True}).getPropertyValue('A')
True
>>> BaseContext({'A':'b'}).getPropertyValue('UNDEFINED_PROPERTY')
Traceback (most recent call last):
...
xpybuild.utils.buildexceptions.BuildException: Property "UNDEFINED_PROPERTY" is not defined
>>> BaseContext({'A':'b'}).getPropertyValue(None)
Traceback (most recent call last):
...
xpybuild.utils.buildexceptions.BuildException: Property "None" is not defined
>>> BaseContext({'A':'b'}).getPropertyValue('')
Traceback (most recent call last):
...
xpybuild.utils.buildexceptions.BuildException: Property "" is not defined

expandPropertyValues(string, expandList=False)[source]¶

Expand all ${PROP_NAME} properties in the specified string.

Use a double dollar to escape if needed, e.g. $${foo} will end up as ${foo} unescaped. This assumes expandPropertyValues is not called more than once on the same string (it is not idempotent).

Boolean values are expanded to “true” or “false”

Returns the expanded string, or raises BuildException if expansion fails.

Parameters

string – The string with unexpanded properties in ${…} to expand. May alternatively be a Composable object which will be later evaluated using its resolveToString method, or a function that accepts a single argument containing the context.
expandList – return a list not a string and expand exactly one ${VAR[]} to multiple list items.

>>> BaseContext({'A':'b'}).expandPropertyValues(None)
>>> BaseContext({'A':'b'}).expandPropertyValues('')
''
>>> BaseContext({'A':'b','BUILD_MODE':'release'}).expandPropertyValues(' ${BUILD_MODE} x ${BUILD_MODE} ')
' release x release '
>>> BaseContext({'A':'b','BUILD_MODE':'release'}).expandPropertyValues(' ${BUILD_MODE} x ${BUILD_MODE} ', expandList=True)
[' release x release ']
>>> BaseContext({'DIR':'dir', 'NAMES[]':'a, b, c', 'SUFFIX':'.jar'}).expandPropertyValues('${DIR}/${NAMES[]}${SUFFIX}', expandList=True)
['dir/a.jar', 'dir/b.jar', 'dir/c.jar']
>>> BaseContext({'DIR':'dir', 'NAMES[]':'a, ${NAMES2[]}', 'NAMES2[]':'b, c', 'SUFFIX':'.jar'}).expandPropertyValues('${DIR}/${NAMES[]}${SUFFIX}', expandList=True)
['dir/a.jar', 'dir/b.jar', 'dir/c.jar']
>>> BaseContext({'NAMES[]':'a, b, c'}).expandPropertyValues('$${${NAMES[]}}', expandList=True)
['${a}', '${b}', '${c}']
>>> BaseContext({'A':''}).expandPropertyValues('${A}', expandList=True)
[]
>>> BaseContext({'A':'b'}).expandPropertyValues('', expandList=True)
[]
>>> BaseContext({'A':'a','B':'b'}).expandPropertyValues(Compose('${A}', '${B}'))
'ab'
>>> BaseContext({'A':'a'}).expandPropertyValues('x${A}x$${A}x${A}x$$${A}x')
'xax${A}xax$${A}x'
>>> BaseContext({'A':'a','B':'b','C':'c'}).expandPropertyValues(Compose('${A}', '${B}')+'${C}')
'abc'
>>> BaseContext({'A':'b'}).expandPropertyValues('${UNDEFINED_PROPERTY}')
Traceback (most recent call last):
...
xpybuild.utils.buildexceptions.BuildException: Property "UNDEFINED_PROPERTY" is not defined
>>> BaseContext({'A':'b'}).expandPropertyValues('${A')
Traceback (most recent call last):
...
xpybuild.utils.buildexceptions.BuildException: Incorrectly formatted property string "${A"
>>> BaseContext({'A[]':'a, b'}).expandPropertyValues('${A[]}${A[]}', expandList=True)
Traceback (most recent call last):
...
xpybuild.utils.buildexceptions.BuildException: Cannot expand as a list a string containing multiple list variables

expandListPropertyValue(propertyName)[source]¶

Get the list represented by the specified property or raise a BuildException if it doesn’t exist.

Parameters: propertyName – the property name (without ${...}) to retrieve. Must be a string and end with “[]”.

getProperties()[source]¶

Return a new copy of the properties dictionary (values may be of any type).

Do not use this method unless really necessary (e.g. for keyword substitution) - in almost all cases it is better to simply specify the required properties explicitly to getPropertyValue or expandPropertyValues.

>>> BaseContext({'A':'b'}).getProperties()
{'A': 'b'}

mergeOptions(target=None, options=None)[source]¶

Deprecated: Instead, use the target’s xpybuild.basetarget.BaseTarget.options to get the resolved dictionary of options instead of this method, or getGlobalOption for PathSets and functors where there is no target available.

Merges together the default options, the globally overridden options and any set on the target.

This is usually called from within a target run() method. Any options provided on the target will take priority, followed by anything overridden globally, finally anything left is taken from the option defaults.

Parameters

target – the target from which to take option values overriding the global defaults.
options – options to override directly - this is retained for backwards compatibility only and should not be used.

Returns

Returns a map of the merged options and their correct values.

getGlobalOption(key)[source]¶

Get the value of the specified global option for this build.

This can be useful for PathSets and functors, however in any situation where there is a target, use xpybuild.basetarget.BaseTarget.options instead, so that per-target option overrides are respected.

getFullPath(path, defaultDir, expandList=False)[source]¶

Expands any properties in the specified path, then removes trailing path separators, normalizes it for this platform and then makes it an absolute path if necessary, using the specified default directory.

Parameters

path – a string representing a relative or absolute path. May be a string or a Composable
defaultDir – the default parent directory to use if this is a relative path; it is invalid to pass None for this parameter. It is permitted to pass a BuildFileLocation for the defaultDir instead of a string, in which case an exception will be thrown if it is an empty location object and the path is relative; this is primarily used for objects like PathSets that capture location when they are instantiated.
expandList – passed to expandPropertyValues, returns a list of paths instead of a single path.

>>> BaseContext({'DEF':'output', 'EL':'element'}).getFullPath('path/${EL}', '${DEF}').replace('\\','/')
'output/path/element'
>>> BaseContext({'DEF':'output', 'EL':'element'}).getFullPath('/path/${EL}', '${DEF}').replace('\\','/')
'/path/element'
>>> BaseContext({'DEF':'output/', 'EL':'element'}).getFullPath('path/${EL}', '${DEF}').replace('\\','/')
'output/path/element'
>>> BaseContext({'DEF':'output/', 'EL':'element'}).getFullPath('path/../path/${EL}', '${DEF}').replace('\\','/')
'output/path/element'

BuildInitializationContext¶

class xpybuild.buildcontext.BuildInitializationContext(propertyOverrides)[source]¶

Bases: xpybuild.buildcontext.BaseContext

Provides context used only during the initialization phase of the build.

Once initialization is complete, this object can no longer be used.

Wherever possible, delay resolution of properties to the build phase instead of performing operations with this class, which results in cleaner build scripts and avoids the problem of trying to use a property before it has been defined.

If you do need an instance of this class, use BuildInitializationContext.getBuildInitializationContext.

Creates a new BuildInitializationContext object.

Should only be called from within xpybuild, not from build files.

Parameters: propertyOverrides – property override values specified by the user on the command line; all values must be of type string.

static getBuildInitializationContext()[source]¶

Returns the singleton BuildInitializationContext instance during parsing of build files, which is occasionally necessary for looking up properties etc.

Wherever possible, delay resolution of properties to the build phase instead of performing operations with this class, which results in cleaner build scripts and avoids the problem of trying to use a property before it has been defined.

It is an error to call this method after parsing of build files has completed, since a BuildContext is used for that phase of the build instead.

isRealBuild() → bool[source]¶

Returns True if a real build is going to take place, or False if the build files are just being parsed in order to list available targets/properties.

This exists for the very special case of preventing expensive initialization-phase operations if they’re not really going to be needed.

getTargetsWithTag(tag)[source]¶: Returns the list of target objects with the specified tag name (throws BuildException if not defined).

tags()[source]¶: Returns the map of tag names to lists of target objects

targets()[source]¶: Return a map of targetName:target

getOutputDirs()[source]¶

Return the list of registered output dirs.

Note that some of these might be nested inside other output dirs.

BuildContext¶

class xpybuild.buildcontext.BuildContext(initializationContext, targetPaths=None)[source]¶

Bases: xpybuild.buildcontext.BaseContext

Provides context used only during the build phase of the build (after initialization is complete), i.e. the ability to expand variables (but not to change their value).

Create a BuildContext from a BuildInitializationContext.

Should not be used directly, will be passed into each target’s run method.

isPathWithinOutputDir(path) → bool[source]¶

Returns True if the specified path is a descendent of any of this build’s output directories.

Parameters: path – A normalized absolute path (must use correct slashes for the platform).

getTargetsWithTag(tag)[source]¶

Returns the list of target objects with the specified tag name.

Throws BuildException if not defined.