include() task can be used to include other build targets in the current build execution.
The following parameters are used by the task:
|Optional name of the build target to invoke. If not specified, a default one is chosen.
|Optional path to the build file that contains the invoked target. The file of the current build script is considered when not specified.
|Optional path to the working directory for the build target. The parent directory of the target build file is used when not specified.
|Optional other parameters to pass to the invoked build target. The parameters may have any arbitrary names.
Path parameters are optional, but at least one of them must be specified.
Path parameter is missing, the target build file is considered to be the same as the one calling 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.
The result of the build target invocation. The output parameters of the invoked target is accessible using the
The following example contains two files (
# includes the compile target in saker.build
# with the "src" value as Directory parameter
include(compile, Directory: src)
# ... some other build steps
# compiles some sources in the parameter directory
# with the library from library.build on path
# include the build target in library.build
# and access the Library output parameter
LibraryPath: include(Path: library.build)[Library]
# input parameter with default value
in Sources = libsrc,
# output parameter of the compiled 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.