saker.build Documentation TaskDoc JavaDoc

global()

The global() task can be used to access a global variable. Global variables are accessible from every build script file. They are different from the regular variables known in the language. The variables can be retrieved and assigned.

The result of the global() task can be used on the left hand side of an assignment expression.

If other scripting languages than SakerScript is used, global variables may be supported by other languages too. It is dependent on the implementation of those languages.

Global variables have very limited use-case and it is recommended to use the sparingly. One use-case might be to specify global configuration in some entry point of the build scripts, and access them from other files without the need of passing the parameters explicitly. It is recommended to have an unique name for global variables to avoid name collisions, as global variables can be assigned at most once during build execution.

Parameters

The following parameters are used by the task:

ParameterDescription
unnamedRequired name of the global variable that is being accessed.

Task result

The reference to the global variable.

Example

The following example contains two files (config.build, and saker.build):

config.build:

# this file is not uploaded to source control
# contains secret data for the project
global(company.ENCRYPTION_KEY) = abcd1234
global(company.PUBLISH_API_KEY) = Y29tcGFueV9zZWNyZXQ=

saker.build:

# this file is the main entry point for builds
# include the configuration build file
include(Path: config.build)
publish {
	# encrypt some data with a secret key
	$data = example.encrypt.data(
		Data: exampledata,
		Key: global(company.ENCRYPTION_KEY)
	)
	# publish that data to somewhere
	example.company.publish(
		$data, 
		ApiKey: global(company.PUBLISH_API_KEY)
	)
}

The above example showcases one use-case for global variables. The config.build file is not published to any source control platforms, and contains secret data related to the operation of the associated project. The saker.build file is the main entry points for builds and developers use this to build the project.

When the publish build target is invoked, the include(Path = config.build) global expression includes the config.build file. The expressions in it are invoked, and the global variables get assigned with the appropriate values. The publish task then encrypts and publishes some arbitrary data, and uses the globally set configuration values to do its work.