### Build and Install Casilda with Meson

Source: https://context7.com/jpu/casilda/llms.txt

Commands for setting up, building, and installing Casilda using the Meson build system. Includes installing system dependencies on Debian/Ubuntu and verifying the installation.

```bash
# Install system dependencies (Debian/Ubuntu example)
sudo apt install libgtk-4-dev libwlroots-dev libwayland-dev \
                 libxkbcommon-dev gi-docgen

# Configure — install to ~/.local for a user-local install
meson setup --wipe --prefix=~/.local _build .

# Build and install
ninja -C _build install

# Verify the pkg-config entry is available
pkg-config --modversion casilda-1.0
# => 1.2.4

# Compile a C program against the installed library
gcc -o my_compositor my_compositor.c \
    $(pkg-config --cflags --libs casilda-1.0)

# Run the bundled C example (spawns gtk4-demo embedded in the compositor)
./_build/examples/casilda-compositor-example

# Or with a named socket
./_build/examples/casilda-compositor-example /tmp/casilda-test.sock

# In a second terminal — connect any GTK 4 app to the named socket
GDK_BACKEND=wayland WAYLAND_DISPLAY=/tmp/casilda-test.sock gtk4-widget-factory
```

--------------------------------

### Launch gtk4-demo with Casilda Compositor (Python)

Source: https://context7.com/jpu/casilda/llms.txt

Launches the gtk4-demo application and connects it to the Casilda compositor. Ensure the Casilda library is installed and accessible.

```python
import gi, sys
gi.require_version("Gtk", "4.0")
gi.require_version("Casilda", "1.0")
from gi.repository import GLib, Gtk, Casilda

class App(Gtk.Application):
    def __init__(self):
        super().__init__(application_id="com.example.CasildaHost")

    def do_activate(self):
        compositor = Casilda.Compositor()   # NULL socket equivalent

        window = Gtk.ApplicationWindow(
            application=self,
            title="Casilda Demo",
            default_width=1024,
            default_height=768,
            child=compositor
        )

        # Spawns /usr/bin/gtk4-demo connected to this compositor
        compositor.spawn_async(
            None,                     # working directory
            ["/usr/bin/gtk4-demo"],
            None,                     # environment: inherit
            GLib.SpawnFlags.DEFAULT
        )

        window.present()

app = App()
sys.exit(app.run(sys.argv))
```

--------------------------------

### Install Casilda with Meson

Source: https://github.com/jpu/casilda/blob/main/README.md

Configure, build, and install Casilda using the Meson build system. Installation is typically done to ~/.local.

```bash
# Configure project in _build directory
meson setup --wipe --prefix=~/.local _build .

# Build and install in ~/.local
ninja -C _build install
```

--------------------------------

### casilda_compositor_get_client_socket_fd

Source: https://context7.com/jpu/casilda/llms.txt

Get a pre-connected client file descriptor for spawning Wayland clients. This function creates a socket pair and returns a file descriptor that is already connected to the compositor's Wayland display. This FD should be passed to a manually-launched child process via the `WAYLAND_SOCKET` environment variable. The parent process must close the returned FD after handing it to the child to ensure proper client disconnection detection.

```APIDOC
## casilda_compositor_get_client_socket_fd

### Description
Get a pre-connected client file descriptor.

Creates a socket pair and returns a file descriptor that is already connected to the compositor's Wayland display. Pass this FD to a manually-launched child process via the `WAYLAND_SOCKET` environment variable. The parent process **must close** the returned FD after handing it to the child; otherwise the compositor will not detect client disconnection.

### C Example
```c
#include <glib/gstdio.h>
#include "casilda-compositor.h"

static void
launch_custom_client (CasildaCompositor *compositor)
{
  GError *error = NULL;
  gint wayland_fd;
  GPid pid;

  /* Get an already-connected socket FD */
  wayland_fd = casilda_compositor_get_client_socket_fd (compositor);

  if (wayland_fd < 0)
    {
      g_warning ("Could not create client socket FD");
      return;
    }

  /* Build environment manually */
  gchar *wayland_socket_env = g_strdup_printf ("WAYLAND_SOCKET=%d", wayland_fd);
  gchar *envp[] = {
    "GDK_BACKEND=wayland",
    wayland_socket_env,
    NULL
  };
  gchar *argv[] = { "/usr/local/bin/my-wayland-client", NULL };

  gboolean ok = g_spawn_async_with_pipes_and_fds (
      NULL, (const gchar *const *) argv, (const gchar *const *) envp,
      G_SPAWN_DEFAULT, NULL, NULL,
      -1, -1, -1,
      &wayland_fd, &wayland_fd, 1,   /* pass FD to child */
      &pid, NULL, NULL, NULL, &error
  );

  /* IMPORTANT: close on the parent side after passing to the child */
  close (wayland_fd);
  g_free (wayland_socket_env);

  if (!ok)
    {
      g_warning ("Spawn failed: %s", error->message);
      g_clear_error (&error);
    }
}
```
```

--------------------------------

### Embed CasildaCompositor in GtkScrolledWindow

Source: https://context7.com/jpu/casilda/llms.txt

Integrates CasildaCompositor as a GtkScrollable within a GtkScrolledWindow. Scrollbars appear automatically when the hosted application exceeds the viewport size. Requires GtkApplication and CasildaCompositor setup.

```c
static void
activate (GtkApplication *app, gpointer user_data)
{
  GtkWidget *window, *sw;
  CasildaCompositor *compositor;

  window = gtk_application_window_new (app);
  gtk_window_set_default_size (GTK_WINDOW (window), 800, 600);

  /* GtkScrolledWindow automatically wires hadjustment/vadjustment */
  sw = gtk_scrolled_window_new ();
  gtk_scrolled_window_set_policy (GTK_SCROLLED_WINDOW (sw),
                                  GTK_POLICY_AUTOMATIC,
                                  GTK_POLICY_AUTOMATIC);

  compositor = casilda_compositor_new (NULL);
  gtk_scrolled_window_set_child (GTK_SCROLLED_WINDOW (sw), GTK_WIDGET (compositor));
  gtk_window_set_child (GTK_WINDOW (window), sw);
  gtk_window_present (GTK_WINDOW (window));

  /* Spawn a large app — scrollbars appear automatically when it exceeds 800×600 */
  gchar *argv[] = { "/usr/bin/gtk4-demo", NULL };
  casilda_compositor_spawn_async (compositor, NULL, argv, NULL,
                                   G_SPAWN_DEFAULT, NULL, NULL, NULL, NULL);
}
```

--------------------------------

### Launch gtk4-demo with Casilda Compositor (JavaScript)

Source: https://context7.com/jpu/casilda/llms.txt

Launches the gtk4-demo application and connects it to the Casilda compositor using GJS. Casilda automatically sets necessary environment variables.

```javascript
import System from 'system';
import GLib from 'gi://GLib';
import GObject from 'gi://GObject';
import Gtk from 'gi://Gtk?version=4.0';
import Casilda from 'gi://Casilda?version=1.0';

const CasildaApp = GObject.registerClass({}, class CasildaApp extends Gtk.Application {
    constructor() {
        super({ application_id: 'com.example.CasildaHost' });
    }

    vfunc_activate() {
        const compositor = new Casilda.Compositor();

        const window = new Gtk.ApplicationWindow({
            application: this,
            title: 'Casilda Demo',
            default_width: 1024,
            default_height: 768,
            child: compositor
        });

        window.connect('close-request', () => this.quit());

        // Spawn gtk4-demo; Casilda sets GDK_BACKEND and WAYLAND_SOCKET automatically
        compositor.spawn_async(null, ['/usr/bin/gtk4-demo'], null, GLib.SpawnFlags.DEFAULT, null);

        window.present();
    }
});

new CasildaApp().run([System.programInvocationName, ...ARGV]);
```

--------------------------------

### Spawn Client Process in Compositor (C)

Source: https://context7.com/jpu/casilda/llms.txt

Launches a child process (e.g., gtk4-demo) and configures its environment to connect to a private CasildaCompositor. This is useful for embedding other GTK 4 applications. Requires the `casilda-compositor.h` header.

```c
/* C — spawn gtk4-demo inside the compositor */
static void
activate (GtkApplication *app, gpointer user_data)
{
  GtkWidget *window;
  CasildaCompositor *compositor;
  GError *error = NULL;
  GPid child_pid;

  window = gtk_application_window_new (app);
  gtk_window_set_default_size (GTK_WINDOW (window), 1024, 768);

  /* NULL socket = private compositor, no external connections allowed */
  compositor = casilda_compositor_new (NULL);
  gtk_window_set_child (GTK_WINDOW (window), GTK_WIDGET (compositor));
  gtk_window_present (GTK_WINDOW (window));

  gchar *argv[] = { "/usr/bin/gtk4-demo", NULL };

  gboolean ok = casilda_compositor_spawn_async (
      compositor,
      NULL,              /* working directory: inherit */
      argv,
      NULL,              /* envp: inherit current environment */
      G_SPAWN_DEFAULT,
      NULL,              /* child_setup callback */
      NULL,              /* user_data for child_setup */
      &child_pid,        /* receives the child PID */
      &error
  );

  if (!ok)
    {
      g_warning ("Failed to spawn child: %s", error->message);
      g_clear_error (&error);
    }
  else
    g_message ("Child launched with PID %d", child_pid);
}
```

--------------------------------

### Create and Present Casilda Compositor

Source: https://github.com/jpu/casilda/blob/main/README.md

Instantiate a CasildaCompositor widget and set it as the child of a GTK window. The window is then presented.

```c
compositor = casilda_compositor_new (NULL);
gtk_window_set_child (GTK_WINDOW (window), GTK_WIDGET (compositor));
gtk_window_present (GTK_WINDOW (window));
```

--------------------------------

### Launch Custom Client with Wayland Socket FD (C)

Source: https://context7.com/jpu/casilda/llms.txt

Manually launches a custom Wayland client, passing a pre-connected Wayland socket file descriptor. The parent process must close the FD after passing it to the child.

```c
#include <glib/gstdio.h>
#include "casilda-compositor.h"

static void
launch_custom_client (CasildaCompositor *compositor)
{
  GError *error = NULL;
  gint wayland_fd;
  GPid pid;

  /* Get an already-connected socket FD */
  wayland_fd = casilda_compositor_get_client_socket_fd (compositor);

  if (wayland_fd < 0)
    {
      g_warning ("Could not create client socket FD");
      return;
    }

  /* Build environment manually */
  gchar *wayland_socket_env = g_strdup_printf ("WAYLAND_SOCKET=%d", wayland_fd);
  gchar *envp[] = {
    "GDK_BACKEND=wayland",
    wayland_socket_env,
    NULL
  };
  gchar *argv[] = { "/usr/local/bin/my-wayland-client", NULL };

  gboolean ok = g_spawn_async_with_pipes_and_fds (
      NULL, (const gchar *const *) argv, (const gchar *const *) envp,
      G_SPAWN_DEFAULT, NULL, NULL,
      -1, -1, -1,
      &wayland_fd, &wayland_fd, 1,   /* pass FD to child */
      &pid, NULL, NULL, NULL, &error
  );

  /* IMPORTANT: close on the parent side after passing to the child */
  close (wayland_fd);
  g_free (wayland_socket_env);

  if (!ok)
    {
      g_warning ("Spawn failed: %s", error->message);
      g_clear_error (&error);
    }
}
```

--------------------------------

### casilda_compositor_spawn_async

Source: https://context7.com/jpu/casilda/llms.txt

Spawns a child process and configures it to connect to the compositor. This is useful for embedding other GTK 4 applications.

```APIDOC
## casilda_compositor_spawn_async — Launch a client process inside the compositor

### Description
Spawns a child process and automatically injects the correct Wayland environment variables (`GDK_BACKEND=wayland`, `WAYLAND_DISPLAY` or `WAYLAND_SOCKET`) so the child connects to this compositor. `DISPLAY` is stripped to prevent fallback to X11. This is the simplest way to embed another GTK 4 application. Wraps `g_spawn_async_with_pipes_and_fds`.

### Method
`casilda_compositor_spawn_async(CasildaCompositor *compositor, const char *working_directory, char *const argv[], char *const envp[], GPid *child_pid, GError **error)`

### Parameters
#### Path Parameters
- **compositor** (CasildaCompositor *) - Required - The compositor instance.
- **working_directory** (string) - Optional - The working directory for the child process. `NULL` to inherit.
- **argv** (char *const[]) - Required - The argument list for the child process.
- **envp** (char *const[]) - Optional - The environment variables for the child process. `NULL` to inherit.
- **child_pid** (GPid *) - Output - Pointer to store the child process ID.
- **error** (GError **) - Output - Pointer to store any errors.
```

--------------------------------

### Create CasildaCompositor with Named Socket (C)

Source: https://context7.com/jpu/casilda/llms.txt

Creates a CasildaCompositor widget that exposes a named Wayland display socket. External clients can connect using the WAYLAND_DISPLAY environment variable.

```c
#include <gtk/gtk.h>
#include "casilda-compositor.h"

static void
activate (GtkApplication *app, gpointer user_data)
{
  GtkWidget *window, *sw;
  CasildaCompositor *compositor;

  window = gtk_application_window_new (app);
  gtk_window_set_title (GTK_WINDOW (window), "Casilda Compositor");
  gtk_window_set_default_size (GTK_WINDOW (window), 1024, 768);

  /* Wrap in a GtkScrolledWindow to get scrollable support */
  sw = gtk_scrolled_window_new ();

  /* Named socket — clients can connect with WAYLAND_DISPLAY=/tmp/my-compositor.sock */
  compositor = casilda_compositor_new ("/tmp/my-compositor.sock");

  gtk_scrolled_window_set_child (GTK_SCROLLED_WINDOW (sw), GTK_WIDGET (compositor));
  gtk_window_set_child (GTK_WINDOW (window), sw);
  gtk_window_present (GTK_WINDOW (window));
}

int
main (int argc, char **argv)
{
  g_autoptr (GtkApplication) app =
    gtk_application_new ("com.example.CasildaHost", G_APPLICATION_DEFAULT_FLAGS);
  g_signal_connect (app, "activate", G_CALLBACK (activate), NULL);
  return g_application_run (G_APPLICATION (app), argc, argv);
}
```

--------------------------------

### Spawn Process in Casilda Compositor

Source: https://github.com/jpu/casilda/blob/main/README.md

Spawn a new process asynchronously within the Casilda compositor. This is useful for embedding other application windows.

```c
gchar *argv[] = { "/usr/bin/gtk4-demo", NULL };
casilda_compositor_spawn_async (compositor, NULL, argv, NULL, G_SPAWN_DEFAULT, NULL, NULL, NULL, NULL);
```

--------------------------------

### Clone Casilda Repository

Source: https://github.com/jpu/casilda/blob/main/README.md

Clone the Casilda source code repository from GNOME gitlab.

```bash
git clone https://gitlab.gnome.org/jpu/casilda.git
```

--------------------------------

### Version macros

Source: https://context7.com/jpu/casilda/llms.txt

Compile-time version checking for Casilda. This section explains how to use version macros to ensure compatibility with specific Casilda library versions at compile time.

```APIDOC
## Version macros

### Description
Compile-time version checking.

Casilda exposes standard GLib-style version macros defined in the generated `casilda-version.h` header (included transitively via `<casilda.h>`). These allow guarding code against specific library versions at compile time.

### C Example
```c
#include <casilda.h>

static void
print_version_info (void)
{
  /* Print version string at runtime */
  g_message ("Running against Casilda %s", CASILDA_VERSION_S);

  /* Integer comparison — encoded as (major << 24 | minor << 16 | micro << 8) */
  g_message ("Version hex: 0x%08x", CASILDA_VERSION_HEX);

  /* Compile-time guard: use an API that appeared in 1.2 */
#if CASILDA_CHECK_VERSION(1, 2, 0)
  g_message ("Fractional scaling support available");
#else
  g_message ("Running on Casilda < 1.2 — no fractional scaling");
#endif

  /* Individual components */
  g_message ("Major=%d  Minor=%d  Micro=%d",
             CASILDA_MAJOR_VERSION,
             CASILDA_MINOR_VERSION,
             CASILDA_MICRO_VERSION);
}
```
```

--------------------------------

### casilda_compositor_new

Source: https://context7.com/jpu/casilda/llms.txt

Creates a new CasildaCompositor widget. It can expose a named Wayland display via a UNIX socket or run as a private compositor.

```APIDOC
## casilda_compositor_new — Create a compositor widget

### Description
Creates a new `CasildaCompositor` widget. Pass a UNIX socket path to expose a named Wayland display that any external client can connect to via `WAYLAND_DISPLAY`, or pass `NULL` to run a private compositor where clients are connected programmatically via `casilda_compositor_spawn_async` or `casilda_compositor_get_client_socket_fd`.

### Method
`casilda_compositor_new(const char *socket_path)`

### Parameters
#### Path Parameters
- **socket_path** (string) - Optional - UNIX socket path for the Wayland display. `NULL` for a private compositor.
```

--------------------------------

### Compile-time Casilda Version Checking (C)

Source: https://context7.com/jpu/casilda/llms.txt

Checks the Casilda library version at compile time using version macros. This allows conditionally compiling code based on API availability.

```c
#include <casilda.h>

static void
print_version_info (void)
{
  /* Print version string at runtime */
  g_message ("Running against Casilda %s", CASILDA_VERSION_S);

  /* Integer comparison — encoded as (major << 24 | minor << 16 | micro << 8) */
  g_message ("Version hex: 0x%08x", CASILDA_VERSION_HEX);

  /* Compile-time guard: use an API that appeared in 1.2 */
#if CASILDA_CHECK_VERSION(1, 2, 0)
  g_message ("Fractional scaling support available");
#else
  g_message ("Running on Casilda < 1.2 — no fractional scaling");
#endif

  /* Individual components */
  g_message ("Major=%d  Minor=%d  Micro=%d",
             CASILDA_MAJOR_VERSION,
             CASILDA_MINOR_VERSION,
             CASILDA_MICRO_VERSION);
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.