Skip to content

Commit

Permalink
Readme: Document the bindings we support
Browse files Browse the repository at this point in the history
Signed-off-by: Jonathan Schwender <[email protected]>
  • Loading branch information
jschwe committed Jan 9, 2025
1 parent 39980ec commit 3c2d830
Show file tree
Hide file tree
Showing 3 changed files with 165 additions and 11 deletions.
76 changes: 65 additions & 11 deletions Readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,73 @@
FFI-bindings for the native API of [OpenHarmony OS]. See the [documentation] for a list of supported components.
This crate is under active development, and not officially affiliated with OpenHarmony OS.

## Status of the bindings

Here is an overview of the available C header directories in the OpenHarmony sysroot, and for which of them
this crate already provides bindings. The API-level column denotes up to which api level the bindings have
already been generated.

| API name | status | API-level |
|----------------------------|---------|-----------|
| AbilityKit | | |
| BasicServicesKit | | |
| ConnectivityKit | | |
| CryptoArchitectureKit | | |
| IPCKit | | |
| LocationKit | | |
| NotificationKit | | |
| accesstoken | | |
| ace/xcomponent || 13 |
| ark_runtime | | |
| arkui | partial | 13 |
| asset | | |
| bundle | | |
| database | | |
| ddk | | |
| ffrt | | |
| filemanagement | | |
| hiappevent | | |
| hicollie | | |
| hid | | |
| hidebug | | |
| hilog || 13 |
| hitrace || 13 |
| huks | | |
| info | | |
| inputmethod || 13 |
| mindspore | | |
| multimedia | | |
| multimodalinput | | |
| napi || 13 |
| native_buffer || 13 |
| native_color_space_manager | | |
| native_display_soloist | | |
| native_drawing || 13 |
| native_effect | | |
| native_image || 13 |
| native_vsync || 13 |
| native_window || 13 |
| network | | |
| neural_network_runtime | | |
| ohaudio | | |
| ohcamera | | |
| purgeable_memory | | |
| qos | | |
| rawfile | | |
| resourcemanager | | |
| sensors | | |
| telephony | | |
| transient_task | | |
| usb | | |
| web | | |
| window_manager | | |

## Development

The current bindings are generated with `bindgen` using `scripts/generate_bindings.sh`.
A separate file is generated for each API version, and (assuming no breaking changes) the new additions are
manually copied to an `apiXX_additions.rs` file, which is included as a module if `feature = api-XX` is selected.
The generated file `drawing_apiXX.rs` should be committed to version control, so we can easily rerun the script on a
patch-release for a given API-level and see what changed.
The file itself is however not needed, and will be excluded from `crates.io` releases.
Bindings are currently generated with the OpenHarmony SDK API level 13, but with items
added after API level 10 feature guarded behind `api-XX` features. this is handled
automatically by the tool based on the documentation comments in the C header files.

# Contributing

Expand All @@ -30,15 +89,10 @@ and adapt it to incorporate new modules.

Please also check the following:

- Ensure that opaque struct definitions do not derive `Copy`, `Clone` and `Debug`.
- Blocklist all unnecessary type definitions, e.g. from the C standard library.
- Preferably generate the bindings with libclang in `C` mode. However, if a header file is not C-compliant
due to an issue of the OpenHarmony SDK, then setting `libclang` to C++ mode is fine.
- Be sure to guard the new component behind a cargo feature and document the feature in Cargo.toml.
- If you did not generate the bindings with API-level 10, specify which API-level you generated the bindings with
and guard the generated module behind the corresponding api-level feature flag.
- Installing `bindgen`: We require at least bindgen 0.70.0, with the `prettyplease` feature enabled.
You can install it by running `cargo install bindgen-cli --features prettyplease`


## License

Expand Down
44 changes: 44 additions & 0 deletions scripts/list_available_apis.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
#!/usr/bin/env python3
import os
from pathlib import Path

# Folders in the /usr/include directory of the sysroot which are not relevant for OpenHarmony bindings,
# since they contain just standard headers
blocklisted = [
'EGL', 'GLES2', 'GLES3',
'KHR',
'aarch64-linux-ohos',
'arm-linux-ohos',
'asm-generic', 'asm-loongarch', 'asm-mips', 'asm-riscv',
'arpa',
'drm',
'fortify',
'linux',
'misc',
'mtd',
'net', 'netinet', 'netpacket',
'rdma',
'scsi',
# not sure about SLES, it also has an OH specific header file.
'SLES',
'sound',
'sys',
'unicode',
'uv',
'video',
'vk_video',
'vulkan',
'i686-linux-ohos',
'x86_64-linux-ohos',
'xen',
]

if __name__ == '__main__':
native_path = Path(os.environ['OHOS_SDK_NATIVE'])
header_root = native_path.joinpath('sysroot/usr/include')
assert header_root.exists(), f"{header_root} does not exist"
dirs = [x.parts[-1] for x in header_root.iterdir() if x.is_dir()]
dirs.sort()
filtered = list(filter(lambda name: name not in blocklisted, dirs))

print("\n".join(filtered))
56 changes: 56 additions & 0 deletions scripts/readme_documented_api_modules
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# Helper file to compare the contents from `list_available_apis.py` over time and new SDK versions.

----------------

AbilityKit
BasicServicesKit
ConnectivityKit
CryptoArchitectureKit
IPCKit
LocationKit
NotificationKit
accesstoken
ace
ark_runtime
arkui
asset
bundle
database
ddk
ffrt
filemanagement
hiappevent
hicollie
hid
hidebug
hilog
hitrace
huks
info
inputmethod
mindspore
multimedia
multimodalinput
napi
native_buffer
native_color_space_manager
native_display_soloist
native_drawing
native_effect
native_image
native_vsync
native_window
network
neural_network_runtime
ohaudio
ohcamera
purgeable_memory
qos
rawfile
resourcemanager
sensors
telephony
transient_task
usb
web
window_manager

0 comments on commit 3c2d830

Please sign in to comment.