freedesktop | Qbs Manual
Description: Provides support for some freedesktop.org specifications.

- Qbs Manual
- QbsModules
- freedesktop
- Qbs 3.1.1

# freedesktop

Provides support for some freedesktop.org specifications. More...

Since: | Qbs 1.16

- List of all members, including inherited members

## Properties

- appName : string
- desktopKeys : var
- hicolorRoot : string `(since 2.5)`

## Detailed Description

The `freedesktop` module contains properties and rules for building and working with applications compliant to freedesktop.org specifications on UNIX platforms. The areas in which this module can be of use include:

- Creation or post-processing of `.desktop` files
- Installation of AppStream metadata
- Defining the location for application icons

This module is available on all platforms but is currently only useful on UNIX platforms.

### Example usage

     Application {
         ...
         Depends { name: "freedesktop" }

         Group {
             files: [
                 ...

                 // Declare the desktop and appstream files
                 "data/my-app.desktop",
                 "data/my-app.metainfo.xml",
             ]
         }

         // Add/change some fields in the desktop file
         freedesktop.desktopKeys: ({
             'Exec': FileInfo.joinPaths(qbs.installPrefix,
                                        product.installDir,
                                        product.targetName) + ' --argument',
             'X-Application-Version': product.version,
         })

         // Define the source directory for application icons
         freedesktop.hicolorRoot: project.sourceDirectory + "/icons/"

         // Declare the application icons
         Group {
             prefix: project.sourceDirectory + "/icons/"
             files: [
                 "32x32/apps/my-application.png",
                 "32x32@2/apps/my-application.png",
                 "32x32/mimetypes/application-format.png",
                 ...
                 "scalable/apps/my-application.svg",
             ]
             fileTags: "freedesktop.appIcon"
         }
     }

### Relevant File Tags

Tag | Auto-tagged File Names | Since | Description
--- | --- | --- | ---
`"freedesktop.desktopfile_source"` | `*.desktop` | 1.16 | A source file with this tag is a `.desktop` file or fragment that will be merged into the application's final `.desktop` file.
`"freedesktop.desktopfile"` | - | 1.16 | Attached to the output artifacts of the rule that produces the merged `.desktop` file.
`"freedesktop.appstream"` | `*.metainfo.xml`, `*.appdata.xml` | 1.16 | Source files with this tag are AppStream metadata files which will be installed under installPrefix`/share/metainfo`
`"freedesktop.appIcon"` | - | 1.16 | Source files with this tag are application icons compliant with the freedesktop.org Icon Theme Specification. These icons will be installed under installPrefix`/share/icons/hicolor` in their respective resolution-based directories (e.g., `48x48/apps/`, `256x256/apps/`), ensuring compatibility with desktop environments following this specification. Note: After Qbs version 2.5, the `hicolorRoot` property must be set to define the source directory for these icons. Without setting this property, icons will not be installed.

## Property Documentation

appName : string

The display name of the application which will be stored in the `.desktop` file.

Default: product.name

desktopKeys : var

A dictionary of key-value pairs to add to the application's `.desktop` file.

The contents of this property will be aggregated with the values from any `.desktop` file. If this property and any `.desktop` files contain the same key, this property will take precedence.

Default: Undefined

hicolorRoot : string `[since 2.5]`

Defines the source directory for application icons, which are installed according to the freedesktop.org Icon Theme Specification. It is used with the `freedesktop.appIcon` tag to install icons into the `share/icons/hicolor` directory structure (e.g., `48x48/apps/`, `256x256/apps/`).

If `hicolorRoot` is not set, icons will not be installed. Set this property to the path containing your icon files.

Default: Undefined

This property was introduced in Qt 2.5.