cmake find_library和 add_library详解

Wan Ning yo

3 min read

·

30-12-2024

6

0

Share

This article provides a detailed explanation of find_library() and add_library() in CMake, two essential commands for managing libraries in your projects. We'll explore their usage, options, and best practices.

Understanding CMake's Role in Library Management

CMake is a powerful cross-platform build system generator. It doesn't directly build your project; instead, it generates build files (like Makefiles or Visual Studio projects) that your system then uses to compile and link your code. find_library() and add_library() are crucial for managing external and internal libraries within this process.

find_library(): Locating External Libraries

The find_library() command searches for libraries on your system. It's vital for linking against pre-built libraries that you don't build as part of your project (e.g., system libraries like pthread or third-party libraries).

Basic Syntax:

find_library(LIBRARY_NAME_VARIABLE NAME "library_name")

• LIBRARY_NAME_VARIABLE: The name of a CMake variable where the path to the found library will be stored. This variable will be empty if the library isn't found.
• NAME: The name of the library you're searching for (without the prefix like lib on Linux/macOS).
• "library_name": The actual name of the library file (with any prefix, extensions etc.). This is optional if the name matches the NAME argument.

Example: Finding the pthread library

find_library(pthread_LIBRARY NAMES pthread) 
if(NOT pthread_LIBRARY)
  message(FATAL_ERROR "pthread library not found!")
endif()

This searches for a library named pthread. If found, its path is stored in pthread_LIBRARY. The if statement checks for success and issues an error if the library isn't located.

Advanced Usage and Options:

• PATHS: Specify search directories. This prevents CMake from searching the entire system.

find_library(OpenCV_LIBS NAMES opencv_core PATHS /usr/local/lib /opt/opencv/lib)

• REQUIRED: Makes the search mandatory. If the library isn't found, CMake will stop with an error.

find_library(mylib REQUIRED NAMES mylib)

• NO_DEFAULT_PATH: Prevents CMake from searching default system paths. Useful when you want to force a specific search path.

Error Handling:

Always check if find_library() was successful. CMake provides variables that indicate the outcome, such as ${pthread_LIBRARY_FOUND} (which would be TRUE if found and FALSE otherwise). Proper error handling ensures your build process stops gracefully if dependencies are missing.

add_library(): Creating Your Own Libraries

add_library() is used to create libraries from the source code within your project. CMake then manages the compilation and linking of these libraries.

Basic Syntax:

add_library(library_name [SHARED|STATIC|MODULE] source1 source2 ... )

• library_name: The name of your library.
• SHARED|STATIC|MODULE: Specifies the library type:
  • SHARED: A shared library (.so on Linux/macOS, .dll on Windows).
  • STATIC: A static library (.a on Linux/macOS, .lib on Windows).
  • MODULE: A loadable module (specific to certain platforms). If omitted, the type is inferred from the source files.
• source1 source2 ...: List of source files for your library.

Example: Creating a Static Library:

add_library(mylib STATIC mylib.cpp mylib_helper.cpp)

This creates a static library named mylib from the source files mylib.cpp and mylib_helper.cpp.

Example: Creating a Shared Library:

add_library(mylib SHARED mylib.cpp mylib_helper.cpp)

This does the same but creates a shared library.

Object Libraries:

You can also create an object library, which is a collection of object files without creating a proper library archive:

add_library(mylib OBJECT mylib.cpp mylib_helper.cpp)

Working with Headers:

You'll likely want to include header files with your libraries. CMake doesn't directly handle this; you need to use target_include_directories() to specify where the header files are located.

add_library(mylib mylib.cpp)
target_include_directories(mylib PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include)

This adds the include directory in the current source directory to the include paths for mylib.

Linking Libraries:

After creating libraries using add_library(), you'll link them to your executables using target_link_libraries().

add_executable(myexe main.cpp)
target_link_libraries(myexe mylib)

This links the myexe executable to the mylib library.

Best Practices

• Use descriptive names: Choose meaningful names for your libraries and variables.
• Handle errors: Always check for successful find_library() calls.
• Organize your project: Structure your CMakeLists.txt file logically.
• Use version control: Track your CMake files in a repository for reproducibility.
• Document your CMake scripts: Add comments to explain your code's purpose and logic.

By mastering find_library() and add_library(), you'll gain essential skills for effectively managing libraries in your CMake projects, leading to cleaner, more maintainable, and robust builds.