linking liblsl on MacOS with homebrew installation fails

[gisogrimm]

Since early 2026, it is not possible to link against liblsl on MacOS using "-llsl" (clang compiler). Also the flags "-framework lsl" and "-framework LSL" failed. Furthermore, no "liblsl*" can be found below /opt (including /opt/homebrew).

What is the correct way to link against recent versions of liblsl on MacOS?

[cboulay]

To be clear, does this mean you did brew install labstreaminglayer/tap/lsl and now you can't find the lsl dependency?

The shared library should be found in /opt/homebrew/Frameworks/lsl.framework/Versions/A/lsl .
Even though it's not in the filename, this is a dylib.

I mostly test with CMake and find_package(lsl) works. I don't know clang's default paths for frameworks.

[gisogrimm]

Yes, I installed via brew install labstreaminglayer/tap/lsl . Since January the behaviour changed, previously it was possible to use traditional library linkage with -llsl; the paths were found automatically. To fix the compilation, I needed to add
CXXFLAGS += $(addprefix -I,$(dir $(shell find /opt/homebrew/ -name lsl_cpp.h)))
and
LDLIBS += -F/opt/homebrew/Cellar/lsl/1.17.4/Frameworks -framework lsl
The system is the standard github runner 'macos-latest'.

This is a functional workaround, but depending on very specific path names is not very robust in case of updates.

[cboulay]

I was just testing locally and the following worked for me:

clang++ -F$(brew --prefix)/Frameworks -framework lsl

Note that when using frameworks, standard include paths are formatted as <FrameworkName/framework.h>. i.e., #include <lsl/lsl_cpp.h> is correct, not #include <lsl_cpp.h>.

IMO, the way we've been installing loose header files (lsl_cpp.h and lsl_c.h) into the global include folder on Unix systems is bad behaviour; I think they should be namespaced. Since we are producing frameworks on Apple for a cross-platform library, the best ergonomics would have the headers namespaced on non-framework platforms too. I suppose I should have modified the installation paths on Windows and Linux to conform to this behaviour. Instead, I used CMake to make the framework appear to conform to the old way:

liblsl/cmake/TargetLib.cmake

Lines 37 to 51 in cdf917d

	if(APPLE AND LSL_FRAMEWORK)
	# For frameworks, the install interface needs to point into the framework bundle
	if(LSL_UNIXFOLDERS)
	set(LSL_INSTALL_INTERFACE_INCLUDE_DIR "${FRAMEWORK_DIR_DEFAULT}/lsl.framework/Versions/A/Headers")
	else()
	set(LSL_INSTALL_INTERFACE_INCLUDE_DIR "LSL/Frameworks/lsl.framework/Versions/A/Headers")
	endif()
	else()
	set(LSL_INSTALL_INTERFACE_INCLUDE_DIR "include")
	endif()
	target_include_directories(lsl
	PUBLIC
	$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
	$<INSTALL_INTERFACE:${LSL_INSTALL_INTERFACE_INCLUDE_DIR}>
	)

i.e., CMake users are insulated from this change and can continue to use the old syntax.

If you aren't using CMake, and you want use the old #include <lsl_cpp.h> syntax cross-platform, then on Apple you can add:

• -I$(brew --prefix)/Frameworks/lsl.framework/Headers

This is effectively what you did, but more straightforward.

However, if you're building exclusively for Apple targets, I'd recommend #include <lsl/lsl_cpp.h>. I might try to head in this direction on non-Apple platforms too.

Note: Unfortunately, I couldn't find an environment variable that clang picks up to append to its Framework search paths. It seems you're using GNU Make, so LDLIBS += -F$(brew --prefix)/Frameworks is good, and it's also a generic solution that will apply to other brew-installed frameworks.

[cboulay]

Documented on dev in 19c439f. The README now covers version-independent Homebrew framework search paths, direct clang++ linking, both header spellings, and the CMake exported target. All three examples were compiled and run against the installed Homebrew package.