The aims of this workshop is to demonstrate how you can get your tests to run automatically for you 'in the clouds' using Docker and the GitHub Actions continous integration (CI) framework. This means that every time you make a change and push this to the main
branch of your repository, your tests will run, and the results will become visible in the GitHub web interface without any further actions from you.
If you're not used to using GitHub to host your APL code, worry not -- we'll work it through together. Even if you prefer another source code revisioning system, or another CI framework (like circle or jenkins), the broad strokes of the approach we'll cover here should hopefully still be relevant to you.
GitHub Actions is free to use for public repositories, and private repositories get a limited, but generous, allocation of free minutes of runner time.
To make the most of this workshop, check that
- you have Docker desktop installed
- you have Dyalog APL v18.2 installed
- you have a GitHub account you can create repositories in
- you have git installed on your computer
If you're on a Mac, install the follwing shell alias to make it easier to run Dyalog from the command line:
alias dyalog="/Applications/Dyalog-18.2.app/Contents/Resources/Dyalog/mapl"
Place this in your shell's expected config file (~/.bashrc
or ~/.bash_profile
if you use bash
or ~/.zshrc
if you use zsh
) and run source {your-shell-config-file}
.
These are the minimum requirements.
Optionally, there are plenty of auxiliary tools that make working with git
and GitHub
more streamlined if you're not a fan of the git
command line. Some examples are:
- GitHub CLI
- GitHub Desktop.
- Mac users may want to consider installing GitUp
Many popular IDEs and code editors have excellent git
and GitHub integration, e.g. Visual Studio Code.
If you do intend to use the GitHub CLI (note: optional), it might be a good idea to get that installed and set up before the day. Same with using git
over SSH (a good idea, but also optional) -- ensure you have working SSH keys installed prior to the workshop.
Now let's get this repository into your own account, and then onto your computer.
-
Fork this repository into your own GitHub account, either using
- the GitHub web interface, or
- the GitHub CLI:
gh repo fork dyalog-training/2023-TP1b
-
Clone your fork to your local machine, using one of the following methods:
- Git SSH:
git clone --recursive git@github.com:{YOUR-GITHUB-ACCOUNT}}/2023-TP1b.git
- Git HTTPS:
git clone --recursive https://github.com/{YOUR-GITHUB-ACCOUNT}/2023-TP1b.git
- GitHub Desktop
- Git SSH:
This repository contains:
- A test runner, run.aplf
- A single function under test (for demo purposes), mysum.aplf
- A directory containing two demo unit tests, written using ]dtest, tests
- A Dockerfile, capable of executing the unit tests
- A yaml file test-runner.yml, which will use the Dockerfile to run the unit tests as a GitHub Actions workflow.
Any push to the main branch of this repository should trigger the unit tests to run in the workflow.
]link.create # {/path/to}/2023-TP1b/src
Replace {/path/to}
with the actual path to the 2023-TP1b
you cloned.
]dtest {/path/to}/2023-TP1b/tests
The source directory contains a test runner that enables us to trigger the tests from the command line:
% dyalog -b -s LOAD=src
That command exits with a 0 if all went OK, and 11 otherwise.
docker build -t dytest .
Mac/Linux:
docker run --rm \
-v "$(pwd)/DBuildTest/DyalogBuild.dyalog:/home/dyalog/MyUCMDs/DyalogBuild.dyalog" \
-v "$(pwd)/src:/src" \
-v "$(pwd)/tests:/tests" \
dytest
In Windows PowerShell:
docker run --rm `
-v "${PWD}/DBuildTest/DyalogBuild.dyalog:/home/dyalog/MyUCMDs/DyalogBuild.dyalog" `
-v "${PWD}/src:/src" `
-v "${PWD}/tests:/tests" `
dytest
Using the Windows Command Prompt:
docker run --rm -v "%cd%\DBuildTest\DyalogBuild.dyalog:/home/dyalog/MyUCMDs/DyalogBuild.dyalog" -v "%cd%\src:/src" -v "%cd%\tests:/tests" dytest