{"id":13437824,"url":"https://github.com/Sean1708/rusty-cheddar","last_synced_at":"2025-03-19T18:30:48.672Z","repository":{"id":44165777,"uuid":"44117242","full_name":"Sean1708/rusty-cheddar","owner":"Sean1708","description":"A Rust crate for automatically generating C header files from Rust source file.","archived":false,"fork":false,"pushed_at":"2018-06-30T10:38:35.000Z","size":4283,"stargazers_count":190,"open_issues_count":24,"forks_count":25,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-14T16:03:31.627Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://sean1708.github.io/rusty-cheddar/","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/Sean1708.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2015-10-12T15:43:18.000Z","updated_at":"2025-02-17T14:22:10.000Z","dependencies_parsed_at":"2022-09-14T13:00:48.234Z","dependency_job_id":null,"html_url":"https://github.com/Sean1708/rusty-cheddar","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sean1708%2Frusty-cheddar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sean1708%2Frusty-cheddar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sean1708%2Frusty-cheddar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sean1708%2Frusty-cheddar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Sean1708","download_url":"https://codeload.github.com/Sean1708/rusty-cheddar/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244483140,"owners_count":20460065,"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-07-31T03:01:00.508Z","updated_at":"2025-03-19T18:30:48.434Z","avatar_url":"https://github.com/Sean1708.png","language":"Rust","funding_links":[],"categories":["Development tools","开发工具 Development tools","开发工具","Rust"],"sub_categories":["FFI","FFI FFI","示例 FFI"],"readme":"**_Please be aware that this crate is no longer actively maintained, please look into the much more feature rich [cbindgen](https://github.com/eqrion/cbindgen/) instead._**\n\n# rusty-cheddar\n\n[![Build Status](https://travis-ci.org/Sean1708/rusty-cheddar.svg)](https://travis-ci.org/Sean1708/rusty-cheddar)\n[![crates.io](http://meritbadge.herokuapp.com/rusty-cheddar)](https://crates.io/crates/rusty-cheddar)\n![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)\n\nrusty-cheddar is a library for converting Rust source files into C header files.\n\n**A note on versioning:** While rusty-cheddar is still in a significant flux (i.e.\npre-`v1.0.0`) it will likely go through numerous breaking changes. However, until `v1.0.0`, any\ntime a breaking change is made the minor version will be bumped and any time a new feature is\nadded the path version will be bumped.\n\nrusty-cheddar targets C99 or later (for sane single line comments and use of `stdint.h` and\n`stdbool.h`), if you really really really really really have to use an older standard then please\nopen an issue at the [repo] and I will begrudgingly figure out how to implement support for it\n(after arguing with you lots and lots).\n\nThe most useful way to use rusty-cheddar is in a build script. To do this add the following\n`build-dependencies` section to your `Cargo.toml` (to use it as a normal library simply replace\n`build-dependencies` with `dependencies`):\n\n```toml\n# Cargo.toml\n\n[build-dependencies]\nrusty-cheddar = \"0.3.0\"\n```\n\nThen create the following `build.rs`:\n\n```rust\n// build.rs\n\nextern crate cheddar;\n\nfn main() {\n    cheddar::Cheddar::new().expect(\"could not read manifest\")\n        .run_build(\"include/my_header.h\");\n}\n```\n\nThis should work as is providing you've set up your project correctly. **Don't forget to add a\n`build = ...` to your `[package]` section, see [the cargo docs] for more info.**\n\nrusty-cheddar will then create a `my_header.h` file in `include/`. Note that rusty-cheddar\nemits very few warnings, it is up to the programmer to write a library which can be correctly\ncalled from C.\n\n#### API In a Module\n\nYou can also place your API in a module to help keep your source code neat. To do this you must\nsupply the name of the module to Cheddar, then ensure that the items are available in the\ntop-level scope:\n\n```rust\n// build.rs\n\nextern crate cheddar;\n\nfn main() {\n    cheddar::Cheddar::new().expect(\"could not read manifest\")\n        .module(\"c_api\").expect(\"malformed module path\")\n        .run_build(\"target/include/rusty.h\");\n}\n```\n\n```rust\n// src/lib.rs\n\npub use c_api::*;\n\nmod c_api {\n    // api goes here ...\n}\n```\n\nThere is also the `.compile()` and `.compile_code()` methods for finer control.\n\n## Conversions\n\nIn the examples below, boilerplate has been omitted from the header.\n\n### Typedefs\n\nrusty-cheddar converts `pub type A = B` into `typedef B A;`. Types containing generics are ignored.\n\nRust:\n\n```rust\ntype UInt32 = u32;\npub type UInt64 = u64;\npub type MyOption\u003cT\u003e = Option\u003cT\u003e\n```\n\nHeader:\n\n```C\n// Some boilerplate omitted.\ntypedef uint64_t UInt64;\n// Some more boilerplate omitted.\n```\n\n### Enums\n\nrusty-cheddar will convert public enums which are marked `#[repr(C)]`. If the enum is generic or\ncontains tuple or struct variants then `cheddar` will fail. rusty-cheddar should correctly handle\nexplicit discriminants.\n\nRust:\n\n```rust\n#[repr(C)]\npub enum Colours {\n    Red = -6,\n    Blue,\n    Green = 7,\n    Yellow,\n}\n\n// This would fail if it was #[repr(C)].\npub enum Tastes\u003cT\u003e {\n    Savoury(T),\n    Sweet,\n}\n\n// This would fail if it was public.\n#[repr(C)]\nenum Units {\n    Kg(f64),\n    M(f64),\n    S(f64),\n    A(f64),\n    K(f64),\n    Mol(f64),\n    Cd(f64),\n}\n```\n\nHeader:\n\n```C\n// Some boilerplate omitted.\ntypedef enum Colours {\n        Red = -6,\n        Blue,\n        Green = 7,\n        Yellow,\n} Colours;\n// Some more boilerplate omitted.\n```\n\n### Structs\n\nStructs are handled very similarly to enums, they must be public, marked `#[repr(C)]`, and they must not\ncontain generics (this currently only checked at the struct-level, generic fields are not checked).\n\nRust:\n\n```rust\n#[repr(C)]\npub struct Person {\n    age: i32,\n    height: f64,\n    weight: f64,\n}\n```\n\nHeader:\n\n```C\n// Some boilerplate omitted.\ntypedef struct Person {\n        int32_t age;\n        double height;\n        double weight;\n} Person;\n// Some more boilerplate omitted.\n```\n\n#### Opaque Structs\n\nOne common C idiom is to hide the implementation of a struct using an opaque struct, which can\nonly be used behind a pointer. This is especially useful in Rust-C interfaces as it allows you\nto use _any arbitrary Rust struct_ in C.\n\nTo define an opaque struct you must define a public newtype which is marked as `#[repr(C)]`.\n\nRust:\n\n```rust\nstruct Foo\u003cT\u003e {\n    bar: i32,\n    baz: Option\u003cT\u003e,\n}\n\n#[repr(C)]\npub struct MyCrate_Foo(Foo\u003cPathBuf\u003e);\n```\n\nHeader:\n\n```C\n// Some boilerplate omitted.\ntypedef struct MyCrate_Foo MyCrate_Foo;\n// Some boilerplate omitted.\n```\n\nNote that the newtype _must not_ be generic but the type that it wraps can be arbitrary.\n\n### Functions\n\nFor rusty-cheddar to pick up on a function declaration it must be public, marked `#[no_mangle]` and\nhave one of the following ABIs:\n\n- C\n- Cdecl\n- Stdcall\n- Fastcall\n- System\n\nI'm not totally up to speed on calling conventions so if you believe one of these has been including\nin error, or if one has been omitted, then please open an issue at the [repo].\n\nrusty-cheddar will fail on functions which are marked as diverging (`-\u003e !`).\n\nRust:\n\n```rust\nuse std::ops::Add;\n\n#[no_mangle]\npub extern fn hello() {\n    println!(\"Hello!\");\n}\n\nfn add\u003cO, R, L: Add\u003cR, Output=O\u003e\u003e(l: L, r: R) -\u003e O {\n    l + r\n}\n\n#[no_mangle]\n#[allow(non_snake_case)]\npub extern fn MyAdd_add_u8(l: u8, r: u8) -\u003e u8 {\n    add(l, r)\n}\n\n#[no_mangle]\n#[allow(non_snake_case)]\npub extern fn MyAdd_add_u16(l: u16, r: u16) -\u003e u16 {\n    add(l, r)\n}\n```\n\nHeader:\n\n```C\n// Some boilerplate omitted.\nvoid hello();\n\nuint8_t MyAdd_add_u8(uint8_t l, uint8_t r);\n\nuint16_t MyAdd_add_u16(uint16_t l, uint16_t r);\n// Some more boilerplate omitted.\n```\n\n### Paths\n\nYou must not put types defined in other modules in an exported type signature without hiding it\nbehind an opaque struct. This is because the C compiler must know the layout of the type and\nrusty-cheddar can not yet search other modules.\n\nThe very important exception to this rule are the C ABI types defined in\nthe `libc` crate and `std::os::raw`. Types from these two modules _must_\nbe fully qualified (e.g. `libc::c_void` or `std::os::raw::c_longlong)\nso that they can be converted properly. Importing them with a `use`\nstatement will not work.\n\n[the cargo docs]: http://doc.crates.io/build-script.html\n[repo]: https://github.com/Sean1708/rusty-cheddar\n\n## Contributing\n\nContributions to rusty-cheddar are more than welcome.\n\n### Bugs\n\nIf you find a bug or have a feature request please open an issue. I can't guarantee that I'll fix it\nbut I'll give it a damn good go.\n\nIf you find the source code unclear in any way then I consider that a bug. I try to make my source\ncode as clear as possible but I'm not very good at it, so any help in that regard is appreciated.\n\n### PRs\n\nI love pull requests they tend to make my job much easier, so if you want to fix a bug or implement\na feature yourself then that would be great. If you're confused by anything or need some pointers on\nhow to proceed then feel free to open an issue so that I can help, otherwise [these docs] are a good\nplace to start.\n\n#### Tests\n\nThe tests require you to have a recent version (\u003e `v2.7.2`) of [CppHeaderParser] installed for the\nversion of Python which is installed as `python` (usually Python 2). Furthermore due to the fact\nthat the tests are a massive pile of wanky hacks, you must be in the same directory as\nrusty-cheddar's `Cargo.toml` to successfully run them.\n\n[rusty-binder]: https://gitlab.com/rusty-binder/rusty-binder\n[these docs]: http://manishearth.github.io/rust-internals-docs/syntax/ast/index.html\n[CppHeaderParser]: https://bitbucket.org/senex/cppheaderparser\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSean1708%2Frusty-cheddar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSean1708%2Frusty-cheddar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSean1708%2Frusty-cheddar/lists"}