Getting started

Working on mimic requires the installation of a small number of development dependencies, which are listed in requirements/development.txt. They can be installed in a virtualenv using pip. This also installs mimic in editable mode.

For example:

$ # Create a virtualenv and activate it
$ pip install --requirement requirements/development.txt

You are now ready to run the tests and build the documentation.

Some of the tox jobs may require certain packages to be installed, so having homebrew installed would be useful if developing on Mac OS.

Running tests

mimic unit tests are found in the mimic/test/ directory. Then can be run via the built-in tox commands after setting up tox.

$ tox -e py27

You can also run the tests for other python interpreters. We use tox, which creates a virtualenv per tox job to run tests, linting, etc.:

$ tox
...
 py26: commands succeeded
 py27: commands succeeded
 pypy: commands succeeded
 docs: commands succeeded
 lint: commands succeeded

Building documentation

mimic documentation is stored in the docs/ directory. It is written in reStructured Text and rendered using Sphinx.

To build the documentation, use tox:

$ tox -e docs

The HTML documentation index can now be found at docs/_build/html/index.html.

Alternately, you can use sphinx directly, if you would like to specify options:

$ sphinx-build -W -b html -d _tmp/doctrees docs docs/_build/html

Building a Mac application

The officially supported method of building of the application depends on the system python, and the pyobjc, and py2app libraries. Travis-CI is configured to build the mac application and run its tests.

To build the application and run its tests locally use the following commands.

$ cd /dir/where/mimic/lives/
$ ./build-app.sh

Once built, mimic.app can be found in the ./dist directory. This application can be treated like any other mac application and moved into ~/Applications. To start mimic, use the open command with the path to mimic.app , e.g. open ./dist/mimic.app.

When the application is running, the letter M will be visible in the menubar. To quit the application, simply click on the M and select Quit. You can view the application logs by opening Applications/Utilities/Console.app.

To run mimic.app‘s tests use

$ /path/to/mimic.app/Contents/MacOS/run-tests

The application can also built as a standalone application that does not depend on the system python. This is not the officially supported method of building the application and is not tested by Travis-CI.

To build a standalone application, py2app requires the installation of a non-system framework python. In my experience, it is easiest to install a brewed 2.7 python. To install a brew python, you’ll need to have homebrew installed.

The following commands will build the standalone application and run its tests.

$ brew install python
$ cd /dir/where/mimic/lives/

$ # build a virtualenv using the brewed python
$ virtualenv -p /usr/local/bin/python2.7 ./venv
$ source ./venv/bin/activate

$ # install mimic's dependencies including pyobjc and py2app
$ pip install -r requirements/production.txt
$ pip install -r requirements/mac-app.txt
$ python setup.py py2app
$ ./dist/mimic.app/Contents/MacOS/run-tests