{"id":18016995,"url":"https://github.com/fabmax/webidl-util","last_synced_at":"2025-08-24T08:23:42.734Z","repository":{"id":57730440,"uuid":"333527126","full_name":"fabmax/webidl-util","owner":"fabmax","description":"A parser and code-generator for WebIDL files.","archived":false,"fork":false,"pushed_at":"2025-02-24T20:42:01.000Z","size":343,"stargazers_count":9,"open_issues_count":1,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-22T07:24:08.514Z","etag":null,"topics":["emscripten","java","jni","kotlin","webidl"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fabmax.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-01-27T18:48:04.000Z","updated_at":"2025-02-24T20:37:10.000Z","dependencies_parsed_at":"2023-10-16T04:14:37.460Z","dependency_job_id":"ac8f4225-c253-481f-8c00-48de38d73fe0","html_url":"https://github.com/fabmax/webidl-util","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabmax%2Fwebidl-util","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabmax%2Fwebidl-util/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabmax%2Fwebidl-util/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabmax%2Fwebidl-util/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fabmax","download_url":"https://codeload.github.com/fabmax/webidl-util/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245722798,"owners_count":20661827,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["emscripten","java","jni","kotlin","webidl"],"created_at":"2024-10-30T04:19:52.561Z","updated_at":"2025-08-24T08:23:42.726Z","avatar_url":"https://github.com/fabmax.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# webidl-util\n\n[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](http://www.apache.org/licenses/LICENSE-2.0.txt)\n[![Maven Central](https://img.shields.io/maven-central/v/de.fabmax/webidl-util.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22de.fabmax%22%20AND%20a:%22webidl-util%22)\n\nA parser and code-generator for WebIDL files.\n\nThe goals of this project are:\n1. Generate external interface definitions for easy access on\n   [emscripten/WebIDL](https://emscripten.org/docs/porting/connecting_cpp_and_javascript/WebIDL-Binder.html)\n   modules in Kotlin/js\n2. Generate JNI (Java Native Interface) code (Java side as well as native glue code) from WebIDL to provide Java\n   bindings for native libraries.\n\nThe two generator targets are especially useful in the context of Kotlin multi-platform projects, which can then\nrely on the same library APIs for JVM and javascript platforms. However, the generated code can of course also\nbe used in non-multiplatform projects.\n\nI use this to generate JNI bindings for Nvidia PhysX:\n[physx-jni](https://github.com/fabmax/physx-jni) with ~370 generated java classes and no manual tweaking.\nSo it's arguably in a state where you can actually use it :smile:\n\n## How to use\nThis library comes in two flavors: A gradle plugin for easy buildscript integration as well as \na plane library, which can be used for advanced use-cases.\n\n### Gradle plugin\nApply the gradle plugin to your project:\n```kotlin\nplugins {\n    id(\"de.fabmax.webidl-util\") version \"0.10.2\"\n}\n```\nThen configure it to generate JNI bindings:\n```kotlin\nwebidl {\n    modelPath = \"path/to/webidlmodel.idl\"   // required\n    modelName = \"MyWebIdl\"                  // optional model name\n\n    generateJni {\n        // required: where to generate the Java classes\n        javaClassesOutputDirectory = file(\"$projectDir/src/main/generated/\")\n        // required: where to generate the JNI C header file\n        nativeGlueCodeOutputFile = file(\"path/to/native/glue_code.h\")\n\n        // optional package prefix for the generated Java classes\n        packagePrefix = \"com.example\"\n        // optional directory with C++ header files to parse documentation strings from\n        nativeIncludeDir = file(\"${projectDir}/src/jsMain/kotlin/physx\")\n        // optional statement to execute in each generated class' static block\n        //  this is particularly useful to call loader code, which loads the corresponding native lib\n        onClassLoadStatement = \"System.out.println(\\\"class loaded\\\")\"\n    }\n}\n```\n\nAlternatively, you can generate Kotlin/JS bindings for an emscripten/WASM library compiled with the given\nWebIDL definition:\n```kotlin\nwebidl {\n    modelPath = \"path/to/webidlmodel.idl\"   // required\n    modelName = \"MyWebIdl\"                  // optional model name\n\n    generateKotlinJsInterfaces {\n        // required: where to generate the Kotlin interfaces\n        outputDirectory = file(\"${projectDir}/src/jsMain/kotlin\")\n        // required: name of the JS module\n        moduleName = \"physx-js-webidl\"\n        // required: name of the JS Promise providing the loaded module\n        modulePromiseName = \"PhysX\"\n        // optional package prefix for the generated Kotlin interfaces\n        packagePrefix = \"com.example\"\n    }\n}\n```\n\n### Plain library usage\nThe library is published on maven central:\n\n```\ndependencies {\n    implementation(\"de.fabmax:webidl-util:0.10.2\")\n}\n```\n\nHere's a small `main()` method which configures and runs the generator:\n\n```kotlin\nfun main() {\n    val model = WebIdlParser().parse(\"SomeWebIdlFile.idl\")\n    \n    // Generate JNI native glue code\n    JniNativeGenerator().apply {\n        outputDirectory = \"path/to/output/jni_native\"\n        // other configuration stuff...\n    }.generate(model)\n\n    // Generate JNI Java classes\n    JniJavaGenerator().apply {\n        outputDirectory = \"path/to/output/jni_java\"\n        // other configuration stuff...\n    }.generate(model)\n    \n    \n    // Or, alternatively, if you are using kotlin/js and\n    // want to use a WebIDL bound emscripten module\n    JsInterfaceGenerator().apply {\n        outputDirectory = \"path/to/output/kotlinjs\"\n        // other configuration stuff...\n    }.generate(model)\n}\n```\n\n## Limitations\nThis is a work-in-progress project, and I implement features as I need them, so there are a few limitations:\n\n### WebIDL Parser\n- The parser is quite robust and provides somewhat useful messages on syntax errors, however there might be edge\n  cases which are not correctly parsed.\n- Consistency of the parsed model is not checked (e.g. missing referenced interfaces don't produce an error).\n\n### Kotlin/js Interface Generator\n- No known issues.\n\n### JNI Generator\n- Array values are only supported for attributes (not for function arguments / return values).\n- Passing java strings into a native API leaks memory: On the native side the string is copied into a char-array,\n  which is never released.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabmax%2Fwebidl-util","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffabmax%2Fwebidl-util","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabmax%2Fwebidl-util/lists"}