Tools: Application launcher

Application Launcher Logo

What is CTK Application Launcher ?

CTK Application launcher is a lightweight open-source utility allowing to set environment before starting a real application. The launcher is available on Linux, Windows and MacOSX.

Getting started

You could either:

• download the pre-built binaries matching your operating system See #Why should I used the pre-build binaries ?

or

• build from the source

See also #How to integrate the launcher in my existing project ?

How does CTK Application Launcher work ?

The launcher looks for a setting file where the path of the real application and its associated environment variable are reported. While setting the environment and loading the real application, it can also display a splash screen.

The settings file follows the format as specified here: https://doc.qt.io/qt-5/qsettings.html#Format-enum

Settings file location

The launcher successively looks for a setting file located either in the current directory or in bin and lib subdirectories. The setting file should match the following pattern <LAUNCHERNAME>LauncherSettings.ini

For example:

 /home/jchris/Projects/AwesomeApp
 /home/jchris/Projects/bin/AwesomeApp-real
 /home/jchris/Projects/bin/AwesomeAppLauncherSettings.ini
 /home/jchris/Projects/lib/libFoo.so

Setting file description

The setting file should have the following format:

[General]
launcherSplashImagePath=bin/Splash.png
launcherSplashScreenHideDelayMs=1000

[Application]
path=bin/AwesomeApp-real
arguments=--multithreading-enabled

[Paths]
1\path=./bin
size=1

[LibraryPaths]
1\path=./lib
size=1

[EnvironmentVariables]
FOO_DIRS=<APPLAUNCHER_DIR>/lib<PATHSEP>/usr/local/lib

Note that the special strings <PATHSEP>, <APPLAUNCHER_NAME> and <APPLAUNCHER_DIR> will be expanded by the launcher to match the current context.

Launcher command line arguments

As described below, the launcher also provides a broad set of command line arguments.

jchris@karakoram:~/Projects/CTK-AppLauncher-Debug/bin $ ./CTKAppLauncher --launcher-help
Usage
  CTKAppLauncher [options]

Options
  --launcher-help                Display help
  --launcher-verbose             Verbose mode
  --launch                       Specify the application to launch
  --launcher-detach              Launcher will NOT wait for the application to finish
  --launcher-no-splash           Hide launcher splash
  --launcher-timeout             Specify the time in second before the launcher kills the application. -1 means no timeout (default: -1)
  --launcher-generate-template   Generate an example of setting file

Why should you use CTK Application Launcher ?

• Very easy to configure
• Standalone executable
• Available on Windows, linux and MacOSX
• Thoroughly tested

How to integrate the launcher in my existing project ?

Superbuild

• Integrate the external project definition
• Use the macro ctkAppLauncherConfigure as described below

    INCLUDE(${CTKAPPLAUNCHER_DIR}/CMake/ctkAppLauncher.cmake)
    INCLUDE(${Slicer_CMAKE_DIR}/SlicerCTKAppLauncherSettings.cmake)

    ctkAppLauncherConfigure(

      TARGET SlicerQT-real

      APPLICATION_INSTALL_SUBDIR ${Slicer_INSTALL_BIN_DIR}
      APPLICATION_NAME Slicer

      SPLASH_IMAGE_PATH ${Slicer_SOURCE_DIR}/Applications/SlicerQT/Resources/Images/SlicerSplashScreen.png
      SPLASH_IMAGE_INSTALL_SUBDIR ${Slicer_INSTALL_BIN_DIR}
      SPLASHSCREEN_HIDE_DELAY_MS 3000

      ADDITIONAL_HELP_SHORT_ARG "-h"
      ADDITIONAL_HELP_LONG_ARG "--help"
      ADDITIONAL_NOSPLASH_LONG_ARG "--no-splash"

      DESTINATION_DIR ${Slicer_BINARY_DIR}

      LIBRARY_PATHS_BUILD "${SLICER_LIBRARY_PATHS_BUILD}"
      PATHS_BUILD "${SLICER_PATHS_BUILD}"
      ENVVARS_BUILD "${SLICER_ENVVARS_BUILD}"

      LIBRARY_PATHS_INSTALLED "${SLICER_LIBRARY_PATHS_INSTALLED}"
      PATHS_INSTALLED "${SLICER_PATHS_INSTALLED}"
      ENVVARS_INSTALLED "${SLICER_ENVVARS_INSTALLED}"
      )

    install(PROGRAMS "${Slicer_BINARY_DIR}/Slicer${CMAKE_EXECUTABLE_SUFFIX}" DESTINATION ".")

    install(
      FILES "${Slicer_SOURCE_DIR}/Applications/SlicerQT/Resources/Images/SlicerSplashScreen.png" 
      DESTINATION ${Slicer_INSTALL_BIN_DIR}
      )

    install(
      FILES "${Slicer_BINARY_DIR}/SlicerLauncherSettingsToInstall.ini" 
      DESTINATION ${Slicer_INSTALL_BIN_DIR}
      RENAME SlicerLauncherSettings.ini
      )

Links for Developers

Build Instructions	Source Code	Report a problem

Known issues

• Windows: Timeout option doesn't work properly

Frequently Asked Questions

Why should I used the pre-build binaries ?

If you distribute the AppLauncher along with your Qt application and if there is a chance that Qt libraries are not installed on the host system, you will probably also distribute Qt libraries along with your package. For that reason, you will prefer using the pre-built binaries since they are statically linked against Qt.