include()

The include() task can be used to include other build targets in the current build execution.

Parameters

The following parameters are used by the task:

Both the Target and Path parameters are optional, but at least one of them must be specified.
If the Path parameter is missing, the target build file is considered to be the same as the one calling the include() task.
If the Target parameter is missing, a default build target will be chosen based on the structure of the target build file:

• If there is only a single build target in the file, that one is chosen.
• If the target file contains a build target named build, that one is used.
• If there are no build targets in the target file or failed to determine based on the above rules, an exception is thrown.

Keep in mind that if there are no explicit build targets, but there are global expressions in your file, then an implicit build target will be defined for you.

Note that build directory related parameter is intentionally left out. All included targets will be invoked with having the execution build directory as their build directories.

Task result

The result of the build target invocation. The output parameters of the invoked target is accessible using the [subscript] operator.

Example

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

saker.build:

build {
	# includes the compile target in saker.build
	#   with the "src" value as Directory parameter
	include(compile, Directory: src)
	# ... some other build steps
}
compile(
	in Directory,
) {
	# compiles some sources in the parameter directory
	#   with the library from library.build on path
	example.compile.sources(
		$Directory,
		# include the build target in library.build
		#   and access the Library output parameter
		LibraryPath: include(Path: library.build)[Library]
	)
}

library.build:

build(
	# input parameter with default value
	in Sources = libsrc,
	# output parameter of the compiled library
	out Library,
) {
	$Library = example.compile.library($Sources)
}

In the above example we can see that the compilation of a library and the user of that library have been decoupled into different build files. They include each other when the result of the given result is needed.