{"id":22190072,"url":"https://github.com/elitemastereric/hxcpp-interop-testbench","last_synced_at":"2025-04-10T23:41:37.504Z","repository":{"id":65261457,"uuid":"589083737","full_name":"EliteMasterEric/hxcpp-interop-testbench","owner":"EliteMasterEric","description":"Minimal working example projects to call C++ code from Haxe.","archived":false,"fork":false,"pushed_at":"2023-01-16T01:06:38.000Z","size":176,"stargazers_count":23,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-24T20:36:03.373Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Haxe","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EliteMasterEric.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2023-01-15T01:49:11.000Z","updated_at":"2023-10-15T10:29:13.000Z","dependencies_parsed_at":"2023-02-10T00:15:47.674Z","dependency_job_id":null,"html_url":"https://github.com/EliteMasterEric/hxcpp-interop-testbench","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/EliteMasterEric%2Fhxcpp-interop-testbench","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EliteMasterEric%2Fhxcpp-interop-testbench/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EliteMasterEric%2Fhxcpp-interop-testbench/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EliteMasterEric%2Fhxcpp-interop-testbench/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EliteMasterEric","download_url":"https://codeload.github.com/EliteMasterEric/hxcpp-interop-testbench/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248317732,"owners_count":21083525,"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":[],"created_at":"2024-12-02T11:42:22.394Z","updated_at":"2025-04-10T23:41:37.486Z","avatar_url":"https://github.com/EliteMasterEric.png","language":"Haxe","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hxcpp-interop-testbench\n\nThis repository demonstrates using the various tools available to Haxe to directly interoperate with C++.\n\n## Introduction\n\n- A **native library** is one which is built as a `dll` (on Windows), a `.so` (on Linux), or `.dylib` (on Mac) file, which contains machine language for the target architecture, which is then linked with the target application.\n- A **foreign function interface** (FFI) is a set of code which allows for executing external code from within a given language.\n    - Haxe's foreign function interfaces allow for executing code from native libraries, without recompiling the runtime itself.\n    - This means that Haxe can access and execute code from a DLL in any language, however setup for this is very different between targets and only `hxcpp` works with this out-of-the-box.\n- A **target native library** is one which is built as a library for a specific programming language, and thus only work when building to that target. \n    - You can use Haxe's `extern` keyword to include these libraries in your project, and these are essential for operating on code outside of Haxe.\n    - For example, when building for the Java target, `jar` files can be used as a target native library, and when building for the NodeJS target, `js` files from NPM packages can be used.\n\n## Examples\n\nEach sample provides a minimum example project, providing a simple addition function to demonstrate how to allow the C++ code to receive and return values. The sample libraries are made for pure Haxe; they do not require any additional libraries (such as Lime) to properly build, but should be fully compatible with them.\n\nThis library contains six examples:\n\nName | Requires Separate DLL | Ease of Use† | Supports Other Targets | Supports Haxelibs\n---|---|---|---|---\n`extern` | NO | 1/5 | ❌ | ✅\n`extern-embedded` | NO | 4/5 | ❌ | ✅\n`function-code` | NO | 4/5 | ✅ | ✅\n`cffi-legacy` | YES | 2/5 | ❌ | ✅\n`cffi-prime` | YES | 3/5 | ❌ | ✅\n`ammer` | NO | 5/5 | ✅†† | ❌\n\n† This is metric is based on my personal opinion on the amount of effort required to work with each method.  \n†† The current version of `ammer` is targeted at `hxcpp` and `hashlink`, with more targets in development.  \n\n1. `extern`: C++ Extern Project\n    - Requires the target application to use the `hxcpp` target, and does not support other targets.\n    - C++ code is placed into a separate folder from the Haxe code for organization.\n    - Links with the source code at build time, and doesn't require a DLL or a separate compilation step.\n        - Compiled project MAY run without any `testinterop.ndll` file.\n    - Linked library cannot be updated without recompiling the executable.\n2. `extern-embedded`: C++ Embedded Externs\n    - Requires the target application to use the `hxcpp` target, and does not support other targets.\n    - C++ code is embedded into the Haxe code.\n        - Results in cleaner code on smaller projects but unmaintainable code on larger projects.\n    - Embedded into source code at build time, and doesn't require a DLL or separate compilation step.\n        - Compiled project MAY run without any `testinterop.ndll` file.\n    - Linked library cannot be updated without recompiling the executable.\n3. `function-code`: functionCode annotation\n    - Embeds the string directly into the compiled application, replacing any haxe expressions in the function's method body.\n    - Easier to sort out functions than `extern-embedded` but harder to make them call each other.\n    - Works on `C++` and `C#` targets.\n    - NOT working on `Python` targets (the `functionCode` annotation is ignored)\n        - It would be cool if you could use compiler defines to choose which language-specific code to use but guess not.\n4. `cffi-legacy` CFFI Legacy\n    - Values must be boxed to be sent between C++ and Haxe, and functions are weakly typed (only checked at runtime).\n    - Links with the built native library at runtime, thus the `ndll` file must be included with the EXE when distributing.\n        - Compiled project CANNOT run without the `testinterop.ndll` file in a nearby directory.\n        - NDLL file can be updated or replaced after building without modifying the executable.\n    - Complex configuration required to use with other targets (`hashlink`, `neko`, `python`, `lua`, etc).\n5. `cffi-prime` CFFI Prime\n    - Modern upgrade to Haxe CFFI.\n    - Values do not need to be boxed and functions are strongly typed (checked at compilation time).\n    - Links with the built native library at runtime, thus the `ndll` file must be included with the EXE when distributing.\n        - Compiled project CANNOT run without the `testinterop.ndll` file in a nearby directory.\n        - NDLL file can be updated or replaced after building without modifying the executable.\n    - Complex configuration required to use with other targets (`hashlink`, `neko`, `python`, `lua`, etc).\n6. [ammer](https://github.com/Aurel300/ammer)\n    - Utilizes a library by Aurel300\n    - Vastly simplified linking process\n    - No additional configuration needed to link against `hashlink` and `lua` (other targets in development)\n    - Complex configuration required to use linked code as a haxelib (library packaging in development)\n\n\n## Useful Resources\n\n- https://github.com/snowkit/hxcpp-guide/issues/1\n- https://community.haxe.org/t/some-questions-about-the-ammer-library-ffi-haxelib-externs/2271\n- https://github.com/Aurel300/ammer\n- https://github.com/larsiusprime/steamwrap\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felitemastereric%2Fhxcpp-interop-testbench","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felitemastereric%2Fhxcpp-interop-testbench","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felitemastereric%2Fhxcpp-interop-testbench/lists"}