Skip to content

Build Functions

  • Easier access to BUILD_HOME (calculates if needed) and environment variables
  • List of all Zesk Build functions
  • Creation and easy access to cache directory
  • Access known environment variables with defaults, and installing install-bin-build.sh in new projects.

⬅ Parent

buildHome

Prints the build home directory (usually same as the application

Usage

buildHome

Prints the build home directory (usually same as the application root)

Arguments

  • none

Return codes

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

Environment

  • BUILD_HOME - Directory. BUILD_HOME is . when this code is installed - at ./bin/build. Usually an absolute path and does NOT end with a trailing slash. This is computed from the current source file using ${BASH_SOURCE[0]}.

  • BUILD_HOME - Directory. BUILD_HOME is . when this code is installed - at ./bin/build. Usually an absolute path and does NOT end with a trailing slash. This is computed from the current source file using ${BASH_SOURCE[0]}.

buildEnvironmentGet

Load and print one or more environment settings

Usage

buildEnvironmentGet [ envName ... ]

Load and print one or more environment settings

If BOTH files exist, both are sourced, so application environments should anticipate values created by build's default.

Modifies local environment. Not usually run within a subshell.

Arguments

  • envName - Optional. String. Name of the environment value to load. Afterwards this should be defined (possibly blank) and exported.
  • --application applicationHome - Path. Optional. Directory of alternate application home. Can be specified more than once to change state.

Return codes

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

Environment

  • $envName
  • BUILD_ENVIRONMENT_DIRS - DirectoryList. Search directory for environment definition files. : separated.
  • : separated list of paths to load env files

buildEnvironmentGetDirectory

Load and print one or more environment settings which represents

Usage

buildEnvironmentGetDirectory [ envName ... ]

Load and print one or more environment settings which represents a directory which should be created.

If BOTH files exist, both are sourced, so application environments should anticipate values created by build's default.

Modifies local environment. Not usually run within a subshell.

Arguments

  • envName - Optional. String. Name of the environment value to load. Afterwards this should be defined (possibly blank) and exported.
  • --subdirectory subdirectory - Optional. String. Name of a subdirectory to return "beneath" the value of environment variable. Created if the flag is set.
  • --mode fileMode - String. Optional. Enforce the mode for mkdir --mode and chmod. Use special mode - to mean no mode enforcement.
  • --owner ownerName - String. Optional. Enforce the owner of the directory. Use special ownerName - to mean no owner enforcement.

Return codes

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

Environment

  • $envName
  • BUILD_ENVIRONMENT_DIRS - DirectoryList. Search directory for environment definition files. : separated.
  • : separated list of paths to load env files

buildEnvironmentFiles

Determine the environment file names for environment variables

Usage

buildEnvironmentFiles [ envName ... ]

Determine the environment file names for environment variables

Arguments

  • envName - Optional. String. Name of the environment value to find
  • --application applicationHome - Path. Optional. Directory of alternate application home. Can be specified more than once to change state.
  • --help - Optional. Flag. Display this help.
  • --handler handler - Optional. Function. Use this error handler instead of the default error handler.

Return codes

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

Environment

buildEnvironmentLoad

Load one or more environment settings from the environment file

Usage

buildEnvironmentLoad [ envName ... ]

Load one or more environment settings from the environment file path.

If BOTH files exist, both are sourced, so application environments should anticipate values created by build's default.

Modifies local environment. Not usually run within a subshell.

Arguments

  • envName - Optional. String. Name of the environment value to load. Afterwards this should be defined (possibly blank) and exported.
  • --application applicationHome - Path. Optional. Directory of alternate application home. Can be specified more than once to change state.
  • --print - Flag. Print the environment file loaded first.
  • --help - Optional. Flag. Display this help.

Return codes

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

Environment

  • $envName
  • BUILD_ENVIRONMENT_DIRS - DirectoryList. Search directory for environment definition files. : separated.
  • : separated list of paths to load env files

buildEnvironmentContext

Run a command and ensure the build tools context matches

Usage

buildEnvironmentContext arguments ...

Run a command and ensure the build tools context matches the current project Avoid infinite loops here, call down.

Arguments

  • contextStart - Required. Directory. Context in which the command should run.
  • command ... - Required. Command to run in new context.

Return codes

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

buildFunctions

Prints the list of functions defined in Zesk Build

Usage

buildFunctions [ --help ]

Prints the list of functions defined in Zesk Build

Arguments

  • --help - Optional. Flag. Display this help.

Return codes

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

Environment

  • BUILD_HOME - Directory. BUILD_HOME is . when this code is installed - at ./bin/build. Usually an absolute path and does NOT end with a trailing slash. This is computed from the current source file using ${BASH_SOURCE[0]}.

buildCacheDirectory

Path to cache directory for build system.

Usage

buildCacheDirectory [ pathSegment ]

Path to cache directory for build system.

Defaults to $XDG_CACHE_HOME/.build unless $XDG_CACHE_HOME is not a directory.

Appends any passed in arguments as path segments.

Arguments

  • pathSegment - One or more directory or file path, concatenated as path segments using /

Examples

logFile=$(buildCacheDirectory test.log)

Return codes

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

Environment

  • XDG_CACHE_HOME - Directory. Base directory for user-specific cache data to be stored

buildQuietLog

Generate the path for a quiet log in the build

Usage

buildQuietLog name

Generate the path for a quiet log in the build cache directory, creating it if necessary.

Arguments

  • name - String. Required. The log file name to create. Trims leading _ if present.
  • --no-create - Flag. Optional. Do not require creation of the directory where the log file will appear.

Return codes

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

Running commands

tools

Run a Zesk Build command or load it

Usage

tools [ --help ] [ --start startDirectory ] [ --verbose ] [ ... ]

Run a Zesk Build command or load it

Arguments

  • --help - Optional. Flag. Display this help.
  • --start startDirectory - Directory. Optional. Start searching for a build installation at this location and searching upwards in the file hierarchy.
  • --verbose - Flag. Optional. Be verbose.
  • ... - Callable. Optional. Run this command after loading in the current build context.

Return codes

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

Installing install-bin-build.sh

installInstallBuild

Installs install-bin-build.sh the first time in a new project, and

Usage

installInstallBuild [ --help ] [ --diff ] [ --local ] [ path [ applicationHome ] ]

Installs install-bin-build.sh the first time in a new project, and modifies it to work in the application path.

Arguments

  • --help - Optional. Flag. This help.
  • --diff - Optional. Flag. Show differences between new and old files if changed.
  • --local - Optional. Flag. Use local copy of install-bin-build.sh instead of downloaded version.
  • path - Optional. Directory. Path to install the binary. Default is bin. If ends with .sh will name the binary this name.
  • applicationHome - Optional. Directory. Path to the application home directory. Default is current directory.

Return codes

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

Installing Zesk Build

Arguments

  • --local localPackageDirectory - Optional. Directory. Directory of an existing bin/build installation to mock behavior for testing
  • --url url - Optional. URL. URL of a tar.gz. file. Download source code from here.
  • --debug - Optional. Flag. Debugging is on.
  • --force - Optional. Flag. Force installation even if file is up to date.
  • --diff - Optional. Flag. Show differences between old and new file.

Return codes

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

Environment

  • Needs internet access and creates a directory ./bin/build

Package Installation

These tools are if you wish to write your own installer for your own software in bash using Zesk Build.

Copy install.sample.sh and rename, and keep up to date in your own project with bin/build/identical-repair.sh --internal.

Arguments

  • --help - Optional. Flag. Display this help.
  • relative - Required. RelativePath. Path from this script to our application root. INTERNAL.
  • defaultPackagePath - Required. RelativePath. Path from application root to where the package should be installed. INTERNAL.
  • packageInstallerName - Required. ApplicationFile. The new installer file, post installation, relative to the installationPath. INTERNAL.
  • installationPath - Optional. ApplicationDirectory. Path to where the package should be installed instead of the defaultPackagePath.
  • --help - Optional. Flag. Display this help.
  • --source source - Optional. String. Source to display for the binary name. INTERNAL.
  • --name name - Optional. String. Name to display for the remote package name. INTERNAL.
  • --local localPackageDirectory - Optional. Directory. Directory of an existing installation to mock behavior for testing. INTERNAL.
  • --url url - Optional. URL. URL of a tar.gz file. Download source code from here.
  • --user username - Optional. String. Add username:password to remote request.
  • --password passwordText - Optional. String. Add username:password to remote request.
  • --header headerText - Optional. String. Add one or more headers to the remote request.
  • --version-function urlFunction - Optional. Function. Function to compare live version to local version. Exits 0 if they match. Output version text if you want. INTERNAL.
  • --url-function urlFunction - Optional. Function. Function to return the URL to download. INTERNAL.
  • --check-function checkFunction - Optional. Function. Function to check the installation and output the version number or package name. INTERNAL.
  • --installer installer - Optional. Executable. Multiple. Binary to run after installation succeeds. Can be supplied multiple times. If installer begins with a @ then any errors by the installer are ignored.
  • --replace file - Optional. File. Replace the target file with this script and delete this one. Internal only, do not use. INTERNAL.
  • --finalize file - Optional. File. Remove the temporary file and exit 0. INTERNAL.
  • --debug - Optional. Flag. Debugging is on. INTERNAL.
  • --force - Optional. Flag. Force installation even if file is up to date.
  • --skip-self - Optional. Flag. Skip the installation script self-update. (By default it is enabled.)
  • --diff - Optional. Flag. Show differences between old and new file.

Return codes

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

Requires

cp rm cat printf realPath whichExists returnMessage fileTemporaryName catchArgument throwArgument catchEnvironment decorate usageArgumentString isFunction __decorateExtensionQuote

installInstallBinary

Installs an installer the first time in a new project,

Usage

installInstallBinary [ --help ] [ --diff ] [ --local ] [ path [ applicationHome ] ]

Installs an installer the first time in a new project, and modifies it to work in the application path.

Arguments

  • --help - Optional. Flag. This help.
  • --diff - Optional. Flag. Show differences between new and old files if changed.
  • --url - Optional. URL. A remote URL to download the installation script.
  • --url-function - Optional. Callable. Fetch the remote URL where the installation script is found.
  • --source - Required. File. The local copy of the --bin file.
  • --local - Optional. Flag. Use local copy --bin instead of downloaded version.
  • --bin - Required. String. Name of the installer file.
  • path - Optional. Directory. Path to install the binary. Default is bin. If ends with .sh will name the binary this name.
  • applicationHome - Optional. Directory. Path to the application home directory. Default is current directory.

Return codes

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

It will download and install your package as outlined in building your own installer