Difference between revisions of "Tools: Application launcher"

From Commontk
Jump to: navigation, search
(Getting started)
(How does CTK Application Launcher work ?)
Line 21: Line 21:
 
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 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: http://doc.qt.nokia.com/qsettings.html
+
The settings file follows the format as specified here: https://doc.qt.io/qt-5/qsettings.html#Format-enum
  
  

Revision as of 12:37, 10 May 2019

Home < 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:

or


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

    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

Commontk build.png Commontk sourcecode.png Commontk ideas.png Commontk bug.png
Build Instructions Source Code Project Ideas Report a problem

Links for Dashboard Maintainers

Commontk dashboard setup.png
Dashboard setup

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.