LIBCOSMIC

A platform toolkit based on iced for creating applets and applications for the COSMIC™ desktop.

Documentation

• API Documentation: Automatically generated from this repository via cargo doc
• libcosmic Book: A reference for learning libcosmic

Templates

• https://github.com/pop-os/cosmic-app-template: Application project template
• https://github.com/pop-os/cosmic-applet-template: Panel applet project template

Dependencies

While libcosmic is written entirely in Rust, some of its dependencies may require shared system library headers to be installed. On Pop!_OS, the following dependencies are all that's necessary to compile a typical COSMIC project:

sudo apt install cargo cmake just libexpat1-dev libfontconfig-dev libfreetype-dev libxkbcommon-dev pkgconf

Made-for-COSMIC Flatpak IDs

To identify a project as a COSMIC Application, add <id>com.system76.CosmicApplication</id> to the provides section of the project's metainfo.

<provides>
  <id>com.system76.CosmicApplication</id>
</provides>

For COSMIC Applets, use com.system76.CosmicApplet.

<provides>
  <id>com.system76.CosmicApplet</id>
</provides>

Publishing

Before submission, ensure that the app or applet is not violating section 5 of the COSMIC trademark policy.

Applets must be submitted to the official COSMIC Flatpak repository. This repository can be added to the system through the COSMIC Store if it is not already installed by the OS.

Applications may be submitted to Flathub. Desktop-specific components—such as COSMIC applets—are not permitted on Flathub so make sure to submit them to the COSMIC Flatpak repository instead.

Examples

Some examples are included in the examples directory to to kickstart your COSMIC adventure. To run them, you need to clone the repository with the following commands:

git clone --recurse-submodules https://github.com/pop-os/libcosmic
cd libcosmic

If you have already cloned the repository, run these to sync with the latest updates:

git fetch origin
git checkout master
git reset --hard origin/master

The examples may then be run by their cargo project names, such as just run application.

Cargo Features

Available cargo features to choose from:

• a11y: Experimental accessibility support.
• animated-image: Enables animated images from the image crate.
• debug: Enables addtional debugging features.
• smol: Uses smol as the preferred async runtime.
  • Conflicts with tokio
• tokio: Uses tokio as the preferred async runtime.
  • If unset, the default executor defined by iced will be used.
  • Conflicts with smol
• wayland: Wayland-compatible client windows.
  • Conflicts with winit
• winit: Cross-platform and X11 client window support
  • Conflicts with wayland
• wgpu: GPU accelerated rendering with WGPU.
  • By default, softbuffer is used for software rendering.
• xdg-portal: Enables XDG portal dialog integrations.

Project Showcase

• COSMIC App Library
• COSMIC Applets
• COSMIC Launcher
• COSMIC Notifications
• COSMIC Panel
• COSMIC Text Editor
• COSMIC Settings

Licence

Licensed under the Mozilla Public License 2.0.

Contact

• Mattermost
• Lemmy
• Mastodon
• Reddit
• Twitter
• Instagram