Using The Build Scripts
The same shell scripts are used both in CI and for local builds.
Running a Local Build
Run scripts/build.sh
. This will execute the desired job stages in
sequence. See build.sh for further detail & command-line options.
Variables
To enforce consistency between CI & local builds, variables are read from the
GitLab YAML files. First from gitlab/build.yml
in this project, then
.gitlab-ci.yml
in the downstream project.
Note that this file lookup relies on the common submodule being at the root of the other project. (If you followed the quick start, you’re good to go).
BASEDIR Note
The BASEDIR
variable is used to provide the absolute path to the base
directory where the build is starting from. As this is not known at CI pipeline
instantiation time, we have to use some tricks to evaluate it later, when the
jobs are running.
So you will see $${BASEDIR}
in the YAML, escaping the $ so GitLab does
not interpret it. The variable BASEDIR
is set to the repositry root in
util.sh. Then, at the time of use, envsubst
is used to substitue the
current value in.
(Perhaps all this complexity could go away if the TCL scripts / tools were able to use relative paths instead??)
Optional Variables
By default, any variable defined in build.yml is considered mandatory.
Optional variables are indicated by having the word EXTRA
in their
name.
That is, if a variable MY_VAR
is defined in build.yml
it must have a non-empty value, either from our build.yml, or from
.gitlab-ci.yml in the downstream project using this submodule.
A variable such as MY_EXTRA_VAR
is allowed to remain empty.
Quality Control
We use shellcheck to enforce good shell scripting practises. You may see some shellcheck directives in comments to control its behaviour.
Script Details
Generally, each CI job stage runs one script.
Local Build
build.sh
Only used for local builds, this loads all variables from the YAML files (both the common one speicified in this repository and the downstream one if present) and then runs the requested jobs in sequence. An interactive menu is presented to allow the choice of running partial builds (e.g. only ARGS, or only up until the synthesis check), with or without simulation & verification.
Optional arguments specify a build string, build mode, and a ‘clean mode’ (what to do if the build directory exists):
build.sh [BUILD_STRING BUILD_MODE CLEAN_MODE]
If specifying arguments by command-line, you must specify all three.
Alternately, any or all options can be specified as environment variables (named as above). An interactive menu will be presented for any unspecified options.
BUILD_MODE
choices (use the number):
1 - ARGS only
2 - ARGS + Create project
3 - ARGS + Create project + Synthesis (lint check)
4 - ARGS + Create project + Synthesis + Build (no sim)
5 - ARGS + Create project + Synthesis + Simulate & Verify (no build)
6 - Everything! (Full build, Sim & Verfiy)
CLEAN_MODE
choices:
clean - delete the directory
rename - rename the directory, appending a timestamp
use - re-use it in place, adding new build products
e.g. build.sh "my first build" 4 rename
Utility Scripts
util.sh
Sets the BASEDIR
variable, and provides these common utility functions,
used by most (all?) job stages:
export_variables
loads the variables section of a YAML file.export_default_variables
loads the common variable definitions from this project.substitute_variables
mimics GitLab’s behaviour of substituting variable names with their contents at the start of pipeline execution.check_all_variables
is used to check that all mandatory variables defined in build.yml are set at the start of each script.get_version
gets the version number from either the “.release” or “version” file.read_version_file
parses the “version” file.check_build_dir
is used to either re-use, delete, or rename an existing build directory.prepare_package_files
to collate the compilation output for packaging
self-test.sh
Verifies the script prerequisites:
Version number is available
Required variables are not empty
yq command installed
jq command installed
vhdl_set_version.sh
Injects a given semantic version number into VHDL code. Used to ensure the version reported by the FPGA matches the label of the file uploaded to the Central Artefact Repository (CAR).
vitis_settings.sh
Loads the Xilinx Vitis/Vivado settings from the configured XILINX_PATH
and VITIS_VERSION
.
args_settings.sh
Loads the ARGS setup_radiohdl.sh settings.
Job Steps
args.sh
Run the Automatic Register Generation System (ARGS) job. This builds a register map for use in later stages.
create_project.sh
Create the Vivado project by calling a downstream TCL script (defined in
CREATE_PRJ_SCRIPT_PATH
).
lint_step.sh & synth_check.tcl
Run synthesis to verify that the project is viable to build.
package_kernel.sh
Your guess is as good as mine.
generate_xo.sh
Your guess is as good as mine.
vpp.sh
Run v++, the Vitis compiler. This takes a very long time.
xsim.sh
Run a vivado simulation, using the downstream-provided xsim.tcl. Requires
variables EXTRA_XSIM_DIR
and EXTRA_MATLAB_MODEL_DIR
.
There are long and short simulations available, long simulation set number of packets per frame to be 27 and process 486 packets; short simulation set number of packets per frame to be 6 and process 108 packets only. To run short simulation, simply add two arguments to the script, i.e xsim.sh 2 false. To run long simulation, no arguments are needed. By default, vivado simulation is long simulation for gitlab, unless there is merge from a branch to main or key word ‘s_sim’ is defined in the commit message, then a short simulation is triggered. Long simulation takes about 10 hours to finish, short simulation takes about 3 hours to finish
riviera_sim.sh
Run a vivado simulation, using the downstream-provided riviera.tcl. Requires
variables EXTRA_XSIM_DIR
and EXTRA_MATLAB_MODEL_DIR
.
This script is basically a copy of xsim.sh, modified to use the Riviera-PRO simulator.
matlab.sh
Verify the simulation result. Requires EXTRA_MATLAB_MODEL_DIR
. Same as
vivado simulation, there are verify long and short simulations available as well.
To run verify short simulation, simply add one argument to the scrip, i.e
matlab.sh false. To run verify long simulation, then no argument is needed
package_firmware.sh
Bundles up the output products into an archive for distribution. If running in a CI pipeline, the archive is uploaded to the GitLab package registry.