macOS

Owned by Caleb Kemere
Last updated: Sept 14, 2020 by Josh Siegle

IMPORTANT: The Open Ephys GUI documentation has migrated to a new site – please visit https://open-ephys.github.io for the most up-to-date information.

Installing the binaries

  1. Download the macOS binaries from this page.
  2. Drag and drop the downloaded and unzipped folder to the location of your choice, and rename it "Open Ephys."
  3. Double-click the "open-ephys" executable to run the application.

Building from source

  1. Create a GitHub account if you haven't already.
  2. While logged into your account, go to https://github.com/open-ephys/plugin-GUI and click the "Fork" button in the upper right. You now have your own copy of the GUI repository. Any changes you make will only affect this copy. (More info on forking here.)
  3. Make sure you have GitHub for Mac installed.
  4. Install Xcode if you haven't already.
  5. (Optional, for plugins that require these external libraries) Use MacPorts to install the HDF5 library (sudo port install hdf5-18, see below) and the ZeroMQ library (sudo port install zmq). Make sure you've run "sudo port selfupdate" recently, so you install the latest versions. (Of the plugins shipped by default, KWIKFormat requires the HDF5 library (version 1.8.12 or higher but below 1.10, see below), and NetworkEvents and EventBroadcaster require ZeroMQ.)  These plugins are no longer shipped with the base GUI. External libraries are only required if installing them. They can be found in their respective repositories for ZMQ plugins and HDF5 Plugins.
  6. Direct your browser to https://github.com/yourusername/plugin-GUI, where "yourusername" is replaced by your actual GitHub user name.
  7. Click the "Clone in Desktop" button.
  8. Create the build files for the GUI
  9. In Xcode, select the "open-ephys-GUI.xcodeproj" file from the plugin-GUI/Build folder.
  10. Select the "All" scheme. (development: the "ALL_BUILD" scheme)
  11. Hit the "Run" button to build the GUI and plugins from source. To be able to run the GUI from XCode, you need to select the "open-ephys" scheme from the selector, instead of the ALL_BUILD

Now you can both use the GUI and make changes to the source code. We recommend reading through the developer documentation before doing so.

Any changes you commit can be synced with your GitHub repository through the GitHub application or from the command line. If you change something that you think would be useful for others, you can submit a pull request to the Open Ephys version of the GUI.


Troubleshooting

  • If some plugins won't compile, it's probably related to issues with the HDF5 or ZeroMQ libraries.  If you used MacPorts, the libraries will be installed in /opt/local/lib, and the headers will be found in /opt/local/include. Make sure Xcode knows how to find these files. In the "Build Settings" for the Target (not the Project), add /opt/local/lib to the "Library Search Paths" and /opt/local/include to the "Header Search Paths."
  • If you get error like "libsz.a file not found", then it's because of some missing dependencies for HDF5 library (HDF5 needs SZIP library). Run sudo port install szip  to fix it.
  • Make sure the architecture (32- vs. 64-bit) and base SDK (OS X 10.8, 10.9, or 10.10) are appropriate for your particular machine

HDF5 versions

HDF5 versions 1.10 and higher are not compatible with our code. If your MacPorts repositories are up to date, chances are that the hdf5 package includes a newer version. Fortunately there is a package called hdf5-18 which provides with the adequate libraries. Unless needed for other projects, we recommend not installing the hdf5 package.

Newer versions of macports might mark hdf5-18 as deprecated. If that is the case, you need to manually download the macports package repository, set it to the latest version with the package and then install it. To do that, run the following commands:

git clone --single-branch https://github.com/macports/macports-ports.git
cd macports-ports
git checkout 461781b947cdc9f942d2e963e8d25e58cc7b93ca
cd science/hdf5-18
sudo port install

Notes on different hardware and software

Works on a late 2017 MacBook Pro with macOS Catalina (10.15.2) and Xcode 11.3.1

Works on a late 2013 Mac Pro with OS X El Capitan (10.11.4) and Xcode 7.3.

Works on late 2010 MacBook Air with OS X Yosemite (10.10) and Xcode 6.0.1.

Works on 2014 MacBook Pro with OS X Mavericks (10.9) and stock Xcode.

Works on a late 2013 MacBook Air, OS X version 10.8.4 with command-line tools installed for Xcode.

Works on a 2012 MacBook Pro, OS X version 10.8.4 with Xcode version 4.6.3.

Works on an early 2009 MacBook Pro, OS X version 10.8.4 with Xcode version 4.6.3