CMake Library Integration

Integrating Zep as a CMake library provides the best build performance and is ideal for production applications. This approach builds Zep separately and links it to your project.

Overview

The CMake library approach involves:

Building and installing Zep on your system
Using find_package() to locate Zep in your project
Linking against the installed library

Installation

Clone the Repository

Get the Zep source code:

git clone https://github.com/Rezonality/zep
cd zep
git submodule update --init

Configure Build Options

Create a build directory and configure with CMake:

mkdir build && cd build
cmake -G "Unix Makefiles" \
  -DBUILD_IMGUI=OFF \
  -DBUILD_TESTS=OFF \
  -DBUILD_DEMOS=OFF \
  -DCMAKE_BUILD_TYPE=Release \
  ..

Build and Install

Build the library and install it to your system:

cmake --build . --config Release --target install

This installs:

Headers to ${CMAKE_INSTALL_PREFIX}/include/zep/
Library to ${CMAKE_INSTALL_PREFIX}/lib/
CMake config files to ${CMAKE_INSTALL_PREFIX}/lib/cmake/zep/

On Linux/macOS, you may need sudo for the install step if installing to system directories. Alternatively, specify -DCMAKE_INSTALL_PREFIX=/path/to/local to install locally.

Build Options

Zep provides several CMake options to control what gets built:

Option	Default	Description
`BUILD_QT`	`OFF`	Build Qt rendering backend
`BUILD_IMGUI`	`OFF`	Build ImGui rendering backend
`BUILD_DEMOS`	`ON`	Build demo applications
`BUILD_TESTS`	`ON`	Build unit tests
`ZEP_FEATURE_CPP_FILE_SYSTEM`	`ON`	Enable C++17 filesystem support

Library-Only Build

For integration purposes, you typically want a minimal build:

cmake -DBUILD_IMGUI=OFF -DBUILD_TESTS=OFF -DBUILD_DEMOS=OFF ..

With ImGui Backend

If you need the ImGui backend pre-built:

cmake -DBUILD_IMGUI=ON -DBUILD_TESTS=OFF -DBUILD_DEMOS=OFF ..

With Qt Backend

For Qt applications:

cmake -DBUILD_QT=ON -DBUILD_TESTS=OFF -DBUILD_DEMOS=OFF ..

Building with BUILD_DEMOS=ON requires additional dependencies (SDL2, OpenGL, etc.). For library-only builds, keep this option off.

Using Zep in Your Project

Once installed, integrating Zep into your CMake project is straightforward.

Basic Integration

CMakeLists.txt

cmake_minimum_required(VERSION 3.2)
project(MyZepApp)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Find the installed Zep package
find_package(Zep REQUIRED)

# Your executable
add_executable(myapp
    src/main.cpp
    src/editor_window.cpp
)

# Link against Zep
target_link_libraries(myapp PRIVATE Zep::Zep)

That’s it! CMake will automatically:

Find the Zep headers and add them to your include path
Link the Zep library
Configure all necessary compiler settings

Custom Install Location

If you installed Zep to a custom location, tell CMake where to find it:

set(CMAKE_PREFIX_PATH "/path/to/zep/install" ${CMAKE_PREFIX_PATH})
find_package(Zep REQUIRED)

Or set it via command line:

cmake -DCMAKE_PREFIX_PATH=/path/to/zep/install ..

Complete Example

Here’s a complete example showing how to use the installed Zep library:

Project Structure

myproject/
├── CMakeLists.txt
└── src/
    └── main.cpp

CMakeLists.txt

cmake_minimum_required(VERSION 3.2)
project(ZepExample VERSION 1.0.0)

# C++17 required for Zep
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Find packages
find_package(Zep REQUIRED)

# If using ImGui, you'll also need to find it
# find_package(imgui REQUIRED)

# Create executable
add_executable(zep_example
    src/main.cpp
)

# Link libraries
target_link_libraries(zep_example 
    PRIVATE 
    Zep::Zep
    # Add your other dependencies (imgui, Qt, etc.)
)

# Optional: Enable warnings
if(MSVC)
    target_compile_options(zep_example PRIVATE /W4)
else()
    target_compile_options(zep_example PRIVATE -Wall -Wextra)
endif()

main.cpp

src/main.cpp

#include <zep/editor.h>
#include <zep/mode_vim.h>
#include <zep/mode_standard.h>
#include <zep/tab_window.h>
#include <zep/window.h>

// Include your display backend
#include <zep/imgui/editor_imgui.h>
#include <zep/imgui/display_imgui.h>

#include <imgui.h>

using namespace Zep;

int main()
{
    // Initialize your windowing/graphics system
    // ...
    
    // Create Zep editor
    auto pixelScale = NVec2f(1.0f, 1.0f);
    ZepEditor_ImGui editor("/path/to/config", pixelScale);
    
    // Load a file or create a buffer
    editor.InitWithText("example.cpp", "// Hello, Zep!\n");
    
    // Set editing mode
    editor.SetGlobalMode(ZepMode_Vim::StaticName());
    // or: editor.SetGlobalMode(ZepMode_Standard::StaticName());
    
    // Main loop
    while (running)
    {
        ImGui::NewFrame();
        
        ImGui::Begin("Zep Editor");
        
        // Get the region for the editor
        auto min = ImGui::GetCursorScreenPos();
        auto max = ImGui::GetContentRegionAvail();
        
        // Set display region
        editor.SetDisplayRegion(
            NVec2f(min.x, min.y),
            NVec2f(min.x + max.x, min.y + max.y)
        );
        
        // Display and handle input
        editor.Display();
        editor.HandleInput();
        
        ImGui::End();
        
        ImGui::Render();
        // Present frame...
    }
    
    return 0;
}

Building Your Project

Configure

mkdir build && cd build
cmake ..

Build

cmake --build . --config Release

Run

./zep_example

Advanced Configuration

Custom Zep Configuration

You can customize Zep’s behavior through CMake definitions:

target_compile_definitions(myapp PRIVATE
    ZEP_FEATURE_CPP_FILE_SYSTEM=1
)

Using Zep as a Submodule

If you prefer not to install Zep system-wide, you can add it as a submodule:

CMakeLists.txt

# Add Zep as a subdirectory
add_subdirectory(external/zep)

# Create your executable
add_executable(myapp src/main.cpp)

# Link against Zep
target_link_libraries(myapp PRIVATE Zep::Zep)

This builds Zep as part of your project without installation.

Installed Files

After installation, Zep provides:

Headers

${CMAKE_INSTALL_PREFIX}/include/zep/
├── buffer.h
├── editor.h
├── mode.h
├── mode_vim.h
├── mode_standard.h
├── window.h
├── tab_window.h
├── imgui/
│   ├── display_imgui.h
│   └── editor_imgui.h
└── qt/
    ├── zepdisplay_qt.h
    └── zepwidget_qt.h

CMake Config Files

${CMAKE_INSTALL_PREFIX}/lib/cmake/zep/
├── zep-config.cmake
├── zep-config-version.cmake
└── zep-targets.cmake

These files enable find_package(Zep) to work automatically.

Troubleshooting

CMake Can’t Find Zep

Problem: find_package(Zep) fails Solutions:

Set CMAKE_PREFIX_PATH: cmake -DCMAKE_PREFIX_PATH=/path/to/install ..
Check install location: find /usr -name "zep-config.cmake" 2>/dev/null
Verify installation: cmake --build . --target install completed successfully

Link Errors

Problem: Undefined references to Zep symbols Solutions:

Ensure you’re linking: target_link_libraries(myapp PRIVATE Zep::Zep)
Check that Zep was built with the same compiler
Verify C++ standard matches (both should use C++17)

Header Not Found

Problem: #include <zep/editor.h> not found Solution: Make sure you’re using the Zep::Zep target, which automatically adds include directories:

target_link_libraries(myapp PRIVATE Zep::Zep)  # Correct
# Don't manually add include directories

Get Started

Core Concepts

Integration

Guides

Advanced

CMake Library Integration

Overview

Installation

Build Options

Library-Only Build

With ImGui Backend

With Qt Backend

Using Zep in Your Project

Basic Integration

Custom Install Location

Complete Example

Project Structure

CMakeLists.txt

main.cpp

Building Your Project

Advanced Configuration

Custom Zep Configuration

Using Zep as a Submodule

Installed Files

Headers

CMake Config Files

Troubleshooting

CMake Can’t Find Zep

Link Errors

Header Not Found

Next Steps

ImGui Integration

Qt Integration

Build docs developers (and LLMs) love

Get Started

Core Concepts

Integration

Guides

Advanced

​Overview

​Installation

​Build Options

​Library-Only Build

​With ImGui Backend

​With Qt Backend

​Using Zep in Your Project

​Basic Integration

​Custom Install Location

​Complete Example

​Project Structure

​CMakeLists.txt

​main.cpp

​Building Your Project

​Advanced Configuration

​Custom Zep Configuration

​Using Zep as a Submodule

​Installed Files

​Headers

​CMake Config Files

​Troubleshooting

​CMake Can’t Find Zep

​Link Errors

​Header Not Found

​Next Steps

ImGui Integration

Qt Integration

Build docs developers (and LLMs) love

Overview

Installation

Build Options

Library-Only Build

With ImGui Backend

With Qt Backend

Using Zep in Your Project

Basic Integration

Custom Install Location

Complete Example

Project Structure

CMakeLists.txt

main.cpp

Building Your Project

Advanced Configuration

Custom Zep Configuration

Using Zep as a Submodule

Installed Files

Headers

CMake Config Files

Troubleshooting

CMake Can’t Find Zep

Link Errors

Header Not Found

Next Steps