DOCSEARCHbyAlgolia
Submit Docs

gtk-rs-core

repository·main·Indexed 18 days ago

https://github.com/gtk-rs/gtk-rs-core

Safe Rust bindings for foundational GObject-based libraries, serving as the base for the gtk-rs ecosystem including GTK 3, GTK 4, and GStreamer. It provides crates such as cairo-rs, gdk-pixbuf, and gio, covering core functionality like asynchronous programming, GObject subclassing, and resource management.

Tokens
108.3K
Snippets
299
Records
538
Agent score
61%

What's inside gtk-rs-core

  1. Overview of gtk-rs-core

    main

    The gtk-rs-core repository contains the foundational Rust crates for GObject-based libraries. The gtk-rs organization provides safe Rust bindings over these libraries.

    Key components include:

    • cairo-rs: Cairo bindings
    • gdk-pixbuf: Rust GDK-PixBuf bindings
    • gio: Rust GIO bindings
    • glib: Rust GLib and GObject bindings
    • And other core libraries like atk, gdk, etc.

    Note: When using external crates that are not part of this repository, ensure they do not pull in incompatible versions of core crates like glib-rs.

  4. How glib objects and inheritance work

    main

    In glib, every class and interface has a corresponding smart pointer struct (e.g., Object for GObject). These objects follow these principles:

    • Reference Counting & Mutability: Objects are reference counted and use interior mutability, similar to the Rc<RefCell<T>> idiom. Cloning an object is cheap, and methods do not require mutable borrows (&mut self).
    • Equality: Two smart pointers are equal if they point to the same underlying object.
    • Hierarchy & Casting: The root of the object hierarchy is Object. Inheritance and subtyping are managed via the IsA marker trait. Use the Cast trait to perform upcasting and downcasting between types.
    • Trait Extensions: Interfaces and non-leaf classes provide functionality through extension traits (e.g., ObjectExt) which are blanketly implemented for all subtypes.

  5. How dynamic typing is handled in glib

    main

    GLib uses a type system that bridges static Rust types with dynamic GLib types:

    • Static Types: Most GLib types have a Type identifier. Their Rust counterparts implement the StaticType trait.
    • Dynamic Values: A [Value] can carry any type that implements StaticType.
    • Variants: [Variant] types can carry values of a [StaticVariantType].

  7. Understand the gtk-rs-core repository structure

    main

    The repository is organized into versioned branches (e.g., 0.20) and a main branch for active development.

    Each crate directory (e.g., atk/, gdk/) follows this structure:

    • README.md: Crate-specific explanations.
    • Cargo.toml: Rust crate descriptor.
    • Gir.toml: Configuration for the gir tool used to generate code.
    • src/: The high-level Rust source code.
    • sys/: 1:1 bindings of the C API.

    Special directories:

    • gir/: A git submodule containing the gir tool.
    • gir-files/: A git submodule containing the gir files used by the generator.

  8. Regenerate crates using gir

    main

    If you need to regenerate crates using gir, follow these steps:

    1. Ensure all submodules are checked out:
    $ git submodule update --checkout
    1. Run the generator script:
    $ python3 generator.py

    To test the generator with a local copy of the gir files instead of the submodule, use the --gir-files-directory argument:

    $ python3 generator.py --gir-files-directory ../gir-files/
    $ git submodule update --checkout
$ python3 generator.py

  9. Build and install the GIO VFS example module

    main

    The GIO VFS example builds a dynamic system library that acts as a GIO module. It implements file operations for URIs starting with myvfs:///.

    To build and prepare the environment, follow these steps:

    1. Build the example library using cargo.
    2. Set GIO_EXTRA_MODULES to a directory containing the compiled .so file so the gio CLI tool can load it.
    3. Set MYVFS_ROOT to define the local directory that serves as the backend for the myvfs:/// URI scheme.

    Note: If MYVFS_ROOT is set to /tmp, then the URI myvfs:///foo will point to the local path /tmp/foo.

    # Build the library
cargo build -p gtk-rs-examples --lib

# Configure GIO to load the module
export GIO_EXTRA_MODULES=/tmp/gio_modules
mkdir -p $GIO_EXTRA_MODULES && cp ./target/debug/libgio_vfs.so $GIO_EXTRA_MODULES

# Define the backend directory for myvfs:///
export MYVFS_ROOT=/tmp/myvfs
mkdir -p $MYVFS_ROOT

  10. Install gdk-pixbuf from git for bleeding edge features

    main

    If you need the latest development features, you can depend on the gtk-rs-core repository directly. When using the git dependency, ensure you specify the package name as gdk-pixbuf.

    [dependencies]
gdk-pixbuf = { git = "https://github.com/gtk-rs/gtk-rs-core.git", package = "gdk-pixbuf" }

  12. Install the glib crate

    main

    To use glib in your project, it is recommended to use the versioned crates from crates.io. If you need to track the bleeding edge, you can use the git dependency directly in your Cargo.toml.

    Warning: Do not mix versioned crates and git dependencies for the same package in your dependency list, as this will cause compilation errors.

    # To use the bleeding edge version
[dependencies]
glib = { git = "https://github.com/gtk-rs/gtk-rs-core.git", package = "glib" }