File Structure

The layout of the folders and files in the Bench environment

The file structure of Bench is divided in two groups, the core and the extended file structure. If the location of files and directories is not changed via custom or site configuration, all files and folders of Bench live in one directory: the root directory of Bench. In the following sections, the file structure is described according to the default configuration. If a directory or file can be configured to be elsewhere, the responsible configuration property is mentioned.

Core Structure

The core structure consists of directories and files, which are installed during the Bench setup, and can not be moved via custom or site configuration.

Extended Structure

The extended structure consists of directories and files, which are created during the usage of Bench – including the installation of apps, and can be moved via custom or site configuration.

Details

Bench Automation Directory

  • Description: The base directory for the Bench scripts and binaries.
  • Path: auto
  • Type: directory

Bench Binary Directory

  • Description: The directory with all binary executables and libraries of Bench.
  • Path: auto\bin
  • Type: directory

Action bench-bash

  • Description: Starts a Git Bash shell in the Bench environment.
  • Path: auto\bin\bench-bash.cmd
  • Type: file

This action will fail if Git is not installed

Action bench-cmd

  • Description: Starts a Windows CMD console in the Bench environment.
  • Path: auto\bin\bench-cmd.cmd
  • Type: file

Action bench-ps

  • Description: Starts a PowerShell console in the Bench environment.
  • Path: auto\bin\bench-ps.cmd
  • Type: file

Bench Script Directory

  • Description: The directory with the PowerShell scripts of Bench.
  • Path: auto\lib
  • Type: directory

User Configuration Directory

  • Description: The directory for the user configuration.
  • Path: config
  • Config Property: CustomConfigDir
  • Type: directory

This directory is designed to be put under version control, to manage and share Bench configurations.

The user configuration directory contains the user configuration and is the user app library at the same time.

App Activation List

  • Description: The list of activated apps.
  • Path: config\apps-activated.txt
  • Config Property: AppActivationFile
  • Type: file

The specified file must be an UTF8 encoded text file. Every non empty line, which is not commented with a # is interpreted as an app ID. Only non-space characters, up to the first space or the end of a line, are considered.

App Deactivation List

  • Description: The list of deactivated apps.
  • Path: config\apps-deactivated.txt
  • Config Property: AppDeactivationFile
  • Type: file

The specified file must be an UTF8 encoded text file. Every non empty line, which is not commented with a # is interpreted as an app ID. Only non-space characters, up to the first space or the end of a line, are considered.

User Configuration File

  • Description: The user configuration file.
  • Path: config\config.md
  • Config Property: CustomConfigFile
  • Type: file

The user configuration file is written in Markdown list syntax.

ConEmu Configuration

  • Description: The configuration for the embedded ConEmu console in the Dasboard.
  • Path: config\ConEmu.xml
  • Config Property: ConEmuConfigFile
  • Type: file

Environment Setup Hook

  • Description: The hook script for environment setup.
  • Path: config\env.ps1
  • Type: file

This script is executed, at the end of the Bench environment setup. Inside of the environment setup hook script is the PowerShell API available.

Setup Hook

  • Description: The hook script for app setup.
  • Path: configsetup.ps1
  • Type: file

This script is executed, at the end of the setup of one ore multiple apps. Inside of the setup hook script is the PowerShell API available.

Bench Resources Directory

  • Description: This directory contains resources for the Bench system.
  • Path: res
  • Type: directory

User App Library Template

App Activation Template

App Deactivation Template

Bootstrap Batch File

  • Description: The installation batch script for setup and upgrade of Bench.
  • Path: res\bench-install.bat
  • Type: file

This file is the installation program for Bench. The latest version can be downloaded from: https://github.com/winbench/bench/raw/master/res/bench-install.bat.

Site Configuration Template

  • Description: The template for the site configuration file.
  • Path: res\bench-site.template.md
  • Config Property: SiteConfigTemplateFile
  • Type: file

The site configuration file is written in Markdown list syntax.

ConEmu Configuration Template

Default Configuration

  • Description: The default configuration of Bench.
  • Path: res\config.md
  • Type: file

The default configuration file is written in Markdown list syntax.

User Configuration Template

Version File

  • Description: A text file with the version number of the Bench release as the only content.
  • Path: res\version.txt
  • Config Property: VersionFile
  • Type: file

Installation Directory

  • Description: This directory is the place for files, loaded and installed by the Bench system.
  • Path: lib
  • Config Property: LibDir
  • Type: directory

App Installation Directory

  • Description: This directory contains the app installations.
  • Path: lib\apps
  • Config Property: AppsInstallDir
  • Type: directory

Every activated app gets installed in it’s target directory. Usually the app target directories are direct sub-folders of the app installation directory. The default value for the target directory of an app is its ID in lower case.

If the app ID is namespaced, like <namespace>.<app ID>, then the namespace becomes a sub-folder in the app installation directory, and the app itself is installed in the namespace folder.

App Library Installation Directory

  • Description: This diectory is used to load the app libraries.
  • Path: lib\applibs
  • Config Property: AppLibsInstallDir
  • Type: directory

App libraries are loaded as sub-directories, named by their ID from the AppLibs table.

Execution Proxy Directory

  • Description: Execution proxy scripts for adorned executables are stored in this directory.
  • Path: lib\proxies
  • Config Property: AppsAdornmentBaseDir
  • Type: directory

For every adorned executable, a batch file is generated, which runs the actual executable with registry isolation, pre-run, and post-run scripts. These execution proxies are stored in a directory named with the apps ID, and placed in the execution proxy directory.

Launcher Script Directory

  • Description: Launcher scripts are stored in this directory.
  • Path: lib\launcher
  • Config Property: LauncherScriptDir
  • Type: directory

For every launcher, a batch file is generated, to inject command line arguments in the shell call and call the execution proxy if necessary.

Version Index Directory

  • Description: The version numbers of the currently installed apps are stored here.
  • Path: lib\versions
  • Config Property: AppsVersionIndexDir
  • Type: directory

When Bench installes an app, it stores the version number from the app property Version in a text file, named with the apps ID. This stored version number is used determine, if the app definition was updated since the installation of the app.

Initialization Script

  • Description: A convenience script for starting the initialization of the Bench environment.
  • Path: bench-initialize.cmd
  • Type: file

This file is copied from res when the Bench setup starts running. When there ist no bench-site.md or there is no config directory, the Bench environment initialization can be started with this script.

This script is merely a wrapper, which calls bench.exe manage initialize.

Setup Script

  • Description: A convenience script for starting the auto setup in the Bench environment.
  • Path: bench-setup.cmd
  • Type: file

This file is copied from res when the Bench setup starts running. When Bench is not behaving right, because some core apps are not installed, this script can help. It starts the auto setup for the actived apps.

This script is merely a wrapper, which calls bench.exe manage setup.

Update Environment Script

  • Description: A convenience script for starting the environment update.
  • Path: bench-update-env.cmd
  • Type: file

This file is copied from res when the Bench setup starts running. When bench was moved or it is used from a flash drive and the root path of bench changed, this script must be executed. It starts the update of the Bench environment. Which includes updating the env.cmd and running custom environment scripts for activated apps.

This script is merely a wrapper, which calls bench.exe manage update-env.

Changelog

  • Description: A file with a description for all changes of Bench throughout the released versions.
  • Path: CHANGELOG.md
  • Type: file

Environment Script File

  • Description: The Bench environment file.
  • Path: env.cmd
  • Type: file

This file is generated as a result of the environment setup of Bench. It can be called from another batch script to load the Bench environment.

This file sets a number of environment variables according to the Bench configuration. These environment variables provide information about the Bench system, provide the isolation from the Windows user profile, and put the Bench apps on the PATH. The following variables are always set:

  • USERNAME from UserName
  • USEREMAIL from UserEmail
  • BENCH_HOME the root directory of Bench
  • BENCH_DRIVE the drive on which the root directory of Bench is stored
  • BENCH_VERSION from the version file
  • BENCH_PATH the directories with executables from the Bench apps

License

  • Description: The text of the license under which Bench is published.
  • Path: LICENSE.md
  • Type: file

Readme

  • Description: A brief project description of Bench.
  • Path: README.md
  • Type: file

Project Archive Directory

  • Description: When the Bench task for the creation of a project backup is executed, it stores an archive file with the project in this directory.
  • Path: archive
  • Config Property: ProjectArchiveDir
  • Type: directory

The format of the archive files can be controlled via the configuration property ProjectArchiveFormat. The name of the archive files in this directory is build with the respective project name and a timestamp.

Cache

  • Description: This directory contains downloaded resources.
  • Path: cache
  • Config Property: CacheDir
  • Type: directory

App Libary Cache

  • Description: This directory contains all downloaded app libraries.
  • Path: cache\applibs
  • Config Property: AppLibsCacheDir
  • Type: directory

App Resource Cache

  • Description: This directory contains all downloaded app resources.
  • Path: cache
  • Config Property: AppsCacheDir
  • Type: directory

Home Directory

  • Description: This directory is the isolated user profile root for the Bench environment.
  • Path: home
  • Config Property: HomeDir
  • Type: directory

If the configuration property OverrideHome is set to true, the environment variables HOME and USERPROFILE in the Bench environment are pointing to this directory.

Local Application Data Directory

  • Description: This directory is the AppData\Local in the isolated user profile for the Bench environment.
  • Path: home\AppData\Local
  • Config Property: LocalAppDataDir
  • Type: directory

If the configuration property OverrideHome is set to true, the environment variable LOCALAPPDATA in the Bench environment is pointing to this directory.

Application Data Directory

  • Description: This directory is the AppData\Roaming in the isolated user profile for the Bench environment.
  • Path: home\AppData\Roaming
  • Config Property: AppDataDir
  • Type: directory

If the configuration property OverrideHome is set to true, the environment variable APPDATA in the Bench environment is pointing to this directory.

Registry Isolation Directory

  • Description: In this directory backups of registry keys are stored when the registry isolation mechanism is used.
  • Path: home\registry_isolation
  • Config Property: AppsRegistryBaseDir
  • Type: directory

Launcher Directory

  • Description: This directory contains Windows shortcuts for all activated apps with a launcher.
  • Path: launcher
  • Config Property: LauncherDir
  • Type: directory

This directory can be added as a toolbar to the Windows taskbar. This way the Bench Dashboard and all graphical apps from Bench are directly available on the Desktop.

Log Directory

  • Description: For every setup and app installation process a log file is stored in this directory.
  • Path: log
  • Config Property: LogDir
  • Type: directory

Projects Root Directory

  • Description: This directory is the root for development projects.
  • Path: projects
  • Config Property: ProjectRootDir
  • Type: directory

If a project folder is placed in this directory, Bench knows about it, and can provide assistance when working on this project in the Bench environment.

Temporary Directory

  • Description: This is the directory for temporary files in the Bench system.
  • Path: tmp
  • Config Property: TempDir
  • Type: directory

If the configuration property OverrideTemp is set to true, the environment variables TEMP and TMP in the Bench environment are pointing to this directory.

Site Configuration File

  • Description: The site configuration file(s).
  • Path: bench-site.md
  • Config Property: SiteConfigFileName
  • Type: file

This file can exist multiple times in the Bench root directory and its parents. All of them are loaded and applied after the default and custom configuration – from the file system root down to the Bench root.

Example

  1. D:\foo\bar\bench\res\config.md (Default Configuration)
  2. D:\foo\bar\bench\config\config.md (Custom Configuration)
  3. D:\foo\bench-site.md (Site Configuration)
  4. D:\foo\bar\bench\bench-site.md (Site Configuration)

The configuration files are loaded in the listed order. If a configuration value appears in multiple configuration files, the value from the file, loaded latest, wins.