[Linux library management tool] In-depth analysis of the integration and application of pkg-config and CMake

Directory title

  • 1. Introduction
    • 1.1 The importance of `pkg-config`
    • 1.2 Article goals and readers
  • 2. `pkg-config` basics
    • 2.1 Principle
      • work process
      • Function and purpose
    • 2.2 Related commands
      • `pkg-config –cflags`
      • `pkg-config –libs`
      • `pkg-config –list-all`
      • `pkg-config –modversion`
      • Other commonly used commands
    • 2.3 Environment variables
  • 3. `.pc` file analysis
    • 3.1 `.pc` file structure
      • Basic fields
      • Compilation and linking fields
      • Custom variables
      • Conditional statements
    • 3.2 How to customize the `.pc` file
      • Create `.pc` file
      • Populate fields
      • Use variables and conditions
      • Validation and testing
    • 3.3 Advanced Usage and Extensions
      • variable substitution
      • Multi-platform support
      • Hooks and scripts
  • 4. Integrate pkg-config in CMake
    • 4.1 Basic integration method
      • Use `find_package(PkgConfig)`
      • Find library
      • Add compilation and linking options
    • 4.2 Customized pkg-config path
      • Set `PKG_CONFIG_PATH`
      • Use `find_program`
      • Verify settings
    • 4.3 Advanced Integration and Extensions
      • conditional compilation
      • Import and export configurations
      • Use scripts and custom commands
  • 5. Advanced usage and extensions
    • 5.1 Cross-platform support
      • Code Example: Cross-Platform Configuration
    • 5.2 Integrate into other build systems
      • Code Example: Integrating with Autotools
    • 5.3 Dynamically generate .pc file
      • Code example: Dynamically generate .pc file
    • 5.4 Version Control and Dependency Management
      • Code Example: Version Control
    • 5.5 Summary
  • Conclusion

1. Introduction

pkg-config is a tool for managing library files, which can help developers manage project dependencies and compilation settings more easily. This tool is particularly common on Linux and Unix systems, but there is a Windows version as well. Its main purpose is to provide a concise and consistent way to obtain compilation and linking information for a library.

1.1 The importance of pkg-config

When developing large software or multi-dependency projects, manually managing library and header file paths is not only tedious, but also error-prone. The emergence of pkg-config greatly simplifies this process. It uses a unified interface and a set of .pc files to make it extremely convenient to query the relevant information of the library.

As Bjarne Stroustrup said in “The C++ Programming Language”: “Managing your libraries and dependencies well is equivalent to solving more than half of the problems in software development.”

1.2 Article goals and readers

This article aims to provide a comprehensive and in-depth introduction to all aspects of pkg-config, from basic usage to advanced settings to how to integrate it in a CMake project. The article assumes that readers have a certain basic knowledge of Linux and programming, but does not require special pkg-config or CMake experience.

Through this article, you will not only master the daily usage of pkg-config, but also learn how to use it flexibly in complex projects and how to solve some common but difficult dependency problems.

While exploring these technical details, we will also occasionally consider how they impact our understanding of building and managing software, and how to organize code and resources more efficiently.

2. pkg-configBasics

2.1 Principle

pkg-config is a command line tool used to provide compilation and linking information for libraries. When you use external libraries in your project, you usually need to know the location of those libraries’ header files and library files. pkg-config provides this information by reading a specific .pc (Package Config) file.


  1. Query library information: When you execute the pkg-config command, it will first query the predefined directory (usually /usr/lib/pkgconfig/ code> or /usr/share/pkgconfig/) to find the .pc file related to the specified library.

  2. Read .pc file: After finding the .pc file, pkg-config will parse the fields in it. These Fields include, but are not limited to, Cflags (compile options) and Libs (link options).

  3. Output information: According to your command options (such as --cflags or --libs), pkg-config Corresponding information will be output, which can be directly used for compilation and linking.

Function and purpose

  • Simplified compilation and linking: By automatically providing the correct compilation and linking options, pkg-config reduces the complexity of manually managing these options.

  • Unified interface: Different libraries may have different configuration methods. pkg-config provides a unified interface, making it easier to handle multiple libraries.

  • Easy for automation: In build systems and scripts, pkg-config can automatically resolve dependency issues without manual intervention.

As Bjarne Stroustrup said in “The C++ Programming Language”: “Automation is not only a convenience, but also a need. It allows us to focus more on the problem itself, rather than the appearance of the problem.”

By understanding the basic principles and workflow of pkg-config, we can have a deeper understanding of its value in software development and how it simplifies and optimizes dependency management and project construction.

2.2 Related commands

pkg-config provides a series of command line options for querying and manipulating various information about the library. Here are some of the most commonly used commands:

pkg-config --cflags

This command is used to obtain the compilation options (Compile Flags) of the library. It outputs a series of compiler options, which usually include the path to the header file.

# Example
pkg-config --cflags gtk+-3.0

pkg-config --libs

This command is used to get the link flags of the library. It outputs a series of library file paths for linking and other link options.

# Example
pkg-config --libs gtk+-3.0

pkg-config --list-all

This command will list all installed libraries and .pc files that pkg-config can find.

# Example
pkg-config --list-all

pkg-config --modversion

This command is used to query the version information of the specified library.

# Example
pkg-config --modversion gtk + -3.0

Other commonly used commands

  • pkg-config --exists: Check whether the specified library exists
  • pkg-config --variable=xxx libname: Query the value of a library-specific variable

As Bjarne Stroustrup said in “The C++ Programming Language”: “Mastering the use of tools is equal to mastering half of the solution to the problem.”

Not only do these commands provide a wealth of information, they can also play an important role in automating scripts and build systems. By using these commands proficiently, you will be able to manage project dependencies and build processes more efficiently.

2.3 Environment variables

The behavior of pkg-config is affected by several key environment variables. These environment variables allow you to customize the behavior of pkg-config, making it more flexible and adaptable to different project needs.


This is the most commonly used environment variable, used to specify the search path for .pc files. When you install libraries in local or custom paths, you can set this environment variable to let pkg-config find them.

# Example
export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig


This environment variable is used to override the default .pc file search path. Unlike PKG_CONFIG_PATH, setting this variable completely replaces the default path, rather than adding to it.

# Example
export PKG_CONFIG_LIBDIR=/custom/lib/pkgconfig


These two environment variables are used to control whether pkg-config is allowed to use system-level CFLAGS and LIBS. This can be useful in cross-compiling or special environments.

# Example

As Bjarne Stroustrup said in “The C++ Programming Language”: “Environment variables are the ‘dark matter’ in software engineering. We cannot see them directly, but they are everywhere and affect every process.”

Understanding these environment variables not only helps us use pkg-config more efficiently, but also gives us a deeper understanding of the complexities of dependency management and project building.

3. .pcFile analysis

3.1 .pcFile structure

The .pc (Package Config) file is the core of the pkg-config tool. It contains the metadata of the library, such as header file paths, library file paths, compilation and linking options wait. A typical .pc file includes the following parts:

Basic fields

  • Name: The name of the library.
  • Description: A short description of the library.
  • Version: The version number of the library.

Compile and link fields

  • Cflags: Options required during compilation, usually including the header file path.
  • Libs: Options required when linking, usually including library file paths.

Custom variables

You can also define your own variables in the .pc file and use them in the Cflags and Libs fields.

# Sample .pc file
Name: MyLibrary
Description: A sample library
Version: 1.0.0
Cflags: -I${includedir}
Libs: -L${libdir} -lmylib

Conditional statement

The .pc file also supports conditional statements, which allow you to change compilation and linking options based on different conditions.

# Example conditional statement
Libs.private: @LIBS_PRIVATE@

As Bjarne Stroustrup said in “The C++ Programming Language”: “Properly organizing and managing code and configuration files is the key to successful software engineering.”

Understanding the basic structure and fields of the .pc file will help us use pkg-config more effectively and better manage project dependencies.

3.2 How to customize the .pc file

Customizing .pc files allows you to manage project dependencies and build processes more flexibly. Here are some key steps and considerations:

Create .pc file

First, create a new .pc file in your library or project directory. The file name is usually the same as the library name, but has a suffix of .pc.

# Example
touch mylibrary.pc

Fill fields

Populate the various fields of the .pc file according to the needs of your library or project. This usually includes Name, Description, Version, Cflags, and Libs, etc.

# mylibrary.pc sample content
Name: MyLibrary
Description: Custom library for special tasks
Version: 1.0.0
Cflags: -I${includedir}/mylibrary
Libs: -L${libdir} -lmylib

Using variables and conditions

You can use custom variables and conditional statements in the .pc file to adapt to different build environments and configurations.

# Add conditional statement
Libs.private: -lsomelib

Verification and testing

After finishing editing the .pc file, use the pkg-config command to verify and test to ensure that all settings are correct.

# Verification example
pkg-config --validate mylibrary.pc

As Bjarne Stroustrup said in “The C++ Programming Language”: “Preparation and verification in advance are the best ways to avoid trouble later.”

By following these steps, you can not only create a .pc file that works for your project, but you can also gain a deeper understanding of how dependency management and build systems work.

3.3 Advanced usage and extensions

The .pc file and the pkg-config tool provide some advanced usage and extended functionality to support more complex and specific needs.

Variable substitution

In the .pc file, you can use the ${variable} syntax for variable substitution. This allows you to reference a field or a custom variable within another field.

# Example

Multi-platform support

By using conditional statements and variables, you can create a cross-platform .pc file.

# Example
Libs: -L${libdir} -lmylib
Libs.private: @LIBS_PRIVATE@

Hooks and scripts

In some cases, you may need to run a custom script before or after pkg-config performs certain actions. Although this is not a standard feature of pkg-config, you can achieve it through environment variables or external tools.

# Example: Using environment variables to trigger scripts
export PKG_CONFIG_CMD="my_script.sh & amp; & amp; pkg-config"

As Bjarne Stroustrup said in “The C++ Programming Language”: “Software engineering is not just about writing code, but also about how to organize and extend code.”

These advanced usage and extension functions not only increase the flexibility of pkg-config, but also provide more possibilities, allowing us to better manage and build complex projects.

4. Integrate pkg-config in CMake

4.1 Basic integration method

CMake is a cross-platform build system that provides multiple ways to find and use external dependencies. pkg-config integrates well with CMake so that libraries managed by pkg-config can be used in CMake projects.

Use find_package(PkgConfig)

CMake provides a module named PkgConfig for finding and using pkg-config.

# CMakeLists.txt example
find_package(PkgConfig REQUIRED)

Search library

Use the pkg_search_module function to find the library you need.

# Find a library named 'mylib'
pkg_search_module(MYLIB REQUIRED mylib)

Add compilation and linking options

Once the required libraries are found, you can use the target_include_directories and target_link_libraries functions to set compilation and linking options.

# Set compilation and linking options
target_include_directories(my_target PUBLIC ${MYLIB_INCLUDE_DIRS})
target_link_libraries(my_target ${MYLIB_LIBRARIES})

As Bjarne Stroustrup said in “The C++ Programming Language”: “The build system is the foundation for the success of a software project. It affects the construction and distribution of the entire project.”

Through the above simple steps, you can integrate pkg-config in your CMake project to manage external dependencies more conveniently.

4.2 Customized pkg-config path

By default, pkg-config looks for the system-level environment variable path to locate the .pc file. But in some projects, you may want pkg-config to look for paths based on ${CMAKE_SOURCE_DIR}. This ensures that the pkg-config used by each CMake project is configured independently.


You can set the PKG_CONFIG_PATH environment variable through the set command in the CMakeLists.txt file.

# CMakeLists.txt example
set(ENV{PKG_CONFIG_PATH} "${CMAKE_SOURCE_DIR}/path/to/pc/files")

Use find_program

In addition to setting environment variables, you can also use find_program to locate the pkg-config executable file in a specific path.

# Find pkg-config under a specific path
find_program(PKG_CONFIG_EXECUTABLE NAMES pkg-config HINTS "${CMAKE_SOURCE_DIR}/path/to/pkg-config")

Authentication settings

To ensure that the path is set correctly, you can output the value of PKG_CONFIG_PATH during the CMake configuration phase for verification.


As Bjarne Stroustrup said in “The C++ Programming Language”: “The correct tools and configuration can greatly improve development efficiency.”

Through these methods, you can flexibly set the path of pkg-config in the CMake project to ensure more accurate and controllable dependency management.

4.3 Advanced Integration and Extensions

In the integration of CMake and pkg-config, there are also some advanced usages and extensions that allow you to more flexibly control the construction and dependency management of the project.

Conditional compilation

You can use CMake’s if statement and the output of pkg-config for conditional compilation.

# CMakeLists.txt example

Import and export configuration

If your project is also a dependency of other projects, you can use CMake’s export command to generate a .pc file so that other projects can pass pkg-config to find it.

# Export .pc file
configure_file(mylib.pc.in mylib.pc @ONLY)

Use scripts and custom commands

You can use CMake’s add_custom_command or add_custom_target to execute custom scripts or commands related to pkg-config.

# Add custom command
add_custom_command(OUTPUT ${OUTPUT}
                   COMMAND ${PKG_CONFIG_EXECUTABLE} --cflags mylib
                   COMMENT "Generating output using pkg-config")

As Bjarne Stroustrup said in “The C++ Programming Language”: “Flexibility and scalability are the keys to the long-term success of software.”

These advanced usages not only increase the flexibility of integration, but also provide more possibilities for complex projects.

5. Advanced usage and extensions

5.1 Cross-platform support

In this section, we’ll explore how to make pkg-config work on different operating system platforms. This is very useful for developers who need to deploy code in multiple environments.

Code example: cross-platform configuration

# On Linux and macOS
export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig

# On Windows
set PKG_CONFIG_PATH=C:\Program Files\pkg-config\lib\pkgconfig

5.2 Integration into other build systems

In addition to CMake, pkg-config can also be integrated with other build systems such as Autotools, Meson, etc.

Code example: Integration with Autotools

# configure.ac file
PKG_CHECK_MODULES([LIBFOO], [libfoo >= 1.0])

5.3 Dynamically generate .pc files

In some cases, we may need to dynamically generate .pc files. This is usually done during the installation of the software.

Code example: dynamically generate .pc file

# Dynamically generate libfoo.pc file
echo "prefix=/usr/local" > libfoo.pc
echo "libdir=\${prefix}/lib" >> libfoo.pc
echo "includedir=\${prefix}/include" >> libfoo.pc

5.4 Version Control and Dependency Management

Managing multiple library versions is a common challenge. pkg-config provides some advanced options to solve this problem.

Code Example: Version Control

# Query a specific version
pkg-config --modversion libfoo

5.5 Summary

Advanced usage and extensions not only provide more flexibility, but also solve more complex problems. These advanced features make pkg-config a powerful and flexible tool that can meet a variety of complex needs.

As Bjarne Stroustrup said in “The C++ Programming Language”: “Mastering the advanced features of a tool equals having more options for solving problems.”

The purpose of this chapter is to let you understand that no matter which platform or build system you are on, pkg-config has its unique value and application scenarios.

I hope this chapter can help you gain a deeper understanding of the advanced usage and extensibility of pkg-config. If you have additional questions or want to explore more, feel free to read on and practice.


In our programming learning journey, understanding is an important step for us to move to a higher level. However, mastering new skills and ideas always requires time and persistence. From a psychological point of view, learning is often accompanied by constant trial and error and adjustment, which is like our brain gradually optimizing its “algorithm” for solving problems.

That’s why when we encounter mistakes, we should view them as opportunities to learn and improve, not just as annoyances. By understanding and solving these problems, we can not only fix the current code, but also improve our programming skills and prevent making the same mistakes in future projects.

I encourage everyone to actively participate and continuously improve their programming skills. Whether you are a beginner or an experienced developer, I hope my blog will be helpful on your learning journey. If you find this article useful, you may wish to click to bookmark it, or leave your comments to share your insights and experiences. You are also welcome to make suggestions and questions about the content of my blog. Every like, comment, share and attention is the greatest support for me and the motivation for me to continue sharing and creating.

Read my CSDN homepage and unlock more exciting content: Bubble’s CSDN homepage