Embedding pugixml in Your C++ Project: Build, Integrate, and Testpugixml is a lightweight, fast, and user-friendly C++ XML processing library. It balances ease of use with performance and a compact API, making it a popular choice for applications that need to parse, traverse, modify, or serialize XML. This article walks through embedding pugixml into your C++ project: choosing a build method, integrating it with modern C++ build systems, writing code that uses the library, and testing to ensure correct behavior and performance.
Why choose pugixml?
- Header-only convenience (optionally): pugixml can be built as a single header/source pair or used as a standard library, simplifying embedding.
- Performance: Designed for speed with a low memory footprint.
- Simple API: Uses intuitive DOM-like traversal and XPath support for queries.
- Permissive license: MIT-style license makes it suitable for commercial and open-source projects.
Two main ways to embed pugixml
- Use pugixml as source files added directly to your project (recommended for small projects or when you want single-file distribution).
- Build pugixml as a standalone library (static/shared) and link against it (recommended for larger projects, reuse across binaries, or to keep compile units smaller).
Both approaches are supported here with examples for CMake and a plain Makefile.
Obtaining pugixml
- Official repo: https://github.com/zeux/pugixml
- Release artifacts include pugixml.hpp and pugixml.cpp (and tests/examples).
Clone or download the repository and place pugixml.hpp / pugixml.cpp under your project’s third_party or external directory. Alternatively, use a package manager (vcpkg, Conan) to fetch pugixml automatically — examples for package managers are shown later.
Option A — Header + Source directly in project
This is the simplest approach: copy pugixml.hpp and pugixml.cpp into your project and compile them with the rest of your sources.
CMake example:
cmake_minimum_required(VERSION 3.10) project(MyApp) set(CMAKE_CXX_STANDARD 17) # Add pugixml source placed in third_party/pugixml add_library(pugixml STATIC third_party/pugixml/pugixml.cpp) target_include_directories(pugixml PUBLIC third_party/pugixml) add_executable(myapp src/main.cpp) target_link_libraries(myapp PRIVATE pugixml) Makefile example:
CXX = g++ CXXFLAGS = -std=c++17 -O2 -Ithird_party/pugixml SRC = src/main.cpp third_party/pugixml/pugixml.cpp OBJ = $(SRC:.cpp=.o) all: myapp myapp: $(OBJ) $(CXX) $(CXXFLAGS) -o $@ $^ clean: rm -f $(OBJ) myapp In your code:
#include "pugixml.hpp" int main() { pugi::xml_document doc; pugi::xml_parse_result result = doc.load_string("<root><item>value</item></root>"); if (!result) return 1; auto node = doc.child("root").child("item"); printf("value: %s ", node.child_value()); return 0; } Option B — Build pugixml as an external library
Build pugixml separately as a static or shared library and link it to multiple targets. This is cleaner for larger projects.
CMake example building pugixml and using it:
cmake_minimum_required(VERSION 3.10) project(MyApp) set(CMAKE_CXX_STANDARD 17) add_subdirectory(third_party/pugixml) # pugixml provides a CMakeLists.txt add_executable(myapp src/main.cpp) target_link_libraries(myapp PRIVATE pugixml) If using prebuilt system libraries, you can find_package or use a package manager:
- vcpkg: vcpkg install pugixml; integrate with CMake using toolchain.
- Conan: add pugixml reference to conanfile and link via targets.
Integration notes & build-time options
- Single-header compilation: pugixml is not strictly header-only; include the.cpp in one translation unit when you want to avoid linking complications.
- Compiler flags: Use -O2 or -O3 for release builds; you can enable or disable exceptions via compile-time defines if your project restricts them.
- Threading: pugixml is not inherently thread-safe for a single document; use separate documents per thread or external synchronization.
- Unicode handling: pugixml supports UTF-8 input and can convert; provide correctly encoded strings.
Using pugixml: core concepts and examples
Main classes:
- pugi::xml_document — in-memory XML DOM root.
- pugi::xml_node — node handle for elements, text, attributes.
- pugi::xml_attribute — attribute handle.
- pugi::xml_parse_result — result object with status and description.
Parsing examples:
Load from string:
pugi::xml_document doc; pugi::xml_parse_result result = doc.load_string("<root><v>1</v></root>"); Load from file:
pugi::xml_document doc; pugi::xml_parse_result result = doc.load_file("data.xml"); Traverse and read:
for (pugi::xml_node item : doc.child("root").children("item")) { printf("item: %s ", item.child_value()); } Modify and save:
pugi::xml_node root = doc.append_child("root"); root.append_child("item").append_child(pugi::node_pcdata).set_value("new"); doc.save_file("out.xml", PUGIXML_TEXT(" ")); XPath:
pugi::xpath_node_set nodes = doc.select_nodes("//item[@id='42']"); for (auto &x : nodes) { printf("%s ", x.node().child_value()); } Memory considerations:
- Documents own nodes; copying a document performs deep copy — avoid unnecessary copying.
- pugi::xml_document::reset() frees memory but fragmentation may remain depending on allocator.
Testing pugixml integration
Automated tests give confidence in parsing, serialization, and edge cases.
Unit test ideas:
- Parse valid and invalid XML strings; assert parse result status and error offsets.
- Round-trip: load_file -> save to string -> parse again and compare expected nodes/values.
- Attribute and namespace handling: ensure attributes, default values, and namespaces are preserved.
- Large document performance: measure parse time and memory use for large XML files.
- Concurrent access: validate separate documents parse correctly on multiple threads.
Example GoogleTest (simplified):
#include <gtest/gtest.h> #include "pugixml.hpp" TEST(PugiXml, ParseSimple) { pugi::xml_document doc; auto res = doc.load_string("<root><a>1</a></root>"); ASSERT_TRUE(res); ASSERT_STREQ(doc.child("root").child("a").child_value(), "1"); } Fuzzing and malformed input:
- Include tests with truncated tags, illegal characters, huge attribute values. pugixml’s parse_result contains error description and offset to assert proper failure behavior.
Performance testing:
- Use a benchmark harness (Google Benchmark or custom timing) to measure parse and serialize times across build types (-O0, -O3).
Debugging tips
- When parsing fails, check pugi::xml_parse_result::description() and offset.
- Enable assertions in debug builds to catch misuse early.
- Use doc.print() or save to an output string to inspect the document state.
- For memory issues, run under Valgrind or ASAN to detect leaks and invalid accesses.
Common pitfalls
- Forgetting to include pugixml.cpp in one translation unit leads to link errors for symbols if using the non-header-only setup.
- Assuming thread-safety for shared documents — use synchronization or separate documents per thread.
- Mishandling encodings — ensure UTF-8 input or perform proper conversion before feeding strings.
Packaging and distribution
- For apps that embed pugixml source files: include pugixml.hpp/.cpp under third_party and mention license in your distribution.
- For systems using package managers, declare dependency (vcpkg/conan) in your build scripts and CI.
- If building as a shared library, bump SONAME and manage ABI carefully.
Example: End-to-end minimal project
Project layout:
- CMakeLists.txt
- src/main.cpp
- third_party/pugixml/pugixml.hpp
- third_party/pugixml/pugixml.cpp
CMakeLists (minimal shown earlier) builds pugixml as a static library and links to myapp. main.cpp demonstrates reading a config.xml, modifying it, and saving.
Conclusion
Embedding pugixml into a C++ project is straightforward: include the provided source files or link to a built library, integrate with your build system, write DOM-based or XPath-driven code, and cover parsing/edge cases with unit and performance tests. For most projects, starting with the header+source approach is simplest; migrate to a shared/static library if reuse or build-time becomes a concern.