Update readme, improve documentation
This commit is contained in:
parent
b60defacb3
commit
efb8d48c6f
|
|
@ -31,4 +31,4 @@ dockerfiles/build
|
|||
.scheme_testrunner
|
||||
retropikzel/pffi/version/main.sld
|
||||
retropikzel/pffi/version/main.rkt
|
||||
|
||||
site
|
||||
|
|
|
|||
260
README.md
260
README.md
|
|
@ -2,12 +2,19 @@
|
|||
|
||||
Foreign function interface that is supported on multiple R7RS Sceheme implementations.
|
||||
|
||||
Note that this software is in alpha stage.
|
||||
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 tracker](https://todo.sr.ht/~retropikzel/r7rs-pffi)
|
||||
|
||||
[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.
|
||||
|
||||
## Goals
|
||||
|
||||
- Support only R7RS implementations
|
||||
|
|
@ -26,10 +33,15 @@ Any help in form of constructive advice and bug reports are appreciated.
|
|||
## Supported implementations
|
||||
|
||||
- [Sagittarius](https://bitbucket.org/ktakashi/sagittarius-scheme/wiki/Home)
|
||||
- Good support, recommended
|
||||
- [Guile](https://www.gnu.org/software/guile/)
|
||||
- Good support, recommended
|
||||
- [Racket](https://racket-lang.org/)
|
||||
- Good support, recommended
|
||||
- [Chicken](https://www.call-cc.org/)
|
||||
- Still needs work
|
||||
- [Gambit](https://gambitscheme.org)
|
||||
- Still needs work
|
||||
|
||||
## Supported excepts callbacks
|
||||
|
||||
|
|
@ -50,6 +62,7 @@ These implementations do not have callback support on their FFI. If I'm wrong pl
|
|||
- --add-exports java.base/jdk.internal.foreign.layout=ALL-UNNAMED
|
||||
- --add-exports java.base/jdk.internal.foreign=ALL-UNNAMED
|
||||
- --enable-native-access=ALL-UNNAMED
|
||||
- Good support (otherwise), recommended
|
||||
|
||||
## Support waiting for the implementation
|
||||
|
||||
|
|
@ -100,248 +113,5 @@ installed to run tests on large scale
|
|||
### Pull requests
|
||||
Pull requests for bug fixes, additional implementation support and additional tests are appreciated.
|
||||
But please do not change the interface (library exports) and if you add support for implementation
|
||||
then all exported procedures of main.sld need to be implemented and tests must pass.
|
||||
then all exported procedures of main.scm need to be implemented and tests must pass.
|
||||
|
||||
## Documentation
|
||||
|
||||
On some implementations these are procedures, on some macros.
|
||||
|
||||
The arguments are in form
|
||||
|
||||
- NAME - TYPE
|
||||
|
||||
The return value is in form
|
||||
|
||||
- TYPE
|
||||
|
||||
### Types
|
||||
|
||||
Types are given as symbols, for example 'int8 or 'pointer.
|
||||
|
||||
- int8
|
||||
- uint8
|
||||
- int16
|
||||
- uint16
|
||||
- int32
|
||||
- uint32
|
||||
- int64
|
||||
- uint64
|
||||
- char
|
||||
- unsigned-char
|
||||
- short
|
||||
- unsigned-short
|
||||
- int
|
||||
- unsigned-int
|
||||
- long
|
||||
- unsigned-long
|
||||
- float
|
||||
- double
|
||||
- string
|
||||
- pointer
|
||||
|
||||
|
||||
### Procedures or macros
|
||||
|
||||
#### pffi-shared-object-auto-load
|
||||
|
||||
Arguments:
|
||||
|
||||
- headers - (list string ...)
|
||||
- C headers of the library
|
||||
- For example (list "curl/curl.h")
|
||||
- object-name - symbol
|
||||
- The name of the dynamic library file you want to load
|
||||
- Without the "lib" in front of it
|
||||
- Without the ".so" or ".dll" at the end
|
||||
- additional-versions - (list string...)
|
||||
- For example (list ".0" ".1")
|
||||
- additional-paths - (list string...)
|
||||
- Any additional paths you want to search for the library
|
||||
- For example (list "./mylibs")
|
||||
|
||||
Returns:
|
||||
|
||||
- object
|
||||
- Shared object, the type depends on the implementation
|
||||
|
||||
#### pffi-shared-object-load
|
||||
|
||||
It is recommended to use the pffi-shared-object-auto-load instead of this
|
||||
directly.
|
||||
|
||||
Arguments:
|
||||
|
||||
- headers - (list string ...)
|
||||
- Headers that need to be included
|
||||
- Example (list "curl/curl.h")
|
||||
- path - string
|
||||
- The full path to the shared object you want to load, including any "lib" infront and .so/.dll at the end
|
||||
- Example "libcurl.so"
|
||||
|
||||
Returns:
|
||||
|
||||
- object
|
||||
- Shared object, the type depends on the implementation
|
||||
|
||||
|
||||
|
||||
#### pffi-define
|
||||
|
||||
Defines new foreign procedure.
|
||||
|
||||
Arguments:
|
||||
|
||||
- scheme-name
|
||||
- The name of the procedure used on scheme side
|
||||
- shared-object - object
|
||||
- The shared object
|
||||
- Use pffi-shared-object-auto-load or pffi-shared-object-load to get this
|
||||
- c-name - symbol
|
||||
- The name of the C function
|
||||
- return-type - symbol
|
||||
- The return type of the C function
|
||||
- arguments-types - (list symbol ...)
|
||||
- The C function argument types
|
||||
|
||||
#### pffi-define-callback
|
||||
|
||||
Defines new callback function.
|
||||
|
||||
Arguments:
|
||||
|
||||
- scheme-name
|
||||
- The name of the function used on scheme side
|
||||
- return-type - symbol
|
||||
- The return type of the callback
|
||||
- arguments-types - (list symbol ...)
|
||||
- The callback function argument types
|
||||
- procedure - procedure
|
||||
- Procedure used as callback function
|
||||
- Argument count must mathc the argument-types count
|
||||
|
||||
#### pffi-size-of
|
||||
|
||||
Get the size of type.
|
||||
|
||||
Arguments:
|
||||
|
||||
- type - symbol
|
||||
- The type you want the size of
|
||||
|
||||
Returns:
|
||||
|
||||
- number
|
||||
- The size of the given type
|
||||
|
||||
|
||||
#### pffi-pointer-allocate
|
||||
|
||||
Allocates a pointer of given size.
|
||||
|
||||
Arguments:
|
||||
|
||||
- size - number
|
||||
- The size of the pointer you want to allocate
|
||||
|
||||
Returns:
|
||||
|
||||
- object
|
||||
- A pointer of given size
|
||||
|
||||
|
||||
#### pffi-pointer-null
|
||||
|
||||
Create a null pointer.
|
||||
|
||||
Returns:
|
||||
- object
|
||||
- Null pointer
|
||||
|
||||
#### pffi-string->pointer
|
||||
|
||||
Arguments:
|
||||
|
||||
- string-content - string
|
||||
- The string you want to transform into pointer
|
||||
|
||||
Returns:
|
||||
|
||||
- object
|
||||
- Pointer of the given string
|
||||
|
||||
|
||||
#### pffi-pointer->string
|
||||
|
||||
Arguments:
|
||||
|
||||
- pointer - object
|
||||
- The pointer you want to transform to string
|
||||
|
||||
Returns:
|
||||
|
||||
- string
|
||||
- String from the given pointer
|
||||
|
||||
#### pffi-pointer-free
|
||||
|
||||
Arguments:
|
||||
|
||||
- pointer - object
|
||||
- The pointer you want to free
|
||||
|
||||
#### pffi-pointer?
|
||||
|
||||
Arguments:
|
||||
|
||||
- object - object
|
||||
- The object you want to check wether it is a pointer or not
|
||||
|
||||
Returns:
|
||||
|
||||
- boolean
|
||||
- Returns true if given object is pointer, otherwise false
|
||||
|
||||
|
||||
#### pffi-pointer-set!
|
||||
|
||||
Arguments:
|
||||
|
||||
- pointer - object
|
||||
- The pointer you want to modify
|
||||
- type - symbol
|
||||
- The type of value that will be put into the pointer
|
||||
- offset -number
|
||||
- The location of the value inside the pointer
|
||||
- For example: (+ (pffi-size-of 'int) (pffi-size-of 'pointer)) or 0
|
||||
- value - object
|
||||
- The value to be placed into the object
|
||||
|
||||
#### pffi-pointer-get
|
||||
|
||||
Arguments:
|
||||
|
||||
- pointer - object
|
||||
- The pointer you want to get the value from
|
||||
- type - symbol
|
||||
- The type of value you want to get
|
||||
- For example: 'int
|
||||
- offset - number
|
||||
- The location of the value inside the pointer
|
||||
- For example: (+ (pffi-size-of 'int) (pffi-size-of 'pointer)) or 0
|
||||
|
||||
Returns:
|
||||
|
||||
- object
|
||||
- The value in the poiner in the given offset as given type
|
||||
|
||||
#### pffi-pointer-deref
|
||||
|
||||
Arguments:
|
||||
|
||||
- pointer
|
||||
- The pointer to dereference
|
||||
|
||||
Returns:
|
||||
|
||||
- object
|
||||
- Whatever the pointer holds
|
||||
|
|
|
|||
|
|
@ -0,0 +1,16 @@
|
|||
# r7rs-pffi
|
||||
|
||||
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.
|
||||
|
||||
[Source](https://git.sr.ht/~retropikzel/r7rs-pffi)
|
||||
|
||||
[Issue tracker](https://todo.sr.ht/~retropikzel/r7rs-pffi)
|
||||
|
||||
[Maling lists](https://sr.ht/~retropikzel/r7rs-pffi/lists)
|
||||
|
||||
|
|
@ -0,0 +1,244 @@
|
|||
# Reference
|
||||
|
||||
# Types
|
||||
|
||||
Types are given as symbols, for example 'int8 or 'pointer.
|
||||
|
||||
- int8
|
||||
- uint8
|
||||
- int16
|
||||
- uint16
|
||||
- int32
|
||||
- uint32
|
||||
- int64
|
||||
- uint64
|
||||
- char
|
||||
- unsigned-char
|
||||
- short
|
||||
- unsigned-short
|
||||
- int
|
||||
- unsigned-int
|
||||
- long
|
||||
- unsigned-long
|
||||
- float
|
||||
- double
|
||||
- string
|
||||
- pointer
|
||||
|
||||
# Procedures or macros
|
||||
|
||||
On some implementations these are procedures, on some macros.
|
||||
|
||||
The arguments are in form
|
||||
|
||||
- NAME - TYPE
|
||||
|
||||
The return value is in form
|
||||
|
||||
- TYPE
|
||||
|
||||
|
||||
## pffi-shared-object-auto-load
|
||||
|
||||
Arguments:
|
||||
|
||||
- headers - (list string ...)
|
||||
- C headers of the library
|
||||
- For example (list "curl/curl.h")
|
||||
- object-name - symbol
|
||||
- The name of the dynamic library file you want to load
|
||||
- Without the "lib" in front of it
|
||||
- Without the ".so" or ".dll" at the end
|
||||
- additional-versions - (list string...)
|
||||
- For example (list ".0" ".1")
|
||||
- additional-paths - (list string...)
|
||||
- Any additional paths you want to search for the library
|
||||
- For example (list "./mylibs")
|
||||
|
||||
Returns:
|
||||
|
||||
- object
|
||||
- Shared object, the type depends on the implementation
|
||||
|
||||
## pffi-shared-object-load
|
||||
|
||||
It is recommended to use the pffi-shared-object-auto-load instead of this
|
||||
directly.
|
||||
|
||||
Arguments:
|
||||
|
||||
- headers - (list string ...)
|
||||
- Headers that need to be included
|
||||
- Example (list "curl/curl.h")
|
||||
- path - string
|
||||
- The full path to the shared object you want to load, including any "lib" infront and .so/.dll at the end
|
||||
- Example "libcurl.so"
|
||||
|
||||
Returns:
|
||||
|
||||
- object
|
||||
- Shared object, the type depends on the implementation
|
||||
|
||||
|
||||
|
||||
## pffi-define
|
||||
|
||||
Defines new foreign procedure.
|
||||
|
||||
Arguments:
|
||||
|
||||
- scheme-name - symbol
|
||||
- The name of the procedure used on scheme side
|
||||
- shared-object - object
|
||||
- The shared object
|
||||
- Use pffi-shared-object-auto-load or pffi-shared-object-load to get this
|
||||
- c-name - symbol
|
||||
- The name of the C function
|
||||
- return-type - symbol
|
||||
- The return type of the C function
|
||||
- arguments-types - (list symbol ...)
|
||||
- The C function argument types
|
||||
- Need to be given in form (list 'type 'type)
|
||||
|
||||
## pffi-define-callback
|
||||
|
||||
Defines new callback function.
|
||||
|
||||
Arguments:
|
||||
|
||||
- scheme-name
|
||||
- The name of the function used on scheme side
|
||||
- return-type - symbol
|
||||
- The return type of the callback
|
||||
- arguments-types - (list symbol ...)
|
||||
- The callback function argument types
|
||||
- procedure - procedure
|
||||
- Procedure used as callback function
|
||||
- Argument count must match the argument-types count
|
||||
|
||||
## pffi-size-of
|
||||
|
||||
Get the size of type.
|
||||
|
||||
Arguments:
|
||||
|
||||
- type - symbol
|
||||
- The type you want the size of
|
||||
|
||||
Returns:
|
||||
|
||||
- number
|
||||
- The size of the given type
|
||||
|
||||
|
||||
## pffi-pointer-allocate
|
||||
|
||||
Allocates a pointer of given size.
|
||||
|
||||
Arguments:
|
||||
|
||||
- size - number
|
||||
- The size of the pointer you want to allocate
|
||||
|
||||
Returns:
|
||||
|
||||
- object
|
||||
- A pointer of given size
|
||||
|
||||
|
||||
## pffi-pointer-null
|
||||
|
||||
Create a null pointer.
|
||||
|
||||
Returns:
|
||||
- object
|
||||
- Null pointer
|
||||
|
||||
## pffi-string->pointer
|
||||
|
||||
Arguments:
|
||||
|
||||
- string-content - string
|
||||
- The string you want to transform into pointer
|
||||
|
||||
Returns:
|
||||
|
||||
- object
|
||||
- Pointer of the given string
|
||||
|
||||
|
||||
## pffi-pointer->string
|
||||
|
||||
Arguments:
|
||||
|
||||
- pointer - object
|
||||
- The pointer you want to transform to string
|
||||
|
||||
Returns:
|
||||
|
||||
- string
|
||||
- String from the given pointer
|
||||
|
||||
## pffi-pointer-free
|
||||
|
||||
Arguments:
|
||||
|
||||
- pointer - object
|
||||
- The pointer you want to free
|
||||
|
||||
## pffi-pointer?
|
||||
|
||||
Arguments:
|
||||
|
||||
- object - object
|
||||
- The object you want to check wether it is a pointer or not
|
||||
|
||||
Returns:
|
||||
|
||||
- boolean
|
||||
- Returns true if given object is pointer, otherwise false
|
||||
|
||||
|
||||
## pffi-pointer-set!
|
||||
|
||||
Arguments:
|
||||
|
||||
- pointer - object
|
||||
- The pointer you want to modify
|
||||
- type - symbol
|
||||
- The type of value that will be put into the pointer
|
||||
- offset -number
|
||||
- The location of the value inside the pointer
|
||||
- For example: (+ (pffi-size-of 'int) (pffi-size-of 'pointer)) or 0
|
||||
- value - object
|
||||
- The value to be placed into the object
|
||||
|
||||
## pffi-pointer-get
|
||||
|
||||
Arguments:
|
||||
|
||||
- pointer - object
|
||||
- The pointer you want to get the value from
|
||||
- type - symbol
|
||||
- The type of value you want to get
|
||||
- For example: 'int
|
||||
- offset - number
|
||||
- The location of the value inside the pointer
|
||||
- For example: (+ (pffi-size-of 'int) (pffi-size-of 'pointer)) or 0
|
||||
|
||||
Returns:
|
||||
|
||||
- object
|
||||
- The value in the poiner in the given offset as given type
|
||||
|
||||
## pffi-pointer-deref
|
||||
|
||||
Arguments:
|
||||
|
||||
- pointer
|
||||
- The pointer to dereference
|
||||
|
||||
Returns:
|
||||
|
||||
- object
|
||||
- Whatever the pointer holds
|
||||
|
|
@ -0,0 +1 @@
|
|||
site_name: r7rs-pffi
|
||||
Loading…
Reference in New Issue