-
Notifications
You must be signed in to change notification settings - Fork 29
TOML for NI VeriStand Custom Devices
Note: A high-level understanding of TOML is recommended. For more information, see TOML.
While the pipeline entry point is defined in the Jenkinsfile, the actual substance of a VeriStand custom device build is defined in build.toml. This document describes the available configuration options in build.toml and how those options impact the actual build.
There are two types of configuration captured in the build file:
- Non-stage configuration
- Stage configuration
Table of Contents
Projects is a list of LabVIEW projects containing build specs that will be used during the build.
To define a new project, include a new table in the projects table.
[projects.newproject]
| Key | Description | Required |
|---|---|---|
path |
location of the project relative to the Jenkins build workspace | YES |
[projects.first]
path = 'src\first.lvproj'
[projects.second]
path = 'src\support\second.lvproj'
If at least one project is included, the codegen stage will be added to the pipeline. During codegen, each project will get a .config file that defines the VeriStand .Net assembly versions required to build the project for the associated VeriStand version. This keeps build information version-agnostic.
Projects can also be referenced by codegen and build steps as described below.
Dependencies is a list of other repositories containing libraries that are needed to build the current repository. It is assumed that each dependency has been built prior to the beginning of the pipeline for the current repository. This is accomplished by specifying the dependencies variable in the Jenkinsfile as described in the readme.
To define a new dependency, include a new table in the dependencies table. The new table name should match the name of the required repository. For example, if there exists repository ni-veristand-cds/dependency-repository, the definition would look like:
[dependencies.dependency-repository]
| Key | Description | Required |
|---|---|---|
libraries |
array of libraries to be copied from the dependency | YES |
copy_location |
location to copy each item in libraries relative to the Jenkins build workspace |
YES |
[depenencies.my-first-repo]
libraries = ['first.lvlibp']
copy_location = 'src'
[dependencies.my-second-repo]
libraries = ['second.llb', 'second.dll']
copy_location = 'src\deps'
If the dependency has multiple versions of a library (for instance a different copy for each supported OS), the correct version can be chosen by using the dependency_target option for codegen and build steps as described below.
The available stages of the build and their order are defined in the main pipeline. The Setup and Checkout stages are always included, but any other stages required for the build must be configured in build.toml. The order in which stages appear in the configuration does not change the order in which they occur during the build.
Some stages may require multiple steps in order to complete. For example, multiple VIs may need to run during code generation or a full build may require building multiple build specs in different projects. This is accomplished by creating a steps array for a given stage. Steps are executed in the order they appear in build.toml and are used by the Codegen and Build stages.
Each step requires a name and type key to be defined. type is the name of the supported step type that should execute
| Key | Description | Required |
|---|---|---|
name |
name of the step within the stage | YES |
type |
string matching the type of step to execute | YES |
To define a new step, a new item must be added to the steps array for the required stage.
[[stage.steps]]
The LvRunVi step executes a VI at the provided path relative to the Jenkins workspace.
| Key | Description | Required |
|---|---|---|
vi |
path to the VI to execute | YES |
[[codegen.steps]]
name = 'Generate Source'
type = 'lvRunVi'
vi = 'src\writeScript.vi'
The lvRunVi step does not accept inputs or return values. It is intended to act like a void function with no parameters. All functionality must be self-contained within the VI or its subVIs.
The LvBuildSpec step builds a single build spec under a specific target in the provided project.
| Key | Description | Required |
|---|---|---|
project |
reference to the project table in the projects section of build.toml
|
YES |
target |
name of the target that owns the build_spec
|
YES |
build_spec |
name of the specification to be built | YES |
dependency_target |
path prepended to a dependency's libraries key to fetch the correct version of a dependency |
NO |
output_dir |
path prepended to a dependency's libraries key |
NO (deprecated) |
output_libraries |
array of libraries to be copied to the output_dir
|
NO (deprecated) |
*If output_librarires is defined, output_dir must also be defined, and vice versa.
Execute a build spec with no dependencies and no alteration of the output directory.
[[build.steps]]
name = 'Configuration Library'
type = 'lvBuildSpec'
project = '{first}' # uses the value 'src\first.lvproj' from the example in the Projects section of this document
target = 'My Computer'
build_spec = 'Configuration Release'
Execute a build spec and require the 64-bit Linux dependency libraries.
[[build.steps]]
name = 'Linux x64 Library'
type = 'lvBuildSpec'
project = '{linux64}' # assume there was a 'projects.linux64' item created
target = 'Linux 64'
build_spec = 'Engine Release'
dependency_target = 'linux64' # get dependencies from linux64 directory
(Deprecated) Execute a build spec and output the specified libraries to a specific sub-directory. Builds spec My Library and copies output.llb to a pharlap directory instead of leaving it where it was built.
[[build.steps]]
name = 'Pharlap Library'
type = 'lvBuildSpec'
project = '{pharlap}' # assume there was a 'projects.pharlap' item created
target = 'PXI Pharlap'
build_spec = 'My Library'
output_libraries = ['output.llb']
output_dir = 'pharlap'
Instead of using this method, the build spec should be responsible for putting libraries in the correct location. This can be accomplished by making the Target destination directory in the build spec look like pharlap:\output.llb. The resulting build will be placed in a pharlap directory, so there is no need to specify where the output should go.
The LvBuildSpecAllTargets step builds all builds specs of the specified name in the provided project.
| Key | Description | Required |
|---|---|---|
project |
reference to the project table in the projects section of build.toml
|
YES |
build_spec |
name of the specification to be built | YES |
dependency_target |
path prepended to a dependency's libraries key to fetch the correct version of a dependency |
NO |
Execute a build spec with no dependencies.
[[build.steps]]
name = 'Engine Libraries'
type = 'lvBuildSpecAllTargets'
project = '{first}' # uses the value 'src\first.lvproj' from the example in the Projects section of this document
build_spec = 'Engine Release'
Execute a build spec and require the 64-bit Linux dependency libraries. This is a little weird because there shouldn't be multiple build specs of the same name if specific dependencies are required, but it still works. Using lvBuildSpec would be more concise.
[[build.steps]]
name = 'Linux x64 Libraries'
type = 'lvBuildSpecAllTargets'
project = '{linux64}' # assume there was a 'projects.linux64' item created
build_spec = 'Linux 64 Release'
dependency_target = 'linux64' # get dependencies from linux64 directory
The LvBuildAll step builds all build specs under all targets in the specified project.
| Key | Description | Required |
|---|---|---|
project |
reference to the project table in the projects section of build.toml
|
YES |
[[build.steps]]
name = 'My Custom Device'
type = 'lvBuildAll'
project = '{first}' # uses the value 'src\first.lvproj' from the example in the Projects section of this document
The LvSetConditionalDisableSymbol step sets a conditional disable symbol defined in the specified project to the desired value.This would typically be used during codegen to configure a project's source prior to building so only the useful code is included.
| Key | Description | Required |
|---|---|---|
project |
reference to the project table in the projects section of build.toml
|
YES |
symbol |
symbol to be set | YES |
condition |
expression to determine which value is chosen for `symbol | YES |
true_value |
desired value of symbol when condition evaluates to TRUE |
YES |
false_value |
desired value of symbol when condition evaluates to FALSE |
YES |
[[codegen.steps]]
name = 'Set Conditional Disable''
type = 'lvSetConditionalDisableSymbol'
project = '{first}' # uses the value 'src\first.lvproj' from the example in the Projects section of this document
symbol = 'My Symbol'
condition = 'lvVersion < 2017'
true_value = '2017 or later'
false_value = '2016 or earlier'
The symbol must already exist in the project. This step will not create a new disable symbol.
condition may only use comparison with lvVersion currently. The supported operators are < <= > >= ==, and !=.
The codegen stage is the first user-defined stage to execute. It is intended to execute steps that prepare the source prior to building.
To define steps to execute during codegen, include a steps array in the codegen table. Valid steps are defined above.
[[codegen.steps]]
As mentioned above, if projects has any items, the codegen stage will be included in the pipeline to generate .config files for each project. After the .config files are created, any steps defined in the [codegen.steps]] array will execute.
The build stage executes immediately after codegen. If there are no items in the [[build.steps]] array, this stage will not be added to the pipeline.
To define steps to execute during build, include a steps array in the build table. Valid steps are defined above.
[[build.steps]]
Most often, this stage will contain one or more of the lvBuild* steps. If there are no steps in [[build.steps]], this stage will not be added to the pipeline.
The package stage executes immediately after the build stage. It takes the build output and packages everything into a single file for simple distribution.
To define an archive stage, add a package table to build.toml.
[package]
The package stage requires a type to be defined, although there is currently only one supported type.
| Key | Description | Required |
|---|---|---|
type |
file extension of the final package | YES |
The nipkg package type builds a package the can be installed through NI Package Manager (NIPM). NIPM must be installed on the build machine in order to build this type.
| Key | Description | Required |
|---|---|---|
payload_dir |
location of files to be packaged | YES |
install_destination |
location where packaged files should be installed | YES |
<lvVersion>_install_destination |
location where packaged files should be installed if building with the supplied lvVersion | NO |
[package]
type = 'nipkg'
payload_dir = 'Built'
install_destination = 'documents\National Instruments\NI VeriStand {veristand_version}\Custom Devices'
2016_install_destination = 'documents\\National Instruments\\NI VeriStand {veristand_version}\\Custom Devices\\SLSC Plug-ins'
If no package stage is defined in build.toml this stage will not be added to the pipeline. If a package stage is defined, an archive stage must also be defined.
The archive stage executes immediately after the package stage. During this stage, the output of the build and package stages is copied to a more permanent location so it can be consumed later.
To define an archive stage, add an archive table to build.toml.
[archive]
| Key | Description | Required |
|---|---|---|
build_output_dir |
top-level directory containing all build output | YES |
archive_location |
absolute path to location where build_output_dir will be copied* |
YES |
*If any Build step contains an output_libraries key, only the output libraries will be copied to archive_location.
[archive]
build_output_dir = 'Built'
archive_location = 'C:\MyCustomDevice'
If any Build step contains an output_libraries key, an archive stage must exist.