X-Git-Url: http://git.bitcoin.ninja/index.cgi?p=ldk-java;a=blobdiff_plain;f=README.md;h=793d2ce8cf78f03086cf0598a2e9cf88119afb35;hp=825c22c716380b2e71be5275842ac9507ad70cbd;hb=HEAD;hpb=99a3d528524ef1de3ad0dd3d0f81e5c2df0de226 diff --git a/README.md b/README.md index 825c22c7..c8061f3c 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ -LDK Java and TypeScript Bindings -================================ +LDK Java, C#, and TypeScript Bindings +===================================== -This repo contains an autogeneration system to generate LDK bindings for garbage-collected languages, currently including Java and TypeScript. See below for the current status of the bindings. +This repo contains an autogeneration system to generate LDK bindings for garbage-collected languages, currently including Java, C#, and TypeScript. See below for the current status of the bindings. The auto-generated code contains copies of the Rust documentation, which can also be viewed at [docs.rs/lightning](https://docs.rs/lightning). High-level documentation of the API can be found at @@ -10,48 +10,42 @@ The auto-generated code contains copies of the Rust documentation, which can als Building ======== -A release build of the Java bindings library for Linux is available in git. Thus, the bindings should work as long as the `LD_LIBRARY_PATH` includes the top-level directory of this repository. - -To build the bindings locally, the bindings require some additional work which is still making its -way upstream, for now it should be built against the -[rust-lightning 2021-03-java-bindings-base branch on git.bitcoin.ninja](https://git.bitcoin.ninja/?p=rust-lightning;a=shortlog;h=refs/heads/2021-03-java-bindings-base). -Check that branch out locally as well as [ldk-c-bindings](https://github.com/lightningdevkit/ldk-c-bindings) -and run the `genbindings.sh` script in ldk-c-bindings to build the required binaries. Thereafter, -in this repo, run the `genbindings.sh` script with the first argument pointing to the ldk-c-bindings -directory, the second the relevant JNI CFLAGS, the third argument set to `true` or `false` to -indicate whether building in debug mode, and the third set to true or false to indicate if the -bindings should be built with workarounds required for Android. JNI CFLAGS on debian are likely -"-I/usr/lib/jvm/java-11-openjdk-amd64/include/ -I/usr/lib/jvm/java-11-openjdk-amd64/include/linux/". -When running a program linking against the library in debug mode, LD_PRELOAD should likely include -the relevant `libclang_rt.asan-platform.so` path. - -Note that building with address sanitizer is only supported on MacOS with upstream clang (ie where -the LLVM version in use matches the LLVM version against which rustc was built), not with Apple clang. -Builds with Apple clang will work fine, but largely only be useful in a release context. -To build on Mac with address sanitizer, you will need to run `ldk-c-bindings`' `genbindings.sh` -script with upstream clang in your PATH and likely replace your $JAVA_HOME/bin/java with a simple -wrapper which calls java after an export like: -`export DYLD_INSERT_LIBRARIES=/path/to/upstream/llvm/lib/clang/12.0.0/lib/darwin/libclang_rt.asan_osx_dynamic.dylib` - -To build for Apple M1 (ie aarch64-apple-darwin), you probably want something like -`CC="clang --target=aarch64-apple-darwin" LDK_TARGET=aarch64-apple-darwin LDK_TARGET_CPU=generic ./genbindings.sh ...` +The releases for Java, C#, and TypeScript are all deterministic. You should be able to reproduce +the release binaries identically by running the scripts run in CI, see +[.github/workflows/build.yml](.github/workflows/build.yml). + +Releases for all platforma re built on Linux as that is the easiest way to get things +deterministic, however building on macOS should also work. Building on Windows is not currently +supported. Status ====== -The TypeScript Bindings are still in early development and generated code contains syntax errors. +## Java + +The Java bindings are relatively mature, and should be considered safe for production use. Still, +as they have relatively few users, unexpected issues remain possible, and bug reports are welcome. + +## TypeScript + +The TypeScript bindings are functionally complete, but should be considered beta quality. As there +are relatively few users, unexpected issues remain likely, and bug reports are welcome. + +The TypeScript bindings require modern web standards, including support for `FinalizationRegistry` +and `WeakRef` (Chrome 84, Firefox 79, Safari 14.1/iOS 14.5 and Node 14.6) and WASM BigInt support +(Chrome 85, Firefox 78, Safari 14.1/iOS 14.5, and Node 15.0). + +For users of Node.JS environments you may wish to use the `lightningdevkit-node-net` package as +well to implement the required network handling to bridge the `lightningdevkit` package's +`SocketDescriptor` interface to Node.JS TCP Sockets. For those wishing to run a lightning node in +the browser you will need to provide your own bridge from `SocketDescriptor` to a WebSocket proxy. + +# C# -While the underlying library and C bindings are relatively mature, the Java bindings should be -considered beta quality and some issues may still appear. Specifically, because the Java bindings -map between two very different memory models - Rust's strict ownership model and Java's reference -cloning and garbage collection - a lot of work occurs in the background to keep the Java GC -informed of Rust ownership semantics. +The C# bindings are functionally complete, but should be considered alpha quality. They are brand +new and likely contain bugs or memory leaks. -The debug-mode build includes memory leak tracking and will print all loose objects when the -program exists, though without calls to `System.gc(); System.runFinalization();` immediately before -exit there will likely be many false positives. While it will require some complicated usage, there -are likely some use-after-free or unkonwn-free bugs remaining. The debug-mode build links LLVM -address sanitizer and will print diagnostic information in case of such issues. +## General The only known issue resulting in a use-after-free bug requires custom a custom ChannelKeys instance created as a part of a new channel. After the channel is created, the ChannelKeys object will not