+## Configuring PSI at build time
+
+PSI supports the following configure switches:
+
+### --enable-psi
+**Enable PHP System Interface support.**
+
+This is only relevant for an in-tree build. Use `--enable-psi` to include
+the PSI extension in the build.
+
+### --with-psi-libjit
+**Path to libjit.**
+
+> **WARNING:**
+> We currently rely on a patched libjit, because of an apparent bug in how
+> libjit creates closures, which still needs to be verified, though.
+> See https://github.com/m6w6/libjit for the preliminary patch.
+
+### --with-psi-libffi
+**Path to libffi.**
+
+## Configuring PSI at runtime
+
+### psi.engine
+
+The backend that PSI should use as FFI, either _jit_ for `libjit` or _ffi_ for `libffi`. Defaults to "ffi".
+
+### psi.directory
+
+A colon separated list of directories to scan for `*.psi` files. Defaults to "psi.d".
+
+### psi.blacklist.decls
+
+A comma separated list of C function declarations to ignore.
+
+### psi.blacklist.vars
+
+A comma separated list of C variable declarations to ignore.
+
+## PSI files
+
+PSI files are augmented C header files. So, everything usually found in C
+headers including comments, preprocessor directives, typedefs, structs,
+unions, enums, function and variable declarations should work.
+
+That means, that you can just include C headers in the usual way:
+
+```c
+#include <stdlib.h>
+```
+
+### Dynamic Libraries
+
+PSI needs to know which library it should `dlopen` unless the declared functions
+are provided by the standard C library. Therefore the PSI preprocessor
+understands a special pragma:
+
+```c
+#pragma lib "crypt"
+```
+
+### Constants
+
+```c
+const int num\ZERO = 0;
+const string pwd\TOKEN = "4WlOjXGL";
+```
+
+Constants must have namespaced identifiers and are registered as userland constants.
+
+C enums and preprocessor macros with numerical or string expressions are
+automatically discovered and registered as constants.
+
+### Implementations
+
+Implementations are the userland visible interfaces to the foreign function interface.
+
+```php
+function str\error(int $num) : string {
+ let errnum = intval($num);
+ return strerror(errnum) as to_string(strerror);
+}
+```
+
+Each implementation refers to exactly one declared foreign function referenced in its `return` statement. Each native function, on the other hand, may have any number of implementations.
+
+## Complete example
+
+```c
+#ifdef __linux__
+/* needed for setkey() in stdlib.h */
+# pragma lib "crypt"
+#endif
+
+/* for free() */
+#include <stdlib.h>
+
+#pragma lib "idn"
+#include <idna.h>
+
+function idn\utf8_to_ascii(string $host, string &$result, int $flags = 0) : int {
+ // there must be a `let` statement for each
+ // declared argument of the called function
+
+ // setup a pointer to NULL
+ let buffer = &NULL;
+
+ // setup a string pointer to $host
+ let host = strval($host);
+
+ // assing the integer value of $flags
+ let flags = intval($flags);
+
+ // the function to call is referenced in
+ // the return statement, along with the
+ // necessary cast how to interpret the
+ // returned native value
+ return idna_to_ascii_8z(host, buffer, flags)
+ as to_int(idna_to_ascii_8z);
+
+ // by-ref vars might receive output values
+ // through `set` statments, which also
+ // require a cast how to marshal the
+ // native data as PHP value
+ set $result = to_string(*buffer);
+
+ // after the buffer has been marshaled
+ // for the PHP engine, we have to free
+ // the buffer to avoid a memory leak
+ free free(*buffer);
+ // note that in this example we omit the
+ // declaration of the free() function called
+ // in our `free` statement for brevity
+}
projects / m6w6 / ext-psi / blobdiff