Appendix A — Development Environment

A.1 Source Code Repositories

The book comprises several components, on the basis of their development, deployment and maintenance. Instead of a monolithic repository containing all of them, they are organized in distinct repositories. Some are very specific to this book while others are more general finding application in other similar projects.

This might also align with and reflect the workflow for most projects in real life.

A.1.1 Application code repository

https://gitlab.com/ada23/embedded/stm32f4disco/projects.git serves as the application code repository. Divided into a series of projects of increasing functionality and complexity. It uses the adl as a submodule. It is designed to be collaborative with other components but can be used independently as well.

Each project eg. cli contains the source code, build, and flash support as well as documentation. The documentation is designed to be integrated with the book but can be built and viewed independently. Typicall the documentation includes extracts from the source code for illustrative purposes.

A.1.2 Documentation repository

The documentation structure is maintained in a separate repository: https://gitlab.com/books9915315/adaembedded.git. It is designed to be integrated with the source code repository above, with annotated source code and documentation pulled in to build the final book.

The intent is to adapt this repository for other similar books.

A.2 Integration approach

In the interest of reducing the pedagogic friction arising out of the diverse computing platforms, this book comes with a pre-configured development environment. The development environment is available as a Docker image, and can be used on any platform that supports Docker. The image includes the GNAT Ada compiler, the Alire package manager, and all the tools and libraries needed to follow along with the examples in this book.

The logical extension of the container is a Development Container; a development environment that can be used with Visual Studio Code’s Remote Containers extension. This allows you to use the full power of Visual Studio Code, including its debugging and code navigation features, while working in the container.

In fact, there are two distinct containers, one for code development, one for building the documentation and data analysis.

A.2.1 Target microcontrollers

The conceptual framework utilitizes the STM32f4 Discovery board as the target microcontroller. Versions of this book and the accompanying code are planned for the ESP32 and the Raspberry Pi Pico.

A.2.2 Usage

The containers are designed to cooperate utilizing shared volumes. The repositories of the source code and the documentation are checked out to the shared volume and the artifacts from each of the containers are shared with the others through the shared volume.

Each of the containers have ssh servers running and can be accessed using ssh. The containers are configured to listen on different ports on the host machine:

Dockerfile	Container	ssh port
Dockerfile.native	devops:latest	2222
Dockerfile.doc	docops:latest	2223
Dockerfile.data	dataops:latest	2224

A.2.3 Building the applications

The container specified by Dockerfile.native is used for building the applications. The shared volume is mounted at /ws in the container. A script buildall.py may be provided by the application to build the example applications.

cd /ws/projects
python3 buildall.py

A.2.4 Code deployment or flashing the target

If the host is Linux, the binaries may also be downloaded to the target using the tools in the container such as openocd and st-flash. Other platforms such as Windows and MacOs may not support direct download from the container and will rely on the host versions of these tools.

A.2.5 Code example extracts

In addition to the binaries of the application, the container also can generate code extracts that are used in the documentation. These code extracts are generated using the codemd tool and are made available to the documentation container through the shared volume. For instance:

codemd -D./.codemd src/*.ad*

will analyze all the ada files, extract the designated segments and deposit them in the .codemd directory.

The script pushdoc.py pushes all the documentation including code extracts in .codemd in the source code repository to the documentation environment prior to building the book.

A.2.6 Building the documentation

The container specified by Dockerfile.doc is used for building the documentation. quarto is the documentation engine used to build the documentation. The book source is made available to the container at /ws/doc and the output is typically available at /ws/doc/public. :

cd /ws/doc/src
quarto render

A.2.6.1 Example session

Once the documentation container is operational, you can log in to the container and build the documentation.

% ssh -p 2223 root@localhost
root@localhost's password: 
Welcome to Ubuntu 24.04.4 LTS (GNU/Linux 5.15.49-linuxkit-pr aarch64)

.......

root@65c4d7a7f3eb:~# cd /ws/doc/src
root@65c4d7a7f3eb:/ws/doc/src# quarto render
[1/3] index.qmd


processing file: index.qmd
1/3                
2/3 [fig-r-example]
3/3                
output file: index.knit.md



processing file: index.qmd
1/3                
2/3 [fig-r-example]
3/3                
output file: index.knit.md

[2/3] chapter1.qmd
[3/3] appendix-a.qmd

pandoc 
  to: latex
  output-file: index.tex
  standalone: true
  toc: true
  number-sections: true
  top-level-division: chapter
  pdf-engine: xelatex
  variables:
    graphics: true
    tables: true
  default-image-extension: pdf
  
metadata
  crossref:
    chapters: true
    lst-title: Listing
  documentclass: scrreprt
  papersize: letter
  classoption:
    - DIV=11
    - numbers=noendperiod
  header-includes:
    - \KOMAoption{captions}{tableheading}
  block-headings: true
  engines:
    - path: /opt/quarto/share/extension-subtrees/julia-engine/_extensions/julia-engine/julia-engine.js
  title: My Quarto Book
  subtitle: HTML + PDF + Executable Code
  author: Your Name
  date: today
  description: A sample Quarto book with Python and R execution, built and deployed via GitLab CI.
  

Rendering PDF
running xelatex - 1
  This is XeTeX, Version 3.141592653-2.6-0.999998 (TeX Live 2026) (preloaded format=xelatex)
   restricted \write18 enabled.
  entering extended mode
  
running xelatex - 2
  This is XeTeX, Version 3.141592653-2.6-0.999998 (TeX Live 2026) (preloaded format=xelatex)
   restricted \write18 enabled.
  entering extended mode
  

Output created: public/index.html

A.2.7 Data Analysis

Most of the applications in this book generate data streams that can be captured and analyzed using the documentation container. The quarto engine is layered on top of R and thus the R environment is utilized for all data analysis.