doc: add FIXME explaining the situation

configure.py

@@ -97,12 +97,6 @@ def meson_string_array(arr):
     meson setup --native-file {args.ini} {args.build} {sourceDir}
     meson install -C {args.build}
     '''))
-    # for rpath in pkg_config_path:
-    #     fp.write(textwrap.dedent(f'''\
-    #     for exe in iguana-example-00-basic iguana-example-01-bank-rows; do
-    #       install_name_tool -add_rpath {rpath}/.. iguana/bin/$exe
-    #     done
-    #     '''))
 os.chmod(installScript, 0o744)
 print(f'''
 Generated installation script {installScript}

examples/build_with_meson/meson.build

@@ -13,9 +13,17 @@ iguana_dep = dependency('iguana')
 # set rpath
 # - this is so that the executable knows where the dependency libraries are
 # - alternatively, set $LD_LIBRARY_PATH before running your executables ($DYLD_LIBRARY_PATH on macOS)
-bin_rpaths = []
-bin_rpaths += hipo_dep.get_variable(pkgconfig: 'libdir')
+bin_rpaths = [
+  hipo_dep.get_variable(pkgconfig: 'libdir'),
+]
 if host_machine.system() != 'darwin'
+  # FIXME(darwin): not sure how to set multiple rpaths on darwin executables, aside
+  # from running `install_name_tool -add_rpath` post-installation; luckily,
+  # darwin-built examples only need `hipo_dep` libraries in the rpath and they
+  # don't need the `iguana` library path explictly included in the rpath, so
+  # this `if` block just keeps `bin_rpaths` to only one element. If we need
+  # more rpath elements someday, either we need to use `install_name_tool` or,
+  # preferably, resolution of https://github.com/mesonbuild/meson/issues/5760
   bin_rpaths += iguana_dep.get_variable(pkgconfig: 'libdir')
 endif
 

examples/meson.build

@@ -4,10 +4,17 @@ example_sources = [
 ]
 
 # add iguana libraries to rpath
-example_rpaths = []
-example_rpaths += hipo_dep.get_variable(pkgconfig: 'libdir')
-example_rpaths += fmt_dep.get_variable(pkgconfig: 'libdir') ### FIXME: this line is not needed, it's just a test
+example_rpaths [
+  hipo_dep.get_variable(pkgconfig: 'libdir'),
+]
 if host_machine.system() != 'darwin'
+  # FIXME(darwin): not sure how to set multiple rpaths on darwin executables, aside
+  # from running `install_name_tool -add_rpath` post-installation; luckily,
+  # darwin-built examples only need `hipo_dep` libraries in the rpath and they
+  # don't need the `iguana` library path explictly included in the rpath, so
+  # this `if` block just keeps `example_rpaths` to only one element. If we need
+  # more rpath elements someday, either we need to use `install_name_tool` or,
+  # preferably, resolution of https://github.com/mesonbuild/meson/issues/5760
   example_rpaths += '$ORIGIN' / '..' / get_option('libdir')
 endif
 
@@ -20,6 +27,6 @@ foreach src : example_sources
     dependencies:        project_deps,
     link_with:           project_libs,
     install:             true,
-    install_rpath:       ' '.join(example_rpaths),
+    install_rpath:       ':'.join(example_rpaths),
   )
 endforeach