编译C++程序时出现Mapnik未定义引用错误的原因排查

问题 #

我通过CMake从源码安装了Mapnik 4.0.0，尝试运行以下C++示例程序：

#define _GLIBCXX_USE_CXX11_ABI 0

#include <mapnik/map.hpp>
#include <mapnik/load_map.hpp>
#include <mapnik/agg_renderer.hpp>
#include <mapnik/image.hpp>
#include <mapnik/image_util.hpp>

int main()
{
    mapnik::Map m(256,256);
    mapnik::load_map(m, "/usr/share/renderd/example-map/mapnik.xml");
    m.zoom_all();
    mapnik::image_rgba8 im(256,256);
    mapnik::agg_renderer<mapnik::image_rgba8> ren(m, im);
    ren.apply();
    mapnik::save_to_file(im, "the_image.png");
    return 0;
}

使用编译命令：

g++ map-renderer.cpp -o a.out -L/usr/local/lib -lmapnik

但持续出现以下未定义引用错误：

g++ map-renderer.cpp -o a.out -L/usr/local/lib -lmapnik
/usr/bin/ld: /tmp/ccKF0om7.o: warning: relocation against `_ZN6mapnik22MAPNIK_GEOGRAPHIC_PROJE' in read-only section `.text'
/usr/bin/ld: /tmp/ccKF0om7.o: in function `main':
map-renderer.cpp:(.text+0x29): undefined reference to `mapnik::MAPNIK_GEOGRAPHIC_PROJ'
/usr/bin/ld: map-renderer.cpp:(.text+0x3e): undefined reference to `mapnik::Map::Map(int, int, std::string const&)'
/usr/bin/ld: map-renderer.cpp:(.text+0xc1): undefined reference to `mapnik::load_map(mapnik::Map&, std::string const&, bool, std::string)'
/usr/bin/ld: map-renderer.cpp:(.text+0x1cd): undefined reference to `void mapnik::save_to_file<mapnik::image<mapnik::rgba8_t> >(mapnik::image<mapnik::rgba8_t> const&, std::string const&)'
/usr/bin/ld: warning: creating DT_TEXTREL in a PIE
collect2: error: ld returned 1 exit status

我尝试过用CMake构建、运行默认bootstrap.sh脚本，但错误仍存在。看起来库的链接顺序是正确的，请问错误原因是什么？

解决方案 #

未定义引用的核心原因是手动编译时没有正确引入Mapnik的所有依赖库和编译参数。Mapnik作为复杂的地理渲染库，除主库libmapnik外，还依赖大量第三方库（如boost、proj、icu等），且需匹配正确的C++标准和ABI设置。

1. 使用mapnik-config自动获取编译链接参数 #

Mapnik安装后自带mapnik-config工具，可直接输出编译和链接所需的完整参数，避免手动遗漏：

g++ map-renderer.cpp -o a.out $(mapnik-config --cflags --libs)

若mapnik-config不在系统PATH中，可直接指定完整路径（如/usr/local/bin/mapnik-config）。

2. 确保C++11 ABI一致性 #

代码中定义了#define _GLIBCXX_USE_CXX11_ABI 0，需保证Mapnik编译时使用了相同的ABI设置：

• 若Mapnik是默认编译的，可能使用新ABI（_GLIBCXX_USE_CXX11_ABI=1），此时可删除代码中的宏定义；
• 若必须使用旧ABI，需重新编译Mapnik，在CMake或bootstrap.sh中添加-D_GLIBCXX_USE_CXX11_ABI=0参数。

3. 手动指定所有依赖库（备用方案） #

如果mapnik-config不可用，需手动指定编译标准、头文件路径、库路径及所有依赖库，且-lmapnik必须放在最后：

g++ map-renderer.cpp -o a.out -std=c++17 -I/usr/local/include/mapnik -L/usr/local/lib -lboost_system -lboost_filesystem -lproj -licuuc -licudata -lfreetype -lpng -ljpeg -lmapnik

注：不同系统和Mapnik版本的依赖库可能有差异，可通过ldd /usr/local/lib/libmapnik.so查看所有依赖项。

4. 验证Mapnik安装完整性 #

执行以下命令确认头文件和库文件路径正确：

# 检查核心头文件是否存在
ls /usr/local/include/mapnik/map.hpp
# 检查主库文件是否存在
ls /usr/local/lib/libmapnik.so

若文件不存在，说明Mapnik安装不完整，需重新编译安装，确保CMake或bootstrap.sh执行过程无报错。

内容的提问来源于stack exchange，提问作者syat-cd