8,236
edits
Difference between revisions of "JS-ctypes"
Jump to navigation
Jump to search
no edit summary
| (3 intermediate revisions by one other user not shown) | |||
| Line 4: | Line 4: | ||
== JS-ctypes == | == JS-ctypes == | ||
ctypes is a [http://en.wikipedia.org/wiki/Foreign_function_interface Foreign Function Interface] which is available in several languages. It allows one to call C functions (of a library) from Javascript or Python or other language supporting it. | ctypes is a [http://en.wikipedia.org/wiki/Foreign_function_interface Foreign Function Interface] which is available in [http://sourceware.org/libffi/ several languages]. It allows one to call C functions (of a library) from Javascript or Python or other language supporting it. | ||
It doesn't require specific C code. It just calls arbitrary functions. | It doesn't require specific C code. It just calls arbitrary functions. | ||
| Line 92: | Line 92: | ||
# convert outputed ''string'' to ''char *'' | # convert outputed ''string'' to ''char *'' | ||
# return the actual data. Most of the time, we only have one return variable. Use that as return type for the wrapper. It's easier and cleaner from the JS perspective. | # return the actual data. Most of the time, we only have one return variable. Use that as return type for the wrapper. It's easier and cleaner from the JS perspective. | ||
# if you need to return multiple values, use a struct [http://kiwix.svn.sourceforge.net/viewvc/kiwix/moulinkiwix/src/contentManager/ContentManagerWrapper.h?revision=HEAD&view=markup example] | |||
Header example | Header example | ||
| Line 148: | Line 149: | ||
I'm not very proud of it, a lot of stuff are hard coded and while it gets a ZIM as argument, it expects the swahili zim to test everything. | I'm not very proud of it, a lot of stuff are hard coded and while it gets a ZIM as argument, it expects the swahili zim to test everything. | ||
=== Write a JS module interfacing with js-ctypes and the C wrapper === | |||
Creating a JS module is not required but it's cleaner and convenient: ctypes calls requires the pointer as first argument and the return value of the calls is specific to ctypes. | |||
Our module will use js-ctypes abstract the C librar so that the whole js-ctypes is hidden. | |||
* JS module [http://kiwix.svn.sourceforge.net/viewvc/kiwix/moulinkiwix/kiwix/chrome/modules/libzimAccessor.jsm?revision=HEAD&view=markup example] | |||
Documentation: | |||
* [https://wiki.mozilla.org/JSctypes js-ctypes intro] | |||
* [https://developer.mozilla.org/en/JavaScript_code_modules/ctypes.jsm MDN page] | |||
* [https://developer.mozilla.org/en/js-ctypes/js-ctypes_reference js-ctypes reference] | |||
* [https://wiki.mozilla.org/Jsctypes/api API on the wiki] | |||
* [https://developer.mozilla.org/en/js-ctypes/Using_js-ctypes a tutotial] | |||
* [http://blog.mozilla.com/dwitte/2010/03/12/extension-authors-browser-hackers-meet-js-ctypes/ example with struct] | |||
Rules: | |||
# Open library and declare functions in register method. | |||
# you need to declare every function of the C API. | |||
# ''char *'' returned by API are available via ''.readString()'' | |||
# ''int'' and ''bool'' returned are available via ''contents'' (raw). | |||
# [https://developer.mozilla.org/en/js-ctypes/js-ctypes_reference/Library#declare() declare()] method gets name, abi (we use default so that it's multiplatform), return type (you need to choose this), then parameter (first one is our pointer to the class). | |||
# retrieving values from a struct [http://blog.mozilla.com/dwitte/2010/03/12/extension-authors-browser-hackers-meet-js-ctypes/ example] | |||
# Change case on method names to differentiate with original API. | |||
# abstract the API by providing direct value output to your methods. | |||
# export your jsm as libXXX | |||
Beware that wrong declaration can cause your jsm not to load (error message is misleading: File Not Found). Comment your declarations out and add them back one by one to find the problem. | |||
I chose arbitrary types which worked for my simple tests and some might be wrong. Think for your self and adjust. | |||
I chose: | |||
* ''int16_t'' (16b integer) for boolean returned | |||
* ''ctypes.int32_t.ptr'' (pointer to 32b integer) for instance pointer | |||
* ''ctypes.char.ptr'' pointer to char for all strings. | |||
=== Fix existing JS code to use the JS module === | |||
This part hasn't been done yet. Only local tests. Due to the way the current code mixes the various components it is very difficult to change that code until all components are converted. | |||
Once all are converted, we can rewrite part of that code and make it a lot simpler & cleaner than it currently is. | |||
== Tips == | == Tips == | ||
* .so | * To test js-ctypes and your jsm, you need to put your statically built CWrapper .so lib in xulrunner folder. We'll search later if there's a way to place it elsewhere and have it discovered. Anyway, js-ctypes.open() can take a full path as parameter. | ||
* jsm are compiled and cache at registration. You need to remove cache (or whole profile) after changes. | |||
== Remaining work == | == Remaining work == | ||
* | === unicode === | ||
* | Absolutely zero work as been done regarding unicode and string handlings. It ''just work'' on Linux but I'm 100% sure it will fail badly on windows or with very exotic paths. | ||
Because of the pain it is to manage string properly, it has been agreed that we would wait until the components are ported then we'll find a way to fix the strings. | |||
I believe we might want then to duplicate code from nsString (mozilla) or libICU. | |||
=== makefiles === | |||
library, wrapper and tester makefiles are hardcoded right now. Well need to move them to autotools. | |||
=== Replace XR with FF === | |||
This is the target. Once we have those compo working, we need to investigate using FF as a XR engine. This is theoretically possible but I haven't found example and initial tests showed difficulties with main.xul. | |||
=== Compatibility with XR 1.9.2 === | |||
js-ctypes have been introduced with XR 1.9.2 but the ABI was incomplete or different. Once we have everything working we'll need to dig that and check if we need it. | |||
== Progression == | |||
* zimAccessor: complete | |||
* contentManager: jsm not finished | |||
* xapianAccessor: not started | |||
* zimXapianIndexer: not started | |||
In the JSM we ''open()'' ''libXX.so''. We'll need to replace that with appropriate extension for each platform. There's an xpcom component which guess the extension based on platform but can't remember the name. | |||
== See also == | |||
* https://developer.mozilla.org/en/js-ctypes | |||