Building Android multilocale locally

Tl;dr: it's now easier to run multilocale builds locally. I'd love feedback in terms of whether this is useful for you, and if there are changes that would make this script better for your workflow.

I updated the wiki as well.

what & why

There are only three ways to get a multilocale build currently:

• triggering a nightly build off of a multilocale-enabled branch,
• pinging me directly and asking for a multilocale build, or
• building multilocale locally. Up until now, that involved a combination of digging through logs, asking for help, and reverse-engineering the multilocale script with a lot of trial and error.

The latter was so difficult because I hadn't spent the time to make it friendly to run locally. Now that bug 753545 has landed, it should now be relatively easy.

The config file is written to [hopefully] be easily editable and usable.

running the script

• Create a directory to run in. It's simplest to create a new directory, although you can use an existing directory with mozilla-central (or other tree) already checked out.

  mkdir multilocale
  cd multilocale
  

• Clone mozharness and copy the standalone config file for easy editing+use.

  hg clone http://hg.mozilla.org/build/mozharness
  cp mozharness/configs/multi_locale/standalone_mozilla-central.py myconfig.py
  

• Customize your config file.

  By default it's going to clone mozilla-central into a directory called mozilla-central.

  It also assumes your objdir will be named objdir-droid and that will be specified in your mozconfig, which will be in a file named mozconfig in this directory.

  This should hopefully be easy to edit. Holler if it's confusing.

  Afterwards, you can verify it's still valid python by typing

  python myconfig.py
  

  which should exit silently.

• If your config file still says that your mozconfig is in os.path.join(os.getcwd(), "mozconfig"), copy your mozconfig into this directory and make sure it's named mozconfig.
• Make sure mozilla-central (or whatever repo you specified) is in this directory.

  You can either clone it manually, or use the script's pull-build-source action:

  mozharness/scripts/multil10n.py --cfg myconfig.py --pull-build-source
  

• Run the script.

  By default, this will:

  • pull the locale source,
  • copy your mozconfig into the tree and build mozilla-central,
  • package the en-US apk,
  • backup your objdir to a -bak directory (e.g. objdir-droid-bak) via rsync,
  • restore your objdir via rsync (no changes),
  • add the locales to your objdir,
  • and package the multilocale build.

  (See the actions section below for more advanced usage.)

  mozharness/scripts/multil10n.py --cfg myconfig.py
  

developing + debugging

The above instructions are sufficient for when you want a single multilocale build.

If you're changing m-c code or otherwise want multiple builds, you probably want to follow this workflow:

• After running the multilocale steps, you want to restore your objdir to en-US. At least until someone figures out how to clobber the multilocale-specific bits, rsyncing from a clean backup directory seemed like the most expedient solution.

  mozharness/scripts/multil10n.py --cfg myconfig.py --restore-objdir
  

• Then make your code changes.
• Then run the default actions again. If this seems like it's doing more than it needs to, you're correct. See the actions section below for more advanced usage.

  mozharness/scripts/multil10n.py --cfg myconfig.py
  

actions

(I covered actions to some degree here as well, but the below specifically covers this script + config file.)

what actions are available?

You can see the default actions, defined in the config file, by:

mozharness/scripts/multil10n.py --cfg myconfig.py --list-actions


This will give you this output:

Actions available: clobber, pull-build-source, pull-locale-source, build, package-en-US, upload-en-US, backup-objdir, restore-objdir, add-locales, package-multi, upload-multi
Default actions: pull-locale-source, build, package-en-US, backup-objdir, restore-objdir, add-locales, package-multi


what do these actions do?

I'd like to have more information about each action built into each script. Here's an overview of multil10n.py's actions:

• clobber - This is effectively no-op as long as work_dir is set to '.'. Otherwise it nukes the entire work_dir.
• pull-build-source - This clones the repos defined in repos.
• pull-locale-source - This clones the repos defined in l10n_repos, as well as the l10n repositories defined in the locales file (specified here)
• build - This copies the mozconfig path specified here into the source tree, and runs make -f client.mk build.
• package-en-US - This runs make package.
• upload-en-US - To be written. It will call make upload.
• backup-objdir - This rsyncs your objdir to a backup directory, since there's no current solution for clobbering the multilocale bits in your objdir.
• restore-objdir - This rsyncs the backup directory into your objdir. If you want to re-run the build or re-add the locales without a lot of old cruft lying around, I recommend doing this first.
• add-locales - This runs compare-locales and adds the locale strings + manifests into your objdir.
• package-multi - This runs make package for your multilocale apk.
• upload-multi - To be written. It will call make upload.

how do I run a single action?

You can run any single action by itself by prepending -- in front of the action name (making it a command line option). For instance, to only run the restore-objdir action,

mozharness/scripts/multil10n.py --cfg myconfig.py --restore-objdir

how do I skip an action?

You can run the default set of actions, minus an action, by prepending --no- to the action(s) you want to skip. To run the default actions without pulling the locale source,

mozharness/scripts/multil10n.py --cfg myconfig.py --no-pull-locale-source

how do I run several actions at once?

Running the script with no action-specific command line options will iterate over the list of default actions.

You can also have a combination of --ACTION or --no-ACTION to add an action to or remove an action from the default list. For example,

mozharness/scripts/multil10n.py --cfg myconfig.py --no-pull-locale-source --no-build --no-package-en-US --no-backup-objdir

and

mozharness/scripts/multil10n.py --cfg myconfig.py --restore-objdir --add-locales --package-multi

are equivalent.

You also have the option of editing your default_actions in myconfig.py if that makes things easier.