App Library

App libraries provide the app definitions, Bench needs, to download and install programs. Bench comes with a number of its own app libraries, hosted on GitHub and preconfigured in a newly initialized Bench environment. But sometimes you want to define your own apps, which are not included in the official Bench app libraries. To define your own apps, you can just edit the apps.md in the config directory. Because, the user configuration directory of a Bench environment is at the same time the user app library. If you want to share your app definitions with others, you can create separate app libraries and host them in different ways.

Overview

• App Definition
• File and Directory Layout
• App Index
• Custom Scripts
• App Setup Resources
• Hosting

App Definition

An app library consists of a number of app definitions. App definitions allows Bench to download extract and install Windows programs. And an app definition consists of:

1. a number of app properties specified in the app index of the library,
2. custom scripts to customize the setup steps of an app via PowerShell, and
3. setup resources, which can be used by the custom scripts.

File and Directory Layout

An app library contains at least an app index file. Additionally it can contain the custom scripts for its apps and setup resources needed by the custom scripts. It is good practice to add a readme and a license file too.

The full layout of an app library looks like this:

• apps.md App Index File
• README.md Readme file with a brief description of the app library
• LICENSE.md The license under which the app library is published
• scripts Custom Scripts Directory (AppLibCustomScriptDirName)
  • app namespace →
  • <app-id>.extract.ps1
  • <app-id>.setup.ps1
  • <app-id>.env.ps1
  • <app-id>.remove.ps1
  • <app-id>.pre-run.ps1
  • <app-id>.post-run.ps1
• res App Setup Resources Directory (AppLibResourceDirName)
  • app namespace →
  • …

Custom scripts and setup resources are organized by the namespace of their app. E.g. if an app MyNamespace.MyApp has a custom script for the environment setup, the custom script would have the path scripts\mynamespace\myapp.env.ps1.

App Index

The IDs and properties of all apps in a library are stored in the app index. The app index consists of a Markdown file, with a section for every app. Additionally to the machine readable app properties, every app definition can contain Markdown text which is displayed as a description for an app in the BenchDashboard.

App Index File

• Description: The app index file.
• Path: <app lib>\apps.md
• Config Property: AppLibIndexFileName
• Type: file
• Required: yes

The app index file is written in Markdown list syntax. Every app is defined by a number of App Properties.

Custom Scripts

Custom scripts allow the maintainer of an app library to customize certain steps in the setup and execution of apps via PowerShell scripts.

The following types of custom scripts are supported:

• extract
• setup
• env
• remove
• pre-run
• post-run
• test

If the file format of the downloadable setup program for an app is not supported by Bench, then the file extraction can be implemented in the custom script for the extract setup.

If the original setup program of a Windows application performs some necessary actions to prepare the program files for execution, these actions usually need to be reimplemented in the custom script for the setup step. And clean-up tasks to uninstall an app properly need to be implemented in the custom script for the remove step.

If the configuration files of a program contain absolute paths the programs installation directory, updating the configuration files need to be implemented in the custom script for the env step.

To perform some tasks every time before or after a program is executed, they can be implemented in the custom scripts for the pre-run and post-run steps.

When the app is tested for proper definition, the test step is performed after the installation.

App Custom Script Directory

• Description: The directory with the custom scripts of the apps.
• Path: <app lib>\scripts
• Config Property: AppLibCustomScriptDirName
• Type: directory
• Required: no

Custom scripts are organized by the namespaces of their app. E.g. if an app MyNamespace.MyApp has a custom script for the environment setup, the custom script would have the path scripts\mynamespace\myapp.env.ps1.

App Custom Script extract

• Description: Custom script for app resource extraction.
• Path: <app lib>\scripts\<app ns>\<app-id>.extract.ps1
• Type: file

Custom scripts for app resource extraction must be named with the app ID in lower case, and the name extension .extract.ps1.

The custom script for extraction is executed if the ArchiveTyp is set to auto or custom. If the ArchiveTyp of the app is set to auto and a custom script for extraction for this app exists, the custom script takes precedence over the other extraction methods.

Inside of the custom script is the PowerShell API available. Custom extraction scripts are called with two command line arguments:

1. The absolute path of the downloaded app resource archive
2. The absolute path of the target directory to extract the resources

Example for the extraction of a nested archive:

param ($archivePath, $targetDir)

$nestedArchive = "nested.zip"

# create temporary directory
$tmpDir = Empty-Dir "$(Get-ConfigValue TempDir)\custom_extract"

# get path of 7-Zip
$7z = App-Exe "Bench.7z"

# call 7-Zip to extract outer archive
& $7z x "-o$tmpDir" "$archivePath"

# check if expected inner archive exists
if (!(Test-Path "$tmpDir\$nestedArchive"))
{
    throw "Did not find the expected content in the app resource."
}

# call 7-Zip to extract inner archive
& $7z x "-o$targetDir" "$tmpDir\$nestedArchive"

# Delete temporary directory
Purge-Dir $tmpDir

App Custom Script setup

• Description: Custom script for app setup.
• Path: <app lib>\scripts\<app ns>\<app-id>.setup.md
• Type: file

Custom scripts for app resource extraction must be named with the app ID in lower case, and the name extension .setup.ps1.

If a custom setup script for an app exists, it is executed after the installation of the (extracted) app resources in the apps target dir. Inside of the custom script is the PowerShell API is available.

App Custom Script env

• Description: Custom script for environment setup.
• Path: <app lib>\scripts\<app ns>\<app-id>.env.ps1
• Type: file

Custom scripts for environment setup must be named with the app ID in lower case, and the name extension .env.ps1.

If a custom environment setup script for an app exists, it is executed after the setup to update configuration files depending on the location of Bench or other configuration properties. It is also called if the Upade Environment task for Bench is executed. Inside of the custom script is the PowerShell API available.

App Custom Script remove

• Description: Custom script for app deinstallation.
• Path: <app lib>\scripts\<app ns>\<app-id>.remove.ps1
• Type: files

Custom scripts for deinstallation must be named with the app ID in lower case, and the name extension .remove.ps1.

If a custom deinstallation script for an app exists, it is executed instead of the default uninstall method. Inside of the custom script is the PowerShell API available.

App Custom Script pre-run

• Description: Pre-run hook for adorned executables of an app.
• Path: <app lib>\scripts\<app ns>\<app-id>.pre-run.ps1
• Type: file

The custom pre-run script is executed immediately before an app executable is run. It is only executed if an app executable is run via its execution proxy. This is usually the case because it is listed in AdornedExecutables. The main executable of an app is automatically included in the list of adorned executables if the registry isolation is used. Inside of the custom script is the PowerShell API available.

App Custom Script post-run

• Description: Post-run hook for adorned executables of an app.
• Path: <app lib>\scripts\<app ns>\<app-id>.post-run.ps1
• Type: file

The custom post-run script is executed immediately after an app executable is run. It is only executed if an app executable is run via its execution proxy. This is usually the case because it is listed in AdornedExecutables. The main executable of an app is automatically included in the list of adorned executables if the registry isolation is used. Inside of the custom script is the PowerShell API available.

App Custom Script test

• Description: Test hook for testing the installation of an app.
• Path: <app lib>\scripts\<app ns>\<app-id>.test.ps1
• Type: file

The custom test script is executed, when an app definition is tested. It is executed after a successful installation, after the existence of the main executable was checked. The test script fails when it writes an error or throws an exception; otherwise it will count as a successful test.

App Setup Resources

App setup resources are files, which are used by custom scripts to perform necessary tasks during the various setup and execution steps of an app.

User App Resources Directory

• Description: The directory with setup resources for the apps.
• Path: <app lib>\res
• Config Property: AppLibResourceDirName
• Type: directory
• Required: no

App setup resources are organized by the namespaces of their app. E.g. if an app MyNamespace.MyApp has a setup resource named config-template.xml, it would have the path <app lib>\res\mynamespace\myapp\config-template.xml.

To get the absolute path of an app setup resource file from a custom script, you can use the PowerShell API function App-SetupResource.

E.g. to retrieve the path of the config-template.xml from above, the custom script <app lib>\scripts\mynamespace\myapp.setup.ps1 could contain:

$myAppDir = App-Dir "MyNamespace.MyApp"
$templateFile = App-SetupResource "MyNamespace.MyApp" "config-template.xml"
copy $templateFile "$myAppDir\config.xml" -Force

Hosting

An app library must be reachable via an URL, so it can be refered to in the AppLibs configuration property. Currently supported are https(s) and file URLs. Additionally, there is a shorthand form for GitHub hosted app libraries.

If the library is hosted via http(s), the library must be packed in a ZIP file. If the library is reachable in the file system, it can be packed in a ZIP file, but it can also just be an open folder. If the library is packed in a ZIP file, its content can be put directly in the ZIP file, or it can be wrapped in exactly one sub-folder. But in this case, no other files or folders are allowed in the root of the ZIP file.

Example 1 – open folder in the filesystem

This is a fitting approach if you want to use a locally maintained app library in multiple Bench environments, or if you have an infrastructure with SMB shares.

• Path to the app library folder: D:\applibs\my-applib
• Content of the folder:
  • apps.md
  • scripts
    • …
• URL in AppLibs: file:///D:/applibs/my-applib

Example 2 – ZIP file on a web server

This is a fitting approach if you want to share you app library without publishing it on GitHub, or if you have an intranet web server under the control of you development team. You could even store the app library in a cloud storage like DropBox and distribute a public link for sharing.

• Name of the ZIP file: my-apps.zip
• Content of the ZIP file:
  • apps.md
  • README.md
  • LICENSE.md
  • scripts
    • …
• URL in AppLibs: http://www.your-domain.net/bench-app-libs/my-apps.zip

Example 3 – public GitHub repository

This is a fitting approach if you app library is free to be used by anybody.

• Username on GitHub: the-programmer
• Repository name: favorite-bench-apps
• Content of the repository:
  • apps.md
  • README.md
  • LICENSE.md
  • scripts
    • …
• URL in the AppLibs: github:the-programmer/favorite-bench-apps
• Main branch must be: master
• Automatically expanded URL: https://github.com/the-programmer/favorite-bench-apps/archive/master.zip
• GitHub generated content of the ZIP archive:
  • favorite-bench-apps-master
    • apps.md
    • README.md
    • LICENSE.md
    • scripts