Do better with platform (font engine) features. (#217)

* freetype: Make optional, rename feature.

Now, the feature for this is called `freetype` rather than
`build-native-freetype`. This was never building FreeType
but just saying to build with FreeType and to use `freetype-sys`.

The default features were disabled for `freetype` and then enabling
the `freetype-sys` feature, but that's exactly what the `freetype`
crate does by default, so simplify by not trying to do it again.

Partial fix for #184 (this doesn't handle the `coretext` side).

* Add `directwrite` feature.

This controls whether or not `winapi` is used to support the
DirectWrite code on Windows.

* Add `coretext` feature.

This controls whether or not the CoreText APIs are supported
on Apple platforms.

Fixes #184.

* Add features list to crate docs and READMEs.

* Add notes to functions about feature required.

Author: waywardmonkeys

harfbuzz-sys/Cargo.toml

@@ -28,23 +28,21 @@ pkg-config = { version = "0.3", optional = true }
 cc = { version = "1", optional = true }
 
 [target.'cfg(target_vendor = "apple")'.dependencies]
-core-graphics = "0.22"
-core-text = "19"
-foreign-types = "0.3"
+core-graphics = { version = "0.22", optional = true }
+core-text = { version = "19", optional = true }
+foreign-types = { version = "0.3", optional = true }
 
 [target.'cfg(target_family = "windows")'.dependencies.winapi]
 version = "0.3"
+optional = true
 features = ["dwrite"]
 
-[target.'cfg(any(target_os = "android", all(unix, not(target_vendor = "apple"))))'.dependencies]
-freetype = { version = "0.7", default-features = false }
-
 [dependencies.freetype]
 version = "0.7"
-default-features = false
 optional = true
 
 [features]
-default = ["build-native-harfbuzz", "build-native-freetype"]
+default = ["build-native-harfbuzz", "coretext", "directwrite", "freetype"]
+coretext = ["core-graphics", "core-text", "foreign-types"]
+directwrite = ["winapi"]
 build-native-harfbuzz = ["cc", "pkg-config"]
-build-native-freetype = ["freetype", "freetype/freetype-sys"]

harfbuzz-sys/README.md

@@ -14,6 +14,12 @@ given a Unicode string.
 
 This crate provides low-level bindings to the C API.
 
+## Features
+
+- `freetype` - Enables bindings to the FreeType font engine. (Enabled by default.)
+- `coretext` - Enables bindings to the CoreText font engine. (Apple platforms only) (Enabled by default.)
+- `directwrite` - Enables bindings to the DirectWrite font engine. (Windows only) (Enabled by default.)
+
 ## License
 
 Licensed under the MIT license ([LICENSE](LICENSE) or <https://opensource.org/licenses/MIT>).

harfbuzz-sys/src/coretext.rs

@@ -7,8 +7,12 @@ use foreign_types::ForeignType;
 type CGFontRef = *mut <CGFont as ForeignType>::CType;
 
 extern "C" {
+    /// This requires that the `coretext` feature is enabled.
     pub fn hb_coretext_face_create(cg_font: CGFontRef) -> *mut hb_face_t;
+    /// This requires that the `coretext` feature is enabled.
     pub fn hb_coretext_font_create(ct_font: CTFontRef) -> *mut hb_font_t;
+    /// This requires that the `coretext` feature is enabled.
     pub fn hb_coretext_face_get_cg_font(face: *mut hb_face_t) -> CGFontRef;
+    /// This requires that the `coretext` feature is enabled.
     pub fn hb_coretext_font_get_ct_font(font: *mut hb_font_t) -> CTFontRef;
 }

harfbuzz-sys/src/directwrite.rs

@@ -3,5 +3,6 @@ use crate::hb_face_t;
 use winapi::um::dwrite::IDWriteFontFace;
 
 extern "C" {
+    /// This requires that the `directwrite` feature is enabled.
     pub fn hb_directwrite_face_create(font_face: *mut IDWriteFontFace) -> *mut hb_face_t;
 }

harfbuzz-sys/src/lib.rs

@@ -1,15 +1,23 @@
-#[cfg(target_vendor = "apple")]
+//! # harfbuzz-sys
+//!
+//! This crate provides raw bindings to the [HarfBuzz](https://harfbuzz.github.io/)
+//! text shaping library.
+//!
+//! ## Features
+//!
+//! - `freetype` - Enables bindings to the FreeType font engine. (Enabled by default.)
+//! - `coretext` - Enables bindings to the CoreText font engine. (Apple platforms only) (Enabled by default.)
+//! - `directwrite` - Enables bindings to the DirectWrite font engine. (Windows only) (Enabled by default.)
+
+#[cfg(all(target_vendor = "apple", feature = "coretext"))]
 pub mod coretext;
 
-#[cfg(target_family = "windows")]
+#[cfg(all(target_family = "windows", feature = "directwrite"))]
 pub mod directwrite;
 
-#[cfg(any(
-    target_os = "android",
-    all(unix, not(target_vendor = "apple")),
-    feature = "build-native-freetype"
-))]
+#[cfg(feature = "freetype")]
 extern "C" {
+    /// This requires that the `freetype` feature is enabled.
     pub fn hb_ft_font_create_referenced(face: freetype::freetype::FT_Face) -> *mut hb_font_t;
 }
 

harfbuzz/Cargo.toml

@@ -19,6 +19,8 @@ version = "0.5.0"
 default-features = false
 
 [features]
-default = ["build-native-harfbuzz", "build-native-freetype"]
+default = ["build-native-harfbuzz", "coretext", "directwrite", "freetype"]
 build-native-harfbuzz = ["harfbuzz-sys/build-native-harfbuzz"]
-build-native-freetype = ["harfbuzz-sys/build-native-freetype"]
+coretext = ["harfbuzz-sys/coretext"]
+directwrite = ["harfbuzz-sys/directwrite"]
+freetype = ["harfbuzz-sys/freetype"]

harfbuzz/README.md

@@ -15,6 +15,12 @@ given a Unicode string.
 This crate provides a higher level API (than the
 [raw C bindings](https://crates.io/crates/harfbuzz-sys)).
 
+## Features
+
+- `freetype` - Enables bindings to the FreeType font engine. (Enabled by default.)
+- `coretext` - Enables bindings to the CoreText font engine. (Apple platforms only) (Enabled by default.)
+- `directwrite` - Enables bindings to the DirectWrite font engine. (Windows only) (Enabled by default.)
+
 ## License
 
 Licensed under either of

harfbuzz/src/lib.rs

@@ -9,6 +9,12 @@
 
 //! HarfBuzz is a text shaping engine. It solves the problem of selecting
 //! and positioning glyphs from a font given a Unicode string.
+//!
+//! ## Features
+//!
+//! - `freetype` - Enables bindings to the FreeType font engine. (Enabled by default.)
+//! - `coretext` - Enables bindings to the CoreText font engine. (Apple platforms only) (Enabled by default.)
+//! - `directwrite` - Enables bindings to the DirectWrite font engine. (Windows only) (Enabled by default.)
 
 #![warn(missing_docs)]
 #![deny(