Steps
Steps make up the fundamental building blocks of BeetleboxCI. This document will describe the features of steps as well as provide examples of using them.
Overview
Every job executes as series of tasks known as steps
.
Steps can run command-line programs and by default are executed in a bash shell.
Status
An individual step may have a status:
Status | Description |
---|---|
Pass | Step has completed succesfully |
Fail | Step has failed |
Pending | Step is in progress |
Idle | Step has not started |
Not Run | Step in job not started due to previous error |
Configuration Examples
Command-line programs
Steps may be used to execute command-line programs.
To do so, the steps
key is used followed by a list of steps to execute.
You can indicate that you wish to run a command through the run
step.
The step must be provided a name through the name
key as well as the commands to be executed through the command
.
In the provided example, two steps will be executed in sequence.
The first step Say Hello World 1
demonstrates running a single line command, whilst Say Hello World 1 and 2
demonstrates how to run multiple commands in a single step.
runners:
example-runner:
image: work1-virtualbox:5000/ubuntu-generic
jobs:
example-build:
runner: example-runner
steps:
- run:
name: Say Hello World 1
command: echo "Hello World 1"
- run:
name: Say Hello World 2 and 3
command: |
echo "Hello World 2"
echo "Hello World 3"
workflows:
workflow-example:
jobs:
- example-build
Step Types
In the previous example, you would have noted that all of the steps listed are a run
type.
There are in fact two types of steps: transfer
and run
.
A transfer
step will copy files to or from a device depending on the source
and destination
specified in the step.
In order to use the transfer step, the user must ensure that they have added a record of the device to the device registry and defined the transfer
command in the device's config settings.
A run
step does exactly what it says: it runs the specified command.
The command in a run
step may be executed directly in the container which handles the job (by default) or the user may specify the on-device
option which instructs BeetleboxCI to execute the command in a terminal within the device itself (for devices that have their own operating system).
In the code snippets below, sshpass
is first installed on the job container, to allow the container to perform password authentication to access the device via SSH.
The second step transfers the contents of the the folder Hardware/package/sd_card/
to the device.
This folder came from the input artifact once the tarball was decompressed.
The transfer
step makes use of the transfer command defined in the device config, as shown in the second code snippet.
The next step is to execute a ./script.sh
on the device and send the output of the execution to a text file called output.txt
.
This script was among the files that were copied to the device in the previous step.
The final step is to read the output.txt
back from the device using another transfer step.
This job has an output artifact specified as output.txt
, and this will be the file that is read back from the device, and it will be saved as an artifact for the user to inspect.
jobs:
run-hw-brief:
runner: generic-runner
device: zcu104-device-vitis
input:
artifact:
- fpga-artifact.tar.gz
output:
artifact:
- output.txt
steps:
- run:
name: Setup
command: apt-get install sshpass
- transfer:
name: Transfer
source: Hardware/package/sd_card/*
destination: root@192.168.1.86:/mnt/sd-mmcblk0p1/
- run:
name: Run device
on-device: True
command: |
cd /mnt/sd-mmcblk0p1
./script.sh > output.txt
- transfer:
name: Transfer
source: root@192.168.1.86:/mnt/sd-mmcblk0p1/output.txt
destination: ~/
devices:
raspberry-pi:
transfer: bash -c "sshpass -p raspberry scp -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -r $SOURCE $DESTINATION"
connection: sshpass -p raspberry ssh -o "UserKnownHostsFile=/dev/null" -o "StrictHostKeyChecking=no" pi@192.168.1.92
prompt: "$"