- add emscripten support and basic example

- skip layout tests in pre-generated bindings to avoid errors on emscripten
- Test more build configuratioions in github CI
- support using pkg-config to find glfw libs
- properly document features/linker flags.

Author: coderedart

.github/workflows/build.yml

@@ -24,6 +24,14 @@ jobs:
           sudo apt update
           sudo apt install libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libxext-dev libwayland-dev libxkbcommon-dev
 
+      # To check vulkan bindings.
+      - name: Prepare Vulkan SDK
+        uses: humbletim/[email protected]
+        with:
+          vulkan-query-version: latest
+          vulkan-components: Vulkan-Headers
+          vulkan-use-cache: true
+
       - name: Source build with static link
         shell: bash
         run: cargo clean && cargo run -vv --example=version --features=src_build,static_link
@@ -36,32 +44,41 @@ jobs:
         shell: bash
         # linux pre-built static libs are not provided, so, static linkign requires src_build.
         if: matrix.os != 'ubuntu'
-        run: cargo clean && cargo run -vv --example=version --features=static_link
+        run: cargo clean && cargo run -vv --example=version --features=static_link,prebuilt_libs
 
+      - name: Prebuilt libs with shared link
+        shell: bash
+        if: matrix.os != 'ubuntu'
+        run: cargo clean && cargo run -vv --example=version --features=prebuilt_libs
+            
       # We delay this, because we don't want the previous steps to "accidentally" succeed
       # by linking to system libraries (on linux).
       - name: Install Glfw Packages (Linux)
         if: matrix.os == 'ubuntu'
         shell: bash
         run: sudo apt install libglfw3-dev
+      
+      - name: Install Glfw Packages (MacOs)
+        if: matrix.os == 'macos'
+        shell: bash
+        run: brew install glfw
 
-      - name: Prebuilt libs with shared link
+      - name: PkgConfig build with static linking (MacOs)
+        if: matrix.os == 'ubuntu' || matrix.os == 'macos'
         shell: bash
-        run: cargo clean && cargo run -vv --example=version && cargo build -vv --examples
+        run: cargo clean && cargo run -vv --example=version --features=static_link
 
-      # To check vulkan bindings.
-      - name: Prepare Vulkan SDK
-        uses: humbletim/[email protected]
-        with:
-          vulkan-query-version: latest
-          vulkan-components: Vulkan-Headers
-          vulkan-use-cache: true
+      - name: PkgConfig build with shared linking (MacOs And Linux)
+        if: matrix.os == 'ubuntu' || matrix.os == 'macos'
+        shell: bash
+        run: cargo clean && cargo run -vv --example=version
+        
 
       # We don't pass --no-default-features, so, this generates bindings for 
       # vulkan and native_gl/egl + other handles too by including system headers.
       - name: Generate Bindings
         shell: bash
-        run: cargo clean && cargo run -vv --example=version --features=bindgen
+        run: cargo clean && cargo run -vv --example=version --features=bindgen,src_build
 
       # Just to make sure that the script works on all platforms.
       - name: Check gen_bindings.sh script

Cargo.toml

@@ -19,6 +19,8 @@ all = ["x11", "wayland", "native_handles", "native_gl", "native_egl", "vulkan"]
 bindgen = ["dep:bindgen"]
 # build from source, instead of using prebuilt libraries.
 src_build = ["dep:cmake"]
+prebuilt_libs = []
+
 static_link = [] # static link (if on linux, src_build must also be enabled)
 vulkan = []
 wayland = []
@@ -34,6 +36,7 @@ osmesa = []
 [build-dependencies]
 bindgen = { version = "0.71", optional = true }
 cmake = { version = "0.1", optional = true }
+pkg-config = "0.3"
 
 [dev-dependencies]
 glow = {version = "0.16"}

README.md

@@ -5,40 +5,52 @@ This repo contains `glfw-sys` crate that provides FFI bindings to [glfw](https:/
 ## Design
 This library has two main purposes:
 1. provide FFI bindings to glfw: pre-generated (fast compile times) and build-time generation (slower).
-2. link to glfw library: source builds (using cmake) and [pre-built official glfw libs](https://github.com/glfw/glfw/releases).
+2. link to glfw library: system builds (using `pkg-config`), source builds (using `cmake`) and [pre-built official glfw libs](https://github.com/glfw/glfw/releases) (only for windows and mac).
 
 
 For normal applications, you only need to care about 2 features:
 1. `src_build` - if you want to build from source. adds around 10 seconds of build time.
 2. `static_link` - if you want to link statically. On linux, this requires `src_build` too, so prefer dynamic linking during development for faster compile times. 
 
 ### Features
-* `static_link` - statically link glfw. not available for linux if `src_build` is disabled.
-* `src_build` - build glfw from source. If disabled, we download pre-built glfw libs using system's curl + unzip/tar and link them.
-* `x11` and `wayland` - enables support for x11/wayland. Enable both and you can choose which one to use during initialization.
-* `vulkan` - enables some vulkan convenience functions (eg: surface creation).
-* `native_handles` - enable APIs to get platform specific window handles or display connections. useful for raw-window-handle support.
-* `native_gl` - enable APIs for getting platform specific gl contexts (wgl, egl, glx, nsgl etc..)
-* `native_egl` - enable egl API even for x11 builds
-* `osmesa` - I have no idea. Ignore this unless you know what you are doing.
-* `bindgen` - generate glfw FFI bindings at build time from headers. See [Below](#bindgen)
 
-### Source Builds
-if `src_build` feature is enabled, we will build glfw from scratch.
-This requires `cmake` to be installed on your system and any other required dependencies.
+#### Building And Linking
+
+> NOTE: For emscripten, none of these features apply. We just pass the necessary flags like `-sUSE_GLFW=3` to linker and simply let emscripten take care of things.
+
+- `static_link` - statically link glfw. If disabled, we will dynamically link glfw.
+
+We try to build glfw in this order:
+- `src_build` - If enabled, build glfw from source (sources are included with crate). Ensure `cmake` is installed and any other required dependencies.
+- `prebuilt_libs` (only for windows/macos. ignored on other platforms) - If enabled, we download and link pre-built glfw libs from <https://github.com/glfw/glfw/releases/>.
+
+> NOTE: We use curl + tar (unzip on macos) to download and extract pre-built libs. mac/win10+ will have these by default.
 
-### Prebuilt-libs builds
-If `src_build` feature is disabled, we will link with prebuilt glfw libraries.
-On windows and mac, we download the official libraries from <https://github.com/glfw/glfw/releases/>
-On linux, we expect user to have installed glfw library for linking (eg: `libglfw3-dev` on ubuntu). For static linking, you may probably require src_build, as most distros don't provide static libs.
+Finally, if neither `src_build` nor `prebuilt_libs` feature is enabled, we will try to use `pkg-config` to find and link to system glfw libs.
 
-> NOTE: We use curl + tar (unzip on unix) to download and extract pre-built libs. mac/win10+/linux will have these by default.
+#### Platform Backends (non-mac and non-windows only)
+* `x11` and `wayland` - enables support for x11/wayland. Enable both and you can choose which one to use during initialization. `x11/wayland` are ignored on windows/macos platforms.
+
+#### Vulkan
+- `vulkan` enables some vulkan convenience functions (eg: `glfwVulkanSupported`).
+- Only enable this if you need vulkan support.
+
+#### Native Handles
+These features expose native "HWND"/"NSWindow"/"X11Connection" etc.. handles.
+Unless you are using `wgpu`-like libs that need raw-window-handles, these features can be ignored.
+- `native_handles` - enable APIs to get platform specific window handles or display connections or monitor ids. useful for raw-window-handle support.
+- `native_gl` - enable APIs for getting platform specific gl contexts (`wgl`, `egl`, `glx`, `nsgl` etc..). Most users should ignore this. 
+- `native_egl` - enable egl API even for x11 builds, if you plan to use `egl` contexts with x11 windows. Most users should ignore this.
+
+#### Miscellaneous
+* `osmesa` - I have no idea. Ignore this unless you know what you are doing.
+* `bindgen` - generate glfw FFI bindings at build time from headers. See [Below](#bindgen)
 
 
 ### Pre-Generated bindings
 We generate FFI bindings at `src/sys/pregenerated.rs` and include them with the crate to keep the compile times fast. These are used when `bindgen` feature is disabled.
 
-This generates core bindings, but skips platform specific bindings (eg: window handles or other platform specific API). Because generating them requires platform headers (eg: `windows.h`) and we can't provide headers for *all* platforms at once.
+This contains core bindings, but skips platform specific bindings (eg: window handles or other platform specific API). Because generating them requires platform headers (eg: `windows.h`) and we can't provide headers for *all* platforms at once.
 
 So, platform specific bindings are manually maintained by hand in `src/sys/manual.rs`.
 
@@ -52,5 +64,6 @@ These features will influence the bindings generated.
 
 ### Release Check List
 * When updating glfw version, make sure to checkout the submodule and commit it. 
-* When updating glfw version, don't forget to change the url link build.rs to download the pre-built libs of the correct version.
+* When updating glfw version, don't forget to change the url link in build.rs to download the pre-built libs of the correct version.
+* When updating glfw version, don't forget to update the pkg-config `atleast_version` argument.
 * Check that the bindings generated are the same on all platforms by checking the CI logs for the `gen_bindings.sh` step.

build.rs

@@ -21,44 +21,88 @@ fn main() {
     #[cfg(feature = "bindgen")]
     generate_bindings(features, &out_dir);
 
-    // only for mac/windows.
-    // other platforms like linux/bsd should install their platform libraries
-    // using system package manager.
-    //
-    // if other platforms require static builds, you may use src builds instead.
-    #[cfg(not(feature = "src_build"))]
-    download_libs(features, &out_dir);
-
-    // build from src, instead of using prebuilt-libraries.
-    #[cfg(feature = "src_build")]
-    build_from_src(features, &out_dir);
+    // lets special case emscripten and early return.
+    if features.os == TargetOs::Emscripten {
+        // tell emscripten to expose glfw bindings
+        println!("cargo:rustc-link-arg=-sUSE_GLFW=3");
+        // Without this, we get errors like
+        // = note: wasm-ld: error: .../basic.diqs9uv01tyf3yxt0iu6v8zc8.rcgu.o: undefined symbol: glfwGetError
+        println!("cargo:rustc-link-arg=-sERROR_ON_UNDEFINED_SYMBOLS=0");
+        return;
+    }
 
-    // emit the linker flags
-    // requires src_build if not win/mac os, as most distros only provide shared libs.
-    if features.static_link {
-        println!("cargo:rustc-link-lib=static=glfw3");
+    // not src build and not prebuilt_libs => use pkg-config
+    let pkgconfig_build = !features.src_build && !features.prebuilt_libs;
+    if features.src_build {
+        // build from src, instead of using prebuilt-libraries. ignore on emscripten target.
+        #[cfg(feature = "src_build")]
+        build_from_src(features, &out_dir);
+    } else if features.prebuilt_libs {
+        download_libs(features, &out_dir);
     } else {
+        assert!(pkgconfig_build);
+        // emits linker flags by default.
+        match pkg_config::Config::new()
+            .statik(features.static_link)
+            .atleast_version("3.4.0")
+            .probe("glfw3")
+        {
+            Ok(lib) => println!("pkg-config found glfw library {lib:#?}"),
+            Err(e) => panic!("pkg-config failed to find glfw library: {e}"),
+        }
+    }
+
+    // pkg-config takes care of emitting linker flags, so we only explicitly
+    // need to emit them if we aren't using pkg-config.
+    if !pkgconfig_build {
+        if features.static_link {
+            println!("cargo:rustc-link-lib=static=glfw3");
+        } else {
+            match features.os {
+                TargetOs::Win => println!("cargo:rustc-link-lib=dylib=glfw3dll"),
+                _ => println!("cargo:rustc-link-lib=dylib=glfw"),
+            }
+        }
+    }
+
+    // First, we link system libs recommended by official glfw docs
+    // from glfw/src/CmakeLists.txt - glfw_PKG_LIBS
+    // and https://www.glfw.org/docs/latest/build_guide.html
+
+    // pkg-config builds will already emit these flags, so we only
+    // need to emit them if we aren't using pkg-config
+    if !pkgconfig_build {
         match features.os {
-            TargetOs::Win => println!("cargo:rustc-link-lib=dylib=glfw3dll"),
-            _ => println!("cargo:rustc-link-lib=dylib=glfw"),
+            TargetOs::Win => {
+                println!("cargo:rustc-link-lib=gdi32");
+            }
+            TargetOs::Mac => {
+                println!("cargo:rustc-link-lib=framework=Cocoa");
+                println!("cargo:rustc-link-lib=framework=IOKit");
+                println!("cargo:rustc-link-lib=framework=CoreFoundation");
+            }
+            _ => {}
         }
     }
-    // extra libraries for win/mac
+    // next, we link extra libs based on glfw-rs/src/ffi/links.rs
+    // TODO: check if we actually need these.
     match features.os {
         TargetOs::Win => {
-            println!("cargo:rustc-link-lib=dylib=gdi32");
-            println!("cargo:rustc-link-lib=dylib=user32");
-            println!("cargo:rustc-link-lib=dylib=kernel32");
-            println!("cargo:rustc-link-lib=dylib=shell32");
+            println!("cargo:rustc-link-lib=opengl32");
+            println!("cargo:rustc-link-lib=user32");
+            println!("cargo:rustc-link-lib=shell32");
         }
         TargetOs::Mac => {
-            println!("cargo:rustc-link-lib=framework=Cocoa");
-            println!("cargo:rustc-link-lib=framework=IOKit");
-            println!("cargo:rustc-link-lib=framework=CoreFoundation");
+            println!("cargo:rustc-link-lib=framework=OpenGL");
             println!("cargo:rustc-link-lib=framework=QuartzCore");
         }
-        TargetOs::Linux => {
-            // Gl? idk.
+        TargetOs::Linux | TargetOs::Others => {
+            if features.x11 {
+                println!("cargo:rustc-link-lib=X11");
+            }
+            if features.wayland {
+                println!("cargo:rustc-link-lib=wayland-client");
+            }
         }
         _ => {}
     }
@@ -70,6 +114,7 @@ enum TargetOs {
     Win,
     Mac,
     Linux,
+    Emscripten,
     Others,
 }
 /// The features enabled for this build
@@ -102,34 +147,46 @@ struct Features {
     /// generate bindings for native gl bindings like wgl, glx, nsgl, egl etc..
     /// For X11, you can explicitly enable egl-related functionality using `egl` feature.
     gl: bool,
+    /// whether we are doing a src build
+    src_build: bool,
+    /// whether we are using prebuilt libs
+    /// This is only true if feature is enabled AND target is win/mac
+    prebuilt_libs: bool,
 }
 /// Use `cfg` macro to get the selected features.
 impl Default for Features {
     fn default() -> Self {
+        let os = match std::env::var("CARGO_CFG_TARGET_OS")
+            .expect("failed to get target os")
+            .as_str()
+        {
+            "windows" => TargetOs::Win,
+            "macos" => TargetOs::Mac,
+            "linux" => TargetOs::Linux,
+            "emscripten" => TargetOs::Emscripten,
+            _ => TargetOs::Others,
+        };
         Self {
             static_link: cfg!(feature = "static_link"),
             vulkan: cfg!(feature = "vulkan"),
             native: cfg!(feature = "native_handles"),
-            os: match std::env::var("CARGO_CFG_TARGET_OS")
-                .expect("failed to get target os")
-                .as_str()
-            {
-                "windows" => TargetOs::Win,
-                "macos" => TargetOs::Mac,
-                "linux" => TargetOs::Linux,
-                _ => TargetOs::Others,
-            },
+            os,
             wayland: cfg!(feature = "wayland"),
             x11: cfg!(feature = "x11"),
             egl: cfg!(feature = "native_egl"),
             osmesa: cfg!(feature = "osmesa"),
             bindgen: cfg!(feature = "bindgen"),
             gl: cfg!(feature = "native_gl"),
+            src_build: cfg!(feature = "src_build"),
+            // this feature only works on windows and mac
+            prebuilt_libs: cfg!(feature = "prebuilt_libs")
+                && (os == TargetOs::Win || os == TargetOs::Mac),
         }
     }
 }
 /// builds from source using cmake.
 /// The sources are included with this crate.
+/// feature-gated to make cmake crate optional.
 #[cfg(feature = "src_build")]
 fn build_from_src(features: Features, _out_dir: &str) {
     let mut config = cmake::Config::new("./glfw");
@@ -169,6 +226,7 @@ fn build_from_src(features: Features, _out_dir: &str) {
 }
 
 /// Generates bindings using bindgen
+/// feature-gated to make bindgen crate optional
 #[cfg(feature = "bindgen")]
 fn generate_bindings(features: Features, out_dir: &str) {
     assert!(features.bindgen); // sanity check
@@ -266,21 +324,26 @@ fn generate_bindings(features: Features, out_dir: &str) {
     for item in DUPLICATE_ITEMS {
         bindings = bindings.blocklist_item(item);
     }
+    // workaround for emscripten - https://github.com/rust-lang/rust-bindgen/issues/1941
+    if features.os == TargetOs::Emscripten {
+        bindings = bindings.clang_arg("-fvisibility=default");
+    }
     // finally!
-    bindings
+    bindings = bindings
         .merge_extern_blocks(true)
         // default is "u32", but glfw uses i32 in its API.
         .default_macro_constant_type(bindgen::MacroTypeVariation::Signed)
         // we only care about items from glfw3 header
         // This is the name of the header we gave for our made-up header above where we merged everything.
-        .allowlist_file(".*glfw3\\.h")
+        .allowlist_file(".*glfw3\\.h");
+    println!("bindgen final config: {:#?}", bindings);
+    bindings
         .generate()
         .expect("failed to generate bindings")
         .write_to_file(format!("{out_dir}/bindings.rs"))
         .expect("failed to write bindings to out_dir/bindings.rs");
 }
 /// Download prebuilt libraries
-#[cfg(not(feature = "src_build"))]
 fn download_libs(features: Features, out_dir: &str) {
     const URL: &str = "https://github.com/glfw/glfw/releases/download/3.4";
     let zip_name: &str = match features.os {
@@ -295,7 +358,7 @@ fn download_libs(features: Features, out_dir: &str) {
         }
         TargetOs::Mac => "glfw-3.4.bin.MACOS",
         _ => {
-            return;
+            unimplemented!("prebuilt libs not available for this OS");
         }
     };
     let url = format!("{}/{}.zip", URL, zip_name);