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