Package documentation for skia

The SKPs are stored in Google Storage in the following dirs in CT_GS_BUCKET: /swarming/skps/${page_type}/${skps_chromium_build}/{start_range..end_num}/ The SKPs are downloaded into subdirectories in the dest_dir.

Args: api: RecipeApi instance. page_type: str. The CT page type. Eg: 1k, 10k. slave_num: int. The number of the swarming bot. skps_chromium_build: str. The build the SKPs were captured from. dest_dir: path obj. The directory to download SKPs into. start_range: int. The subdirectory number to start from. num_skps: int. The total number of SKPs to download starting with start_range.

recipe_modules / env

DEPS: recipe_engine/context

class EnvApi(RecipeApi):

recipe_modules / flavor

DEPS: depot_tools/bot_update, recipe_engine/context, recipe_engine/file, recipe_engine/path, recipe_engine/platform, recipe_engine/properties, recipe_engine/python, recipe_engine/raw_io, recipe_engine/step, builder_name_schema, env, run, vars

class SkiaFlavorApi(RecipeApi):

— def cleanup_steps(self):

— def compile(self, target):

— def copy_directory_contents_to_device(self, host_dir, device_dir):

— def copy_directory_contents_to_host(self, device_dir, host_dir):

— def copy_extra_build_products(self, swarming_out_dir):

— def copy_file_to_device(self, host_path, device_path):

— def create_clean_device_dir(self, path):

— def create_clean_host_dir(self, path):

— def device_path_join(self, *args):

— def get_flavor(self, builder_cfg):

Return a flavor utils object specific to the given builder.

— def install(self, skps=False, images=False, svgs=False, resources=False):

— def install_everything(self):

@property
— def out_dir(self):

— def read_file_on_device(self, path, **kwargs):

— def remove_file_on_device(self, path):

— def setup(self):

— def step(self, name, cmd, **kwargs):

recipe_modules / git

DEPS: recipe_engine/path, env

class GitApi(RecipeApi):

— def env(self):

Add Git to PATH

Requires the infra/git and infra/tools/git CIPD packages to be installed in the ‘git’ relative path.

recipe_modules / gsutil

DEPS: recipe_engine/context, recipe_engine/step, run, vars

class GSUtilApi(RecipeApi):

— def cp(self, name, src, dst, extra_args=None):

Attempt to upload or download files to/from Google Cloud Storage (GCS).

Args: name: string. Will be used to fill out the step name. src: string. Absolute path for a local file or gcs file (e.g. gs://...) dst: string. Same as src. extra_args: optional list of args to be passed to gsutil. e.g. [-Z] asks all files be compressed with gzip after upload and before download.

If the operation fails, it will be retried multiple times.

recipe_modules / infra

DEPS: recipe_engine/context, recipe_engine/step, run, vars

class InfraApi(RecipeApi):

@property
— def go_bin(self):

@property
— def go_env(self):

@property
— def go_exe(self):

— def go_version(self):

Print the Go version.

@property
— def gopath(self):

@property
— def goroot(self):

— def update_go_deps(self):

Attempt to update go dependencies.

This fails flakily sometimes, so perform multiple attempts.

recipe_modules / isolate

DEPS: depot_tools/git, depot_tools/gsutil, recipe_engine/context, recipe_engine/file, recipe_engine/json, recipe_engine/path, recipe_engine/properties, recipe_engine/python, recipe_engine/step, recipe_engine/tempfile, swarming_client

class IsolateApi(RecipeApi):

APIs for interacting with isolates.

— def clean_isolated_files(self, build_dir):

Cleans out all *.isolated files from the build directory in preparation for the compile. Needed in order to ensure isolates are rebuilt properly because their dependencies are currently not completely described to gyp.

— def find_isolated_tests(self, build_dir, targets=None, **kwargs):

Returns a step which finds all *.isolated files in a build directory.

Useful only with ‘archive’ isolation mode. In ‘prepare’ mode use ‘isolate_tests’ instead.

Assigns the dict {target name -> *.isolated file hash} to the swarm_hashes build property. This implies this step can currently only be run once per recipe.

If |targets| is None, the step will use all *.isolated files it finds. Otherwise, it will verify that all |targets| are found and will use only them. If some expected targets are missing, will abort the build.

@isolate_server.setter
— def isolate_server(self, value):

Changes URL of Isolate server to use.

— def isolate_tests(self, build_dir, targets=None, verbose=False, set_swarm_hashes=True, always_use_exparchive=False, **kwargs):

Archives prepared tests in |build_dir| to isolate server.

src/tools/isolate_driver.py is invoked by ninja during compilation to produce *.isolated.gen.json files that describe how to archive tests.

This step then uses *.isolated.gen.json files to actually performs the archival. By archiving all tests at once it is able to reduce the total amount of work. Tests share many common files, and such files are processed only once.

Assigns the dict {target name -> *.isolated file hash} to the swarm_hashes build property (also accessible as ‘isolated_tests’ property). This implies this step can currently only be run once per recipe.

@property
— def isolated_tests(self):

The dictionary of ‘target name -> isolated hash’ for this run.

These come either from the incoming swarm_hashes build property, or from calling find_isolated_tests, above, at some point during the run.

— def run_isolated(self, name, isolate_hash, args=None, **kwargs):

Runs an isolated test.

recipe_modules / run

DEPS: recipe_engine/file, recipe_engine/json, recipe_engine/path, recipe_engine/platform, recipe_engine/python, recipe_engine/step, env, vars

class SkiaStepApi(RecipeApi):

— def __call__(self, steptype, name, abort_on_failure=True, fail_build_on_failure=True, **kwargs):

Run a step. If it fails, keep going but mark the build status failed.

— def __init__(self, *args, **kwargs):

Initialize the recipe module.

— def check_failure(self):

Raise an exception if any step failed.

— def copy_build_products(self, src, dst):

Copy whitelisted build products from src to dst.

@property
— def failed_steps(self):

— def readfile(self, filename, *args, **kwargs):

Convenience function for reading files.

— def rmtree(self, path):

Wrapper around api.file.rmtree.

— def run_once(self, fn, *args, **kwargs):

— def with_retry(self, steptype, name, attempts, between_attempts_fn=None, abort_on_failure=True, fail_build_on_failure=True, **kwargs):

— def writefile(self, filename, contents):

Convenience function for writing files.

recipe_modules / skia_swarming

DEPS: depot_tools/depot_tools, recipe_engine/context, recipe_engine/file, recipe_engine/json, recipe_engine/path, recipe_engine/properties, recipe_engine/python, recipe_engine/raw_io, recipe_engine/step, isolate, run, swarming, swarming_client

class SkiaSwarmingApi(RecipeApi):

Provides steps to run Skia tasks on swarming bots.

— def batcharchive(self, targets):

Calls batcharchive on the skia.isolated.gen.json file.

Args: targets: list of str. The suffixes of the isolated.gen.json files to archive.

Returns: list of tuples containing (task_name, swarming_hash).

— def collect_swarming_task(self, swarming_task):

Collects the specified swarming task.

Args: swarming_task: An instance of swarming.SwarmingTask.

— def create_isolated_gen_json(self, isolate_path, base_dir, os_type, task_name, extra_variables, blacklist=None):

Creates an isolated.gen.json file (used by the isolate recipe module).

Args: isolate_path: path obj. Path to the isolate file. base_dir: path obj. Dir that is the base of all paths in the isolate file. os_type: str. The OS type to use when archiving the isolate file. Eg: linux. task_name: str. The isolated.gen.json file will be suffixed by this str. extra_variables: dict of str to str. The extra vars to pass to isolate. Eg: {‘SLAVE_NUM’: ‘1’, ‘MASTER’: ‘ChromiumPerfFYI’} blacklist: list of regular expressions indicating which files/directories not to archive.

— def isolated_file_path(self, task_name):

Get the path to the given task's .isolated file.

— def setup(self, luci_go_dir, swarming_rev=None):

Performs setup steps for swarming.

— def setup_go_isolate(self, luci_go_dir):

Generates and puts in place the isolate Go binary.

@property
— def swarming_temp_dir(self):

Path where artifacts like isolate file and json output will be stored.

@property
— def tasks_output_dir(self):

Directory where the outputs of the swarming tasks will be stored.

— def trigger_swarming_tasks(self, swarm_hashes, dimensions, idempotent=False, store_output=True, extra_args=None, expiration=None, hard_timeout=None, io_timeout=None, cipd_packages=None):

Triggers swarming tasks using swarm hashes.

Args: swarm_hashes: list of str. List of swarm hashes from the isolate server. dimensions: dict of str to str. The dimensions to run the task on. Eg: {‘os’: ‘Ubuntu’, ‘gpu’: ‘10de’, ‘pool’: ‘Skia’} idempotent: bool. Whether or not to de-duplicate tasks. store_output: bool. Whether task output should be stored. extra_args: list of str. Extra arguments to pass to the task. expiration: int. Task will expire if not picked up within this time. DEFAULT_TASK_EXPIRATION is used if this argument is None. hard_timeout: int. Task will timeout if not completed within this time. DEFAULT_TASK_TIMEOUT is used if this argument is None. io_timeout: int. Task will timeout if there is no output within this time. DEFAULT_IO_TIMEOUT is used if this argument is None. cipd_packages: CIPD packages which these tasks depend on.

Returns: List of swarming.SwarmingTask instances.

recipe_modules / swarming

DEPS: recipe_engine/context, recipe_engine/json, recipe_engine/path, recipe_engine/platform, recipe_engine/properties, recipe_engine/python, recipe_engine/raw_io, recipe_engine/step, isolate, swarming_client

class SwarmingApi(RecipeApi):

Recipe module to use swarming.py tool to run tasks on Swarming.

General usage:

Tweak default task parameters applied to all swarming tasks (such as default_dimensions and default_priority).
Isolate some test using ‘isolate’ recipe module. Get isolated hash as a result of that process.
Create a task configuration using ‘task(...)’ method, providing isolated hash obtained previously.
Tweak the task parameters. This step is optional.
Launch the task on swarming by calling ‘trigger_task(...)’.
Continue doing useful work locally while the task is running concurrently on swarming.
Wait for task to finish and collect its result (exit code, logs) by calling ‘collect_task(...)’.

See also example.py for concrete code.

— def add_default_tag(self, tag):

Adds a tag to the Swarming tasks triggered.

Tags are used for maintenance, they can be used to calculate the number of tasks run for a day to calculate the cost of a type of type (CQ, ASAN, etc).

Tags can be added per individual task.

— def check_client_version(self, step_test_data=None):

Yields steps to verify compatibility with swarming_client version.

— def collect(self, tasks, **kwargs):

Batch version of ‘collect_task’.

Deprecated, to be removed soon. Use ‘collect_task’ in a loop instead, properly handling exceptions. This method doesn't handle collect failures well (it aborts on a first failure).

— def collect_task(self, task, **kwargs):

Waits for a single triggered task to finish.

If the task is sharded, will wait for all shards to finish. Behaves as a regular recipe step: returns StepData with step results on success or raises StepFailure if task fails.

Args: task: SwarmingTask instance, previously triggered with ‘trigger’ method. kwargs: passed to recipe step constructor as-is.

@property
— def default_dimensions(self):

Returns a copy of the default Swarming dimensions to run task on.

The dimensions are what is used to filter which bots are able to run the task successfully. This is particularly useful to discern between OS versions, type of CPU, GPU card or VM, or preallocated pool.

Example: {‘cpu’: ‘x86-64’, ‘os’: ‘Windows-XP-SP3’}

This value can be changed per individual task.

@property
— def default_env(self):

Returns a copy of the default environment variable to run tasks with.

By default the environment variable is not modified. Additional environment variables can be specified for each task.

This value can be changed per individual task.

@default_expiration.setter
— def default_expiration(self, value):

@default_hard_timeout.setter
— def default_hard_timeout(self, value):

@default_idempotent.setter
— def default_idempotent(self, value):

@default_io_timeout.setter
— def default_io_timeout(self, value):

@default_priority.setter
— def default_priority(self, value):

@default_user.setter
— def default_user(self, value):

— def get_collect_cmd_args(self, task):

SwarmingTask -> argument list for ‘swarming.py’ command.

— def get_step_name(self, prefix, task):

SwarmingTask -> name of a step of a waterfall.

Will take a task title (+ step name prefix) and append OS dimension to it.

Args: prefix: prefix to append to task title, like ‘trigger’. task: SwarmingTask instance.

Returns: ‘[] on ’

@staticmethod
— def prefered_os_dimension(platform):

Given a platform name returns the prefered Swarming OS dimension.

Platform name is usually provided by ‘platform’ recipe module, it's one of ‘win’, ‘linux’, ‘mac’. This function returns more concrete Swarming OS dimension that represent this platform on Swarming by default.

Recipes are free to use other OS dimension if there's a need for it. For example WinXP try bot recipe may explicitly specify ‘Windows-XP-SP3’ dimension.

— def set_default_dimension(self, key, value):

— def set_default_env(self, key, value):

@show_isolated_out_in_collect_step.setter
— def show_isolated_out_in_collect_step(self, value):

@show_shards_in_collect_step.setter
— def show_shards_in_collect_step(self, value):

@returns_placeholder
— def summary(self):

@swarming_server.setter
— def swarming_server(self, value):

Changes URL of Swarming server to use.

— def task(self, title, isolated_hash, ignore_task_failure=False, shards=1, task_output_dir=None, extra_args=None, idempotent=None, cipd_packages=None, build_properties=None, merge=None):

Returns a new SwarmingTask instance to run an isolated executable on Swarming.

For google test executables, use gtest_task() instead.

At the time of this writting, this code is used by V8, Skia and iOS.

The return value can be customized if necessary (see SwarmingTask class below). Pass it to ‘trigger_task’ to launch it on swarming. Later pass the same instance to ‘collect_task’ to wait for the task to finish and fetch its results.

Args: title: name of the test, used as part of a task ID. isolated_hash: hash of isolated test on isolate server, the test should be already isolated there, see ‘isolate’ recipe module. ignore_task_failure: whether to ignore the test failure of swarming tasks. By default, this is set to False. shards: if defined, the number of shards to use for the task. By default this value is either 1 or based on the title. task_output_dir: if defined, the directory where task results are placed. The caller is responsible for removing this folder when finished. extra_args: list of command line arguments to pass to isolated tasks. idempotent: whether this task is considered idempotent. Defaults to self.default_idempotent if not specified. cipd_packages: list of 3-tuples corresponding to CIPD packages needed for the task: (‘path’, ‘package_name’, ‘version’), defined as follows: path: Path relative to the Swarming root dir in which to install the package. package_name: Name of the package to install, eg. “infra/tools/authutil/${platform}” version: Version of the package, either a package instance ID, ref, or tag key/value pair. build_properties: An optional dict containing various build properties. These are typically but not necessarily the properties emitted by bot_update. merge: An optional dict containing: “script”: path to a script to call to post process and merge the collected outputs from the tasks. The script should take one named (but required) parameter, ‘-o’ (for output), that represents the path that the merged results should be written to, and accept N additional paths to result files to merge. The merged results should be in the JSON Results File Format (https://www.chromium.org/developers/the-json-test-results-format) and may optionally contain a top level “links” field that may contain a dict mapping link text to URLs, for a set of links that will be included in the buildbot output. “args”: an optional list of additional arguments to pass to the above script.

— def trigger(self, tasks, **kwargs):

Batch version of ‘trigger_task’.

Deprecated, to be removed soon. Use ‘trigger_task’ in a loop instead, properly handling exceptions. This method doesn't handle trigger failures well (it aborts on a first failure).

— def trigger_task(self, task, **kwargs):

Triggers one task.

It the task is sharded, will trigger all shards. This steps justs posts the task and immediately returns. Use ‘collect_task’ to wait for a task to finish and grab its result.

Behaves as a regular recipe step: returns StepData with step results on success or raises StepFailure if step fails.

Args: task: SwarmingTask instance. kwargs: passed to recipe step constructor as-is.

@verbose.setter
— def verbose(self, value):

Enables or disables verbose output in swarming scripts.

recipe_modules / swarming_client

DEPS: depot_tools/git, recipe_engine/path, recipe_engine/properties, recipe_engine/python, recipe_engine/raw_io, recipe_engine/step

class SwarmingClientApi(RecipeApi):

Code that both isolate and swarming recipe modules depend on.

Both swarming and isolate scripts live in a single repository called ‘swarming client’. This module include common functionality like finding existing swarming client checkout, fetching a new one, getting version of a swarming script, etc.

— def checkout(self, revision=None, curl_trace_file=None, can_fail_build=True):

Returns a step to checkout swarming client into a separate directory.

Ordinarily swarming client is checked out via Chromium DEPS into src/tools/swarming_client. This step configures recipe module to use a separate checkout.

If |revision| is None, this requires the build property ‘parent_got_swarming_client_revision’ to be present, and raises an exception otherwise. Fail-fast behavior is used because if machines silently fell back to checking out the entire workspace, that would cause dramatic increases in cycle time if a misconfiguration were made and it were no longer possible for the bot to check out swarming_client separately.

— def ensure_script_version(self, script, min_version, step_test_data=None):

Yields steps to ensure a script version is not older than |min_version|.

Will abort recipe execution if it is.

— def get_script_version(self, script):

Returns a version of some swarming script as a tuple (Major, Minor, Rev).

It should have been queried by ‘query_script_version’ step before. Raises AssertionError if it wasn't.

@property
— def path(self):

Returns path to a swarming client checkout.

It's subdirectory of Chromium src/ checkout or a separate directory if ‘checkout_swarming_client’ step was used.

— def query_script_version(self, script, step_test_data=None):

Yields a step to query a swarming script for its version.

Version tuple is later accessible via ‘get_script_version’ method. If |step_test_data| is given, it is a tuple with version to use in expectation tests by default.

Does nothing if script's version is already known.