Add README to block sys crate

Author: madsmtm

objc2/src/lib.rs

@@ -75,10 +75,6 @@ extern crate std;
 #[doc = include_str!("../README.md")]
 extern "C" {}
 
-#[cfg(doctest)]
-#[doc = include_str!("../../README.md")]
-extern "C" {}
-
 pub use objc2_encode::{Encode, EncodeArguments, Encoding, RefEncode};
 
 pub use crate::message::{Message, MessageArguments, MessageError, MessageReceiver};

objc2_block_sys/Cargo.toml

@@ -15,7 +15,7 @@ repository = "https://github.com/madsmtm/objc2"
 documentation = "https://docs.rs/objc2_block_sys/"
 license = "MIT"
 
-# readme = "README.md"
+readme = "README.md"
 
 # Downstream users can customize the linking!
 # See https://doc.rust-lang.org/cargo/reference/build-scripts.html#overriding-build-scripts
@@ -24,14 +24,11 @@ build = "build.rs"
 
 [features]
 # Link to Apple's libclosure (exists in libSystem)
-# See https://opensource.apple.com/source/libclosure/
-# Accessible mirror https://github.com/madsmtm/libclosure
 #
 # This is the default on Apple platforms
 apple = []
 
 # Link to libBlocksRuntime from compiler-rt
-# See https://github.com/llvm/llvm-project/tree/release/13.x/compiler-rt/lib/BlocksRuntime
 #
 # This is the default on non-Apple platforms
 compiler-rt = []

objc2_block_sys/README.md

@@ -0,0 +1,111 @@
+# `objc2_block_sys`
+
+[![Latest version](https://badgen.net/crates/v/objc2_block_sys)](https://crates.io/crates/objc2_block_sys)
+[![License](https://badgen.net/badge/license/MIT/blue)](../LICENSE.txt)
+[![Documentation](https://docs.rs/objc2_block_sys/badge.svg)](https://docs.rs/objc2_block_sys/)
+[![Apple CI](https://github.com/madsmtm/objc2/actions/workflows/apple.yml/badge.svg)](https://github.com/madsmtm/objc2/actions/workflows/apple.yml)
+[![GNUStep CI](https://github.com/madsmtm/objc2/actions/workflows/gnustep.yml/badge.svg)](https://github.com/madsmtm/objc2/actions/workflows/gnustep.yml)
+
+Raw Rust bindings to Apple's C language extension of blocks
+
+## Runtime Support
+
+This library is basically just a raw interface to the aptly specified [Blocks
+ABI](https://clang.llvm.org/docs/Block-ABI-Apple.html). However, different
+runtime implementations exist and act in slightly different ways (and have
+several different helper functions), the most important aspect being that the
+libraries are named differently, so the linking must take that into account.
+
+The user can choose the desired runtime by using the relevant cargo feature
+flags, see the following sections:
+
+
+### Apple's [`libclosure`](https://opensource.apple.com/source/libclosure/)
+
+- Feature flag: `apple`.
+
+This is naturally the most sophisticated runtime, and it has quite a lot more
+features than the specification mandates. This is used by default on Apple
+platforms when no feature flags are specified.
+
+The minimum required operating system versions are as follows:
+- macOS: `10.6`
+- iOS: `3.2`
+- tvOS: Unknown
+- watchOS: Unknown
+
+Though in practice Rust itself requires higher versions than this.
+
+A git mirror of the sources is available [here](https://github.com/madsmtm/libclosure).
+
+
+### LLVM `compiler-rt`'s [`libBlocksRuntime`](https://github.com/llvm/llvm-project/tree/release/13.x/compiler-rt/lib/BlocksRuntime)
+
+- Feature flag: `compiler-rt`.
+
+This is the default runtime on all non-Apple platforms when no feature flags
+are specified.
+
+This is effectively just a copy of Apple's older (around macOS 10.6) runtime,
+and is now used in [Swift's `libdispatch`] and [Swift's Foundation] as well.
+
+This can be easily used on many Linux systems with the `libblocksruntime-dev`
+package.
+
+[Swift's `libdispatch`]: https://github.com/apple/swift-corelibs-libdispatch/tree/swift-5.5.1-RELEASE/src/BlocksRuntime
+[Swift's Foundation]: https://github.com/apple/swift-corelibs-foundation/tree/swift-5.5.1-RELEASE/Sources/BlocksRuntime
+
+
+### GNUStep's [`libobjc2`](https://github.com/gnustep/libobjc2)
+
+- Feature flag: `gnustep-1-7`, `gnustep-1-8`, `gnustep-1-9`, `gnustep-2-0` and
+  `gnustep-2-1` depending on the version you're using.
+
+GNUStep is a bit odd, because it bundles blocks support into its Objective-C
+runtime. This means we have to link to `libobjc`, and this is done by
+depending on the `objc2_sys` crate. A bit unorthodox, yes, but it works.
+
+Sources:
+- [`Block.h`](https://github.com/gnustep/libobjc2/blob/v2.1/objc/blocks_runtime.h)
+- [`Block_private.h`](https://github.com/gnustep/libobjc2/blob/v2.1/objc/blocks_private.h)
+
+
+### Microsoft's [`WinObjC`](https://github.com/microsoft/WinObjC)
+
+- Feature flag: `winobjc`.
+
+Essentially just [a fork](https://github.com/microsoft/libobjc2) based on
+GNUStep's `libobjc2` version 1.8.
+
+
+### [`ObjFW`](https://github.com/ObjFW/ObjFW) (WIP)
+
+- Feature flag: `objfw`.
+
+TODO.
+
+
+## C Compiler configuration
+
+To our knowledge, currently only `clang` supports the [Language Specification
+for Blocks][block-lang]. To assist in compiling C (or Objective-C) sources
+using these features, this crate's build script expose the `DEP_BLOCK_CC_ARGS`
+environment variable to downstream build scripts.
+
+Example usage in your `build.rs` (using the `cc` crate) would be as follows:
+
+```rust , ignore
+fn main() {
+    let mut builder = cc::Build::new();
+    builder.compiler("clang");
+    builder.file("my_script_using_blocks.c");
+
+    for flag in std::env::var("DEP_BLOCK_CC_ARGS").unwrap().split(' ') {
+        builder.flag(flag);
+    }
+
+    builder.compile("libmy_script_using_blocks.a");
+}
+```
+
+[block-lang]: https://clang.llvm.org/docs/BlockLanguageSpec.html

objc2_block_sys/src/lib.rs

@@ -1,9 +1,12 @@
+//! # Raw bindings to Apple's C language extension of blocks
 //!
-//! See:
-//! - https://github.com/apple/swift-corelibs-libdispatch/tree/main/src/BlocksRuntime
-//! - https://github.com/apple/swift-corelibs-foundation/tree/main/Sources/BlocksRuntime
-//! - https://clang.llvm.org/docs/BlockLanguageSpec.html
-//! - https://clang.llvm.org/docs/Block-ABI-Apple.html
+//! The documentation for these bindings is a mix from GNUStep's and Apple's
+//! sources, but the [ABI specification][ABI] is really the place you should
+//! be looking!
+//!
+//! See also the `README.md` for more info.
+//!
+//! [ABI]: https://clang.llvm.org/docs/Block-ABI-Apple.html
 
 // Update in Cargo.toml as well.
 #![doc(html_root_url = "https://docs.rs/objc2_block_sys/0.0.0")]
@@ -12,6 +15,10 @@
 #[cfg(feature = "gnustep-1-7")]
 extern crate objc2_sys;
 
+#[cfg(doctest)]
+#[doc = include_str!("../README.md")]
+extern "C" {}
+
 use core::cell::UnsafeCell;
 use core::ffi::c_void;
 use core::marker::{PhantomData, PhantomPinned};
@@ -90,7 +97,7 @@ pub const BLOCK_IS_GLOBAL: block_flags = 1 << 28;
 ///     (true, true)   => ABI.2010.3.16, stret calling convention, presence of signature field,
 /// }
 ///
-/// See https://clang.llvm.org/docs/Block-ABI-Apple.html#high-level
+/// See <https://clang.llvm.org/docs/Block-ABI-Apple.html#high-level>
 #[doc(alias = "BLOCK_USE_SRET")]
 #[doc(alias = "BLOCK_HAS_DESCRIPTOR")] // compiler-rt || macOS 10.6
 pub const BLOCK_USE_STRET: block_flags = 1 << 29;