Using INTERFACE, ALIAS, and IMPORTED Libraries

An ALIAS library creates a second name for an existing target. It's not a copy; it's just a reference. Linking to the original name or the alias is identical.

A common convention in larger projects is to create "namespaced" aliases using the :: separator. When there are many targets, this convention makes the origin of a target clearer, and helps reduce the probability of naming conflicts.

Let's add an alias for our GreeterLib. We still need to use our regular name internally, but if our collection of Greeter targets is being shared for use in a larger project, providing namespaced aliases like Greeter::Lib and Greeter::App could be appreciated.

In a CMakeLists.txt, after defining the original target, we can add an alias like this:

1cmake_minimum_required(VERSION 3.16)
2
3add_library(GreeterLib src/Greeter.cpp)
4add_library(Greeter::Lib ALIAS GreeterLib) 
5
6target_include_directories(GreeterLib PUBLIC
7  "${CMAKE_CURRENT_SOURCE_DIR}/include"
8)

Consumers can now refer to our target using whichever name they prefer:

1cmake_minimum_required(VERSION 3.16)
2
3add_executable(GreeterApp src/main.cpp)
4
5# These two are equivalent
6target_link_libraries(GreeterApp GreeterLib)
7target_link_libraries(GreeterApp Greeter::Lib)

So far, we've only worked with targets built from source files within our project. But many library creators prefer not to share their source code. They distribute their libraries only in a precompiled form, alongside the header files describing what is in the library.

Handling such a dependency is the job of an IMPORTED library. It's a target that represents a binary that already exists on disk. You create the target and then manually set the properties that tell CMake where to find its files.

For example, let's imagine that our GreeterLib component is shared as a precompiled binary, rather than the complete source code. If you want to replice this scenario to follow along, you can find the compiled library in your /build/greeter directory, and copy it into a more permanant location in the project, such as /greeter/lib.

You can also delete the /greeter/src directory, or just pretend it doesn't exist. Your project directory might look something like this:

1(project root)/
2└─ greeter/
3   ├─ include/
4   │  └─ greeter/
5   │     └─ Greeter.h
6   ├─ lib/
7   │  └─ libgreeter.a
8   └─ CMakeLists.txt
9└─ ... (our other directories)

We need to update our greeter/CMakeLists.txt file to reflect this new situation. No longer is our build compiling GreeterLib from its /src directory - instead we need to import the already-compiled file from the /lib directory.

Lets take a look at the three changes we need to make, and then we'll walk through them step by step:

1cmake_minimum_required(VERSION 3.16)
2
3# 1. Change our library to IMPORTED STATIC GLOBAL
4add_library(GreeterLib src/Greeter.cpp)
5add_library(GreeterLib IMPORTED STATIC GLOBAL)
6
7# 2. Change our include directory visibility to INTERFACE
8target_include_directories(GreeterLib PUBLIC
9target_include_directories(GreeterLib INTERFACE
10  "${CMAKE_CURRENT_SOURCE_DIR}/include"
11)
12
13# 3. Provide the path to our prebuild binary
14set_target_properties(GreeterLib PROPERTIES 
15  # This property points to the actual binary file
16  IMPORTED_LOCATION "${CMAKE_CURRENT_SOURCE_DIR}/lib/libgreeter.a" 
17)

Step 1: Changing to an IMPORTED STATIC GLOBAL Library

Here's what these three keywords do:

IMPORTED: Instead of our add_library() command providing the list of source files, we now declare that the library is already compiled and only needs to be IMPORTED into our build.

STATIC: With IMPORTED libraries, we also need to explicitly state whether they are STATIC or SHARED. We'll revisit this topic in the next lesson and learn the difference between specifying and omitting the library type within an add_library() command.

GLOBAL: A side-effect of targets that are defined using the IMPORTED keyword is that their scope is restricted to just the CMakeLists.txt file in which they are declared. We can change this, and return GreeterLib to the global scope it previously had, by adding the GLOBAL keyword. This makes the target accessible to other CMakeLists.txt files in our build - most notably, the /app/CMakeLists.txt file, where GreeterApp declares GreeterLib as a dependency.

Step 2: Changing the Include Directories to INTERFACE

Previously, our target_include_directories() were declared as PUBLIC, as they were required both for GreeterLib and anything that consumes it.

With GreeterLib now being a precompiled IMPORTED library, it doesn't need these header files itself, as it no longer needs to be compiled. As such, we can restrict their visibility to just consumers by using the INTERFACE keyword.

Step 3: Setting the IMPORTED_LOCATION Property

Finally, and most obviously, we need to tell CMake where this precompiled library is on our hard drive. CMake expects this location to be provided as the IMPORTED_LOCATION property on the target. There is no convenient helper function for this, so we just use the general set_target_properties() function to set it:

1cmake_minimum_required(VERSION 3.16)
2
3add_library(GreeterLib STATIC IMPORTED GLOBAL)
4
5target_include_directories(GreeterLib INTERFACE
6  "${CMAKE_CURRENT_SOURCE_DIR}/include"
7)
8
9# This is where we attach the physical file locations to
10# our abstract target
11set_target_properties(GreeterLib PROPERTIES 
12  # This property points to the actual binary file
13  IMPORTED_LOCATION "${CMAKE_CURRENT_SOURCE_DIR}/lib/libgreeter.a" 
14)

Using the Imported Target

From the perspective of any other target, GreeterLib is just another library. The root CMakeLists.txt file continues to import it using add_subdirectory(), the app/CMakeLists.txt file for our GreeterApp target continues to link to it, and nothing in our source code needs to change either.

The IMPORTED keyword let us create a simple wrapper for a pre-compiled binary, allowed it to be integrating into our build just like any other target.

After a change like this, it is a good idea to clean out our /build directory by deleting everything in there. This removes old unused files still lurking around from previous builds and, when we next run the configure step, cmake will regenerate a fresh copy of just the stuff we need.

1cmake ..

We can then create a build and run app/GreeterApp or app/GreeterApp.exe to verify that everything still works after our changes:

1cmake --build .

1./app/GreeterApp

1Hello from the modular Greeter library!

This lesson introduced advanced target types that allow you to create clean, modular, and robust abstractions for your build logic and dependencies.

• INTERFACE Libraries as Property Groups: Use INTERFACE targets to bundle common sets of usage requirements (like compiler flags) that can be applied to other targets.
• ALIAS Libraries for Namespacing: Use add_library(... ALIAS ...) to create clean, namespaced Project::Component names for your targets. This is a key modern CMake best practice.
• IMPORTED Libraries for Binaries: Use add_library(... IMPORTED) to wrap pre-compiled third-party libraries. This creates a proper target that can be integrated into your dependency graph, abstracting away the physical file paths.

By mastering these patterns, you can move beyond simple builds and start designing sophisticated build systems that are a pleasure to work with, even as your projects scale in complexity.