Production export and deployment

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

Caution

On macOS, the framework can also be shipped as an application bundle, which uses its own special folder structure that ignores the FHS.

Distributing your application as an application bundle is the only way to distribute your application, unless it's made to only be invoked from the command line. More information can be found here.

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 may be installed here in some
  • /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 is 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
  notifications: false
  polkit: false
  ufont: 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
  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.

Tip

When installing on Freedesktop systems(Linux and BSD), try to also consider the XDG Base directory specification when deciding on installation directories.

The XDG Module provides a library that implements the spec and allows you to interact with it.

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 also find your application there.

As on Unix and macOS, 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:
  window:
    - file: test.txt
      directory: "C:/"
      macro-name: WINDOWS_TEST_INSTALL_DIR
      is-directory: false

Compiling for production

This section will detail all 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 3 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-vendored: 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-vendored: 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 lets 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>.

Note

Only <prefix> changes the directory strings.

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. Debian & derivatives - Coming soon!
4. RPM - Coming soon!