Running from source

This page describes how to set up a complete Python environment on your computer, so that you can run OpenSesame directly from the source code.

Download source code

Download the source code of the latest stable release from GitHub:

• https://github.com/smathot/OpenSesame/releases

You can also download a development snapshot of the code. To obtain a reasonable stable snapshot, download from the master branch. To get the latest, greatest, and potentially very unstable snapshot, download from the the branch that corresponds to the major version of OpenSesane (e.g., heisenberg for 2.9, ising for 3.0).

• https://github.com/smathot/OpenSesame/

Dependencies

Icon theme

If you run OpenSesame directly from source, the icon theme is not included. OpenSesame uses two icon themes: MokaSesame, a fork of Moka, and Faba.

It's possible to compile these icon themes yourself, but you can also download precompiled themes from here:

• http://forum.cogsci.nl/uploads/editor/we/p1y3i4qm70ch.zip

Place the Faba and MokaSesame folders as subfolders of opensesame_resources/theme/default/.

Required

The following packages are required to run a minimal version of the OpenSesame GUI, with only support for the legacy backend, no sound support, and no plugin support.

• Python is the programming language in which OpenSesame is created. The following versions of Python are supported:
  • Python 2.7 (default)
  • OpenSesame >= 3.0.0 supports Python >= 3.4
• PyGame is a library that is used for graphics and sound.
• qtpy is the abstraction layer on top of PyQt4 or PyQt5.
  • PyQt4 is the graphics toolkit that is used to for the user interface; or
  • PyQt5 is the graphics toolkit that is used to for the user interface.
• QScintilla2 is a basic text-editor component. In some cases, it is bundled with PyQt4.
• QProgEdit is an advanced text-editor component built on top of QScintilla2.
  • OpenSesame >= 3.1.0 requires QProgEdit >= 4.0.0
• PyYAML is a library used for loading yaml files.
• WebColors is a library used for interpreting color descriptions.
• python-datamatrix is used by the loop item.
• python-qdatamatrix is used by the loop item.
• python-pseudorandom is used by the loop item.
• QNotifications is used by the notifications extension.

Optional

The following packages are not required, but some functionality will be missing if they are not installed.

• Expyriment is required for the xpyriment backend.
  • OpenSesame >= 3.0.0 requires Expyriment >= 0.8.0.
• NumPy is an advanced mathematical library that is used for various things, such as sound support.
• PIL is an imaging library that is used for various things.
  • You can also use pillow, an actively maintained fork of the original, and no longer maintained PIL.
• PsychoPy is required for the psycho backend.
• pyflakes is required for automatic validation of your Python scripts.
• Pyglet is required by PsychoPy.
• PyOpenGL is required by PsychoPy and Expyriment.
• pySerial is required for serial-port communication.
• python-markdown is required for viewing in-program help files.
• IPython, when available, is used for the debug window.
• python-fileinspector is used to generate file-type-specific icons.
• shapely is used to check the boundaries of Canvas elements

Extra

The following packages are not used directly by OpenSesame, but may come in handy while developing your experiments, and are included with the official Windows distribution of OpenSesame.

• PyAudio is an alternative library for sound recording and playback.
• Matplotlib is a library for plotting graphs.
• Scipy is a set of miscellaneous scientific routines.
• pyCairo is a library for vector graphics.
• pyParallel allows communication via the parallel port.
• OpenCV (Python bindings) is an extensive computer-vision library.
• PyGaze is a Python library for eye tracking.
  • OpenSesame >= 3.0.0 requires PyGaze >= 0.6.0.

Instructions for Mac OS

There are three ways to prepare the software environment for running OpenSesame from source on Mac OS X. You can either download and install all required packages manually, or compose the required source environment by using the repository-based package managers MacPorts or Homebrew. The easiest and preferred method nowadays to get OpenSesame working is by using Homebrew. This package manager works very fast, handles dependency requirements very well, and is very well maintained. The other package manager, MacPorts, is basically a large repository containing the source code of programs that have been ported from Linux to Mac OS X (which are very related as Mac OS X is also a Unix based system, as you might know). Compared to Homebrew, Macports takes an astoundingly long time to compile all dependencies. Furthermore, even though Macports used to work very well, it nowadays experiences a lot of 'breaks' due to dependency issues. The downside of homebrew is that it is 'less complete' than macports and you have to manually install many python packages (using easy_install or pip).

Download Xcode

If you want to install with either Homebrew or Macports, the first thing that you need to do is install Xcode, the Apple developer toolkit. You can get the latest version of Xcode for free from the App Store or from their website (you do need to login with an apple account though).

Website: https://developer.apple.com/xcode/

Using the App Store is preferable, as it will keep your version of X Code automatically up to date. You do need to also manually install the Command Line tools for X Code (and do this each time again after it is updated).

Installing with Homebrew

Homebrew is a newer and easier way to build a source tree on your mac. It has many benefits on top of macports, such as speed, and nowadays seems to have less trouble compiling and updating packages than macports does. You can install homebrew as instructed on http://brew.sh/. Then issue the following command to get started:

brew update
brew doctor

Solve any issues that the 'doctor' command comes up with. This should be easy and usually the solutions (in the form of simple commands) are already given together with the problem statement.

Next, add some other required repositories by using homebrew's "tap" command:

brew tap homebrew/python
brew tap homebrew/headonly
brew tap homebrew/science

Now it's time to start installing homebrew's own python environment. It's not really necessary to install another Python environment next to your system's python, but the Homebrew version is generally newer and better maintained, so it is definitely recommendable to do this.

brew install python

After python has been installed, you have to make it the 'default' python used by OS X. This means that the home-brewed python interpreter will be used whenever you issue the command 'python' in a terminal instead of the default system python. To do this type the command

echo export PATH="/usr/local/bin:$PATH" >> ~/.bash_profile

This will position the reference to the folder in which all your homebrew stuff is located (/usr/local/bin) in front of the rest of the PATH variable. From now on, whenever you issue a command in your terminal, OS X will look in this folder first for the script or program to execute and if it doesn't find it there, it will continue to look in the other folders in the PATH variable. Close and reopen your terminal or enter the command

source ~/.bash_profile

to rerun the commands written in your .bash_profile. If you then run the command

which python

it should output something like '/usr/local/bin/python'. If it still outputs '/usr/bin/python', OSX is still using the default system python, which is not what you want. You can now continue with installing the rest of the required packages by executing

brew install qt pyqt qscintilla2 freetype portaudio numpy scipy portmidi hg pillow

For pygame, it is preferable to first install the SDL libraries and smpeg (these are all better than the version that came with OS X, which seem to miss some important functionality):

brew install --HEAD smpeg
brew install sdl sdl_image sdl_mixer sdl_ttf pygame

Install the necessary python packages

pip install pyopengl pyflakes markdown python-bidi pyserial billiard

Install QProgEdit (from OpenSesame 2.8 on)

git clone https://github.com/smathot/QProgEdit.git
cd QProgEdit
python setup.py install
cd ..
rm -R QProgEdit

Install expyriment (from OpenSesame 0.27 on)

git clone https://github.com/expyriment/expyriment.git
cd expyriment
python setup.py install
cd ..
rm -R expyriment

Install psychopy and its dependency pyglet. For psychopy to work, you (currently) need the latest repository versions from both pyglet and psychopy

First install pyglet:

hg clone https://code.google.com/p/pyglet/
cd pyglet
python setup.py install
cd ..
rm -R pyglet

Then psychopy. Install it and do some cleanup with:

git clone https://github.com/psychopy/psychopy.git
cd psychopy
python setup.py install
cd ..
rm -R psychopy

During installing you might receive an error with the message "Unknown locale UTF8". You can easily fix this by placing the line "LC_ALL=en_US.UTF8" in your ~/.bash_profile and then re-open your terminal.

You should now be able to run OpenSesame, but you'll notice you're missing some icons! You need to download the Faenza icon theme from http://tiheum.deviantart.com/art/Faenza-Icons-173323228 and place it under resources/theme/default/. Furthermore, there is a quirk in that multiprocessing won't work when the main file is not present as a .py file, which is the case for opensesame. To enable the multiprocessing support, you need to rename the opensesame file to opensesame.py, then if you run an experiment now once, you'll see that opensesame.pyc will have been created. From the moment this file is present, Python will use the .pyc when spawning new processes and you can now rename back opensesame.py to opensesame again. This is a weird fix to get multiprocessing working, but at the moment it is the only one we know.

The following packages are optional, but might be useful to install nevertheless:

brew install matplotlib opencv
pip install pycairo pyparallel scikit-image

Installing with MacPorts

Another way to install the necessary packages on Mac OS is by using MacPorts, a large repository of packages. It takes a long time (and by this I mean many hours!) to install all the packages that are required for running OpenSesame, because MacPorts works by compiling from source. But on the bright side, it's a pretty straightforward process.

Download MacPorts

You can download macports from its website on which you can also find the necessary documentation and a catalogue of all available packages.

Website: http://www.macports.org/install.php

You can add +universal to your /opt/local/etc/macports/variants.conf to ask MacPorts to build all ports you install with that variant (thus 32-bit and 64-bit versions packed in the same module), without having to remember to type it at every install command. However, some ports have not yet been tested as universal binaries and may not build properly.

Install dependencies

Essentially, you can now install all required packages by running a single command in a terminal:

sudo port install py27-game py27-pyqt4 py27-scintilla py27-serial py27-pil py27-opengl py27-pyaudio opencv +python27 py27-pip

This takes forever and, in my case, crashed a few times with a checksum error. You can simply recover from such errors by executing the following command:

sudo port clean --all [package_that_caused_the_error]

Then you repeat the first command and MacPorts should be on its way again.

Install the remaining necessary python packages by using pip

sudo pip install pyflakes markdown python-bidi pyserial billiard

Install QProgEdit (the default code editor from OpenSesame 2.8 on)

git clone https://github.com/smathot/QProgEdit.git
cd QProgEdit
sudo python setup.py install
cd ..
rm -R QProgEdit

Expyriment and Psychopy backends

Next to the legacy backend, which is based on pygame, OpenSesame also offers you the option of using expyriment or psychopy. In contrast to the legacy backend, both of these backends are hardware accelerated (OpenGL) and should have increased timing precision.

Install expyriment (from OpenSesame 0.27 on)

git clone https://github.com/expyriment/expyriment.git
cd expyriment
sudo python setup.py install
cd ..
rm -R expyriment

Install psychopy and its dependency pyglet:

First install pyglet:

hg clone https://code.google.com/p/pyglet/
cd pyglet
sudo python setup.py install
cd ..
rm -R pyglet

Then install psychopy:

git clone https://github.com/psychopy/psychopy.git
cd psychopy
python setup.py install
cd ..
rm -R psychopy

PsychoPy refuses to run without the wxPython library installed (which is weird, because OpenSesame doesn't use any of the wx GUI components of psychopy), so as a final step install wxPython with:

sudo port install py27-wxpython-dev

Make the MacPorts Python the default Python

Mac OS comes with a custom version of Python but, for our purpose (and many purposes), you need the official Python. This has already been installed by MacPorts, but you still need to make it the default. You can do this with the following command:

sudo port select --set python python27

Installing packages manually

If you want to install all Opensesame dependecies yourself you need to download and install the following package distributions:

Install Python

The python installation that comes with OS X is usually of an older version. Therefore it is better to install the newest version from python.org:

Website: http://www.python.org/

Direct download: http://www.python.org/ftp/python/2.7.3/python-2.7.3-macosx10.6.dmg

Another option is to install the Enthought Python Distribution (EPD) instead. This distribution includes Python and many of the modules OpenSesame depends on (view a complete list).

Install PyGame

Website: http://www.pygame.org/

Direct download (Snow Leopard): http://www.pygame.org/ftp/pygame-1.9.2pre-py2.6-macosx10.6.mpkg.zip
Direct download ((Mountain) Lion): http://www.pygame.org/ftp/pygame-1.9.2pre-py2.7-macosx10.7.mpkg.zip

Install PyQt4

There is no official distribution (from Riverbank) available of PyQt4 for Mac OS X. However there are some well maintained unofficial distributions:

Official website: http://www.riverbankcomputing.co.uk/software/pyqt/intro

Mac OS X distribution (PyQtX) website: http://sourceforge.net/projects/pyqtx/ (Direct download: http://sourceforge.net/projects/pyqtx/files/latest/download)

After PyQt4 is installed, download and install the QScintilla module, which is used for the inline script editor in OpenSesame:

PyQScintillaX: http://sourceforge.net/projects/pyqtx/files/PyQScintillaX/

Install NumPy and SciPy

Getting the latest versions of NumPy or SciPy can be done in two ways:

You can use the installation script which can be found at http://fonnesbeck.github.com/ScipySuperpack/ (Direct download: https://raw.github.com/fonnesbeck/ScipySuperpack/master/install_superpack.sh) along with the instructions of how to use it. This script will automatically find the latest versions of numpy and scipy and install them for you. Basically you just have to run

sudo sh ./install_superpack.sh

in the console in the folder which you downloaded the script.

Alternatively, you can download and install the packages from the projects' own websites:

Numpy: http://sourceforge.net/projects/numpy/files/NumPy/ (Direct download version 1.7.0: http://sourceforge.net/projects/numpy/files/NumPy/1.7.0/numpy-1.7.0-py2.7-python.org-macosx10.6.dmg/download) Scipy: http://sourceforge.net/projects/scipy/files/scipy/ (Direct download version 0.11.0: http://sourceforge.net/projects/scipy/files/scipy/0.11.0/scipy-0.11.0-py2.7-python.org-macosx10.6.dmg/download)

Install PsychoPy and Expyriment(optional)

PsychoPy requires the installation of a number of dependencies. Most of these can be installed fairly easily using setuptools.

Website: http://pypi.python.org/pypi/setuptools

Direct download: http://pypi.python.org/packages/2.7/s/setuptools/setuptools-0.6c11-py2.7.egg#md5=fe1f997bc722265116870bc7919059ea

As described on the website, installation should proceed through the following steps:

Download the appropriate egg for your version of Python (e.g. setuptools-0.6c9-py2.7.egg). Do NOT rename it.

Run it as if it were a shell script, e.g.

sh setuptools-0.6c9-py2.7.egg

Setuptools will install itself using the matching version of Python (e.g. python2.7), and will place the easy_install executable in the default location for installing Python scripts (as determined by the standard distutils configuration files, or by the Python installation). Afterwards, install most dependencies with the command:

sudo easy_install psychopy pyglet pyopengl pil expyriment

You may need to manually install Matplotlib, wxPython because (at the time of testing) these didn't install using easy_install. Make sure you install the versions that match your Python version.

NOTE: The psychopy backend does not seem to work yet and crashes. The reason is that PsychoPy (or rather its underlying library pyglet) can't cope with the 64-bit cocoa environment of the newer Mac OS X versions yet. In newer versions of psychopy this problem is hopefully solved.

Install wxPython (Optional, required for the PsychoPy backend)

You can download wxPython yourself or install it using easy_install (see "install PsychoPy").

Website: http://wxpython.org/

Direct download: http://downloads.sourceforge.net/wxpython/wxPython2.9-osx-2.9.4.0-cocoa-py2.7.dmg

Install PyOpenGL (Optional, required for opengl or expyriment backend)

You can download PyOpenGL yourself or install it using easy_install (see "install PsychoPy").

Website: http://pyopengl.sourceforge.net/

Direct download: https://pypi.python.org/packages/source/P/PyOpenGL/PyOpenGL-3.0.2.tar.gz#md5=77becc24ffc0a6b28030aa109ad7ff8b

Run OpenSesame

Download the source code of the latest OpenSesame release here. Extract the .tar.gz to your home folder (any other location works analogously). Open a terminal and switch to the location of OpenSesame (this example assumes that the version is 0.26):

cd /Users/[your username]/opensesame-0.26

Run OpenSesame using one of the following commands:

python opensesame
python opensesame --debug