Linking h3-pg against the system libh3

[df7cb]

The h3-pg Debian package has been patched to properly link against a packaged version of libh3:

https://salsa.debian.org/postgresql/h3-pg/-/blob/master/debian/patches/include-dir?ref_type=heads
https://salsa.debian.org/postgresql/h3-pg/-/blob/master/debian/patches/use-system-libh3?ref_type=heads

So far, that worked.

The new h3-pg version 4.5.0 seems to require a lot of internal h3 headers beyond h3api.h though:

[ 49%] Linking C shared module h3.so
cd /home/myon/projects/postgresql/h3-pg/h3-pg/build-18/h3 && /usr/bin/cmake -E cmake_link_script CMakeFiles/postgresql_h3.dir/link.txt --verbose=1
/usr/lib/ccache/cc -fPIC -g -O2 -Werror=implicit-function-declaration -ffile-prefix-map=/home/myon/projects/postgresql/h3-pg/h3-pg=. -fstack-protector-strong -fstack-clash-protection -Wformat -Werror=format-security -fcf-protection -Wdate-time -D_FORTIFY_SOURCE=2 -flto=auto -fno-fat-lto-objects -shared -Wl,-z,relro -Wl,--dependency-file=CMakeFiles/postgresql_h3.dir/link.d  -o h3.so CMakeFiles/postgresql_h3.dir/src/binding/edge.c.o CMakeFiles/postgresql_h3.dir/src/binding/hierarchy.c.o CMakeFiles/postgresql_h3.dir/src/binding/indexing.c.o CMakeFiles/postgresql_h3.dir/src/binding/inspection.c.o CMakeFiles/postgresql_h3.dir/src/binding/miscellaneous.c.o CMakeFiles/postgresql_h3.dir/src/binding/regions.c.o CMakeFiles/postgresql_h3.dir/src/binding/traversal.c.o CMakeFiles/postgresql_h3.dir/src/binding/vertex.c.o CMakeFiles/postgresql_h3.dir/src/algos.c.o CMakeFiles/postgresql_h3.dir/src/deprecated.c.o CMakeFiles/postgresql_h3.dir/src/extension.c.o CMakeFiles/postgresql_h3.dir/src/guc.c.o CMakeFiles/postgresql_h3.dir/src/init.c.o CMakeFiles/postgresql_h3.dir/src/opclass_btree.c.o CMakeFiles/postgresql_h3.dir/src/opclass_gist.c.o CMakeFiles/postgresql_h3.dir/src/opclass_hash.c.o CMakeFiles/postgresql_h3.dir/src/opclass_spgist.c.o CMakeFiles/postgresql_h3.dir/src/operators.c.o CMakeFiles/postgresql_h3.dir/src/srf.c.o CMakeFiles/postgresql_h3.dir/src/type.c.o ../include/CMakeFiles/postgresql_h3_shared.dir/error.c.o  /usr/lib/x86_64-linux-gnu/libpq.so -lh3 /usr/lib/x86_64-linux-gnu/libpq.so
/home/myon/projects/postgresql/h3-pg/h3-pg/h3_postgis/src/wkb_regions.c:25:10: fatal error: linkedGeo.h: Datei oder Verzeichnis nicht gefunden
   25 | #include <linkedGeo.h>
      |          ^~~~~~~~~~~~~
compilation terminated.
In file included from /home/myon/projects/postgresql/h3-pg/h3-pg/h3_postgis/src/wkb_vertex_graph.c:24:
/home/myon/projects/postgresql/h3-pg/h3-pg/h3_postgis/src/wkb_vertex_graph.h:21:10: fatal error: latLng.h: Datei oder Verzeichnis nicht gefunden
   21 | #include <latLng.h>
      |          ^~~~~~~~~~
compilation terminated.

I can make the libh3.deb package contain these files, but then I still have to do a lot of patching to fix the paths to the header files.

Is there any chance to have this use case officially supported?

[Komzpa]

@df7cb it may be possible, however, it will require vendoring the pieces of h3 library on h3_pg side once again and probably defeat the purpose of you trying to reuse the system h3 library.

Other concern here is performance: h3_pg is supposed to be built with flags that allow the compiler to inline and simplify math across h3_pg > h3 > h3_pg boundary using LTO. If you're using shared system one you'll probably miss on that (or get the build that won't care about your system h3 update anyway) and we'd love to discourage that, as it's common to have h3 in "big data" pipelines.

What would be the best way from here?

[df7cb]

Fwiw I just tried shoveling all h3 .h files into libh3-dev and making h3-pg use -I/usr/include/h3 so we don't need that h3/ prefix in all #include <xx.h> calls. The patch for that is this:

Index: h3-pg/CMakeLists.txt
===================================================================
--- h3-pg.orig/CMakeLists.txt   2026-06-17 16:43:55.926341376 +0200
+++ h3-pg/CMakeLists.txt        2026-06-17 16:52:28.265284010 +0200
@@ -59,9 +59,6 @@ if(CMAKE_PROJECT_NAME STREQUAL PROJECT_N
   include(CTest)
 endif()
 
-# Include core library
-add_subdirectory(cmake/h3)
-
 # Include extensions and their shared code
 add_subdirectory(include)
 add_subdirectory(h3)
Index: h3-pg/h3/CMakeLists.txt
===================================================================
--- h3-pg.orig/h3/CMakeLists.txt        2026-06-17 16:43:55.926341376 +0200
+++ h3-pg/h3/CMakeLists.txt     2026-06-17 16:51:31.402853600 +0200
@@ -93,6 +93,7 @@ configure_file(src/config.h.in src/confi
 target_include_directories(postgresql_h3 PRIVATE
   ${CMAKE_CURRENT_BINARY_DIR}/src
   src
+  /usr/include/h3
 )
 
 # link
Index: h3-pg/h3_postgis/CMakeLists.txt
===================================================================
--- h3-pg.orig/h3_postgis/CMakeLists.txt        2026-06-08 03:55:17.000000000 +0200
+++ h3-pg/h3_postgis/CMakeLists.txt     2026-06-17 16:50:51.992554510 +0200
@@ -46,7 +46,7 @@ PostgreSQL_add_extension(postgresql_h3_p
 
 # link
 target_link_libraries(postgresql_h3_postgis PRIVATE postgresql_h3_shared h3)
-target_include_directories(postgresql_h3_postgis PRIVATE ${H3_INTERNAL_INCLUDE_DIR})
+target_include_directories(postgresql_h3_postgis PRIVATE /usr/include/h3)
 
 # Emit PostgreSQL JIT bitcode only after all include/link settings are final.
 PostgreSQL_add_extension_bitcode(postgresql_h3_postgis h3_postgis ${PROJECT_NAME})
Index: h3-pg/include/CMakeLists.txt
===================================================================
--- h3-pg.orig/include/CMakeLists.txt   2026-06-08 03:55:17.000000000 +0200
+++ h3-pg/include/CMakeLists.txt        2026-06-17 16:50:30.670392418 +0200
@@ -6,6 +6,6 @@ target_link_libraries(postgresql_h3_shar
 )
 target_include_directories(postgresql_h3_shared
   INTERFACE ./
-  PRIVATE ${H3_INCLUDE_DIR}
+  PRIVATE /usr/include/h3
 )
 set_target_properties(postgresql_h3_shared PROPERTIES POSITION_INDEPENDENT_CODE True)

After that, it still explodes:

In file included from /home/myon/projects/postgresql/h3-pg/h3-pg/h3/src/algos.c:24:
/home/myon/projects/postgresql/h3-pg/h3-pg/h3/src/upstream_macros.h:31:5: error: redeclaration of enumerator ‘CENTER_DIGIT’
   31 |     CENTER_DIGIT = 0,
      |     ^~~~~~~~~~~~
In file included from /usr/include/h3/algos.h:24,
                 from /home/myon/projects/postgresql/h3-pg/h3-pg/h3/src/algos.c:23:
/usr/include/h3/coordijk.h:71:5: note: previous definition of ‘CENTER_DIGIT’ with type ‘enum <anonymous>’
   71 |     CENTER_DIGIT = 0,
      |     ^~~~~~~~~~~~


In file included from /home/myon/projects/postgresql/h3-pg/h3-pg/h3/src/operators.c:21:
/home/myon/projects/postgresql/h3-pg/h3-pg/h3/src/operators.c: In function ‘h3index_overlaps’:
/home/myon/projects/postgresql/h3-pg/h3-pg/h3/src/operators.c:152:24: error: implicit declaration of function ‘containment’ [-Wimplicit-function-declaration]
  152 |         PG_RETURN_BOOL(containment(a, b) != 0);
      |                        ^~~~~~~~~~~

... and a few dozen similar messages.

[df7cb]

About the performance, did anyone measure how much difference LTO makes practically?

[df7cb]

I mean if it's totally not feasible or really makes sense to vendor-optimize it, then so be it and we can use the bundled version... 🙄

[Komzpa]

Per #75 LTO brings at least ~12-15%, there were follow ups to it afterwards that made it even faster.

Bringing in a new h3 minor release faster is probably a desired thing but I guess we need to find another way to do it...

[df7cb]

Building with the vendored h3 results in the message that the lib isn't vendored but needs to be downloaded first:

### PostgreSQL 18 run ###
+ dh_auto_configure -B build-18 -- -DPostgreSQL_CONFIG=/usr/lib/postgresql/18/bin/pg_config
        cd build-18 && DEB_PYTHON_INSTALL_LAYOUT=deb PKG_CONFIG=/usr/bin/pkg-config cmake -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=None -DCMAKE_INSTALL_SYSCONFDIR=/etc -DCMAKE_INSTALL_LOCALSTATEDIR=/var -DCMAKE_EXPORT_NO_PACKAGE_REGISTRY=ON -DCMAKE_FIND_USE_PACKAGE_REGISTRY=OFF -DCMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY=ON -DFETCHCONTENT_FULLY_DISCONNECTED=ON -DCMAKE_INSTALL_RUNSTATEDIR=/run -DCMAKE_SKIP_INSTALL_ALL_DEPENDENCY=ON "-GUnix Makefiles" -DCMAKE_VERBOSE_MAKEFILE=ON -DCMAKE_INSTALL_LIBDIR=lib/x86_64-linux-gnu -DPostgreSQL_CONFIG=/usr/lib/postgresql/18/bin/pg_config ..
...

CMake Warning at /usr/share/cmake-4.3/Modules/FetchContent.cmake:2124 (message):
  FETCHCONTENT_FULLY_DISCONNECTED is set to true, which requires the source
  directory for dependency h3 to already be populated.  This generally means
  it must not be set to true the first time CMake is run in a build
  directory.  The following source directory should already be populated, but
  it doesn't exist:

    /home/myon/projects/postgresql/h3-pg/h3-pg/build-18/_deps/h3-src

  Policy CMP0170 controls enforcement of this requirement.
Call Stack (most recent call first):
  /usr/share/cmake-4.3/Modules/FetchContent.cmake:2399 (__FetchContent_Populate)
  cmake/h3/CMakeLists.txt:18 (FetchContent_MakeAvailable)


CMake Error at cmake/h3/CMakeLists.txt:20 (set_target_properties):
  set_target_properties Can not find target to add properties to: h3


CMake Error at cmake/h3/CMakeLists.txt:26 (target_compile_options):
  Cannot specify compile options for target "h3" which is not built by this
  project.


-- Configuring incomplete, errors occurred!

We would need a tarball that contains the full source to be compiled.