diff --git a/.gitignore b/.gitignore index 67bc9fa..30dbb1f 100644 --- a/.gitignore +++ b/.gitignore @@ -31,4 +31,4 @@ dockerfiles/build .scheme_testrunner retropikzel/pffi/version/main.sld retropikzel/pffi/version/main.rkt - +site diff --git a/README.md b/README.md index fe6f33a..a7e338a 100644 --- a/README.md +++ b/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 diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..4d09604 --- /dev/null +++ b/docs/index.md @@ -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) + diff --git a/docs/reference.md b/docs/reference.md new file mode 100644 index 0000000..d41bc94 --- /dev/null +++ b/docs/reference.md @@ -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 diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..07e5ca3 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1 @@ +site_name: r7rs-pffi