This fallback behavior can be disabled by setting `includeSettings = false` when including the hook:

```nix
{
  lib,
  rustPlatform,
  libcosmicAppHook,
}:
let
  # Get build-time version of libcosmicAppHook
  libcosmicAppHook' = (libcosmicAppHook.__spliced.buildHost or libcosmicAppHook).override {
    includeSettings = false;
  };
in
rustPlatform.buildRustPackage {
  # ...
  nativeBuildInputs = [ libcosmicAppHook' ];
  # ...
}
```

Note that `cosmic-settings` is a separate application and not a part of the libcosmic settings
system itself. It's included by default in `libcosmicAppHook` only to provide these fallback theme
settings.

### Icons {#ssec-cosmic-icons}

COSMIC applications can use icons from the COSMIC icon theme. While COSMIC applications can build
and run without these icons, they would be missing visual elements. The `libcosmicAppHook`
automatically includes `cosmic-icons` in the wrapped application's `XDG_DATA_DIRS` as a fallback,
ensuring that the application has access to its required icons even if the system doesn't have the
COSMIC icon theme installed globally.

Unlike the `cosmic-settings` fallback, the `cosmic-icons` fallback cannot be removed or disabled, as
it is essential for COSMIC applications to have access to these icons for proper visual rendering.

### Runtime Libraries {#ssec-cosmic-runtime-libraries}

COSMIC applications built on libcosmic and Iced require several runtime libraries that are dlopen'd
rather than linked directly. The `libcosmicAppHook` ensures that these libraries are correctly
linked by setting appropriate Rust linker flags. The libraries handled include:

- Graphics libraries (EGL, Vulkan)
- Input libraries (xkbcommon)
- Display server protocols (Wayland, X11)

This ensures that the applications will work correctly at runtime, even though they use dynamic
loading for these dependencies.

### Adding custom wrapper arguments {#ssec-cosmic-custom-wrapper-args}

You can pass additional arguments to the wrapper using `libcosmicAppWrapperArgs` in the `preFixup` hook:

```nix
{
  lib,
  rustPlatform,
  libcosmicAppHook,
}:
rustPlatform.buildRustPackage {
  # ...
  preFixup = ''
    libcosmicAppWrapperArgs+=(--set-default ENVIRONMENT_VARIABLE VALUE)
  '';
  # ...
}
```

## Frequently encountered issues {#ssec-cosmic-common-issues}

### Setting up Vergen environment variables {#ssec-cosmic-common-issues-vergen}

Many COSMIC applications use the Vergen Rust crate for build-time information. The `libcosmicAppHook`
automatically sets up the `VERGEN_GIT_COMMIT_DATE` environment variable based on `SOURCE_DATE_EPOCH`
to ensure reproducible builds.

However, some applications may explicitly require additional Vergen environment variables.
Without these properly set, you may encounter build failures with errors like:

```
>   cargo:rerun-if-env-changed=VERGEN_GIT_COMMIT_DATE
>   cargo:rerun-if-env-changed=VERGEN_GIT_SHA
>
>   --- stderr
>   Error: no suitable 'git' command found!
> warning: build failed, waiting for other jobs to finish...
```

While `libcosmicAppHook` handles `VERGEN_GIT_COMMIT_DATE`, you may need to explicitly set other
variables. For applications that require these variables, you should set them directly in the
package definition:

```nix
{
  lib,
  rustPlatform,
  libcosmicAppHook,
}:
rustPlatform.buildRustPackage {
  # ...
  env = {
    VERGEN_GIT_COMMIT_DATE = "2025-01-01";
    VERGEN_GIT_SHA = "0000000000000000000000000000000000000000"; # SHA-1 hash of the commit
  };
  # ...
}
```

Not all COSMIC applications require these variables, but for those that do, setting them explicitly
will prevent build failures.