Testing:Mac OS X Testing Environment

From OpenLP
Jump to: navigation, search

Mac OS X Development Build

The easiest way to test OpenLP is to use the Development Build. Note however that this development release could be a few days or weeks behind the current development trunk.

If you want to run the most up to date version, the following steps will guide you through the process:

Install Dependencies with MacPorts

In order to run the very latest "trunk" (where approved code is updated before release) or developers' personal branches, you will need to install several pieces of extra software. OSX comes with Python pre-installed, but unfortunately it does not have all the required modules. The recommended way to set up the installation is using macports, a free software repository which lets you install different versions of many standard *NIX programs & libraries.

Python is 3.4 is required: various packages are currently not compatible with Python 3.5

Install Xcode

For recent OSX (Mountain Lion, Mavericks or El Capitan) you can install Xcode from the App Store (it's free). There's more information about Xcode at developer.apple.com.

Xcode contains gcc or clang (C/C++ compiler) and other development tools necessary to set up the testing environment via MacPorts.

Install MacPorts

Download and install MacPorts from http://www.macports.org/

Settings for Mac OS X Compatibility

Note: This is only required if you are going to be packaging OpenLP for general download.

It is recommended to make the macports installation compatible with older OS X version. Otherwise OpenLP builds won't work on older OS X releases. For instance, without the following settings OpenLP built on 10.11 won't run on 10.10 or 10.9.

Open the following file in a text editor


and add the following:

# macosx_deployment_target - Earliest OS X version to be compatible with.
macosx_deployment_target            10.9

Tools from Macports in PATH

When you install Macports, it should make itself accessible from the terminal. However, if you choose not to let it do that when you install it, you can do it manually:

We need to modify the environment variable $PATH.

Open the following file in a text editor


and add at the end line

# Adding an appropriate PATH variable for use with MacPorts.
export PATH=/opt/local/bin:$PATH
# Finished adapting your PATH environment variable for use with MacPorts.

To have tools from macports available in your currently open terminal run command

source ~/.profile

Update list of available packages

To be able to install latest version of libraries you usually need to tell MacPorts to update the package list:

sudo port -v selfupdate

Install Basic Development Tools

Now we are ready to use MacPorts to install Python, dependencies and other tools. If you want to use Bazaar, or vim, etc. then you can install them now (if you already have an editor, and/or you want to use the Nightly Build Tarball, then you can skip this):

sudo port install bzr git mupdf python34

If you aren't using MacPorts' Python 2.X, you can make Python 3 the default Python:

sudo port select --set python python34

If you want to keep on using Python 2 as your default python, you can set Python 3 only to be your default 'python3':

sudo port select --set python3 python34

Install Python Libraries (MacPorts)

Now you can install libraries. This can take a lot of time (several hours) compiling the Qt5 libraries.

First install PyQt5 with both WebEngine and WebKit (they are called "variants" in MacPorts language).

sudo port install py34-pyqt5 +webengine +webkit

Then install the rest.

sudo port install py34-pip py34-lxml py34-sqlalchemy py34-mako py34-nose py34-beautifulsoup4 py34-psycopg2 py34-sphinx py34-alembic py34-chardet py34-enchant py34-pyobjc-cocoa


sudo port install hunspell-dict-af_ZA hunspell-dict-ca_ES hunspell-dict-cs_CZ hunspell-dict-cy_GB hunspell-dict-de_DE hunspell-dict-el_GR hunspell-dict-en_CA hunspell-dict-en_GB hunspell-dict-en_NZ hunspell-dict-en_US hunspell-dict-en_ZA hunspell-dict-eo_EO hunspell-dict-es_ES hunspell-dict-es_MX hunspell-dict-fo_FO hunspell-dict-fy_NL hunspell-dict-ga_IE hunspell-dict-gd_GB hunspell-dict-gsc_FR hunspell-dict-gu_IN hunspell-dict-he_IL hunspell-dict-hi_IN hunspell-dict-hr_HR hunspell-dict-id_ID hunspell-dict-ku_TR hunspell-dict-lt_LT hunspell-dict-mg_MG hunspell-dict-mk_MK hunspell-dict-ms_MY hunspell-dict-nb_NO hunspell-dict-nl_NL hunspell-dict-nn_NO hunspell-dict-nr_ZA hunspell-dict-ns_ZA hunspell-dict-ny_MW hunspell-dict-oc_FR hunspell-dict-rw_RW hunspell-dict-sl_SI hunspell-dict-ss_ZA hunspell-dict-st_ZA hunspell-dict-sw_KE hunspell-dict-tet_ID hunspell-dict-th_TH hunspell-dict-tl_PH hunspell-dict-tn_ZA hunspell-dict-ts_ZA hunspell-dict-uk_UA hunspell-dict-ve_ZA hunspell-dict-xh_ZA hunspell-dict-zu_ZA

Install Libraries not in MacPorts

Some Python dependencies are not in MacPorts. These you will need to install using pip:

The version of MySQL Connector currently on PyPI is broken. You will need to tell pip to install the latest version from MySQL's website. At the time of writing it is version 2.1.3.

You may also need to add the --egg if you encounter an error when installing it.

sudo pip-3.4 install --egg https://dev.mysql.com/get/Downloads/Connector-Python/mysql-connector-python-2.1.3.zip

Sphinx no longer comes with the ReadTheDocs theme bundled, this needs to be installed via pip too.

sudo pip-3.4 install sphinx_rtd_theme

Get rid of session error

After installation of dbus package, you need to load the dbus daemon. Get the commands to run from:

port notes dbus

Otherwise OpenLP might not start correctly!

Keep MacPorts up to date

From time to time newer library versions are available, to install them do first a

sudo port selfupdate

to update MacPorts itself, then run

sudo port upgrade outdated

to upgrade the existing tools and libraries.

Skip to Checkout

If you've installed the dependencies using MacPorts, you don't need to install them again with Homebrew.

Click here to jump to instructions for checking out the latest code.

Install Dependencies with Homebrew (Experimental)

It is not usually a good idea to install MacPorts and Homebrew simultaneously. If you are using MacPorts, as described previously, please skip this section.

Mac OS X Compatibility

Unfortunately Homebrew doesn't allow macosx_deployment_target to be set. This means that projects built with Homebrew can only be packaged for the system used to build them. If you want to package OpenLP to be compatible with older OS X versions, please use MacPorts, as described above.

Install Command Line Tools

To install the Command Line Tools, run

xcode-select --install

xcode-select --install installs gcc or clang (C/C++ compiler) and other development tools necessary to set up the testing environment via Homebrew.

Install Homebrew

Download and install Homebrew from http://brew.sh

Update list of available packages

To be able to install latest version of libraries you usually need to tell Homebrew to update the package list:

brew update

Install basic development tools

Now we are ready to use Homebrew to install python, libraries and other tools. If you want to use Bazaar, or vim, etc. then you can install them now (if you already have an editor, and/or you want to use the Nightly Build Tarball, then you can skip this):

brew install bzr git wget vim htop-osx

Install Python and Libraries

Now you can install libraries.

Note: The current version of qt does not include qtwebkit by default. The --with-qtwebkit flag will trigger a source build that contains the missing qtwebkit. You may need to brew remove qt first.

brew install qt --with-qtwebkit
brew install postgresql python3 enchant

Note: The default version of pyqt provided by brew does not link to qtwebkit, even if it is correctly installed as described above. The --build-from-source flag will enable pyqt to find qtwebkit. You may need to brew remove pyqt first.

brew install pyqt --build-from-source

Then to complete run following:

Note: If this doesn't work, make sure that you have run xcode-select --install as described above.

pip3 install lxml sqlalchemy mako nose beautifulsoup4 psycopg2 sphinx alembic chardet pyenchant

For the next installation, check PyPi for the latest download link. e.g.

pip3 install http://cdn.mysql.com/Downloads/Connector-Python/mysql-connector-python-2.0.4.zip#md5=3df394d89300db95163f17c843ef49df

NOTE: pyobjc takes a very long time to install

pip3 install pyobjc

Install Dictionaries

Dictionaries help with spell checking while writing lyrics and other text in OpenLP. Install the aspell or hunspell dictionaries you like: Homebrew doesn't include hunspell dictionaries, but you can install hunspell as follows, then install compatible dictionaries from external sources. Compatible dictionaries can be found here: http://cgit.freedesktop.org/libreoffice/dictionaries/tree/ Find the *.aff and *.dic files, and install them to the required location. Hunspell dictionaries should be installed to ~/Library/Spelling or /Library/Spelling.

brew install hunspell

Homebrew includes the aspell dictionaries. To see which dictionaries are available, simply run:

brew info aspell

Then use the relevant flags to install the dictionary of your choice. For instance, install all dictionaries with:

brew install aspell --with-all-langs

Or install just English US and UK with:

brew install aspell --with-lang-en --with-lang-uk

Keep Homebrew up to date

From time to time newer library versions are available, to install them, first run:

brew update

to update Homebrew itself, then run

brew upgrade

to upgrade the existing tools and libraries.

Check out the latest code

Python code.png

OpenLP uses the Bazaar DVCS (read more about Bazaar) and the main branch is hosted at Launchpad.net. Do the following to set up your local branch:

  1. Identify yourself to Bazaar:
    $ bzr whoami "Raoul Snyman <raoulsnyman@example.com>"
  2. Log in to Launchpad:
    $ bzr launchpad-login raoul-snyman
  3. Create a shared repository:
    $ bzr init-repo ~/openlp
  4. Checkout the latest code:
    $ bzr checkout lp:openlp ~/openlp/trunk

Verify Installation

To verify the installation checkout the source code of OpenLP and change to the OpenLP source directory. Then run the following script:

python3 scripts/check_dependencies.py

The output should be similar to the following:

bash-3.2$ python3 scripts/check_dependencies.py 
Checking Python version...
  Python >= 3.0 ...                    3.5.1.final.0
Checking for modules...
  PyQt5 ...                            OK
  PyQt5.QtCore ...                     OK
  PyQt5.QtGui ...                      OK
  PyQt5.QtWidgets ...                  OK
  PyQt5.QtNetwork ...                  OK
  PyQt5.QtOpenGL ...                   OK
  PyQt5.QtSvg ...                      OK
  PyQt5.QtTest ...                     OK
  PyQt5.QtWebKit ...                   OK
  PyQt5.QtMultimedia ...               OK
  sqlalchemy ...                       OK
  alembic ...                          OK
  sqlite3 ...                          OK
  lxml ...                             OK
  chardet ...                          OK
  enchant ...                          OK
  bs4 ...                              OK
  mako ...                             OK
  uno ...                              FAIL
Checking for optional modules...
  mysql.connector (MySQL support)...   OK
  psycopg2 (PostgreSQL support)...     OK
  nose (testing framework)...          OK
  jenkins (access jenkins api - package name: jenkins-webapi)...  FAIL
Checking for Mac OS X specific modules...
  objc ...                             OK
  AppKit ...                           OK
Verifying version of modules...
  PyQt5 >= 5.0 ...                     5.5.1
  Qt5 >= 5.0 ...                       5.5.1
  sqlalchemy >= 0.5 ...                1.0.11
  enchant >= 1.3 ...                   1.6.6
Qt5 image formats...
  read: bmp, cur, dds, gif, icns, ico, jp2, jpeg, jpg, mng, pbm, pgm, png, ppm, svg, svgz, tga, tif, tiff, wbmp, webp, xbm, xpm
  write: bmp, cur, dds, icns, ico, jp2, jpeg, jpg, pbm, pgm, png, ppm, tif, tiff, wbmp, webp, xbm, xpm
Enchant (spell checker)...
  available backends: aspell
  available languages: en, en_CA, en_GB, en_US, uk

Launch OpenLP

Assuming all required dependency checks have passed in the previous section, you should be able to run OpenLP. To run OpenLP, simply navigate to your OpenLP development directory, and run

python3 openlp.py


Log File

The OpenLP log file is at /Users/USERNAME/Library/Application Support/openlp/openlp.log

Other ways to install Bazaar

If you followed the instructions, the command line Bazaar (bzr) client should be installed. However, you can use the official version for Mac OS X. Go to the Bazaar download page, and download and install the version of Bazaar for your version of Mac OS X.

Configuring SSH

See the instructions on setting up SSH on Linux and Mac OS X.

Optional development tools

The following tools are not necessary to run the source code but are useful for debugging and improving code quality:

pip3 install pep8 pyflakes ipython