{"id":20415427,"url":"https://github.com/riot-os/rust-riot-sys","last_synced_at":"2025-03-17T16:13:16.728Z","repository":{"id":38196221,"uuid":"498388623","full_name":"RIOT-OS/rust-riot-sys","owner":"RIOT-OS","description":"The Rust riot-sys crate, used for modules and applications on RIOT OS","archived":false,"fork":false,"pushed_at":"2025-02-24T12:22:20.000Z","size":1836,"stargazers_count":12,"open_issues_count":9,"forks_count":7,"subscribers_count":22,"default_branch":"main","last_synced_at":"2025-03-05T02:34:19.316Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","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/RIOT-OS.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-31T15:16:28.000Z","updated_at":"2025-02-24T12:21:52.000Z","dependencies_parsed_at":"2024-03-12T11:31:05.198Z","dependency_job_id":"6ecf6c8a-9421-4a57-bedf-5ddab75cafe0","html_url":"https://github.com/RIOT-OS/rust-riot-sys","commit_stats":{"total_commits":305,"total_committers":5,"mean_commits":61.0,"dds":0.02950819672131144,"last_synced_commit":"b4bd4bde7520d0ffd79b89c2c5454f74de29dc39"},"previous_names":[],"tags_count":39,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RIOT-OS%2Frust-riot-sys","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RIOT-OS%2Frust-riot-sys/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RIOT-OS%2Frust-riot-sys/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RIOT-OS%2Frust-riot-sys/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RIOT-OS","download_url":"https://codeload.github.com/RIOT-OS/rust-riot-sys/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244066189,"owners_count":20392406,"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-11-15T06:15:59.049Z","updated_at":"2025-03-17T16:13:16.708Z","avatar_url":"https://github.com/RIOT-OS.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- WARNING: README.md is auto-generated using `cargo readme`, don't modify that file --\u003e\n\n# riot-sys\n\n## Bindings for RIOT system calls\n\nThis crate contains dynamically generated Rust FFI bindings to the [RIOT\nOperating System](https://riot-os.org/).\n\nThose bindings are inherently unsafe; it is recommended that their safe\nabstractions in the [riot-wrappers] crate are used in most applications.\n\nFor a newcomer's starting point, see [RIOT's documentation on using it with Rust].\nThis also contains installation instructions / dependencies.\n\n[riot-wrappers]: https://crates.io/crates/riot-wrappers\n[RIOT's documentation on using it with Rust]: https://doc.riot-os.org/using-rust.html\n\n### RIOT integration\n\nWhich functions and structs are present in this crate, and sometimes their\ndetails, inherently depends on the RIOT configuration this will be used with.\nFor example, RIOT's `thread_t` only has a member `name` if `DEVHELP` is\nset for a build, and its `flags` member is only present if the `thread_flags`\nmodule is in use.\n\nAll the relevant information -- including the location of the actually used\nRIOT header files and flags influencing the ABI -- is conveyed to `riot-sys` by passing on the\ncompiler and the CFLAGS. This can either be done by passing in the path to a \"compile commads\"\nfile through the `RIOT_COMPILE_COMMANDS` environment variable (accompanied by a\n`RIOT_USEMODULES`, as that part of `CFLAGS` is missing from the compile commands), or\nalternatively by passing in the C compiler as `RIOT_CC` and the CFLAGS (both their\n`CFLAGS_WITH_MACROS` and the `INCLUDES` part from RIOT's build system) in. When called from\nwithin RIOT's build system, care must be taken to clear `CC` and `CFLAGS`, as these would be\ninterpreted by Cargo (Rust's build system) to refer to the host compiler and flags.\nThe flags will be interpreted by libclang based tools; care must be taken to pass in flags\nsuitable for clang and not for GCC.\n\nThese steps are automated in RIOT's build system.\n\n\nThe `RIOT_CC` and `RIOT_CFLAGS` are made available to dependent crates through\nCargo (as `DEP_RIOT_SYS_CC` etc); see [riot-wrappers]'s build.sh for an example. Similarly,\ncustom markers are made available based on the presence of certain defines or features in RIOT\nas downstream crates require that information (typically to allow a crate to work across a\nwider range of RIOT versions); see the section below for details.\n\n\n### Extension\n\nCurrently, only a subset of all the RIOT headers is processed; all the relevant\nheader files are included in this crate's `riot-headers.h` header file. If you\nneed access to more RIOT APIs, more includes can be added there.\n\n\n### Versioning\n\n`riot-sys` is versioned using SemVer,\nand efforts are made to not make breaking changes even while in the 0.x phase.\nNote that as it passes on RIOT internals,\nany of the SemVer guarantees only hold when built on the *same* RIOT --\nonce the underlying C code is changed, all bets are off.\nUsers of `riot-rs` can introspect the `DEP_RIOT_SYS_...` variables\nthat are available to crates that set `links = \"riot-sys\"`\nto affect the symbols those crates use.\nTypical variables to inspect are `DEP_RIOT_SYS_BINDGEN_OUTPUT_FILE`\n(to determine whether a symbol is imported in the first place, eg. when RIOT renames something)\nand `DEP_RIOT_SYS_CFLAGS` which includes the enabled modules.\n\n#### Markers\n\n**Deprecated, see below**.\n\nSome decisions of downstream crates need to depend on whether some feature is around in\nRIOT. For many things that's best checked on module level, but some minor items have no\nmodule to mark the feature, and checking for versions by numers is not fine-grained enough,\nso it's easiest to check for concrete strings in the bindgen output.\n\nThe `build.rs` of this crate contains a list of marker conditions. These lead to `MARKER_foo=1`\nitems emitted that are usable as `DEP_RIOT_SYS_MARKER_foo=1` by crates that explicitly `links =\n\"riot-sys\"`. They are stable in that they'll only go away in a breaking riot-sys version;\ndownstream users likely stop using them earlier because they sooner or later stop supporting\nold RIOT versions.\n\nFor example, in [PR #17957](https://github.com/RIOT-OS/RIOT/pull/17957), an argument to a\nparticular handler function changed fundamentally; no amount of `.into()` would allow writing\nsensible abstractions. The marker `coap_request_ctx_t` was introduced, and is present\nautomatically on all RIOT versions that have that particular pull request merged. Code in\n`riot-wrappers` uses conditions like `#[cfg(marker_coap_request_ctx_t)] ` to decide whether to\nuse the old or the new conventions.\n\nThese markers are currently checked against bindgen's output, but could query any property\nthat riot-sys has access to. The markers are defined in terms of some change having happened\nin RIOT; the way they are tested for can change. (In particular, when riot-sys stops\nsupporting an older RIOT version, it can just always emit that marker).\n\nCrates building on this should preferably not alter their own APIs depending on these,\nbecause that would add extra (and hard-to-track) dimensions to them. If they can, they\nshould provide a unified view and degrade gracefully. (For example, riot-wrappers has the\nunit `T` of the `phydat_unit_t` in its enum, but converts it to the generic unspecified unit\non RIOT versions that don't have the T type yet -- at least for as long as it supports\n2022.01).\n\n**Deprecation note / successor**: As of 2023-02, no new markers will be added, because\nimplementing this mechanism here has shown to be impracitcal: Changes need to go into riot-sys\nfirst before they can be use (and tested in) with riot-wrappers. Instead, `BINDGEN_OUTPUT_FILE`\nis exported (usable as `DEP_RIOT_SYS_BINDGEN_OUTPUT_FILE`), which points to the Rust file\ngenerated by bindgen. Downstream crates can inspect that file, possibly using the same\nstring-based methods as riot-sys uses, but without any cross-crate dependencies.\n\nCrates accessing the `BINDGEN_OUTPUT_FILE` should exercise the same caution that is recommended\nabove for the use of markers.\n\n---\n\nThe types and constants of RIOT are translated in two forms:\nthrough bindgen (to be linked together), and through C2Rust (transpiled, to be inlined).\nThis is necessary because neither can express the full set of useful RIOT APIs.\n\nAll bindgen types are reexported in the main module and exclusively public through there. The\nC2Rust types largely reside in the [inline] module, with some pub used into the root module as\nnecessary or convenient.\n\nLicense\n-------\n\nThis crate is licensed under the same terms as of the LGPL-2.1, following the\nlicense terms of the RIOT Operating System.\n\nIt is maintained by Christian Amsüss \u003cchrysn@fsfe.org\u003e as part of the etonomy\nproject, see \u003chttps://etonomy.org/\u003e, and the RIOT team.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friot-os%2Frust-riot-sys","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Friot-os%2Frust-riot-sys","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friot-os%2Frust-riot-sys/lists"}