Bug 1449: Convert manual/index.html to `gfm` (GitHub-Flavored Markdown) using markdown -> manual/index.md and add conversion recipes + make/scripts/md2html_update.sh

Noyte: Additionally edited 'doc/misc/macos_nativelib_dependencies.md` to include `Use explicit OpenJDK/Temurin JDK `java` executable path` as a workaround to pass `DYLD_LIBRARY_PATH` to `/usr/bin/java`.
author: Sven Gothel <[email protected]> 2023-08-14 04:22:25 +0200
committer: Sven Gothel <[email protected]> 2023-08-14 04:22:25 +0200
commit: fd623305d90a88fd01dea3dccf6b9fe76b19703f (patch)
tree: c5bdaad79e250332f20ff91f14b4f0f7421ad3ee /doc/misc
parent: 9b825a445c3d2646546306c1815f498406e2f8c3 (diff)
2 files changed, 500 insertions, 2 deletions
diff --git a/doc/misc/macos_nativelib_dependencies.html b/doc/misc/macos_nativelib_dependencies.html
new file mode 100644
index 0000000..b4214ae
--- /dev/null
+++ b/doc/misc/macos_nativelib_dependencies.html
@@ -0,0 +1,485 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
+<head>
+  <meta charset="utf-8" />
+  <meta name="generator" content="pandoc" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
+  <title>macos_nativelib_dependencies.md</title>
+  <style>
+        div#header, header
+            {
+
+            border-bottom: 1px solid #aaa;
+            margin-bottom: 0.5em;
+            }
+
+        .title
+            {
+            text-align: center;
+            }
+
+        .author, .date
+            {
+            text-align: center;
+            }
+
+        div#TOC, nav#TOC
+            {
+
+            border-bottom: 1px solid #aaa;
+            margin-bottom: 0.5em;
+            }
+
+        nav#TOC {
+          margin-bottom: var(--line-height);
+
+          padding-bottom: 0.5rem;
+        }
+
+        nav#TOC input {
+          display: none;
+        }
+
+        nav#TOC label {
+          color: var(--color-link);
+          cursor: pointer;
+        }
+
+        nav#TOC > ul {
+          display: none;
+        }
+
+        nav#TOC > input:checked + ul {
+          display: block;
+        }
+
+        @media print
+            {
+            div#TOC, nav#TOC
+                {
+
+                display: none;
+                }
+            }
+
+        div.content
+            {
+                color: #111111;
+                font-size: 14px;
+                line-height: 1.6;
+            }
+
+        div#cgit a
+            {
+                color: #1212a0;
+            }
+
+        div#cgit a.sourceLine
+            {
+                color: #111111;
+            }
+
+        h1, h2, h3, h4, h5, h6
+        {
+            font-family: "Helvetica Neue", Helvetica, "Liberation Sans", Calibri, Arial, sans-serif;
+
+            page-break-after: avoid;
+
+            margin: 20px 0 10px;
+            padding: 0;
+        }
+
+        h2 {
+            border-bottom: 1px solid #ccc;
+        }
+
+        div div
+            {
+
+            }
+
+        section section
+            {
+            margin-left: 2em;
+            }
+
+        p {}
+
+        blockquote
+            {
+            font-style: italic;
+            }
+
+        li
+            {
+            }
+
+        li > p
+            {
+            margin-top: 1em;
+            }
+
+        ul
+            {
+            }
+
+        ul li
+            {
+            }
+
+        ol
+            {
+            }
+
+        ol li
+            {
+            }
+
+        hr {}
+
+        sub
+            {
+            }
+
+        sup
+            {
+            }
+
+        em
+            {
+            }
+
+        em > em
+            {
+            font-style: normal;
+            }
+
+        strong
+            {
+            }
+
+        a
+            {
+
+            text-decoration: none;
+            }
+
+        @media screen
+            {
+            a:hover
+                {
+
+                text-decoration: underline;
+                }
+            }
+
+        @media print
+            {
+            a {
+
+                color: black;
+                background: transparent;
+                }
+
+            a[href^="http://"]:after, a[href^="https://"]:after
+                {
+
+                content: " (" attr(href) ") ";
+                font-size: 90%;
+                }
+            }
+
+        img
+            {
+
+            vertical-align: middle;
+            }
+
+        div.figure
+            {
+
+            margin-left: auto;
+            margin-right: auto;
+            text-align: center;
+            font-style: italic;
+            }
+
+        p.caption
+            {
+
+            }
+
+        pre, code
+            {
+            background-color: #f8f8f8;
+
+            white-space: pre-wrap;
+            white-space: -moz-pre-wrap !important;
+            white-space: -pre-wrap;
+            white-space: -o-pre-wrap;
+            word-wrap: break-word;
+
+            }
+
+        pre
+            {
+
+            padding: 0.5em;
+            border-radius: 5px;
+
+            background-color: #f8f8f8;
+            border: 1px solid #ccc;
+            font-size: 13px;
+            line-height: 19px;
+            overflow: auto;
+            padding: 6px 10px;
+
+            margin-left: 0.5em;
+            margin-right: 0.5em;
+            }
+
+        @media screen
+            {
+            pre
+                {
+
+                white-space: pre;
+                overflow: auto;
+
+                border: 1px dotted #777;
+                }
+            }
+
+        code
+            {
+            }
+
+        p > code, li > code
+            {
+
+            padding-left: 2px;
+            padding-right: 2px;
+            }
+
+        li > p code
+            {
+
+            padding: 2px;
+            }
+
+        span.math
+            {
+
+            }
+
+        div.math
+            {
+            }
+
+        span.LaTeX
+            {
+            }
+
+        eq
+            {
+            }
+
+        table
+            {
+            border-collapse: collapse;
+            border-spacing: 0;
+
+            margin-left: auto;
+            margin-right: auto;
+            }
+
+        thead
+            {
+            border-bottom: 1pt solid #000;
+            background-color: #eee;
+            }
+
+        tr.header
+            {
+            }
+
+        tbody
+            {
+            }
+
+        tr {
+            }
+        tr.odd:hover, tr.even:hover
+            {
+            background-color: #eee;
+            }
+
+        tr.odd {}
+        tr.even {}
+
+        td, th
+            {
+            vertical-align: top;
+            vertical-align: baseline;
+            padding-left: 0.5em;
+            padding-right: 0.5em;
+            padding-top: 0.2em;
+            padding-bottom: 0.2em;
+            }
+        th
+            {
+            font-weight: bold;
+            }
+
+        tfoot
+            {
+            }
+
+        caption
+            {
+            caption-side: top;
+            border: none;
+            font-size: 0.9em;
+            font-style: italic;
+            text-align: center;
+            margin-bottom: 0.3em;
+            padding-bottom: 0.2em;
+            }
+
+        dl
+            {
+            border-top: 2pt solid black;
+            padding-top: 0.5em;
+            border-bottom: 2pt solid black;
+            }
+
+        dt
+            {
+            font-weight: bold;
+            }
+
+        dd+dt
+            {
+            border-top: 1pt solid black;
+            padding-top: 0.5em;
+            }
+
+        dd
+            {
+            margin-bottom: 0.5em;
+            }
+
+        dd+dd
+            {
+            border-top: 1px solid black;
+            }
+
+        a.footnote, a.footnoteRef {
+            font-size: small;
+            vertical-align: text-top;
+        }
+
+        a[href^="#fnref"], a.reversefootnote
+            {
+            }
+
+        @media print
+            {
+            a[href^="#fnref"], a.reversefootnote
+                {
+
+                display: none;
+                }
+            }
+
+        div.footnotes
+            {
+            }
+
+        div.footnotes li[id^="fn"]
+            {
+            }
+
+        @media print
+            {
+            .noprint
+                {
+                display:none;
+                }
+            }
+      </style>
+</head>
+<body>
+<nav id="TOC" role="doc-toc">
+    <strong>Contents</strong><label for="contents">⊕</label>
+  <input type="checkbox" id="contents">
+  <ul>
+  <li><a href="#loading-a-macos-native-librarys-dependencies">Loading a
+  MacOS Native Library's Dependencies</a>
+  <ul>
+  <li><a
+  href="#just-use-dynamic-loading-via-gluegens-procaddresstable">Just
+  use dynamic loading via GlueGen's ProcAddressTable</a></li>
+  <li><a href="#cant-pass-dyld_library_path-to-usrbinjava">Can't pass
+  <code>DYLD_LIBRARY_PATH</code> to <code>/usr/bin/java</code></a></li>
+  <li><a
+  href="#workaround-inability-to-pass-dyld_library_path-to-usrbinjava">Workaround
+  inability to pass <code>DYLD_LIBRARY_PATH</code> to
+  <code>/usr/bin/java</code></a>
+  <ul>
+  <li><a
+  href="#use-explicit-openjdktemurin-jdk-java-executable-path">Use
+  explicit OpenJDK/Temurin JDK <code>java</code> executable
+  path</a></li>
+  <li><a href="#using-loader_path-within-dependent-library">Using
+  ``@loader_path` within dependent library</a></li>
+  </ul></li>
+  </ul></li>
+  </ul>
+</nav>
+<h1 id="loading-a-macos-native-librarys-dependencies">Loading a MacOS
+Native Library's Dependencies</h1>
+<p>Assume we have <code>libBindingtest1p1.dylib</code>, which links to
+<code>libtest1.dylib</code>, i.e. requires the OS native library to load
+<code>libtest1.dylib</code> to resolve symbols.</p>
+<p>Usually we just se <code>DYLD_LIBRARY_PATH</code> including the path
+where <code>libtest1.dylib</code> is located and we are good to go.</p>
+<h2 id="just-use-dynamic-loading-via-gluegens-procaddresstable">Just use
+dynamic loading via GlueGen's ProcAddressTable</h2>
+<p>Note, the above problem does not occur when using GlueGen's
+ProcAddressTable, i.e. loading the underlying tool library
+<code>libtest2.dylib</code> w/ dlopen and passing all symbols to the JNI
+library <code>libBindingtest1p2.dylib</code>.</p>
+<h2 id="cant-pass-dyld_library_path-to-usrbinjava">Can't pass
+<code>DYLD_LIBRARY_PATH</code> to <code>/usr/bin/java</code></h2>
+<p>This is supposed to be related to MacOS's
+<code>System Integrity Protect (SIP)</code>.</p>
+<h2
+id="workaround-inability-to-pass-dyld_library_path-to-usrbinjava">Workaround
+inability to pass <code>DYLD_LIBRARY_PATH</code> to
+<code>/usr/bin/java</code></h2>
+<h3 id="use-explicit-openjdktemurin-jdk-java-executable-path">Use
+explicit OpenJDK/Temurin JDK <code>java</code> executable path</h3>
+<p>Interestingly passing <code>DYLD_LIBRARY_PATH</code> works using the
+explicit <code>java</code> executable path, set by default as
+follows:</p>
+<pre><code># MacOS: Select JVM path to allow DYLD_LIBRARY_PATH
+JAVA_HOME=`/usr/libexec/java_home -version 17`
+PATH=$JAVA_HOME/bin:$PATH
+export JAVA_HOME PATH</code></pre>
+<h3 id="using-loader_path-within-dependent-library">Using
+``@loader_path` within dependent library</h3>
+<p>Set location of referenced library <code>libtest1.dylib</code> to
+same path of dependent library <code>libBindingtest1p1.dylib</code>
+using <code>@loader_path</code>.</p>
+<pre><code>cd build-macosx/test/build/natives/
+otool -L libBindingtest1p1.dylib 
+install_name_tool -change libtest1.dylib @loader_path/libtest1.dylib libBindingtest1p1.dylib
+otool -L libBindingtest1p1.dylib </code></pre>
+<p>Further we could try <code>@executable_path</code> and
+<code>@rpath</code>.</p>
+<p>See <a
+href="https://www.joyfulbikeshedding.com/blog/2021-01-13-alternative-to-macos-dyld-library-path.html">An
+alternative to macOS's DYLD_LIBRARY_PATH</a>.</p>
+</body>
+</html>
diff --git a/doc/misc/macos_nativelib_dependencies.md b/doc/misc/macos_nativelib_dependencies.md
index 70d0973..6592c44 100644
--- a/doc/misc/macos_nativelib_dependencies.md
+++ b/doc/misc/macos_nativelib_dependencies.md
@@ -10,10 +10,23 @@ Note, the above problem does not occur when using GlueGen's ProcAddressTable,
 i.e. loading the underlying tool library `libtest2.dylib` w/ dlopen
 and passing all symbols to the JNI library `libBindingtest1p2.dylib`.
 
-## Can't pass `DYLD_LIBRARY_PATH` to `java`
+## Can't pass `DYLD_LIBRARY_PATH` to `/usr/bin/java`
 This is supposed to be related to MacOS's `System Integrity Protect (SIP)`.
 
-## Workaround inability to pass `DYLD_LIBRARY_PATH` to `java`
+## Workaround inability to pass `DYLD_LIBRARY_PATH` to `/usr/bin/java`
+
+### Use explicit OpenJDK/Temurin JDK `java` executable path
+
+Interestingly passing `DYLD_LIBRARY_PATH` works using the 
+explicit `java` executable path, set by default as follows:
+
+```
+# MacOS: Select JVM path to allow DYLD_LIBRARY_PATH
+JAVA_HOME=`/usr/libexec/java_home -version 17`
+PATH=$JAVA_HOME/bin:$PATH
+export JAVA_HOME PATH
+```        
+
 
 ### Using ``@loader_path` within dependent library
 Set location of referenced library `libtest1.dylib` to same path of dependent library `libBindingtest1p1.dylib`
author	Sven Gothel <[email protected]>	2023-08-14 04:22:25 +0200
committer	Sven Gothel <[email protected]>	2023-08-14 04:22:25 +0200
commit	fd623305d90a88fd01dea3dccf6b9fe76b19703f (patch)
tree	c5bdaad79e250332f20ff91f14b4f0f7421ad3ee /doc/misc
parent	9b825a445c3d2646546306c1815f498406e2f8c3 (diff)