Source¶

class Consistency¶

Bases: object

INCONSISTENT = 0¶

Inconsistent

Inconsistent sources have no explicit reference set. They cannot produce a cache key, be fetched or staged. They can only be tracked.

RESOLVED = 1¶

Resolved

Resolved sources have a reference and can produce a cache key and be fetched, however they cannot be staged.

CACHED = 2¶

Cached

Cached sources have a reference which is present in the local source cache. Only cached sources can be staged.

exception SourceError(message, *, reason=None)¶

Bases: buildstream._exceptions.BstError

This exception should be raised by Source implementations to report errors to the user.

Parameters:	message (str) – The error message to report to the user reason (str) – An optional machine readable reason string, used for test cases

class Source¶

Bases: buildstream.plugin.Plugin

Base Source class.

All Sources derive from this class, this interface defines how the core will be interacting with Sources.

COMMON_CONFIG_KEYS = ['kind', 'directory']¶

Common source config keys

Source config keys that must not be accessed in configure(), and should be checked for using node_validate().

get_mirror_directory()¶

Fetches the directory where this source should store things

Returns:	The directory belonging to this source
Return type:	(str)

translate_url(url)¶

Translates the given url which may be specified with an alias into a fully qualified url.

Parameters:	url (str) – A url, which may be using an alias
Returns:	The fully qualified url, with aliases resolved
Return type:	str

get_project_directory()¶

Fetch the project base directory

This is useful for sources which need to load resources stored somewhere inside the project.

Returns:	The project base directory
Return type:	str

tempdir()¶

Context manager for working in a temporary directory

Yields:	(str) – A path to a temporary directory

This should be used by source plugins directly instead of the tempfile module. This one will automatically cleanup in case of termination by catching the signal before os._exit(). It will also use the ‘mirror directory’ as expected for a source.

get_consistency()¶

Report whether the source has a resolved reference

Returns:	The source consistency
Return type:	(`Consistency`)

get_ref()¶

Fetch the internal ref, however it is represented

Returns:	The internal source reference
Return type:	(simple object)

Note

The reference is the user provided (or track resolved) value the plugin uses to represent a specific input, like a commit in a VCS or a tarball’s checksum. Usually the reference is a string, but the plugin may choose to represent it with a tuple or such.

set_ref(ref, node)¶

Applies the internal ref, however it is represented

Parameters:	ref (simple object) – The internal source reference to set node (dict) – The same dictionary which was previously passed to `configure()`

See get_ref() for a discussion on the ref parameter.

track()¶

Resolve a new ref from the plugin’s track option

Returns:	A new internal source reference, or None
Return type:	(simple object)

If the backend in question supports resolving references from a symbolic tracking branch or tag, then this should be implemented to perform this task on behalf of build-stream track commands.

This usually requires fetching new content from a remote origin to see if a new ref has appeared for your branch or tag. If the backend store allows one to query for a new ref from a symbolic tracking data without downloading then that is desirable.

See get_ref() for a discussion on the ref parameter.

fetch()¶

Fetch remote sources and mirror them locally, ensuring at least that the specific reference is cached locally.

Raises:	`SourceError`

Implementors should raise SourceError if the there is some network error or if the source reference could not be matched.

stage(directory)¶

Stage the sources to a directory

Parameters:	directory (str) – Path to stage the source
Raises:	`SourceError`

Implementors should assume that directory already exists and stage already cached sources to the passed directory.

Implementors should raise SourceError when encountering some system error.

init_workspace(directory)¶

Initialises a new workspace

Parameters:	directory (str) – Path of the workspace to init
Raises:	`SourceError`

Default implementation is to call stage().

Implementors overriding this method should assume that directory already exists.

Implementors should raise SourceError when encountering some system error.