Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
543 lines (452 sloc) 22 KB
#!/usr/bin/env python
# -*- coding: utf-8 -*-
# Copyright 2018-2019 releng-tool
# Implementation in this file is considered "API safe". There is a strong
# attempt to prevent the changing of the following classes, methods, etc. to
# prevent compatibility issues as both this tool and extensions (if any) evolve.
class RelengRegistryInterface(object):
"""
interface of the registry passed into an extension's setup stage
This is the public interface of the releng-tool's registry which outlines
methods which can be invoked by an extension during the setup stage. When an
extension defines "def releng_setup(app):" the ``app`` value will be an
instance of this interface (``RelengRegistryInterface``). During the setup
call, an extension may call any of the defined methods using their ``app``
context.
"""
def add_extract_type(self, name, handler):
"""
register extraction support with a given name for this extension
An extension will invoke this method will attempting to support a custom
extraction method for a release engineering process. The extraction
type is identified by the provided ``name`` value. Packages being
processed with VCS type paired with a extension-defined fetch type or a
package extraction override will be processed through the provided
``handler``.
An extension must define a proper ``name`` for the extract-type:
- The name is a string value.
- The name must be prefixed with ``ext-``.
- The name should be all lowercase.
- The dash character ``-`` is the recommended separator.
The ``handler`` must be compatible with the implementation defined in
``RelengExtractExtensionInterface``. There is no requirement that the
handler needs to inherit this interface.
Additional notes:
- The releng-tool process may instantiation one or more of the provided
handler types.
- The first extension loaded with a custom extract-type will take
precedence over other extensions.
Args:
name: the name of this extract type
handler: the extract-type class handler
Raises:
RelengInvalidSetupException: raised when the provided ``name`` or
``handler`` values are not supported by the releng-tool process
"""
pass
def add_fetch_type(self, name, handler):
"""
register fetch support with a given name for this extension
An extension will invoke this method will attempting to support a custom
fetch method for a release engineering process. The fetch type is
identified by the provided ``name`` value. Packages being processed with
a matching VCS type will be processed through the provided ``handler``.
An extension must define a proper ``name`` for the fetch-type:
- The name is a string value.
- The name must be prefixed with ``ext-``.
- The name should be all lowercase.
- The dash character ``-`` is the recommended separator.
The ``handler`` must be compatible with the implementation defined in
``RelengFetchExtensionInterface``. There is no requirement that the
handler needs to inherit this interface.
Additional notes:
- The releng-tool process may instantiation one or more of the provided
handler types.
- The first extension loaded with a custom fetch-type will take
precedence over other extensions.
Args:
name: the name of this fetch type
handler: the fetch-type class handler
Raises:
RelengInvalidSetupException: raised when the provided ``name`` or
``handler`` values are not supported by the releng-tool process
"""
pass
def add_package_type(self, name, handler):
"""
register package support with a given name for this extension
An extension will invoke this method will attempting to support a custom
package methods for a release engineering process. The package type is
identified by the provided ``name`` value. Packages being processed with
a matching type will be processed through the provided ``handler`` for
each package stage (configuration, building, etc.).
An extension must define a proper ``name`` for the package-type:
- The name is a string value.
- The name must be prefixed with ``ext-``.
- The name should be all lowercase.
- The dash character ``-`` is the recommended separator.
The ``handler`` must be compatible with the implementation defined in
``RelengPackageExtensionInterface``. There is no requirement that the
handler needs to inherit this interface.
Additional notes:
- The releng-tool process may instantiation one or more of the provided
handler types.
- The first extension loaded with a custom package-type will take
precedence over other extensions.
Args:
name: the name of this package type
handler: the package-type class handler
Raises:
RelengInvalidSetupException: raised when the provided ``name`` or
``handler`` values are not supported by the releng-tool process
"""
pass
def require_version(self, version):
"""
perform a required-version check
Enables an extension to explicitly check for a required releng-tool
version before being loaded. Invoking this method with a
dotted-separated ``version`` string, the string will be parsed and
compared with the running releng-tool version. If the required version
is met, this method will have no effect. In the event that the required
version is not met, the exception ``RelengVersionNotSupportedException``
will be raised. The extension implementation does not need to explicitly
handle this exception (as it is caught by the registry loading process).
Args:
version: dotted-separated version string
Raises:
RelengVersionNotSupportedException: raised when the required version
for this extension is not met
"""
pass
# ##############################################################################
class RelengPackageOptions(object):
"""
releng package-type options
Provides a series of options from the releng process into a package-type
handler. A handler's ``configure``, ``build``, and ``install`` methods will
be passed options to react on.
Attributes:
def_dir: the directory holder the package definition
env: package's environment variables
ext: extension (pass-through) options
name: the name of the package being processed
version: the version of the package
"""
def __init__(self):
self.def_dir = None
self.env = None
self.ext = {}
self.name = None
self.version = None
class RelengConfigureOptions(RelengPackageOptions):
"""
releng configure-type options
Provides a series of options from the releng process into a configure-type
handler. A handler's ``configuration`` method will be passed options to
react on.
Attributes:
build_dir: directory for a package's buildable content
build_output_dir: build output directory for the package process
conf_defs: command line definitions to apply
conf_env: environment variables to use
conf_opts: command line options to apply
host_dir: directory container for host tools
install_type: installation type (host, staging, target or images)
jobs: number of calculated jobs to allow at a given time
jobsconf: number of jobs to allow at a given time (0: auto)
prefix: prefix for system root (if applicable)
staging_dir: directory container for staged content
symbols_dir: directory container for symbols content
target_dir: directory container for target content
"""
def __init__(self):
super(RelengConfigureOptions, self).__init__()
self.build_dir = None
self.build_output_dir = None
self.conf_defs = None
self.conf_env = None
self.conf_opts = None
self.host_dir = None
self.install_type = None
self.jobs = 1
self.jobsconf = 0
self.prefix = None
self.staging_dir = None
self.symbols_dir = None
self.target_dir = None
class RelengBuildOptions(RelengPackageOptions):
"""
releng build-type options
Provides a series of options from the releng process into a build-type
handler. A handler's ``build`` method will be passed options to react on.
Attributes:
build_defs: command line definitions to apply
build_dir: directory for a package's buildable content
build_env: environment variables to use
build_opts: command line options to apply
build_output_dir: build output directory for the package process
host_dir: directory container for host tools
jobs: number of calculated jobs to allow at a given time
jobsconf: number of jobs to allow at a given time (0: auto)
prefix: prefix for system root (if applicable)
staging_dir: directory container for staged content
symbols_dir: directory container for symbols content
target_dir: directory container for target content
"""
def __init__(self):
super(RelengBuildOptions, self).__init__()
self.build_defs = None
self.build_dir = None
self.build_env = None
self.build_opts = None
self.build_output_dir = None
self.host_dir = None
self.jobs = 1
self.jobsconf = 0
self.prefix = None
self.staging_dir = None
self.symbols_dir = None
self.target_dir = None
class RelengExtractOptions(RelengPackageOptions):
"""
releng extract-type options
Provides a series of options from the releng process into a extract-type
handler. A handler's ``extract`` method will be passed options to react on.
Attributes:
cache_dir: directory to store cached content (if applicable)
cache_file: file to store cached content (if applicable)
revision: revision to use to fetch from source control
strip_count: strip-count for package extraction (if applicable)
work_dir: the working directory
"""
def __init__(self):
super(RelengExtractOptions, self).__init__()
self.cache_dir = None
self.cache_file = None
self.revision = None
self.strip_count = 1
self.work_dir = None
class RelengFetchOptions(RelengPackageOptions):
"""
releng fetch-type options
Provides a series of options from the releng process into a fetch-type
handler. A handler's ``fetch`` method will be passed options to react on.
Attributes:
cache_dir: directory to store cached content (if applicable)
cache_file: file to store cached content (if applicable)
revision: revision to use to fetch from source control
site: the site (uri) to acquire a package's resources
"""
def __init__(self):
super(RelengFetchOptions, self).__init__()
self.cache_dir = None
self.cache_file = None
self.revision = None
self.site = None
class RelengInstallOptions(RelengPackageOptions):
"""
releng install-type options
Provides a series of options from the releng process into a install-type
handler. A handler's ``installation`` method will be passed options to react
on.
Attributes:
build_dir: directory for a package's buildable content
build_output_dir: build output directory for the package process
cache_file: location to cache file (if applicable)
dest_dirs: list of directories to install to
host_dir: directory container for host tools
images_dir: directory container for (final) images
install_defs: command line definitions to apply
install_env: environment variables to use
install_opts: command line options to apply
install_type: installation type
prefix: prefix for system root (if applicable)
staging_dir: directory container for staged content
symbols_dir: directory container for symbols content
target_dir: directory container for target content
"""
def __init__(self):
super(RelengInstallOptions, self).__init__()
self.build_dir = None
self.build_output_dir = None
self.cache_file = None
self.dest_dirs = None
self.host_dir = None
self.images_dir = None
self.install_defs = None
self.install_env = None
self.install_opts = None
self.install_type = None
self.prefix = None
self.staging_dir = None
self.symbols_dir = None
self.target_dir = None
# ##############################################################################
class RelengExtensionInterface(object):
"""
interface to implement a custom fetch-type
Extensions wishing to define a custom fetch type can implement this
interface and register it (see ``add_fetch_type``) during the extension's
setup stage. This will allow an project support custom VCS-types defined in
package definitions (for example "<PKG>_VCS_TYPE='ext-myawesomefetchtype'").
"""
pass
class RelengExtractExtensionInterface(RelengExtensionInterface):
"""
interface to implement a custom fetch-type
Extensions wishing to define a custom fetch type can implement this
interface and register it (see ``add_fetch_type``) during the extension's
setup stage. This will allow an project support custom VCS-types defined in
package definitions (for example "<PKG>_VCS_TYPE='ext-myawesomefetchtype'").
"""
def extract(self, name, opts):
"""
handle a custom extract operation
When a package attempts to be "extracted" and VCS-type is defined to the
custom extraction name, this method will be invoked. Package information
to perform the extraction is provided by the ``opts`` argument. The main
goal of this operation is to populate the provided work or "build"
directory (same as the working directory) based off the package's cache
directory or file (which varies base don the package type). On
completion, this method should return ``True`` to indicate a successful
extraction. If an error occurs, this method should return ``False``. A
failed extraction operation is not required to clean the work directory.
The ``extract`` method may be called multiple times throughout the
lifetime of a releng-tool process (i.e. once per project being
extracted).
Args:
name: the name of this extraction type
opts: the extract options (see ``RelengExtractOptions``)
Returns:
``True`` on successful extraction; otherwise ``False``
"""
return False
class RelengFetchExtensionInterface(RelengExtensionInterface):
"""
interface to implement a custom fetch-type
Extensions wishing to define a custom fetch type can implement this
interface and register it (see ``add_fetch_type``) during the extension's
setup stage. This will allow an project support custom VCS-types defined in
package definitions (for example "<PKG>_VCS_TYPE='ext-myawesomefetchtype'").
"""
def fetch(self, name, opts):
"""
handle a custom fetch operation
When a package attempts to be "fetched" and VCS-type is defined to the
custom fetch name, this method will be invoked. Package information to
perform the fetch on is provided by the ``opts`` argument. The main goal
of this operation is to fetch content from a provided site into either
a cache file or a cache directory. On completion, this method should
return either the cache file or cache directory depending on which has
been populated from the fetch operation. The returned catch value should
match the same value provided in the fetch options: ``opts.cache_file``
if the fetch operation populates a cached file or ``opts.cache_dir`` if
the fetch operation populates a cache directory. If the fetch operation
returns a ``None`, this is an indication that the fetch operation has
failed. A failed fetch operation is not required to clean the work
directory; however, it is the responsibility of the custom fetch type to
manage the state of the ``cache_dir`` (if applicable) and other external
resources it may managed.
The ``fetch`` method may be called multiple times throughout the
lifetime of a releng-tool process (i.e. once per project being fetched).
Args:
name: the name of this fetch type
opts: the fetch options (see ``RelengFetchOptions``)
Returns:
``True`` on successful fetch; otherwise ``False``
"""
return False
class RelengPackageExtensionInterface(RelengExtensionInterface):
"""
interface to implement a custom fetch-type
Extensions wishing to define a custom fetch type can implement this
interface and register it (see ``add_fetch_type``) during the extension's
setup stage. This will allow an project support custom VCS-types defined in
package definitions (for example "<PKG>_VCS_TYPE='ext-myawesomefetchtype'").
"""
def build(self, name, opts):
"""
handle a custom build operation
When a package reaches the building stage and package-type is defined
to the custom package-type name, this method will be invoked. Package
information to perform the build on is provided by the ``opts``
argument. The main goal of this operation is to complete the build stage
of a specific package in the provided work directory (same as the
working directory). On completion, this method should return ``True`` to
indicate a successful build. If an error occurs, this method should
return ``False``. A failed build operation is not required to clean the
work directory; however, the implementation should (attempt) to support
a build request on a package which may have previously failed (i.e.
build options or sources may have been changed to result in a successful
build).
The ``build`` method may be called multiple times throughout the
lifetime of a releng-tool process (i.e. once per project being built).
Args:
name: the name of this package type
opts: the build options (see ``RelengPackageOptions``)
Returns:
``True`` on a successful build; otherwise ``False``
"""
return False
def configure(self, opts):
"""
handle a custom configure operation
When a package reaches the configuration stage and package-type is
defined to the custom package-type name, this method will be invoked.
Package information to perform the configuration on is provided by the
``opts`` argument. The main goal of this operation is to complete the
configuration stage of a specific package in the provided work directory
(same as the working directory). On completion, this method should
return ``True`` to indicate a successful configuration. If an error
occurs, this method should return ``False``. A failed configuration
operation is not required to clean the work directory; however, the
implementation should (attempt) to support a configuration request on a
package which may have previously failed (i.e. configuration options or
sources may have been changed to result in a successful configuration).
The ``configure`` method may be called multiple times throughout the
lifetime of a releng-tool process (i.e. once per project being
configured).
Args:
name: the name of this package type
opts: the configuration options (see ``RelengPackageOptions``)
Returns:
``True`` on a successful configuration; otherwise ``False``
"""
return False
def install(self, name, opts):
"""
handle a custom install operation
When a package reaches the installation stage and package-type is
defined to the custom package-type name, this method will be invoked.
Package information to perform the installation on is provided by the
``opts`` argument. The main goal of this operation is to complete the
install stage of a specific package in the provided work directory
(same as the working directory). On completion, this method should
return ``True`` to indicate a successful installation. If an error
occurs, this method should return ``False``. A failed install operation
is not required to clean the work directory; however, the implementation
should (attempt) to support an install request on a package which may
have previously failed (i.e. install options or sources may have been
changed to result in a successful installation).
The ``install`` method may be called multiple times throughout the
lifetime of a releng-tool process (i.e. once per project being
installed).
Args:
name: the name of this package type
opts: the install options (see ``RelengPackageOptions``)
Returns:
`True`` on a successful installation; otherwise ``False``
"""
return False
# ##############################################################################
class RelengInvalidSetupException(Exception):
"""
exception raised when a loading extension has a setup issue
"""
pass
class RelengVersionNotSupportedException(Exception):
"""
exception raised when an extension does not support the releng-tool version
"""
pass
You can’t perform that action at this time.