STM8 eForth Build and Test Automation
Since Travis-CI.org was discontinued a while ago STM8 eForth migrated to GitHub Actions (which is far more convenient to use) instead of moving to Travis-CI.com. At this point I'd like to thank Travis-CI for helping to make STM8 eForth better!
The docs below will be updated eventually - until then please ignore the Travis-CI set-up guide. GitHub Actions should work out of the box.
In the meantime please have a look at the GitHub Action Workflow.
STM8 eForth uses Travis-CI and Docker containers for build and test automation. The build system is based on old fashioned Make, the test automation is a bit of a unique beast in the world of embedded control.
STM8 eForth test automation is part of a continuous integration process which uses the GitHub "protected branches" feature (master is protected), Travis-CI (free for FOSS projects). It uses a Docker image with the tool chain, which includes uCsim, for building, testing, and deploying STM8 eForth binaries to GitHub Releases.
Besides the STM8 eForth repository, the relevant configuration items are:
- Test board configuration
- Travis-CI configuration
- Travis-CI STM8EF test result
- docker-sdcc Dockerfile
The test automation is part of the STM8 eForth Framework, and its designed to reduce the effort of reproducing the build, and test process.
The required steps are:
- fork the STM8 eForth repository
- create a Travis-CI account
- link your fork to your Travis-CI account
- create a set of secure credentials for deployment
- copy the credentials into your .travis.yml
Feel free to file a "support ticket" in the issue tracker if you need more information.
This project uses the free Travis-CI services for FOSS projects for quality assurance (commits and pull requests), and releases (triggered by tagging in the master branch). Downstream projects use a similar method for Forth code test and release automation based on STM8 eForth binary releases.
This section describes how forks and downstream projects can easily replicate the setup.
Create and configure a Travis-CI account
- create a free Travis-CI account
- link your GitHub account to Travis-CI
- on GitHub, fork TG9541/stm8ef
- on Travis-CI, sync your repositories, find your fork in the repository list and activate it
- edit
.travis.ymlin your fork to point to your repository - test your set-up by triggering a build manually
Protect your master branch in settings by checking the following in GitHub "Stettings/Branches/Branch Protection"
- "Protect this branch"
- "Dismiss stale pull request approvals when new commits are pushed"
- Optionally: "Require review from Code Owners"
- "Require status checks to pass before merging"
- "Require branches to be up to date before merging"
- "continuous-integration/travis-ci"
- Optionally: Include "Enforce all configured restrictions for administrators".
An automated release to GitHub Releases works by giving Travis-CI a GitHub "access token":
- install the Travis CLI tool
- run
travis setup releases --forcefor creating a secure token- enter your credentials (will be encrypted and only usable between your Travis-CI and GitHub accounts)
- compare your new
.travis.ymlwith the one in this repository, add missing lines
- tag your master branch to check if release works
The library file utils/tester.fs provides a facility for testing Forth words.
As an example, the core word SWAP can be tested with the following code:
#require utils/tester.fs
T{ 511 1 SWAP -> 1 511 }T
T{ is just "syntactic sugar", 511 1 SWAP is what we want to test, -> saves stack depth and result values, and }T compares the saved results with the expected values on the stack.
It's also possible to run regression tests on words that output text to the console. The following example tests .( ..) (comment-print):
#require utils/tester.fs
T{e .( abc123) e-> 6 444 }T
T{e redirects the console output to a test output word that counts characters, and sums up their ordinal value, .( abc123) is the phrase under test, e-> restores the console output vector, and puts the result of the test output word to the stack. }T compares the results with the expected values.
A practical way for getting the compare values is to first run the test with dummy values, and then copy the expected result to the test code.
The effectiveness of the comparison is limited: swapped characters can't be detected. Applying a CRC instead of a sum would improve detection but for automated regression tests the presented approach is sufficient.
Please refer to test/board.fs for the collection of tests currently run against the STM8 eForth core.