Working With Docker

Why should I care/ Whats the point of using docker?

• We use a compiler that can be annoying for users to install

• Our testing framework uses a different compiler, dependencies, and platform than the normal build

• Rather than install these, you can simply install docker and let it handle the dependencies.

• In the future, I want to make a dockerfile for flashing and running code as well, that way developers can customize their environments completely and not need to bother with STM32 software until absolutely necessary .

Prerequisites:

• You need docker: https://docs.docker.com/engine/install/

• linux users should download just the engine, not docker desktop (its terrible and you don't really need it)

• To push to dockerhub, youll need a dockerhub account

  • most developers do not need to worry about this, this is only for modifying and developing the dockerfiles themselves. If you need to modify a dockerfile, let me (Aadi) know, youll need access to push the built image to the dockerhub.

Windows Instructions

• Youre going to have to use docker desktop and set it up to use wsl2 as a backend. There are instructions to do that in the above link for Docker Engine Installation link

• Youll need to pull the docker images using docker pull snaccoverflow/build-zp:latest and for unit testing use docker pull snaccoverflow/test-zp:latest in powershell

• There is a powershell script for running docker build, but to run it, youll need to enable powershell script execution ( THIS IS NOT NECESSARY, DO IT AT YOUR OWN RISK)

  • Set-ExecutionPolicy RemoteSigned -Scope CurrentUser is the powershell command that will enable ps1 scripts

  • There are risks to doing this as malicious scripts can now be executed on your windows machine, leaving you vulnerable

  • If you do not want to do this the following commands are the equivalent of the ps1 script (execute in powershell)

    • cd into project folder

    • dos2unix .\Tools\build.bash will convert the build script to work with unix, because windows will mess up the script.

      • if no work its because you don’t have it https://community.chocolatey.org/packages/dos2unix

    • docker run --rm -v ${pwd}:/project snaccoverflow/build-zp:latest from the project root will run the build, and delete the container after it finishes execution.

    • docker run --rm -v ${pwd}:/project snaccoverflow/test-zp:latest from the project root will run the tests, and delete the container after it finishes execution.

  • If you dont like powershell or cmdline stuff you can make use of docker desktop, but instructions on how to use it are out of scope of this document. You can ask for help on that in #infra channel.

Linux Instructions

Building ZP3 with Docker

• pull the docker image for building

  • docker pull snaccoverflow/build-zp:latest

• run the script from the Tools folder

  • ./Tools/build-docker.bash build

• It should now do the following steps

  • Mount your ZP project folder into the docker container

  • execute the normal build script

  • the script will build ZP3 into your ./build folder

  • exit

• now your build folder should have the built ZP3 ELF

Testing ZP3 with Docker

• pull the docker image for testing

  • docker pull snaccoverflow/test-zp:latest

• run the script from the Tools folder

  • ./Tools/build-docker.bash test

• It should now do the following steps

  • Mount your ZP project folder into the docker container

  • execute the normal testing build script

  • the script will build ZP3 unit tests into your ./testing/build folder

  • run the unit tests that were just built, and display the results in your terminal

  • exit

• now your testing/build folder should have the built ZP3 unit tests

Notes

• If you have any issues with the dockers, talk to SnackOverflowError#0543

• The dockerfiles are the same ones used to do CI build and unit tests when you PR, so if they fail locally, theyll fail in PR.

• If the dockerfiles are failing (but not your code), you should see issues with dependencies, or the dockers failing to execute a step (CMake will complain that your compiler failed a simple test program). If it starts to compile, the dockers are most likely not the issue.