Improving documentation

This commit is contained in:
2025-03-12 15:52:31 +02:00
parent 1ba179d7cd
commit fe7822cb29
6 changed files with 1115 additions and 39 deletions
+980
View File
@@ -0,0 +1,980 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="date" content=''>
<title>Portable Foreign Function Interface for R7RS
Documentation</title>
<style>
h5 { font-weight: normal; }
table { width: 250%; }
nav { float: left; width: 20%;}
main { float: right; width: 80%; }
pre { background-color: lightgrey; }
</style>
</head>
<body>
<h1 id="portable-foreign-function-interface-for-r7rs">Portable
Foreign Function Interface for R7RS</h1>
<p>Portable foreign function interface for R7RS. It is portable
in the sense that it supports multiple implementations, as
opposed to being portable by conforming to some
specification.</p>
<p><a
href="https://todo.sr.ht/~retropikzel/r7rs-pffi">Project</a></p>
<p><a href="https://sr.ht/~retropikzel/r7rs-pffi/trackers">Issue
trackers</a></p>
<p><a href="https://sr.ht/~retropikzel/r7rs-pffi/lists">Maling
lists</a></p>
<p><a
href="https://jenkins.scheme.org/job/r7rs_pffi/job/r7rs-pffi/">Jenkins</a></p>
<h2 id="table-of-contents">Table of contents</h2>
<nav>
<ul>
<li><a href="#goals">Goals</a></li>
<li><a href="#non-goals">Non Goals</a></li>
<li><a href="#status">Status</a>
<ul>
<li><a href="#current-caveats">Current caveats</a></li>
</ul></li>
<li><a href="#implementation-table">Implementation table</a>
<ul>
<li><a href="#beta">Beta</a></li>
<li><a href="#alpha">Alpha</a></li>
<li><a href="#not-started">Not started</a></li>
<li><a href="#other">Other</a></li>
</ul></li>
<li><a href="#documentation">Documentation</a>
<ul>
<li><a href="#usage">Usage</a>
<ul>
<li><a href="#usage-chibi">Chibi</a></li>
<li><a href="#usage-chicken">Chicken</a></li>
<li><a href="#usage-racket">Racket</a></li>
<li><a href="#usage-kawa">Kawa</a></li>
</ul></li>
<li><a href="#reference">Reference</a></li>
<li><a href="#types">Types</a></li>
<li><a href="#procedures-and-macros">Procedures and macros</a>
<ul>
<li><a href="#pffi-init">pffi-init</a></li>
<li><a href="#pffi-size-of">pffi-size-of</a></li>
<li><a href="#pffi-align-of">pffi-align-of</a></li>
<li><a
href="#pffi-shared-object-auto-load">pffi-shared-object-auto-load</a></li>
<li><a
href="#pffi-shared-object-load">pffi-shared-object-load</a></li>
<li><a href="#pffi-pointer-null">pffi-pointer-null</a></li>
<li><a href="#pffi-pointer-null?">pffi-pointer-null?</a></li>
<li><a
href="#pffi-pointer-allocate">pffi-pointer-allocate</a></li>
<li><a
href="#pffi-pointer-address">pffi-pointer-address</a></li>
<li><a href="#pffi-pointer?">pffi-pointer?</a></li>
<li><a href="#pffi-pointer-free">pffi-pointer-free</a></li>
<li><a href="#pffi-pointer-set!">pffi-pointer-set!</a></li>
<li><a href="#pffi-pointer-get">pffi-pointer-get</a></li>
<li><a
href="#pffi-string-to-pointer">pffi-string-&gt;pointer</a></li>
<li><a
href="#pffi-pointer-to-string">pffi-pointer-&gt;string</a></li>
<li><a href="#pffi-struct-make">pffi-struct-make</a></li>
<li><a href="#pffi-struct-pointer">pffi-struct-pointer</a></li>
<li><a
href="#pffi-struct-offset-get">pffi-struct-offset-get</a></li>
<li><a href="#pffi-struct-get">pffi-struct-get</a></li>
<li><a href="#pffi-struct-set!">pffi-struct-set!</a></li>
<li><a href="#pffi-define">pffi-define</a></li>
<li><a
href="#pffi-define-callback">pffi-define-callback</a></li>
</ul></li>
</ul></li>
</ul>
</nav>
<main>
<h2 id="goals">Goals</h2>
<p><a name="goals"></a></p>
<ul>
<li>Support only R7RS implementations</li>
<li>Same interface on all implementations
<ul>
<li>Some things that are procedures on one implementation are
macros on other, but they must behave the same</li>
</ul></li>
<li>Stability and being boring after 1.0.0 is reached</li>
</ul>
<h2 id="non-goals">Non goals</h2>
<p><a name="non-goals"></a></p>
<ul>
<li>To have every possible FFI feature</li>
<li>Compiling of used library C code at any point
<ul>
<li>That is no stubs, no C code generated by the library and so
on</li>
<li>The pffi library itself may require compilation on
installation</li>
</ul></li>
</ul>
<h2 id="status">Status</h2>
<p><a name="status"></a></p>
<p>Currently the interface of the library is in okay shape. It
propably will not change much but no guarantees are being made
just yet.</p>
<p>Due to supporting many different Scheme implementations,
different parts of this software are in different stage. As a
whole it is still in <strong>alpha</strong> stage. That said the
interface should not be changing anymore and some
implementations are in <strong>beta</strong>.</p>
<h3 id="current-caveats">Current caveats</h3>
<p><a name="current-caveats"></a></p>
<ul>
<li>No way to pass structs by value</li>
<li>Most implementations are missing callback support</li>
</ul>
<h2 id="implementation-table">Implementation table</h2>
<p><a name="implementation-table"></a></p>
<h3 id="beta">Beta</h3>
<p><a name="beta"></a></p>
<table>
<colgroup>
<col style="width: 3%" />
<col style="width: 2%" />
<col style="width: 3%" />
<col style="width: 7%" />
<col style="width: 5%" />
<col style="width: 4%" />
<col style="width: 4%" />
<col style="width: 5%" />
<col style="width: 5%" />
<col style="width: 3%" />
<col style="width: 4%" />
<col style="width: 4%" />
<col style="width: 4%" />
<col style="width: 5%" />
<col style="width: 5%" />
<col style="width: 4%" />
<col style="width: 4%" />
<col style="width: 5%" />
<col style="width: 3%" />
<col style="width: 4%" />
<col style="width: 3%" />
<col style="width: 5%" />
</colgroup>
<thead>
<tr class="header">
<th></th>
<th style="text-align: center;">pffi-init</th>
<th style="text-align: center;">pffi-size-of</th>
<th
style="text-align: center;">pffi-shared-object-auto-load</th>
<th style="text-align: center;">pffi-shared-object-load</th>
<th style="text-align: center;">pffi-pointer-null</th>
<th style="text-align: center;">pffi-pointer-null?</th>
<th style="text-align: center;">pffi-pointer-allocate</th>
<th style="text-align: center;">pffi-pointer-address</th>
<th style="text-align: center;">pffi-pointer?</th>
<th style="text-align: center;">pffi-pointer-free</th>
<th style="text-align: center;">pffi-pointer-set!</th>
<th style="text-align: center;">pffi-pointer-get</th>
<th style="text-align: center;">pffi-string-&gt;pointer</th>
<th style="text-align: center;">pffi-pointer-&gt;string</th>
<th style="text-align: center;">pffi-struct-make</th>
<th style="text-align: center;">pffi-struct-pointer</th>
<th style="text-align: center;">pffi-struct-offset-get</th>
<th style="text-align: center;">pffi-struct-get</th>
<th style="text-align: center;">pffi-struct-set!</th>
<th style="text-align: center;">pffi-define</th>
<th style="text-align: center;">pffi-define-callback</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>Chibi</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
</tr>
<tr class="even">
<td>Gauche</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
</tr>
<tr class="odd">
<td>Guile</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
</tr>
<tr class="even">
<td>Kawa</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
</tr>
<tr class="odd">
<td>Racket</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
</tr>
<tr class="even">
<td>Saggittarius</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
</tr>
</tbody>
</table>
<h3 id="alpha">Alpha</h3>
<p><a name="alpha"></a></p>
<table>
<colgroup>
<col style="width: 3%" />
<col style="width: 2%" />
<col style="width: 3%" />
<col style="width: 7%" />
<col style="width: 5%" />
<col style="width: 4%" />
<col style="width: 4%" />
<col style="width: 5%" />
<col style="width: 5%" />
<col style="width: 3%" />
<col style="width: 4%" />
<col style="width: 4%" />
<col style="width: 4%" />
<col style="width: 5%" />
<col style="width: 5%" />
<col style="width: 4%" />
<col style="width: 4%" />
<col style="width: 5%" />
<col style="width: 3%" />
<col style="width: 4%" />
<col style="width: 3%" />
<col style="width: 5%" />
</colgroup>
<thead>
<tr class="header">
<th></th>
<th style="text-align: center;">pffi-init</th>
<th style="text-align: center;">pffi-size-of</th>
<th
style="text-align: center;">pffi-shared-object-auto-load</th>
<th style="text-align: center;">pffi-shared-object-load</th>
<th style="text-align: center;">pffi-pointer-null</th>
<th style="text-align: center;">pffi-pointer-null?</th>
<th style="text-align: center;">pffi-pointer-allocate</th>
<th style="text-align: center;">pffi-pointer-address</th>
<th style="text-align: center;">pffi-pointer?</th>
<th style="text-align: center;">pffi-pointer-free</th>
<th style="text-align: center;">pffi-pointer-set!</th>
<th style="text-align: center;">pffi-pointer-get</th>
<th style="text-align: center;">pffi-string-&gt;pointer</th>
<th style="text-align: center;">pffi-pointer-&gt;string</th>
<th style="text-align: center;">pffi-struct-make</th>
<th style="text-align: center;">pffi-struct-pointer</th>
<th style="text-align: center;">pffi-struct-offset-get</th>
<th style="text-align: center;">pffi-struct-get</th>
<th style="text-align: center;">pffi-struct-set!</th>
<th style="text-align: center;">pffi-define</th>
<th style="text-align: center;">pffi-define-callback</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>Chicken-5</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
</tr>
<tr class="even">
<td>Cyclone</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
</tr>
<tr class="odd">
<td>Gambit</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
</tr>
<tr class="even">
<td>Gerbil</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
</tr>
<tr class="odd">
<td>Larceny</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
</tr>
<tr class="even">
<td>Mosh</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
</tr>
<tr class="odd">
<td>Skint</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
</tr>
<tr class="even">
<td>Stklos</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
</tr>
<tr class="odd">
<td>tr7</td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
</tr>
<tr class="even">
<td>Ypsilon</td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;">X</td>
<td style="text-align: center;"></td>
<td style="text-align: center;"></td>
</tr>
</tbody>
</table>
<h3 id="not-started">Not started</h3>
<p><a name="not-started"></a></p>
<ul>
<li><a href="https://lips.js.org/">LIPS</a>
<ul>
<li>Will work on nodejs by using some C FFI library from
npm</li>
<li>Javascript side needs design</li>
</ul></li>
<li><a href="https://www.biwascheme.org/">Biwascheme</a>
<ul>
<li>Will work on nodejs by using some C FFI library from
npm</li>
<li>Javascript side needs design</li>
</ul></li>
<li><a
href="https://www.gnu.org/software/mit-scheme/">MIT-Scheme</a>
<ul>
<li>Need to study the implementation more</li>
</ul></li>
<li><a
href="https://gitlab.com/mbabich/airship-scheme">Airship</a>
<ul>
<li>Need to study the implementation more</li>
</ul></li>
<li><a href="https://gambitscheme.org/">Other gambit targets</a>
<ul>
<li>Gambit compiles to different targets other than C too, for
example Javascript. It would be cool and interesting to see if
this FFI could also support some of those</li>
<li>When LIPS and Biwascheme Javascript side is done then Gambit
should be done too</li>
</ul></li>
<li><a
href="https://codeberg.org/prescheme/s48-r7rs">s48-r7rs</a>
<ul>
<li>Need to study the implementation more</li>
</ul></li>
<li><a
href="https://codeberg.org/prescheme/prescheme">prescheme</a>
<ul>
<li>Need to study the implementation more</li>
</ul></li>
</ul>
<h3 id="other">Other</h3>
<p><a name="other"></a></p>
<ul>
<li><a
href="https://scheme.fail://ccrma.stanford.edu/software/snd/snd/s7.html">s7</a>
<ul>
<li>Propably does not need FFI as it is embeddable only</li>
</ul></li>
<li><a href="https://scheme.fail/">Loko</a>
<ul>
<li>Desires no C interop, I can respect that</li>
</ul></li>
</ul>
<h2 id="documentation">Documentation</h2>
<p><a name="documentation"></a></p>
<h3 id="usage">Usage</h3>
<p><a name="usage"></a></p>
<h4 id="chibi">Chibi</h4>
<p><a name="usage-chibi"></a></p>
<p>Needs libffi-dev, on Debina/Ubuntu/Mint install with:</p>
<pre><code>apt install libffi-dev</code></pre>
<p>Build with:</p>
<pre><code>chibi-ffi retropikzel/r7rs-pffi/r7rs-pffi-chibi.stub
gcc -o retropikzel/r7rs-pffi/r7rs-pffi-chibi.so -fPIC -shared retropikzel/r7rs-pffi/r7rs-pffi-chibi.c -lchibi-scheme -lffi</code></pre>
<h4 id="chicken">Chicken</h4>
<p><a name="usage-chicken"></a></p>
<p>Needs <a href="https://wiki.call-cc.org/eggref/5/r7rs">r7rs
egg</a>, install with:</p>
<pre><code>chicken-install r7rs</code></pre>
<h4 id="racket">Racket</h4>
<p><a name="usage-racket"></a></p>
<p>Needs <a
href="https://github.com/lexi-lambda/racket-r7rs">racket-r7rs</a>,
install with:</p>
<pre><code>raco pkg install --auto r7rs</code></pre>
<h4 id="kawa">Kawa</h4>
<p><a name="usage-kawa"></a></p>
<p>Kawa Needs at least Java version 22</p>
<p>Needs jvm flags:</p>
<ul>
<li>–add-exports
java.base/jdk.internal.foreign.abi=ALL-UNNAMED</li>
<li>–add-exports
java.base/jdk.internal.foreign.layout=ALL-UNNAMED</li>
<li>–add-exports java.base/jdk.internal.foreign=ALL-UNNAMED</li>
<li>–enable-native-access=ALL-UNNAMED</li>
</ul>
<h3 id="reference">Reference</h3>
<p><a name="reference"></a></p>
<h4 id="types">Types</h4>
<p><a name="types"></a></p>
<p>Types are given as symbols, for example ’int8 or
’pointer.</p>
<ul>
<li>int8</li>
<li>uint8</li>
<li>int16</li>
<li>uint16</li>
<li>int32</li>
<li>uint32</li>
<li>int64</li>
<li>uint64</li>
<li>char</li>
<li>unsigned-char</li>
<li>short</li>
<li>unsigned-short</li>
<li>int</li>
<li>unsigned-int</li>
<li>long</li>
<li>unsigned-long</li>
<li>float</li>
<li>double</li>
<li>pointer</li>
<li>callback
<ul>
<li>Callback function</li>
</ul></li>
</ul>
<h4 id="procedures-and-macros">Procedures and macros</h4>
<p><a name="procedures-and-macros"></a></p>
<p>Some of these are procedures and some macros, it might also
change implementation to implementation.</p>
<h5 id="pffi-init"><strong>pffi-init</strong></h5>
<p><a name="pffi-init"></a></p>
<p>Always call this first, on most implementation it does
nothing but some implementations might need initialisation
run.</p>
<h5
id="pffi-size-of-object---number"><strong>pffi-size-of</strong>
object -&gt; number</h5>
<p><a name="pffi-size-of"></a></p>
<p>Returns the size of the pffi-struct, pffi-enum or
pffi-type.</p>
<h5
id="pffi-align-of-type---number"><strong>pffi-align-of</strong>
type -&gt; number</h5>
<p><a name="pffi-align-of"></a></p>
<p>Returns the align of the type.</p>
<h5
id="pffi-shared-object-auto-load-headers-shared-object-name-options---object"><strong>pffi-shared-object-auto-load</strong>
headers shared-object-name [options] -&gt; object</h5>
<p><a name="pffi-shared-object-auto-load"></a></p>
<p>Load given shared object automatically searching many
predefined paths.</p>
<p>Takes as argument a list of C headers, these are for the
compiler ones. And an shared-object name, used by the dynamic
FFI’s. The name of the shared object should not contain suffix
like .so or .dll. Nor should it contain any prefix like
“lib”.</p>
<p>Additional options argument can be provided, theys should be
a pair with a keyword. The options are:</p>
<ul>
<li>additional-versions
<ul>
<li>Search for additional versions of shared object, given
shared object “c” and additional versions “6” “7” on linux the
files “libc”, “libc.6”, “libc.7” are searched for.</li>
<li>Can be either numbers or strings</li>
</ul></li>
<li>additional-paths
<ul>
<li>Give additional paths to search shared objects for</li>
</ul></li>
</ul>
<p>Example:</p>
<pre><code>(define libc-stdlib
(cond-expand
(windows (pffi-shared-object-auto-load (list &quot;stdlib.h&quot;) &quot;ucrtbase&quot;))
(else (pffi-shared-object-auto-load (list &quot;stdlib.h&quot;)
&quot;c&quot;
&#39;(additional-versions . (&quot;6&quot;))
&#39;(additional-search-paths . (&quot;.&quot;))))))</code></pre>
<h5
id="pffi-shared-object-load-headers-path-options"><strong>pffi-shared-object-load</strong>
headers path [options]</h5>
<p><a name="pffi-shared-object-load"></a></p>
<p>It is recommended to use the pffi-shared-object-auto-load
instead of this directly.</p>
<p>Headers is a list of strings needed to be included, for
example</p>
<pre><code>(list &quot;curl/curl.h&quot;)</code></pre>
<p>Path is the full path of the shared object without any “lib”
prefix or “.so/.dll” suffix. For example:</p>
<pre><code>&quot;curl&quot;</code></pre>
<p>Options:</p>
<ul>
<li>additional-versions
<ul>
<li>List of different versions of library to try, for example
(list “.0” “.1”)</li>
</ul></li>
</ul>
<h5
id="pffi-pointer-null---pointer"><strong>pffi-pointer-null</strong>
-&gt; pointer</h5>
<p><a name="pffi-pointer-null"></a></p>
<p>Returns a new NULL pointer.</p>
<h5
id="pffi-pointer-null-pointer---boolean"><strong>pffi-pointer-null?</strong>
pointer -&gt; boolean</h5>
<p><a name="pffi-pointer-null?"></a></p>
<p>Returns #t if given pointer is null pointer, #f
otherwise.</p>
<h5
id="pffi-pointer-allocate-size---pointer"><strong>pffi-pointer-allocate</strong>
size -&gt; pointer</h5>
<p><a name="pffi-pointer-allocate"></a></p>
<p>Returns newly allocated pointer of given size.</p>
<h5
id="pffi-pointer-address-pointer---number"><strong>pffi-pointer-address</strong>
pointer -&gt; number</h5>
<p><a name="pffi-pointer-address"></a></p>
<p>Returns the address of given pointer as number.</p>
<h5
id="pffi-pointer-object---boolean"><strong>pffi-pointer?</strong>
object -&gt; boolean</h5>
<p><a name="pffi-pointer?"></a></p>
<p>Returns #t if given object is pointer, #f otherwise.</p>
<h5
id="pffi-pointer-free-pointer"><strong>pffi-pointer-free</strong>
pointer</h5>
<p><a name="pffi-pointer-free"></a></p>
<p>Frees given pointer.</p>
<h5
id="pffi-pointer-set-pointer-type-offset-value"><strong>pffi-pointer-set!</strong>
pointer type offset value</h5>
<p><a name="pffi-pointer-set!"></a></p>
<p>Sets the value on a pointer on given offset. For example:</p>
<pre><code>(define p (pffi-pointer-allocate 128))
(pffi-pointer-set! p &#39;int 64 100)</code></pre>
<p>Would set the offset of 64, on pointer p to value 100.</p>
<h5
id="pffi-pointer-get-pointer-type-offset---object"><strong>pffi-pointer-get</strong>
pointer type offset -&gt; object</h5>
<p><a name="pffi-pointer-get"></a></p>
<p>Gets the value from a pointer on given offset. For
example:</p>
<pre><code>(define p (pffi-pointer-allocate 128))
(pffi-pointer-set! p &#39;int 64 100)
(pffi-pointer-get p &#39;int 64)
&gt; 100</code></pre>
<h5
id="pffi-string-pointer-string---pointer"><strong>pffi-string-&gt;pointer</strong>
string -&gt; pointer</h5>
<p><a name="pffi-string-to-pointer"></a></p>
<p>Makes pointer out of a given string.</p>
<h5
id="pffi-pointer-string-pointer---string"><strong>pffi-pointer-&gt;string</strong>
pointer -&gt; string</h5>
<p><a name="pffi-pointer-to-string"></a></p>
<p>Makes string out of a given pointer.</p>
<h5
id="pffi-struct-make-c-type-members-.-pointer---pffi-struct"><strong>pffi-struct-make</strong>
c-type members . pointer -&gt; pffi-struct</h5>
<p><a name="pffi-struct-make"></a></p>
<p>Creates a new pffi-struct and allocates pointer for it. The
members argument is a list of member names and types. For
example:</p>
<pre><code>(define color (pffi-struct-make &#39;color &#39;((int8 . r) (int8 . g) (int8 . b) (int8 .a ))))
(define test (pffi-struct-make &quot;struct test&quot; &#39;((int8 . r) (int8 . g) (int8 . b) (int8 .a ))))</code></pre>
<p>C-type argument can be symbol or a string.</p>
<h5
id="pffi-struct-pointer-pffi-struct---pointer"><strong>pffi-struct-pointer</strong>
pffi-struct -&gt; pointer</h5>
<p><a name="pffi-struct-pointer"></a></p>
<p>Returns the pointer that holds the struct content. You need
to use this when passing a struct as a pointer to foreign
functions.</p>
<pre><code>(define s (pffi-struct-make &#39;test &#39;((int . r) (int . g) (int . b))))
(pffi-struct-pointer s)</code></pre>
<h5
id="pffi-struct-offset-get-member-name---number"><strong>pffi-struct-offset-get</strong>
member-name -&gt; number</h5>
<p><a name="pffi-struct-offset-get"></a></p>
<p>Returns the offset of a struct member with given name.</p>
<h5
id="pffi-struct-get-pffi-struct-member-name---object"><strong>pffi-struct-get</strong>
pffi-struct member-name -&gt; object</h5>
<p><a name="pffi-struct-get"></a></p>
<p>Returns the value of the givens struct member.</p>
<h5
id="pffi-struct-set-pffi-struct-member-name-value"><strong>pffi-struct-set!</strong>
pffi-struct member-name value</h5>
<p><a name="pffi-struct-set!"></a></p>
<p>Sets the value of the givens struct member. It is up to you
to make sure that the type of value is correct.</p>
<h5
id="pffi-define-scheme-name-shared-object-c-name-return-type-argument-types"><strong>pffi-define</strong>
scheme-name shared-object c-name return-type argument-types</h5>
<p><a name="pffi-define"></a></p>
<p>Defines a new foreign function to be used from Scheme code.
For example:</p>
<pre><code>(define libc-stdlib
(cond-expand
(windows (pffi-shared-object-auto-load (list &quot;stdlib.h&quot;) (list) &quot;ucrtbase&quot; (list &quot;&quot;)))
(else (pffi-shared-object-auto-load (list &quot;stdlib.h&quot;) (list) &quot;c&quot; (list &quot;&quot; &quot;6&quot;)))))
(pffi-define c-puts libc-stdlib &#39;puts &#39;int (list &#39;pointer))
(c-puts &quot;Message brought to you by FFI!&quot;)</code></pre>
<h5
id="pffi-define-callback-scheme-name-return-type-argument-types-procedure"><strong>pffi-define-callback</strong>
scheme-name return-type argument-types procedure</h5>
<p><a name="pffi-define-callback"></a></p>
<p>Defines a new Sceme function to be used as callback to C
code. For example:</p>
<pre><code>; Load the shared library
(define libc-stdlib
(cond-expand
(windows (pffi-shared-object-auto-load (list &quot;stdlib.h&quot;) (list) &quot;ucrtbase&quot; (list &quot;&quot;)))
(else (pffi-shared-object-auto-load (list &quot;stdlib.h&quot;) (list) &quot;c&quot; (list &quot;&quot; &quot;6&quot;)))))
; Define C function that takes a callback
(pffi-define qsort libc-stdlib &#39;qsort &#39;void (list &#39;pointer &#39;int &#39;int &#39;callback))
; Define our callback
(pffi-define-callback compare
&#39;int
(list &#39;pointer &#39;pointer)
(lambda (pointer-a pointer-b)
(let ((a (pffi-pointer-get pointer-a &#39;int 0))
(b (pffi-pointer-get pointer-b &#39;int 0)))
(cond ((&gt; a b) 1)
((= a b) 0)
((&lt; a b) -1)))))
; Create new array of ints to be sorted
(define array (pffi-pointer-allocate (* (pffi-size-of &#39;int) 3)))
(pffi-pointer-set! array &#39;int (* (pffi-size-of &#39;int) 0) 3)
(pffi-pointer-set! array &#39;int (* (pffi-size-of &#39;int) 1) 2)
(pffi-pointer-set! array &#39;int (* (pffi-size-of &#39;int) 2) 1)
(display array)
(newline)
;&gt; (3 2 1)
; Sort the array
(qsort array 3 (pffi-size-of &#39;int) compare)
(display array)
(newline)
;&gt; (1 2 3)</code></pre>
</main>
</body>
</html>
Binary file not shown.