open-ephys-plugins / oecommonlib

Open Ephys common library template

This repository contains a template for building libraries intended to be used by plugins for the Open Ephys GUI. Information on the plugin architecture can be found on our wiki.

Creating a new library

1. Rename the "CommonLib" folder to the name the library file will have
2. Add source files to the Source folder. The existing files can be used as a template
3. Create the build files through CMake

Using external libraries

To link the library to other external libraries, it is necessary to manually edit the Build/CMakeLists.txt file. The code for linking libraries is located in comments at the end. For most commonly used libraries, the find_package option is recommended. An example would be

find_package(ZLIB)
target_link_libraries(${COMMONLIB_NAME} ${ZLIB_LIBRARIES})
target_include_directories(${COMMONLIB_NAME} PRIVATE ${ZLIB_INCLUDE_DIRS})

If there is no standard package finder for cmake, find_libraryand find_path can be used to find the library and include files respectively. The commands will search in a variety of standard locations For example

find_library(ZMQ_LIBRARIES NAMES libzmq-v120-mt-4_0_4 zmq zmq-v120-mt-4_0_4) #the different names after names are not a list of libraries to include, but a list of possible names the library might have, useful for multiple architectures. find_library will return the first library found that matches any of the names
find_path(ZMQ_INCLUDE_DIRS zmq.h)

target_link_libraries(${COMMONLIB_NAME} ${ZMQ_LIBRARIES})
target_include_directories(${COMMONLIB_NAME} PRIVATE ${ZMQ_INCLUDE_DIRS})

Providing libraries for Windows

Since Windows does not have standardized paths for libraries, as Linux and macOS do, it is sometimes useful to pack the appropriate Windows version of the required libraries alongside the library files. To do so, a libs directory has to be created at the top level of the repository, alongside this README file, and files from all required libraries placed there. The required folder structure is:

    libs
    ├─ include           #library headers
    ├─ lib
        ├─ x64           #64-bit compile-time (.lib) files
        └─ x86           #32-bit compile time (.lib) files, if needed
    └─ bin
        ├─ x64           #64-bit runtime (.dll) files
        └─ x86           #32-bit runtime (.dll) files, if needed

DLLs in the bin directories will be copied to the open-ephys GUI shared folder when installing.

oecommonlib's Issues

Not sure how to link a common lib that is built separately

I'm trying to set up a situation where I build a common library using CMake from one repository, then build two plugins from other repositories that need to link this library.

I know that in order to pull in the library header, I have to have the library repository as a parallel directory to the others and use target_include_directories to point CMake to the library Source folder. That's fine although a little inelegant.

However, when building the library (on Windows), the common lib CMake script only copies the .dll to the shared folder, which is where I was trying to find the library in order to link it. I think I need the .lib instead, but that's not installed, but buried in the library Build folder under an arbitrary subdirectory. I could just assume it's Build/VS2013, and then Linux and Mac might be able to link from what's in the shared folder instead. Not sure if this is what you intended or if there's a better way in the works though.

Thanks by the way, I was skeptical at first but I think this CMake system could make it a lot easier to manage several plugins with independent development timelines, rather than keeping them all in one repository like we've been doing.

"CONFIGURATIONS" should come before what it applies to

In a few places, I've seen commands like this:

install(TARGETS ${COMMONLIB_NAME}
	LIBRARY DESTINATION ${GUI_COMMONLIB_DIR}/${CONFIGURATION_FOLDER}/lib/${CMAKE_LIBRARY_ARCHITECTURE}
	CONFIGURATIONS ${CMAKE_CONFIGURATION_TYPES}
	ARCHIVE DESTINATION ${GUI_COMMONLIB_DIR}/${CONFIGURATION_FOLDER}/lib/${CMAKE_LIBRARY_ARCHITECTURE}
	CONFIGURATIONS ${CMAKE_CONFIGURATION_TYPES}
	)

In this case, no configurations are excluded, so it doesn't matter and the CONFIGURATIONS options could just be deleted. However, for versions 3.11 and later, the documentation states:

Note that the values specified for this option only apply to options listed AFTER the CONFIGURATIONS option.

(Prior to this version, it's not specified.)