Development setup¶
The following instructions outline the process for setting up a development environment for the VC-2 conformance software and the procedures for running tests and generating documentation.
Checking out repositories¶
The VC-2 conformance software is split across in the following Git repositories, each containing a Python package of the same name:
- https://github.com/bbc/vc2_conformance (
vc2_conformance
) The main conformance software repository on which this documentation focuses.
- https://github.com/bbc/vc2_conformance_data (
vc2_conformance_data
) Data files (e.g. test pictures) used in the conformance testing process.
- https://github.com/bbc/vc2_data_tables (
vc2_data_tables
) Data tables and constant definitions from the VC-2 standard.
- https://github.com/bbc/vc2_bit_widths (
vc2_bit_widths
) Mathematical routines for computing near worst case signals for VC-2 codecs.
The above repositories should be cloned into local directories, e.g. using:
$ git clone git@github.com:bbc/vc2_conformance.git
$ git clone git@github.com:bbc/vc2_conformance_data.git
$ git clone git@github.com:bbc/vc2_data_tables.git
$ git clone git@github.com:bbc/vc2_bit_widths.git
Pre-commit hooks are used to enforce certain code standards in these repositories. These should be installed as follows:
$ # For each cloned repository...
$ cd path/to/repo/
$ pre-commit install
Virtual environment¶
It is strongly recommended that development is carried out in a Python virtual environment (see warning below). This can be setup using:
$ python -m virtualenv --python <PYTHON INTERPRETER> venv
This will create a virtual environment in the directory venv
which uses the
python interpreter <PYTHON INTERPRETER>
, which should generally be one of
python2
or python3
.
Once created, the virtual environment must be activated in any shell you use using:
$ source venv/bin/activate
Note
Python virtual environment provides an isolated environment in which
packages can be installed without impacting on the rest of the system.
Once activated, the python
and pip
commands will use the python
version and packages setup within the virtual environment.
Warning
When working outside a virtual environment, Python packages included by some operating systems (e.g. Ubuntu) can be very out of date leading to problems during development. This is the result of certain development dependencies not correctly specifiying their version requirements and is outside of our control. By using a virtual environment, up-to-date versions of all dependencies will be installed which avoids these problems.
Note
The VC-2 conformance software itself does correctly specify its dependencies so these problems only apply during development and should not affect end users.
Development installation¶
A development installation of the conformance software can be performed directly from each of the cloned repositories as follows:
$ # Each repo should be installed as follows, in the following order:
$ # * vc2_data_tables
$ # * vc2_bit_widths
$ # * vc2_conformance_data
$ # * vc2_conformance
$ cd path/to/repo/
$ # Install in editable/development mode (so edits take effect immediately)
$ pip install -e .
$ # Install test suite dependencies
$ pip install -r requirements-test.txt
$ # Install documentation building dependencies (not present for all
$ # repositories)
$ pip install -r requirements-docs.txt
After installation, the various vc2-*
commands will be made available in
your $PATH
and the various vc2_*
Python modules in your
$PYTHONPATH
. These will point directly to the cloned source code and so
changes will take effect immediately.
Running tests¶
Test routines relating to the code in each repository can be found in the
tests/
directory of each repository. The test suites are built on pytest and, once a development install has been
completed, can be executed as follows:
$ py.test path/to/vc2_data_tables/tests/
$ py.test path/to/vc2_bit_widths/tests/
$ py.test path/to/vc2_conformance_data/tests/
$ py.test path/to/vc2_conformance/tests/
Building documentation¶
HTML documentation (including the documentation you’re reading now) is built as follows (after a development install has been performed):
$ make -C path/to/vc2_data_tables/docs html
$ make -C path/to/vc2_bit_widths/docs html
$ make -C path/to/vc2_conformance_data/docs html
$ make -C path/to/vc2_conformance/docs html
HTML documentation will be written to the docs/build/html/
directory (open
the index.html
file in a web browser to read it).
Alternatively, PDF documentation can be built by replacing html
with
latexpdf
in the above commands. This will require a working installation of
LaTeX and Inkscape to build. In addition, for cross-references between
PDFs to be created correctly, the documentation must be built within the Python
virtual environment where the various vc2_*
Python packages are installed
in development/editable mode.