Testing:Mac OS X Testing Environment
- 1 Mac OS X Development Build
- 2 Install Dependencies with MacPorts
- 2.1 Install Xcode
- 2.2 Install MacPorts
- 2.3 Settings for Mac OS X Compatibility
- 2.4 Tools from Macports in PATH
- 2.5 Update list of available packages
- 2.6 Install Basic Development Tools
- 2.7 Install Python Libraries (MacPorts)
- 2.8 Install Libraries not in MacPorts
- 2.9 Get rid of session error
- 2.10 Keep MacPorts up to date
- 2.11 Skip to Checkout
- 3 Install Dependencies with Homebrew (Experimental)
- 4 Check out the latest code
- 5 Hints
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
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.
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
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
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
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.
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 installs gcc or clang (C/C++ compiler) and other development tools necessary to set up the testing environment via 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:
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.
brew install postgresql python3 pyqt5 enchant
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
pyobjc takes a very long time to install
NOTE: The version of
pyobjc-core on PyPI is incompatible with Python 3.5, which we have installed with Homebrew.
The second line updates the
pyobjc-core to version 3.0.5, which includes a workaround.
This workaround should be removed when the PyPI version of
pyobjc is updated to a version greater than 3.0.4.
Note that you must run both commands to install
pip3 install pyobjc pip3 install https://github.com/GreatFruitOmsk/pyobjc-core/releases/download/v3.0.5.dev0/pyobjc-core-3.0.5.tar.gz
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:
to update Homebrew itself, then run
to upgrade the existing tools and libraries.
Check out the latest code
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:
- Identify yourself to Bazaar:
$ bzr whoami "Raoul Snyman <firstname.lastname@example.org>"
- Log in to Launchpad:
$ bzr launchpad-login raoul-snyman
- Create a shared repository:
$ bzr init-repo ~/openlp
- Checkout the latest code:
$ bzr checkout lp:openlp ~/openlp/trunk
To verify the installation checkout the source code of OpenLP and change to the OpenLP source directory. Then run the following script:
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 bash-3.2$
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
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.
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