diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000..cad616a --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,174 @@ +# Apache License +Version 2.0, January 2004 + + +## TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + +### 1. Definitions. + +**"License"** shall mean the terms and conditions for use, reproduction, +and distribution as defined by Sections 1 through 9 of this document. + +**"Licensor"** shall mean the copyright owner or entity authorized by +the copyright owner that is granting the License. + +**"Legal Entity"** shall mean the union of the acting entity and all +other entities that control, are controlled by, or are under common +control with that entity. For the purposes of this definition, +"control" means (i) the power, direct or indirect, to cause the +direction or management of such entity, whether by contract or +otherwise, or (ii) ownership of fifty percent (50%) or more of the +outstanding shares, or (iii) beneficial ownership of such entity. + +**"You" (or "Your")** shall mean an individual or Legal Entity exercising +permissions granted by this License. + +**"Source" form** shall mean the preferred form for making modifications, +including but not limited to software source code, documentation source, +and configuration files. + +**"Object" form** shall mean any form resulting from mechanical +transformation or translation of a Source form, including but not +limited to compiled object code, generated documentation, and +conversions to other media types. + +**"Work"** shall mean the work of authorship, whether in Source or +Object form, made available under the License, as indicated by a +copyright notice that is included in or attached to the work +(an example is provided in the Appendix below). + +**"Derivative Works"** shall mean any work, whether in Source or Object +form, that is based on (or derived from) the Work and for which the +editorial revisions, annotations, elaborations, or other modifications +represent, as a whole, an original work of authorship. For the purposes +of this License, Derivative Works shall not include works that remain +separable from, or merely link (or bind by name) to the interfaces of, +the Work and Derivative Works thereof. + +**"Contribution"** shall mean any work of authorship, including the +original version of the Work and any modifications or additions to that +Work or Derivative Works thereof, that is intentionally submitted to +the Licensor for inclusion in the Work by the copyright owner or by an +individual or Legal Entity authorized to submit on behalf of the +copyright owner. + +**"Contributor"** shall mean Licensor and any individual or Legal Entity +on behalf of whom a Contribution has been received by Licensor and +subsequently incorporated within the Work. + +### 2. Grant of Copyright License. + +Subject to the terms and conditions of this License, each Contributor +hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, +royalty-free, irrevocable copyright license to reproduce, prepare +Derivative Works of, publicly display, publicly perform, sublicense, +and distribute the Work and such Derivative Works in Source or Object +form. + +### 3. Grant of Patent License. + +Subject to the terms and conditions of this License, each Contributor +hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, +royalty-free, irrevocable (except as stated in this section) patent +license to make, have made, use, offer to sell, sell, import, and +otherwise transfer the Work, where such license applies only to those +patent claims licensable by such Contributor that are necessarily +infringed by their Contribution(s) alone or by combination of their +Contribution(s) with the Work to which such Contribution(s) was +submitted. If You institute patent litigation against any entity +(including a cross-claim or counterclaim in a lawsuit) alleging that +the Work or a Contribution incorporated within the Work constitutes +direct or contributory patent infringement, then any patent licenses +granted to You under this License for that Work shall terminate as of +the date such litigation is filed. + +### 4. Redistribution. + +You may reproduce and distribute copies of the Work or Derivative Works +thereof in any medium, with or without modifications, and in Source or +Object form, provided that You meet the following conditions: + +1. You must give any other recipients of the Work or Derivative Works a + copy of this License; and + +2. You must cause any modified files to carry prominent notices stating + that You changed the files; and + +3. You must retain, in the Source form of any Derivative Works that You + distribute, all copyright, patent, trademark, and attribution notices + from the Source form of the Work, excluding those notices that do not + pertain to any part of the Derivative Works; and + +4. If the Work includes a "NOTICE" text file as part of its distribution, + then any Derivative Works that You distribute must include a readable + copy of the attribution notices contained within such NOTICE file, + excluding those notices that do not pertain to any part of the + Derivative Works, in at least one of the following places: within a + NOTICE text file distributed as part of the Derivative Works; within + the Source form or documentation, if provided along with the Derivative + Works; or, within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents of the + NOTICE file are for informational purposes only and do not modify the + License. You may add Your own attribution notices within Derivative + Works that You distribute, alongside or as an addendum to the NOTICE + text from the Work, provided that such additional attribution notices + cannot be construed as modifying the License. + +You may add Your own copyright statement to Your modifications and may +provide additional or different license terms and conditions for use, +reproduction, or distribution of Your modifications, or for any such +Derivative Works as a whole, provided Your use, reproduction, and +distribution of the Work otherwise complies with the conditions stated +in this License. + +### 5. Submission of Contributions. + +Unless You explicitly state otherwise, any Contribution intentionally +submitted for inclusion in the Work by You to the Licensor shall be +under the terms and conditions of this License, without any additional +terms or conditions. Notwithstanding the above, nothing herein shall +supersede or modify the terms of any separate license agreement you +may have executed with Licensor regarding such Contributions. + +### 6. Trademarks. + +This License does not grant permission to use the trade names, +trademarks, service marks, or product names of the Licensor, except as +required for describing the origin of the Work and reproducing the +content of the NOTICE file. + +### 7. Disclaimer of Warranty. + +Unless required by applicable law or agreed to in writing, Licensor +provides the Work (and each Contributor provides its Contributions) on +an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either +express or implied, including, without limitation, any warranties or +conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR +A PARTICULAR PURPOSE. You are solely responsible for determining the +appropriateness of using or redistributing the Work and assume any +risks associated with Your exercise of permissions under this License. + +### 8. Limitation of Liability. + +In no event and under no legal theory, whether in tort (including +negligence), contract, or otherwise, unless required by applicable law +(such as deliberate and grossly negligent acts) or agreed to in writing, +shall any Contributor be liable to You for damages, including any direct, +indirect, special, incidental, or consequential damages of any character +arising as a result of this License or out of the use or inability to use +the Work (including but not limited to damages for loss of goodwill, work +stoppage, computer failure or malfunction, or any and all other commercial +damages or losses), even if such Contributor has been advised of the +possibility of such damages. + +### 9. Accepting Warranty or Additional Liability. + +While redistributing the Work or Derivative Works thereof, You may choose +to offer, and charge a fee for, acceptance of support, warranty, indemnity, +or other liability obligations and/or rights consistent with this License. +However, in accepting such obligations, You may act only on Your own behalf +and on Your sole responsibility, not on behalf of any other Contributor, +and only if You agree to indemnify, defend, and hold each Contributor +harmless for any liability incurred by, or claims asserted against, such +Contributor by reason of your accepting any such warranty or additional +liability. diff --git a/README.md b/README.md index 459fe96..d096092 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,65 @@ -# Binding # -There are many common data types and functions used when interfacing -with C libraries. The Binding library attempts to define the more commonly -needed types and functions to help speed up the process of wrapping -these libraries. +# Binding + +`binding` is a foundational Rust crate providing safe and ergonomic +abstractions for Foreign Function Interface (FFI) bindings. It serves as the +core layer for building robust, cross-platform Rust bindings to native C APIs, +enabling seamless integration between Rust and C codebases. + +--- + +## Features + +- Safe abstractions over unsafe FFI calls +- Ergonomic trait-driven interfaces for common binding patterns +- Cross-platform support for Windows and Linux +- Designed with zero-cost abstractions in mind, maintaining performance +- Facilitates building high-quality Rust wrappers around C libraries + +--- + +## Add to Your Project + +This library is hosted on the CyberMages registry. To add it to your project, +the CyberMages registry must be added to your Cargo configuration as described +in the [Cargo Book](https://doc.rust-lang.org/cargo/reference/registries.html). + +First, add the registry to your Cargo config (`.cargo/config.toml` or +`$CARGO_HOME/config.toml`): + +```toml +[registries.cybermages] +index = "sparse+https://workshop.cybermages.tech/api/packages/CyberMages/cargo/" +``` + +Then add `binding` as a dependency in your `Cargo.toml`: + +```toml +[dependencies] +binding = { version = "0.x", registry = "cybermages" } +``` + +--- + +## Getting Started + +## Motivation + +Working with native C libraries from Rust often requires careful handling of +unsafe code and complex boilerplate. The `binding` crate aims to reduce this +friction by providing reusable, well-tested abstractions that improve safety, +readability, and maintainability of Rust FFI code. + +--- + +## Copyright & License + +Copyright 2017 CyberMages LLC + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this library except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS diff --git a/examples/enums.rs b/examples/enums.rs index 7559c5e..7e43b4f 100644 --- a/examples/enums.rs +++ b/examples/enums.rs @@ -1,3 +1,6 @@ +// SPDX-License-Identifier: Apache-2.0 +// Sealed with Magistamp. + use binding::c_enum; diff --git a/examples/flags.rs b/examples/flags.rs index d36f00d..e858e8c 100644 --- a/examples/flags.rs +++ b/examples/flags.rs @@ -1,3 +1,6 @@ +// SPDX-License-Identifier: Apache-2.0 +// Sealed with Magistamp. + use binding::c_flags; diff --git a/src/c_enum.rs b/src/c_enum.rs index 2db0247..e42bdaf 100644 --- a/src/c_enum.rs +++ b/src/c_enum.rs @@ -1,3 +1,6 @@ +// SPDX-License-Identifier: Apache-2.0 +// Sealed with Magistamp. + /// Create a C exportable enum. These are useful for working with C FFIs. /// /// As C has no idea about tuples or structs enums diff --git a/src/c_flags.rs b/src/c_flags.rs index d6604e5..d7835f9 100644 --- a/src/c_flags.rs +++ b/src/c_flags.rs @@ -1,3 +1,6 @@ +// SPDX-License-Identifier: Apache-2.0 +// Sealed with Magistamp. + /// Creates a Flag type that is also very useful for working with C FFIs. #[macro_export] macro_rules! c_flags diff --git a/src/c_ptr.rs b/src/c_ptr.rs index 50e1c5b..cc632d9 100644 --- a/src/c_ptr.rs +++ b/src/c_ptr.rs @@ -1,3 +1,6 @@ +// SPDX-License-Identifier: Apache-2.0 +// Sealed with Magistamp. + /// A C Pointer to an undefined structure. /// /// A lot of C libraries return a pointer to an undefined structure. diff --git a/src/c_struct.rs b/src/c_struct.rs index 9fa5e7d..d08c851 100644 --- a/src/c_struct.rs +++ b/src/c_struct.rs @@ -1,3 +1,6 @@ +// SPDX-License-Identifier: Apache-2.0 +// Sealed with Magistamp. + /// Defines a C style structure. #[macro_export] macro_rules! c_struct diff --git a/src/c_types.rs b/src/c_types.rs index de9c837..f739d34 100644 --- a/src/c_types.rs +++ b/src/c_types.rs @@ -1,3 +1,6 @@ +// SPDX-License-Identifier: Apache-2.0 +// Sealed with Magistamp. + //! This defines the primitive types that may be seen //! when creating 'C' bindings. //! diff --git a/src/lib.rs b/src/lib.rs index 8f19083..7d62a11 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,3 +1,6 @@ +// SPDX-License-Identifier: Apache-2.0 +// Sealed with Magistamp. + //! The Binding library is a place where common macros and functions //! that are used when interfacing with C libraries can be stored //! for use amoungst all of CyberMages LLC's projects. diff --git a/src/macros.rs b/src/macros.rs index 75f6e5b..0a46c01 100644 --- a/src/macros.rs +++ b/src/macros.rs @@ -1,3 +1,6 @@ +// SPDX-License-Identifier: Apache-2.0 +// Sealed with Magistamp. + #[macro_export] macro_rules! c_library { diff --git a/src/raw.rs b/src/raw.rs index 494bed5..da3aa41 100644 --- a/src/raw.rs +++ b/src/raw.rs @@ -1,3 +1,6 @@ +// SPDX-License-Identifier: Apache-2.0 +// Sealed with Magistamp. + //! These types are here to be used in bindings only. Other conversion //! traits, either from the spellbook or standard library are to be used //! at all other times. These were determined to be used at the binding