Design and Architecture
Q. What does mozharness do? What problems does it solve for me?
A. "Mozharness is a configuration-driven python script harness with full logging that allows production infrastructure and individual developers to use the same scripts."
- designed to be able to run in multiple environments/platforms/configurations
- Since mozharness allows for complex configuration, scripts don't need to hardcode as much behavior, and running a script on a different-but-similar system has a better chance of running (with a new configuration file).
- designed to be easier to debug or replicate problems
The logs are often comprehensive enough to debug problems without running.When they're not enough, mozharness is designed to be able to run scripts standalone, without a full buildbot setup.
- designed to be able to iterate over small sections of code more easily
When writing or debugging large pieces of automation, it can be time consuming to run through the entire thing over and over, when you really want to test and iterate on a section. Mozharness' actions allow you to run each action individually, or skip specific actions, or run a subset of the actions easily.
Q. What are the parts of mozharness and how do they all fit together?
A. Mozharness lives at http://hg.mozilla.org/build/mozharness/; its primary parts are as follows:
- mozharness.base.* contains generic script harness code: configuration, logging, vcs support, and the like. These libraries could be used anywhere.
- mozharness.mozilla.* contains mozilla-specific code. Talos support, Firefox unittest support, Firefox localization, code to interface with the existing Mozilla buildbot infrastructure.
- scripts/ contains the mozharness scripts.
- configs/ contains configuration files to run mozharness scripts on different platforms/branches/environments.
There are three core classes:
All scripts derive from this class. It provides the logic for actions, creates a self.log_obj and self.config (from MultiFileLogger and BaseConfig+ReadOnlyDict), as well as methods to do basic scripting with logging.For instance, self.mkdir_p(path) will basically os.makedirs(path), but will also log that we're doing so (via self.log_obj). self.run_command() and self.get_output_from_command() allow the script to call other executables easily, while keeping information in the logs.BaseScript.run() makes the script go.
- This combines the initial script config, the config file, and the command line options into a single config, which becomes the BaseScript self.config. This config is locked (via ReadOnlyDict) at the end of BaseScript.__init__() and dumped to the logs for ease of debugging and more predictable behavior.
Almost every mozharness object inherits this mixin at some level, to allow for the various log-level methods.If self.log_obj isn't set, we fall back to print's. If it is set to a subclass of BaseLogger (or otherwise compatible logging object that has a log_message() method), then we log through that object.By default, BaseScript uses MultiFileLogger as its log_obj, which creates a file per logging level.
There are also a number of other classes and mixins that provide useful functionality but aren't required for all script/job types. This semi-complete list will most likely fall out of date at some point:
- mozharness.base.log.OutputParser - parses for errors from BaseScript.run_command()
- mozharness.base.parallel.ChunkingMixin - split a long list of items up into separate jobs.
- mozharness.base.signing.AndroidSigningMixin - Android signing
- mozharness.base.transfer.TransferMixin - uploading/downloading directories
- mozharness.base.vcs.vcsbase.VCSScript - provides mercurial functionality. More VCS support as they're added.
- mozharness.mozilla.buildbot.BuildbotMixin - interface with buildbot and mozilla-specific buildbot setup
- mozharness.mozilla.l10n.locales.LocalesMixin - localization support
- mozharness.mozilla.mock.MockMixin - mock_mozilla support
- mozharness.mozilla.release.ReleaseMixin and SigningMixin - release automation support
- mozharness.mozilla.testing.device.DeviceMixin - Android adb + sut device controlling support
- mozharness.mozilla.testing.talos.Talos - talos support
- mozharness.mozilla.testing.testbase.TestingMixin - unittest and talos support
- mozharness.mozilla.tooltool.TooltoolMixin - tooltool support
Q. What classes of mozharness scripts are there (or should there be)? Tests, tools, etc?
A. Right now mozharness is slated to replace buildbotcustom as MoCo releng's source of automation logic.
There are/will be scripts in mozharness for builds, tests, repacks, releases. We may also put machine maintenance type scripts here; anything we want run on releng build+test farms. At some point we will just be able to consider these compute farms, and mozharness will be what runs on that compute farm.
Since mozharness is just a python harness, almost anything that can be written in Python could potentially be added to mozharness.
Q. I want to write a mozharness script for a new automation problem. How do I do this?
For your first mozharness script, it's probably easiest to use existing, similar scripts as examples; that's definitely easier than writing an entirely new type of script.
- Split your script into logical chunks, or actions.
- What actions are needed by some people or jobs, but not others?
- What actions could potentially be independent of others? For example, installing Firefox to run tests. You don't necessarily have to do this if you point to a pre-installed Firefox to run those tests. Or packaging after building. Or uploading the logs somewhere.
- Since actions can be run by themselves, or skipped, they're a logical place to split up a script's behavior.
- These will be listed in the script's all_actions. A default set of actions, if different from all_actions, is defined in default_actions. But the user can turn any or all actions on or off via command line options or config file.
- You need to have a method per action. This method will be named the same as the action, with underscores replacing dashes.
- If you want to define pre-action or post-action behavior, you can write optional preflight_actionname() and/or postflight_actionname() methods, again with underscores instead of dashes.
Figure out the different configurations that might be in play; these should be pre-defineable in either command line options or config files. (Complex data structures are best suited in config files; commonly overridden options should be available via command line.)