How to Link a third Party Library (LibUSB) in CMake

Question

I am attempting to use LibUSB in a project. However whenever I attempt to use basic libUSB functions I get the following error:

...src/main/main.cpp.o: In function `main':
...src/main/main.cpp:10: undefined reference to `libusb_init'
...src/main/main.cpp:11: undefined reference to `libusb_set_debug'
collect2: error: ld returned 1 exit status

The package LibUSB-devel is installed (I'm on fedora 22) and my IDE KDevelop finds and recognises the headers, to the point it offers LibUSB code completions once you have added the import statement. I don't have any custom include lines in either my IDE or CMake (my build system) so I would like to know what I need to to to make CMake find the LibUSB headers.

This is the contents of main.cpp, just in case I messed something up:

#include <iostream>
#include <libusb-1.0/libusb.h>

int main(int argc, char **argv) {
      libusb_init(NULL);
      libusb_set_debug(NULL, LIBUSB_LOG_LEVEL_WARNING);

      /*snip*/

      std::cout << "Hello, world! PTPID="  << std::endl;
      return 0;
}

The following are the CMakeLists.txt:
../

cmake_minimum_required(VERSION 2.8.11)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++11")
set(CMAKE_BUILD_TYPE Debug)

project(aProjectThatHasHadIt'sNameObcured)
add_subdirectory(src)

.../src/cmakelists.txt just adds subdirectories

.../src/main/

add_executable(main main.cpp)

Answer 1

In general, to link a third party library, you need to add the include directory where the compiler will look for the headers, and the libraries which are used by the linker.
To add include directories use target_include_directories, to add a library to be linked to a target use target_link_libraries.
For libUSB and a testLibUSB.cpp source file this would result in

add_executable(targetTestLibUSB testLibUSB.cpp)
target_include_directories(targetTestLibUSB ${LIBUSB_INCLUDE_DIR})
target_link_libraries(targetTestLibUSB ${LIBUSB_LIBRARY})

If you have several targets, you might want to use include_directories and link_libraries before defining any target. These commands apply to all targets of a project after they are set and save a lot of repetition

You can specify the paths for LIBUSB_INCLUDE_DIR and LIBUSB_LIBRARY by hand. But more flexible and portable is to use CMake built-in mechanisms to find headers and libraries.
Header can be searched by find_path and libraries by find_library.
in your case this could be

find_path(LIBUSB_INCLUDE_DIR
  NAMES libusb.h
  PATH_SUFFIXES "include" "libusb" "libusb-1.0")
find_library(LIBUSB_LIBRARY
  NAMES usb
  PATH_SUFFIXES "lib" "lib32" "lib64")

The PATH_SUFFIXES are optional. If you have installed the library in a default location, CMake will find it automatically. Otherwise specify CMAKE_PREFIX_PATH and CMake will look for the headers and libraries there, too. You can specify the variable either by adding it in the CMake GUI or adding -DCMAKE_PREFIX_PATH=/path/to/add to your CMake call.

A common pitfall is to not delete the CMakeCache.txt file in the build directory. CMake caches the values for LIBUSB_INCLUDE_DIR and LIBUSB_LIBRARY and if you makes adjustment to the prefix path or your search logic, it still does not reevaluate the variable values but sticks to the cached values.

Answer 2

From your projects CMakeLists.txt file it doesn't become apparent to me how you've tried to link libusb. The way I would do is the following:

target_link_libraries(project_name <other_dependencies> usb-1.0)

(Just to clarify I mean the CMakeLIsts.txt file in which you add your executable)

You're trying to import from <libusb-1.0/...> thus you need to link usb-1.0 (the lib is always omitted from linker commands!)

I'm on Fedora 23, also using KDevelop and I didn't have to specify a path. Especially because on my system all the environment variables used in the previous answer are NULL anyways.

And to confirm where and how a library is installed in the future you can just do: locate libusb | grep .so

Hope this was somewhat helpful.

Answer 3

Since recently (May 2023) there is totally different alternative: https://github.com/libusb/libusb-cmake

A few things to be aware:

• as of this moment CMake exports/package is not available (i.e. CMake's find_package will not be of use);
• this is not officially supported by the mainline libusb maintainers, but hosted under Libusb Org. on Github and supported by the community;
• this is going to be the most useful for those who need to include libusb as part of their project as a subdirectory;