This page details the ways you can export your application for distribution.

Installation directories and configuration

This part of the page expects full knowledge of the Config files and folder structure page.

Unix and macOS

On Unix systems, the FHS (Filesystem Hierarchy Standard) defines installation directories. The following directories are of interest:

• /bin - Essential system binaries like cat and ls. Most applications shouldn’t install here
• /etc - System-wide configuration files; Config and Content may be installed here in some cases
• /opt - Configuration files for add-ons
• /lib - Essential libraries. Most applications shouldn’t install here
• /opt - For add-on applications. If compiling in vendored (explained later) mode but not in static mode, your application and libraries will be installed there. The binary will be installed in /usr/bin using a symbolic link
• /sbin - Essential system binaries like fsck. Most applications shouldn’t install here
• /usr - Secondary hierarchy for read-only multi-user data. We install there by default
  • /bin - When compiling in unvendored mode or in static mode, your application binary will be installed there
  • /include - Headers for your application will be installed there
  • /lib - When compiling in unvendored mode without being in static mode, framework libraries will be installed there
  • /libexec - An alternative directory to bin for cases where the application is made to be executed by another application (e.g. IBus engines)
  • /local - Local host data directory. Same as /usr in structure. This may be used to debug deployment without polluting your main /usr directory
  • /sbin - Non-essential system binaries
  • /share - Architecture-independent data. By default, Content and Config are installed here
  • /src - This can store full source code of your application or the framework

By default, no user interaction is needed to control installation directories, since we already have enough metadata to calculate correct file placement. However, in some cases, it may be useful to override these locations (e.g. in cases where you’re developing a plugin for an application). This can be achieved by modifying your uvproj.yaml file to look like this:

name: "my-application"
version: "1.0.0.0"
engine-version: "1.0.0.0"
enabled-modules:
  os: false
  dbus: false
  uexec: false
  theming: false
  i18n: false
  undo_redo: false
  plotting: false
  knobs: false
  spinners: false
  toggles: false
  text_utils: false
  cli_parser: false
install-override:
  unix:
    framework-library-dir: "lib/"
    framework-application-library-dir: "lib/"
    application-binary-dir: "bin/"
    config-dir: "share/config/my-application/"
    content-dir: "share/my-application/"
    framework-include-dir: "include/my-application/"
    application-include-dir: "include/my-application/"
  macos:
    framework-library-dir: "lib/"
    framework-application-library-dir: "lib/"
    application-binary-dir: "bin/"
    config-dir: "share/config/my-application/"
    content-dir: "share/my-application/"
    framework-include-dir: "include/my-application/"
    application-include-dir: "include/my-application/"

This example uses the default directories. For example, you can change the application-binary-dir to libexec when developing an IBus engine.

Additionally, you can add custom install directives for files. For example, using the following config:

additional-installs:
  unix:
    - file: test.txt
      directory: "tmp/"
      macro-name: UNIX_TEST_INSTALL_DIR
      is-directory: false
    - file: assets/
      directory: "share/my-application/"
      macro-name: UNIX_ASSETS_INSTALL_DIR
      is-directory: true
  macos:
    - file: test.txt
      directory: "tmp/"
      macro-name: MACOS_TEST_INSTALL_DIR
      is-directory: false

The macro-name string field is used to generate a compiler macro definition that points to the directory listed.

The is-directory boolean field is used to define whether the file field points to a file or directory so that the right installation algorithm is used. Setting it to true recursively installs the directory contents under directory.

Windows

On Windows, there is no directory structure similar to that on Unix systems. For that reason, we install all files under C:/Program Files/<Your application here>, because most applications are installed there. Therefore, it makes sense to the user to find your application there as well.

You can also override this directory like this:

install-override:
  windows:
    framework-library-dir: "Program Files/my-application/"
    framework-application-library-dir: "Program Files/my-application/"
    application-binary-dir: "Program Files/my-application/"
    config-dir: "Program Files/my-application/"
    content-dir: "Program Files/my-application/"
    framework-include-dir: "Program Files/my-application/"

The folder for the application will be created automatically.

Furthermore, additional installation directives can also be added, just like on Unix:

additional-installs:
  windows:
    - file: test.txt
      directory: "C:/"
      macro-name: WINDOWS_TEST_INSTALL_DIR
      is-directory: false

Compiling for production

This section will detail all the steps to compile your application for production.

Files and directory access

Check for any cases where a file is not using predefined directory prefix macros. Documentation can be found on the directory strings and Config.hpp pages.

Enable file logging

It may be useful to log the state of the application to a file. To enable file logging, call the following functions:

Logger::setCurrentLogFile("log.txt"); // Replace this with any other file name and location
Logger::setLogOperation(UVK_LOG_OPERATION_FILE_AND_TERMINAL); // Sets the logging mode to file and terminal

* Please keep in mind that the terminal/console will be hidden when compiling for production on Windows.

Define your application distribution type

There are 4 variables that define your distribution type:

1. vendored - Means that all libraries, including the framework, will not be dynamically linked from the same libraries in PATH
2. static - Will compile the framework, application library and executable into a single executable (libraries will be linked dynamically)
3. system-wide - When this is set to true, it enables every module, regardless of settings. This is useful when the framework library has to be shipped system-wide on a Unix system
4. install-framework - When set to true, the framework headers will be installed. Defaults to false

This can be defined in the uvproj.yaml like this:

name: "ude-welcome"
version: "1.0.0.0"
engine-version: "1.0.0.0"
build-mode-vendor: false
build-mode-static: false
system-wide: false

Unix

On Unix and macOS systems, it’s recommended that you do not enable vendored builds, as the framework may already be installed globally.

Windows

On Windows systems, it’s recommended that you run a vendored build. Static builds are also recommended, except for cases where plugin support for the application is enabled.

Configure production settings

Additionally, the uvproj.yaml file allows you to set production settings under the production key:

name: "ude-welcome"
version: "1.0.0.0"
engine-version: "1.0.0.0"
build-mode-vendor: false
build-mode-static: false
system-wide: false
production:
  crash-on-error: true

List of keys:

1. crash-on-error - can be used to override the default functionality of crashing when an error is printed using UntitledLog. By default, applications are set to crash on error when compiled for production. Setting this to false disables this functionality after the renderer is started. If you need to disable crashing on error at an earlier stage, insert this line: Logger::setCrashOnError(false) in your Instance’s constructor.

Export using the UVKBuildTool

Once configured, go to the UVKBuildTool folder and run ./UVKBuildTool --build <staging prefix> <prefix> <directory to project>. The build tool will then compile and install everything as expected.

The <staging prefix> argument is used by Ports-based package managers that install files to a staging directory that then gets merged into your system prefix. If you’re not using a staging directory, simply set <staging prefix> to be the same as <prefix>.

Example packages

MadLadSquad maintains the following package repositories that you can use as a reference for your own applications:

1. Gentoo: UntitledDesktopOverlay
2. Arch Linux PKGBUILDs: AUR page
3. RPM - UntitledDesktopRPM, UntitledDesktopRPM (GitHub repository)
4. Debian, Ubuntu and derivatives - Coming soon!