Skip to content

Hooks

🛠️ Tools · ⬅ Top

Hooks are called to enable custom actions at specific times which can be overwritten or intercepted by the application.

hasHook

Determine if a hook exists

Usage

hasHook [ --application applicationHome ] hookName0 [ hookName1 ... ]

Does a hook exist in the local project?

Check if one or more hook exists. All hooks must exist to succeed. Return Code: 0 - If all hooks exist

Arguments

  • --application applicationHome - Path. Optional. Directory of alternate application home. Can be specified more than once to change state.
  • --extensions extensionList - ColonDelimitedList. Optional. List of extensions to search, in order for matching files in each hook directory. Defaults to BUILD_HOOK_EXTENSIONS.
  • --next scriptName - File. Optional. Locate the script found after the named script, if any. Allows easy chaining of scripts.
  • hookName0 - one or more hook names which must exist

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Environment

  • BUILD_HOOK_EXTENSIONS - ColonDelimitedList. List of extensions to run when looking for hooks BUILD_HOOK_DIRS - ApplicationDirectoryList. List of directories to search for hooks. Defaults to bin/hooks:bin/build/hooks. Colon (:) separated list. BUILD_DEBUG - CommaDelimitedList. Constant for turning debugging on during build to find errors in the build scripts. Enable debugging globally in the build scripts. Set to a comma (,) delimited list string to enable specific debugging, or true for ALL debugging, false (or blank) for NO debugging.

hookRun

Run a project hook

Usage

hookRun [ --application applicationHome ] hookName [ arguments ... ]

Run a hook in the project located at ./bin/hooks/

See (Hooks documentation)[../hooks/index.md] for standard hooks.

Hooks provide an easy way to customize your build. Hooks are binary files located in your project directory at ./bin/hooks/ and are named hookName with a .sh extension added. So the hook for version-current would be a file at:

bin/hooks/version-current.sh

Sample hooks (scripts) can be found in the build source code at ./bin/hooks/.

Default hooks (scripts) can be found in the current build version at bin/build/hooks/

Return Code: Any - The hook exit code is returned if it is run Return Code: 1 - is returned if the hook is not found

Arguments

  • --application applicationHome - Path. Optional. Directory of alternate application home.
  • --extensions extensionList - ColonDelimitedList. Optional. List of extensions to search, in order for matching files in each hook directory. Defaults to BUILD_HOOK_EXTENSIONS.
  • --next scriptName - File. Optional. Run the script found after the named script, if any. Allows easy chaining of scripts.
  • hookName - String. Required. Hook name to run.
  • ... - Arguments. Optional. Any arguments to the hook. See each hook implementation for details.
  • --help - Optional. Flag. Display this help.

Debugging settings

Append to the value of BUILD_DEBUG (a comma-delimited (,) list) and add these tokens to enable debugging:

  • hook - hookRun and hookSource and optional versions of the same functions will output additional debugging information

Examples

version="$(hookRun version-current)"

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Environment

  • BUILD_HOOK_EXTENSIONS - ColonDelimitedList. List of extensions to run when looking for hooks BUILD_HOOK_DIRS - ApplicationDirectoryList. List of directories to search for hooks. Defaults to bin/hooks:bin/build/hooks. Colon (:) separated list. BUILD_DEBUG - CommaDelimitedList. Constant for turning debugging on during build to find errors in the build scripts. Enable debugging globally in the build scripts. Set to a comma (,) delimited list string to enable specific debugging, or true for ALL debugging, false (or blank) for NO debugging.

hookSource

Run a project hook

Usage

hookSource [ --application applicationHome ] hookName [ arguments ... ]

Run a hook in the project located at ./bin/hooks/

See (Hooks documentation)[../hooks/index.md] for standard hooks.

Hooks provide an easy way to customize your build. Hooks are binary files located in your project directory at ./bin/hooks/ and are named hookName with a .sh extension added. So the hook for version-current would be a file at:

bin/hooks/version-current.sh

Sample hooks (scripts) can be found in the build source code at ./bin/hooks/.

Default hooks (scripts) can be found in the current build version at bin/build/hooks/

Return Code: Any - The hook exit code is returned if it is run Return Code: 1 - is returned if the hook is not found

Arguments

  • --application applicationHome - Path. Optional. Directory of alternate application home.
  • --extensions extensionList - ColonDelimitedList. Optional. List of extensions to search, in order for matching files in each hook directory. Defaults to BUILD_HOOK_EXTENSIONS.
  • hookName ... - String. Required. Hook to source.

Debugging settings

Append to the value of BUILD_DEBUG (a comma-delimited (,) list) and add these tokens to enable debugging:

  • hook - hookRun and hookSource and optional versions of the same functions will output additional debugging information

Examples

version="$(hookSource version-current)"

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Environment

  • BUILD_HOOK_EXTENSIONS - ColonDelimitedList. List of extensions to run when looking for hooks BUILD_HOOK_DIRS - ApplicationDirectoryList. List of directories to search for hooks. Defaults to bin/hooks:bin/build/hooks. Colon (:) separated list. BUILD_DEBUG - CommaDelimitedList. Constant for turning debugging on during build to find errors in the build scripts. Enable debugging globally in the build scripts. Set to a comma (,) delimited list string to enable specific debugging, or true for ALL debugging, false (or blank) for NO debugging.

hookRunOptional

Identical to hookRun but returns exit code zero if the

Usage

hookRunOptional [ --application applicationHome ] hookName [ arguments ... ]

Identical to hookRun but returns exit code zero if the hook does not exist.

Return Code: Any - The hook exit code is returned if it is run Return Code: 1 - is returned if the hook is not found

Arguments

  • --next scriptName - File. Optional. Run the script found after the named script, if any. Allows easy chaining of scripts.
  • --application applicationHome - Path. Optional. Directory of alternate application home.
  • --extensions extensionList - ColonDelimitedList. Optional. List of extensions to search, in order for matching files in each hook directory. Defaults to BUILD_HOOK_EXTENSIONS.
  • hookName - String. Required. Hook name to run.
  • ... - Arguments. Optional. Any arguments to the hook. See each hook implementation for details.
  • --help - Optional. Flag. Display this help.

Debugging settings

Append to the value of BUILD_DEBUG (a comma-delimited (,) list) and add these tokens to enable debugging:

  • hook - hookRun and hookSource and optional versions of the same functions will output additional debugging information

Examples

version="$(hookRunOptional version-current)"

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Environment

  • BUILD_HOOK_EXTENSIONS - ColonDelimitedList. List of extensions to run when looking for hooks

  • BUILD_HOOK_DIRS - ApplicationDirectoryList. List of directories to search for hooks. Defaults to bin/hooks:bin/build/hooks. Colon (:) separated list.

hookSourceOptional

Identical to hookRun but returns exit code zero if the

Usage

hookSourceOptional [ --application applicationHome ] [ --extensions extensionList ] hookName ...

Identical to hookRun but returns exit code zero if the hook does not exist.

Return Code: Any - The hook exit code is returned if it is run Return Code: 0 - is returned if the hook is not found

Arguments

  • --application applicationHome - Path. Optional. Directory of alternate application home.
  • --extensions extensionList - ColonDelimitedList. Optional. List of extensions to search, in order for matching files in each hook directory. Defaults to BUILD_HOOK_EXTENSIONS.
  • hookName ... - String. Required. Hook to source (if it exists).

Debugging settings

Append to the value of BUILD_DEBUG (a comma-delimited (,) list) and add these tokens to enable debugging:

  • hook - hookRun and hookSource and optional versions of the same functions will output additional debugging information

Examples

if ! hookSourceOptional test-cleanup >>"$quietLog"; then
    buildFailed "$quietLog"
fi

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Environment

  • BUILD_HOOK_EXTENSIONS - ColonDelimitedList. List of extensions to run when looking for hooks

  • BUILD_HOOK_DIRS - ApplicationDirectoryList. List of directories to search for hooks. Defaults to bin/hooks:bin/build/hooks. Colon (:) separated list.

  • BUILD_DEBUG - CommaDelimitedList. Constant for turning debugging on during build to find errors in the build scripts. Enable debugging globally in the build scripts. Set to a comma (,) delimited list string to enable specific debugging, or true for ALL debugging, false (or blank) for NO debugging.

whichHook

Find the path to a hook binary file

Usage

whichHook [ --application applicationHome ] [ --extensions extensionList ] [ --next scriptName ] hookName0 [ hookName1 ]

Does a hook exist in the local project?

Find the path to a hook. The search path is:

  • ./bin/hooks/
  • ./bin/build/hooks/

If a file named hookName with the extension .sh is found which is executable, it is output.

Arguments

  • --application applicationHome - Path. Optional. Directory of alternate application home. Can be specified more than once to change state.
  • --extensions extensionList - ColonDelimitedList. Optional. List of extensions to search, in order for matching files in each hook directory. Defaults to BUILD_HOOK_EXTENSIONS.
  • --next scriptName - File. Optional. Locate the script found after the named script, if any. Allows easy chaining of scripts.
  • hookName0 - Required. String. Hook to locate
  • hookName1 - Optional. String. Additional hooks to locate.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Environment

  • BUILD_HOOK_EXTENSIONS - ColonDelimitedList. List of extensions to run when looking for hooks BUILD_HOOK_DIRS - ApplicationDirectoryList. List of directories to search for hooks. Defaults to bin/hooks:bin/build/hooks. Colon (:) separated list. BUILD_DEBUG - CommaDelimitedList. Constant for turning debugging on during build to find errors in the build scripts. Enable debugging globally in the build scripts. Set to a comma (,) delimited list string to enable specific debugging, or true for ALL debugging, false (or blank) for NO debugging.

See Defined Hooks