xpybuild.buildcommon

Contains standard functionality for use in build files such as xpybuild.buildcommon.include, useful constants such as xpybuild.buildcommon.IS_WINDOWS and functionality for adding prefixes/suffixes to paths such as xpybuild.buildcommon.FilenameStringFormatter.

XPYBUILD_VERSION

xpybuild.buildcommon.XPYBUILD_VERSION: str = '4.0'

The current xpybuild version.

IS_WINDOWS

xpybuild.buildcommon.IS_WINDOWS: bool = False

A boolean that specifies whether this is Windows or some other operating system.

PREFERRED_ENCODING

xpybuild.buildcommon.PREFERRED_ENCODING = 'UTF-8'

The operating system’s preferred/default encoding for reading/writing the contents of text data in files and process stdout/stderr for the current environment (or machine).

This returns the same value as Python’s locale.getpreferredencoding() method, but as that method is not thread-safe, this constant must always be used in builds to avoid race conditions when running in parallel.

The OS preferred encoding should not be confused with Python’s ‘default’ encoding (sys.getdefaultencoding()) which is usually not relevant in a build.

New in version 4.0.

isDirPath

xpybuild.buildcommon.isDirPath = <function isDirPath>

Returns true if the path is a directory (ends with a slash, / or \\).

StringFormatter

class xpybuild.buildcommon.StringFormatter(formatstring)

Bases: object

A simple named functor for applying a %s-style string format, useful in situations where a function is needed to add a suffix/prefix for the value of an option.

FilenameStringFormatter

class xpybuild.buildcommon.FilenameStringFormatter(formatstring)

Bases: object

A simple named functor for applying a %s-style string format. Formatter is just applied to the basename part of the filename, the dirname part is preserved as-is.

include

xpybuild.buildcommon.include(file)

Parse and register the targets and properties in in the specified XXX.xpybuild.py file.

Targets should only be defined in files included using this method, not using python import statements.

Parameters

file – a path relative to the directory containing this file.

isWindows

xpybuild.buildcommon.isWindows()

Returns True if this is a windows platform.

Deprecated

Use the IS_WINDOWS constant instead.

defineAtomicTargetGroup

xpybuild.buildcommon.defineAtomicTargetGroup(*targets)

The given targets must all be built before anything which depends on any of those targets.

Returns the flattened list of targets.

requireXpybuildVersion

xpybuild.buildcommon.requireXpybuildVersion(version: str)

Checks that this xpybuild is at least a certain version number.

registerBuildLoadPostProcessor

xpybuild.buildcommon.registerBuildLoadPostProcessor(fn)

Add a callback function that will be invoked just after the build files have been parsed and all targets added, to allow for custom post processing logic to execute before the clean/build.

This is useful for performing global customizations of targets throughout the build, such as adding tags or additional target options. For example, to override the default retry setting and add a tag to all defined targets of a particular Python class:

def demoPostProcessor(context):
        for target in context.targets().values():
                if isinstance(target, MyCustomTarget) or 'FooBar' in target.name: 
                        # Override options for these targets
                        target.option(BaseTarget.Options.failureRetries, 2)

                        # Add additional tags for these targets
                        target.tags('my-post-processed-tag')

registerBuildLoadPostProcessor(demoPostProcessor)

Parameters

fn (Callable[xpybuild.buildcontext.BuildInitializationContext]) – A function that takes a context as its argument. You may wish to use BuildInitializationContext methods such as xpybuild.buildcontext.BuildInitializationContext.targets from your function.

registerPreBuildCheck

xpybuild.buildcommon.registerPreBuildCheck(fn)

Defines a check which will be called after any clean but before any build actions take place, to provide fail-fast behaviour if something is wrong.

See also registerBuildLoadPostProcessor.

Parameters

fn (Callable[xpybuild.buildcontext.BuildInitializationContext]) – A function that takes a context as its argument, and raises a BuildException if the check fails.

enableLegacyXpybuildModuleNames

xpybuild.buildcommon.enableLegacyXpybuildModuleNames()

Adds aliases for pre-3.0 module names e.g. buildcommon instead of xpybuild.buildcommon, etc.

The old names are deprecated, so this should be used only as a temporary measure.