Tools: Application launcher: Difference between revisions

From Commontk
Jump to navigationJump to search
No edit summary
 
(46 intermediate revisions by the same user not shown)
Line 1: Line 1:
[[Main Page|Back to CTK main page]]
[[Image:commontk_applauncher.png|200px|frame|right|Application Launcher Logo]]
[[Image:commontk_applauncher.png|200px|frame|right|Application Launcher Logo]]


=== What is CTK Application Launcher ?===  
=== What is CTK Application Launcher ?===  
Line 10: Line 7:
=== Getting started ===
=== Getting started ===


* Download: Linux, windows, MacOSX
You could either:
* download the [https://github.com/commontk/AppLauncher/releases pre-built binaries] matching your operating system {{note-with-icon-only}}See [[#Why should I used the pre-build binaries ?]]''


=== How does CTK Application Launcher works ?===  
or
 
* [[Tools:_Application_launcher/Build_Instructions|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 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




Line 83: Line 90:
* Available on Windows, linux and MacOSX
* Available on Windows, linux and MacOSX
* Thoroughly tested
* Thoroughly tested
=== How to integrate the launcher in my existing project ? ===
====  Superbuild ====
* Integrate the [[Tools:_Application_launcher/external project definition|external project definition]]
* Use the macro '''ctkAppLauncherConfigure''' as described below
<pre>
    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
      )
</pre>


= Links for Developers =
= Links for Developers =
Line 88: Line 145:
{| cellspacing="20"
{| cellspacing="20"
|- style="vertical-align:top;"
|- style="vertical-align:top;"
|| [[File:Commontk build.png|150px|link=CTKAppLauncher:Build Instructions]]
|| [[File:Commontk build.png|150px|link=Tools:_Application_launcher/Build_Instructions]]
|| [[File:Commontk sourcecode.png|150px|link=http://github.com/CTK/AppLauncher]]
|| [[File:Commontk sourcecode.png|150px|link=http://github.com/commontk/AppLauncher]]
|| [[File:Commontk dashboard.png|150px|link=http://my.cdash.org/index.php?project=CTK&subproject=CTKAppLauncher]]
<!--
|| [[File:Commontk dashboard.png|150px|link=http://my.cdash.org/index.php?project=CTKAppLauncher]]
|| [[File:commontk_ideas.png|150px|link=Tools:_Application_launcher/Project Ideas]]
-->
|| [[File:Commontk bug.png|150px|link=http://github.com/commontk/AppLauncher/issues]]
|- style="text-align:center; font-size: large"
|| [[Tools:_Application_launcher/Build_Instructions|Build Instructions]]
|| [http://github.com/commontk/AppLauncher Source Code]
<!--
|| [http://my.cdash.org/index.php?project=CTKAppLauncher Source Code's <br/>Quality Dashboard]
|| [[Tools:_Application_launcher/Project_Ideas|Project Ideas]]
-->
|| [http://github.com/commontk/AppLauncher/issues Report a problem]
|}
 
<!--
 
= Links for Dashboard Maintainers =
 
{| cellspacing="20"
|- style="vertical-align:top;"
|| [[File:Commontk dashboard setup.png|150px|link=CTKAppLauncher:Dashboard setup]]
|- style="text-align:center; font-size: large"
|- style="text-align:center; font-size: large"
|| [[CTKAppLauncher:Build Instructions|Build Instructions]]
|| [[Tools:_Application_launcher/Dashboard setup|Dashboard setup]]
|| [http://github.com/jcfr/CTKAppLauncher Source Code]
|| [http://my.cdash.org/index.php?project=CTK&subproject=CTKAppLauncher Source Code's <br/>Quality Dashboard]
|}
|}
-->
= 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.

Latest revision as of 13:38, 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 bug.png
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.