Creating and Maintaining a Development Environment

Requirements

To create a development and test environment, you’ll need Linux or OS X host operating system. Windows is currently not supported.

You will need Python 2.7.

Many components use Docker. You’ll need Docker to perform many tasks. Functionality requiring Docker should be skipped if Docker is not available.

Aside from the base requirements, the development and testing environment should be fully self-contained and won’t pollute your system.

If you are on Windows or want to create a fully-isolated environment, the Vagrant configuration used by Jenkins provides a fully capable environment.

Ubuntu Requirements

On a fresh Ubuntu 16.04 install, the following packages need to be installed:

  • build-essential

  • git

  • python-dev

  • libcurl4-openssl-dev

  • libffi-dev

  • liblzma-dev

  • libsasl2-dev

  • libldap2-dev

  • libssl-dev

  • python3

  • sqlite3

  • zlib1g-dev

  • mercurial (to clone version-control-tools)

Many of these dependencies are needed to compile binary Python extensions that are part of the virtualenv.

You can install these dependencies by running:

$ sudo apt-get install build-essential git python-dev \
  libcurl4-openssl-dev libffi-dev liblzma-dev \
  libsasl2-dev libldap2-dev libssl-dev python3 sqlite3 zlib1g-dev \
  mercurial

You will also need to install Docker for a number of test and dev environments to work. See the official Docker instructions for more. You will likely need to go through the post installation steps for Linux as well.

Creating and Updating Your Environment

Development and testing requires the creation of a special environment containing all the prerequisites necessary to develop and test. The environment is managed by uv and the dependency groups are declared in pyproject.toml.

Install uv first (see the upstream docs for options), then from the root of a version-control-tools checkout run:

$ ./run sync test

This wraps uv sync --only-group test and materialises a virtualenv at .venv/. The dev group is also available and is a superset of test useful for interactive local work:

$ ./run sync dev

The deploy group installs just what the ./deploy entry point needs (Ansible, mach, and vcttesting) for running deployments against hg.mozilla.org:

$ ./run sync deploy
$ source .venv/bin/activate
$ ./deploy hgmo

Tip

You should periodically re-run ./run sync <group> to ensure everything is up to date after pulling new changes.

Activating an Environment

Once ./run sync has finished, activate the virtualenv so your current shell has access to all its wonders:

$ source .venv/bin/activate

Note

Unlike the old create-environment test, ./run sync does not build the Docker images used by the integration tests. After syncing, run:

$ ./run hgmo build

to build the hgmo Docker images. This step can take a while on the first run.

boot2docker

If you are running OS X and have boot2docker installed to run Docker containers, you may want to increase the amount of memory available to the boot2docker VM.

Run the following to see how much memory is currently allocated to boot2docker:

$ boot2docker config | grep Memory
2048

The default is 2048 (megabytes). We recommend at least 4096 MB.

To adjust the amount of memory allocated to boot2docker, run the following:

$ VBoxManage modifyvm boot2docker-vm --memory 4096

Alternatively, if you haven’t created a boot2docker VM yet, define the memory allocation when you create it:

$ boot2docker init --memory=4096