This page lists tips many common tasks when developing applications for different platforms

Windows

Introduction to resource files

Resource files in Windows are special scripts that can be used to set different resources for your application, such as icons, cursors, string tables, etc.

The main use for a resource file in your application will mainly be setting the application's icon. They are capable of much more, but most of the time you'd find it easier and more practical to use the framework's facilities, such as the i18n module for localisation.

Here is the most basic example of a resource file:

#include "resource.h"

IDI_APP_ICON ICON "Icon.ico"

This resource file, as well as resource.h can be found under the Config/Resources/ folder. More information on resources can be found here.

Warning

When editing resource.h you might encounter an error citing an unexpected end of line. To fix it simply add an empty line at the bottom of the file.

Creating a .ico application icon

As said in the previous paragraph, icons in resource files are in the .ico format, which is similar to the Apple .icns format, by their ability to store images of multiple sizes in a single icon file.

Tip

The image names in Config/Resources/Icon.iconset are completely compatible with .ico files, so it's best you put all your icons there and reuse them for macOS and Windows

In order to create a .ico file, install ImageMagick, which is a utility for converting between different image formats.

Using the following command you can generate a .ico file in your Config/Resources directory:

user $ cd Config/Resources/Icon.iconset/
user $ magick *.png Icon.ico && mv Icon.ico .https://madladsquad.com/

Tip

If ImageMagick is detected on your system, the build scripts will automatically try to compile your

Setting the types of files your application can open

Unlike on macOS, or Linux, where such settings are stored in a per-application file, on Windows, you have to write to the registry. Stack overflow question for more information.

It's a good practice to do this step in your application's installer script, so that elevated privileges are required only during installation.

macOS

Introduction to application bundles

Since macOS is Unix-based, the default installation directories set in the UVKBuildTool are set to the standard Unix directories.

This is fine for utility applications, that you do not want to be discoverable in application menus, however, if your application is made to be used by normal users, you will need to implement an application bundle.

An application bundle is a special type of folder that contains your application's binaries and some additional metadata. These application bundles are installed to the /Applications folder and have the .app extension.

These bundles can then be further archived into the familiar .dmg format, where they can then be distributed to users on your website, an app store, or a package manager, like Homebrew.

Enabling the creation of application bundles

In order to enable the creation of application bundles, you need to modify your uvproj.yaml file to enable bundling.

Here is an example that enables both bundling, and packaging:

name: "UImGuiDemo"
version: "1.0.0.0"
engine-version: "1.0.0.0"
build-mode-static: false
build-mode-vendor: true
system-wide: false
macos:
  bundle: true

Caution

Application bundles are self-contained which means that some settings in your uvproj.yaml file might not behave as expected:

  1. Compilation is always in vendored mode, because your application can only rely on the OS libraries
  2. The framework is always going to be installed, for the same reason

Setting up an Info.plist file

Now that you have enabled bundling, you need to set up your Info.plist file. Since release v0.9.9.8 of the framework each newly created project should have the macOS folder containing an Info.plist file. Example:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <!-- Application Metadata -->
    <key>CFBundleName</key>
    <string>UImGuiDemo</string>

    <key>CFBundleDisplayName</key>
    <string>UntitledImGuiFramework Demo</string>

    <key>CFBundleIdentifier</key>
    <string>com.madladsquad.UImGuiDemo</string>

    <key>CFBundleVersion</key>
    <string>1.0</string>

    <key>CFBundleShortVersionString</key>
    <string>1.0.0</string>

    <!-- Executable -->
    <key>CFBundleExecutable</key>
    <string>UImGuiDemo</string>

    <key>CFBundlePackageType</key>
    <string>APPL</string>

    <!-- Icon -->
    <key>CFBundleIconFile</key>
    <string>example-icon</string>

    <!-- Minimum macOS Version -->
    <key>LSMinimumSystemVersion</key>
    <string>12.0.0</string>

    <!-- High Resolution Support -->
    <key>NSHighResolutionCapable</key>
    <true/>

    <!-- Application Category -->
    <key>LSApplicationCategoryType</key>
    <string>public.app-category.utilities</string>

    <!-- Security Configuration -->
    <key>NSAppTransportSecurity</key>
    <dict>
        <key>NSAllowsArbitraryLoads</key>
        <false/>
    </dict>
</dict>
</plist>

This file is installed automatically when targeting an application bundle.

Tip

The Info.plist file can also be used to define the types of files your application can open.

Configuring your icon

Application bundles require icons to be in the .icns format. In order to generate such a file for your application, you can use iconutil, which is a standard utility that should already be installed on your system.

To package your icons, do the following:

  1. Create a folder named <application name>.iconset
  2. Add your icon at different sizes, so that your folder's structure looks like this: 
    AppIcon.iconset/
├── icon_16x16.png
├── icon_16x16@2x.png
├── icon_32x32.png
├── icon_32x32@2x.png
├── icon_128x128.png
├── icon_128x128@2x.png
├── icon_256x256.png
├── icon_256x256@2x.png
├── icon_512x512.png
├── icon_512x512@2x.png
  3. After that, run iconutil -c icns AppIcon.iconset to generate an AppIcon.icns file

When building the bundle, the UVKBuildTool will try to create an icon set and install it correctly as App.app/Contents/Resources/App.icns.

Tip

Sometimes, during local development and testing, you may encounter an issue, where the application displays the correct item in the application drawer when opened, but it doesn't, in other places, such as Finder. This can usually be solved by either restarting Finder using killall Finder, or by restarting your computer.

This is caused by Finder and other system UI, having updated the applications database, before your build system could fully install everything in /Applications, leading these application to believe that your application is corrupt in some way.

Packaging as a .dmg installer

Creating .dmg installers for your application is out of the scope of the framework's build system, due to the many options and edge-cases that need to be handled. Check out a project like create-dmg for a nice CLI utility for creating .dmg installers.

Freedesktop

Installing files in standard directories

On Unix-based systems, it's really important to make sure you're following the Filesystem hierarchy standard and XDG base directory specifications. You can use the XDG basedir submodule for an easy way to get the correct directories.

Desktop files

When developing an application for freedesktop-based systems, you need a .desktop file for it. This file lists metadata, that controls the following:

  1. Whether the application can be seen in the menus
  2. What file types the application can open
  3. The icon of the application on some desktop environments(for example, GNOME)
  4. Right-click items on the dock/taskbar
  5. Name of the application in multiple languages
  6. And more

Here is an example desktop file, which details everything about it. After being installed to /usr/share/applications/ the application will appear in the menus and application search in the desktop.

[Desktop Entry]
Type=Application
Version=1.0
Name=UntitledDesktop Session Logout
GenericName=SessionLogout
Comment=Allows the user to log out, power off, restart and put the computer to sleep using a GUI
Icon=ude-session-logout
TryExec=ude-session-logout
Exec=ude-session-logout
Categories=System;Utility;
Terminal=false
StartupNotify=false
StartupWMClass=ude-session-logout

More information on the Freedesktop desktop entry specification.

Tip

Always set the StartupWMClass property of the desktop file to your application's binary name, as set in the uvproj.yaml file. This makes some desktop environments, like GNOME, to use the correct icon for your application's window.

Interacting with the desktop environment

Many applications may need to interact with the desktop environment as part of their feature set. On Freedesktop systems most interactions between applications go through standardised DBus interfaces. You can enable the dbus submodule to easily communicate over the bus in a type- and memory-safe manner.

There are many standard interfaces, however there are 2 main types:

  1. Normal interfaces
  2. XDG desktop portals

Normal interfaces and XDG desktop portal interfaces can be very similar, however there are a few differences. For starters, XDG desktop portals were created for applications that were are containerised in environments like Flatpak or Snaps. They may provide better security features, or may be updated more frequently compared to normal interfaces. On the other hand, they may lack many features that might be a security concern in containerised workflows.

A list of XDG desktop portal interfaces can be found here.

A list of normal standardised DBus interfaces can be found here, though they are mixed with other XDG standards.