# Portable Foreign Function Interface for R7RS schemes

Foreign function interface that is supported on multiple R7RS Sceheme implementations.

Note that this software is in **alpha** stage. That said the interface should not be changing anymore.

Any help in form of constructive advice and bug reports are appreciated.

[Documentation](https://retropikzel.neocities.org/r7rs-pffi/) or run mkdocs serve or see docs/.

[Issue trackers](https://sr.ht/~retropikzel/r7rs-pffi/trackers)

[Maling lists](https://sr.ht/~retropikzel/r7rs-pffi/lists)

For documentation see [retropikzel.neocities.org/r7rs-pffi](retropikzel.neocities.org/r7rs-pffi)
or run mkdocs serve or see or docs/ directory.

For status of what tests pass on which implementations see
[Jenkins](https://jenkins.staging.scheme.org/job/r7rs-pffi/job/master/).

## Goals

- Support only R7RS implementations
- Same interface on all implementations
  - Some things that are procedures on one implementation are macros on other,
  but they must behave the same

## Non goals

- To have every possible FFI feature
- Compiling of used library C code at any point
    - That is no stubs, no C code generated by the library and so on
    - The pffi library itself may require compilation on installation

## Status

Currently the interface of the library is in okay shape. It propably will not change much but no
guarantees are being made just yet.

## Implementation table

|                                 | Chibi | Chicken | Cyclone |  Gambit | Gauche | Gerbil | Guile | Kawa | Mosh | Racket | Sagittarius | Skint | STklos | tr7 |
| ------------------------------- | ----- | ------- | ------- | ------- | ------ | ------ | ----- | ---- | ---- | ------ | ----------- | ----- | ------ | --- |
| pffi-init                       | X     | X       | X       |         |        |        | X     | X    | X    | X      | X           |       | X      |     |
| pffi-size-of                    | X     | X       | X       |         |        |        | X     | X    | X    | X      | X           |       | X      |     |
| pffi-shared-object-auto-load    | X     | X       | X       |         |        |        | X     | X    | X    | X      | X           |       | X      |     |
| pffi-shared-object-load         | X     | X       | X       |         |        |        | X     | X    | X    | X      | X           |       | X      |     |
| pffi-pointer-null               | X     | X       | X       |         |        |        | X     | X    | X    | X      | X           |       | X      |     |
| pffi-pointer-null?              | X     | X       | X       |         |        |        | X     | X    | X    | X      | X           |       | X      |     |
| pffi-pointer-allocate           | X     | X       | X       |         |        |        | X     | X    | X    | X      | X           |       | X      |     |
| pffi-pointer?                   | X     | X       | X       |         |        |        | X     | X    | X    | X      | X           |       | X      |     |
| pffi-pointer-free               | X     | X       | X       |         |        |        | X     | X    | X    | X      | X           |       | X      |     |
| pffi-pointer-set!               | X     | X       | X       |         |        |        | X     | X    | X    | X      | X           |       |        |     |
| pffi-pointer-get                | X     | X       | X       |         |        |        | X     | X    | X    | X      | X           |       |        |     |
| pffi-string->pointer            | X     | X       | X       |         |        |        | X     | X    | X    | X      | X           |       |        |     |
| pffi-pointer->string            | X     | X       | X       |         |        |        | X     | X    | X    | X      | X           |       |        |     |
| pffi-define                     | X     | X       | X       |         |        |        | X     | X    | X    | X      | X           |       |        |     |
| pffi-define-callback            |       | X       |         |         |        |        | X     |      | X    | X      | X           |       |        |     |
| pffi-pointer-address            |       | X       |         |         |        |        | X     |      |      | X      | X           |       |        |     |
| pffi-pointer-dereference        |       |         |         |         |        |        | X     |      |      | X      | X           |       |        |     |

### Usage notes

- Chibi
    - Install libffi-dev
    - Build with:
      - chibi-ffi retropikzel/r7rs-pffi/r7rs-pffi-chibi.stub
      - ${CC} -o retropikzel/r7rs-pffi/r7rs-pffi-chibi.so -fPIC -shared retropikzel/r7rs-pffi/r7rs-pffi-chibi.c -lchibi-scheme -lffi
- Chicken 5
    - Needs [r7rs egg](https://wiki.call-cc.org/eggref/5/r7rs)
- Racket
    - Needs [racket-r7rs](https://github.com/lexi-lambda/racket-r7rs)
- Kawa
    - Needs at least Java version 22
    - Needs jvm flags:
        - --add-exports java.base/jdk.internal.foreign.abi=ALL-UNNAMED
        - --add-exports java.base/jdk.internal.foreign.layout=ALL-UNNAMED
        - --add-exports java.base/jdk.internal.foreign=ALL-UNNAMED
        - --enable-native-access=ALL-UNNAMED

### Design/exploration/waiting for implementation features

- [LIPS](https://lips.js.org/)
    - Will work on nodejs by using some C FFI library from npm
    - Javascript side needs design
- [Biwascheme](https://www.biwascheme.org/)
    - Will work on nodejs by using some C FFI library from npm
    - Javascript side needs design
- [MIT-Scheme](https://www.gnu.org/software/mit-scheme/)
- [s7](https://scheme.fail://ccrma.stanford.edu/software/snd/snd/s7.html)
- [Ypsilon](http://www.littlewingpinball.com/doc/en/ypsilon/)
- [Larceny](https://larcenists.org/)
- [Airship](https://gitlab.com/mbabich/airship-scheme)
- [Other gambit targets](https://gambitscheme.org/)
  - 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
- [s48-r7rs](https://codeberg.org/prescheme/s48-r7rs)
- [prescheme](https://codeberg.org/prescheme/prescheme)

### Will/can not be supported

- [Loko](https://scheme.fail/)
    - Desires no C interop, I can respect that