Add source for JOSS'25 paper

Signed-off-by: Antonio Paolillo <[email protected]>

Author: apaolillo

doc/joss25/build.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python3
+"""
+Build the JOSS25 paper using pythainer.
+"""
+
+from pythainer.runners import ConcreteDockerRunner
+from pathlib import Path
+IMAGE = "myimg"
+CONTAINER = "myimg"
+LIB_DIR = "/home/${USER_NAME}/workspace/libraries"
+
+
+def main() -> None:
+    """Build the JOSS25 paper according to JOSS website instructions."""
+    this_dir = Path(__file__).parent.resolve()
+
+    runner = ConcreteDockerRunner(
+        image="openjournals/inara",
+        environment_variables={
+            "JOURNAL": "joss",
+        },
+        volumes={
+            f"{this_dir}": "/data",
+        },
+        other_options=[],
+        tty=False,
+        interactive=False,
+    )
+
+    runner.run()
+
+
+if __name__ == "__main__":
+    main()

doc/joss25/paper.bib

@@ -0,0 +1,189 @@
+@misc{nvblox,
+  title        = {{nvblox: GPU-Accelerated Incremental Signed Distance Field Mapping}},
+  author       = {Alexander Millane and Helen Oleynikova and Emilie Wirbel and Remo Steiner and Vikram Ramasamy and David Tingdahl and Roland Siegwart},
+  year         = 2024,
+  url          = {https://arxiv.org/abs/2311.00626},
+  eprint       = {2311.00626},
+  archiveprefix = {arXiv},
+  primaryclass = {cs.RO}
+}
+
+@misc{robotcore,
+  title        = {{RobotCore: An Open Architecture for Hardware Acceleration in ROS 2}},
+  author       = {Víctor Mayoral-Vilches and Sabrina M. Neuman and Brian Plancher and Vijay Janapa Reddi},
+  year         = 2023,
+  url          = {https://arxiv.org/abs/2205.03929},
+  eprint       = {2205.03929},
+  archiveprefix = {arXiv},
+  primaryclass = {cs.RO}
+}
+
+@inproceedings{tani2020reproducible,
+  title        = {{Integrated Benchmarking and Design for Reproducible and Accessible Evaluation of Robotic Agents}},
+  author       = {Tani, Jacopo and Daniele, Andrea F. and Bernasconi, Gianmarco and Camus, Amaury and Petrov, Aleksandar and Courchesne, Anthony and Mehta, Bhairav and Suri, Rohit and Zaluska, Tomasz and Walter, Matthew R. and Frazzoli, Emilio and Paull, Liam and Censi, Andrea},
+  year         = 2020,
+  booktitle    = {2020 IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS)},
+  volume       = {},
+  number       = {},
+  pages        = {6229--6236},
+  doi          = {10.1109/IROS45743.2020.9341677},
+  keywords     = {Benchmark testing;Tools;Hardware;Software;Complexity theory;Robots;System analysis and design}
+}
+
+@article{macenski2022ros2,
+  title        = {{Robot Operating System 2: Design, architecture, and uses in the wild}},
+  author       = {Steven Macenski  and Tully Foote  and Brian Gerkey  and Chris Lalancette  and William Woodall},
+  year         = 2022,
+  journal      = {Science Robotics},
+  volume       = 7,
+  number       = 66,
+  pages        = {eabm6074},
+  doi          = {10.1126/scirobotics.abm6074},
+  url          = {https://www.science.org/doi/abs/10.1126/scirobotics.abm6074},
+  eprint       = {https://www.science.org/doi/pdf/10.1126/scirobotics.abm6074}
+}
+
+@manual{nvidiaCudaPg13,
+  title        = {{CUDA C++ Programming Guide}},
+  year         = 2025,
+  note         = {Version 13.0},
+  organization = {NVIDIA Corporation},
+  howpublished = {\url{https://docs.nvidia.com/cuda/cuda-c-programming-guide/}, accessed 2025-09-15}
+}
+
+@misc{qemu,
+  title        = {{QEMU: A generic and open source machine emulator and virtualizer}},
+  author       = {{QEMU Project}},
+  year         = 2003,
+  howpublished = {\url{https://www.qemu.org/} accessed 2025-09-15}
+}
+
+@misc{docker,
+  title        = {{Docker: Accelerated Container Application Development}},
+  author       = {{Docker, Inc.}},
+  year         = 2013,
+  howpublished = {\url{https://www.docker.com/} accessed 2025-09-15}
+}
+
+@inproceedings{llvm,
+  title        = {{LLVM: a compilation framework for lifelong program analysis & transformation}},
+  author       = {Lattner, C. and Adve, V.},
+  year         = 2004,
+  booktitle    = {International Symposium on Code Generation and Optimization, 2004. CGO 2004.},
+  volume       = {},
+  number       = {},
+  pages        = {75--86},
+  doi          = {10.1109/CGO.2004.1281665},
+  keywords     = {Information analysis;Program processors;Performance analysis;High level languages;Virtual machining;Runtime;Arithmetic;Application software;Software safety;Algorithm design and analysis}
+}
+
+@inproceedings{mlir,
+  title        = {{MLIR: Scaling Compiler Infrastructure for Domain Specific Computation}},
+  author       = {Lattner, Chris and Amini, Mehdi and Bondhugula, Uday and Cohen, Albert and Davis, Andy and Pienaar, Jacques and Riddle, River and Shpeisman, Tatiana and Vasilache, Nicolas and Zinenko, Oleksandr},
+  year         = 2021,
+  booktitle    = {2021 IEEE/ACM International Symposium on Code Generation and Optimization (CGO)},
+  volume       = {},
+  number       = {},
+  pages        = {2--14},
+  doi          = {10.1109/CGO51591.2021.9370308},
+  keywords     = {Program processors;Buildings;Semantics;Hardware;Software;Generators;Optimization}
+}
+
+@inproceedings{shen2025sentryrt1,
+  title        = {{SentryRT‑1: A Case Study in Evaluating Real‑Time Linux for Safety‑Critical Robotic Perception}},
+  author       = {Yuwen Shen and Jorrit Vander Mynsbrugge and Nima Roshandel and Robin Bouchez and Hamed FirouziPouyaei and Constantin Scholz and Hoang‑Long Cao and Bram Vanderborght and Wouter Joosen and Antonio Paolillo},
+  year         = 2025,
+  month        = {July 8},
+  booktitle    = {Proceedings of the 19th Workshop on Operating Systems Platforms for Embedded Real‑Time Applications (OSPERT 2025)},
+  address      = {Brussels, Belgium},
+  series       = {ECRTS Workshops},
+  pages        = {35--41}
+}
+
+@misc{itf24safebot,
+  title        = {{imec ITF World 2024 SAFEBOT demo}},
+  year         = 2024,
+  note         = {Demonstration booth at imec Technology Forum (ITF) 2024},
+  howpublished = {\url{https://www.youtube.com/watch?v=F7m5_kQ_mRQ} accessed 2025-09-15}
+}
+
+@inproceedings{degreef2025macros,
+  title        = {{Towards Macro-Aware C-to-Rust Transpilation (WIP)}},
+  author       = {De Greef, Robbe and Discepoli, Attilio and Aguililla Klein, Esteban and Engels, Th\'{e}o and Hasselmann, Ken and Paolillo, Antonio},
+  year         = 2025,
+  booktitle    = {Proceedings of the 26th ACM SIGPLAN/SIGBED International Conference on Languages, Compilers, and Tools for Embedded Systems},
+  location     = {Seoul, Republic of Korea},
+  publisher    = {Association for Computing Machinery},
+  address      = {New York, NY, USA},
+  series       = {LCTES '25},
+  pages        = {57–61},
+  doi          = {10.1145/3735452.3735535},
+  isbn         = 9798400719219,
+  url          = {https://doi.org/10.1145/3735452.3735535},
+  abstract     = {The automatic translation of legacy C code to Rust presents significant challenges, particularly in handling preprocessor macros.   C macros introduce metaprogramming constructs that operate at the text level, outside of C's syntax tree, making their direct translation to Rust non-trivial.   Existing transpilers --- source-to-source compilers --- expand macros before translation, sacrificing their abstraction and reducing code maintainability.   In this work, we introduce Oxidize, a macro-aware C-to-Rust transpilation framework that preserves macro semantics by translating C macros into Rust-compatible constructs while selectively expanding only those that interfere with Rust's stricter semantics.  We evaluate our techniques on a small-scale study of real-world macros and find that the majority can be safely and idiomatically transpiled without full expansion.},
+  numpages     = 5,
+  keywords     = {Abstract Syntax Tree, C, Embedded, Macros, Metaprogramming, Preprocessor, Rust, Transpilation}
+}
+
+@inproceedings{discepoli2025computeKernels,
+  title        = {{Compute Kernels as Moldable Tasks: Towards Real‑Time Gang Scheduling in GPUs}},
+  author       = {Attilio Discepoli and Mathias Louis Huygen and Antonio Paolillo},
+  year         = 2025,
+  month        = {July 8},
+  booktitle    = {Proceedings of the 19th Workshop on Operating Systems Platforms for Embedded Real‑Time Applications (OSPERT 2025)},
+  address      = {Brussels, Belgium},
+  series       = {ECRTS Workshops},
+  pages        = {29--33}
+}
+
+@misc{docker_compose,
+  title        = {{Docker Compose}},
+  author       = {{Docker, Inc.}},
+  year         = 2014,
+  howpublished = {\url{https://docs.docker.com/compose/} accessed 2025-09-15}
+}
+
+@misc{docker_sdk_python,
+  title        = {{Docker SDK for Python}},
+  author       = {{Docker, Inc.}},
+  year         = 2014,
+  howpublished = {\url{https://docker-py.readthedocs.io/} accessed 2025-09-15}
+}
+
+@misc{devcontainers,
+  title        = {{Development Containers Specification}},
+  author       = {{Dev Containers Spec}},
+  year         = 2022,
+  howpublished = {\url{https://containers.dev} accessed 2025-09-15}
+}
+
+@misc{repo2docker,
+  title        = {{repo2docker: Turn repositories into Jupyter-enabled Docker images}},
+  author       = {{Project Jupyter}},
+  year         = 2017,
+  howpublished = {\url{https://repo2docker.readthedocs.io/} accessed 2025-09-15}
+}
+
+@inproceedings{nix04lisa,
+  title        = {{Nix: A Safe and Policy-Free System for Software Deployment}},
+  author       = {Dolstra, Eelco and de Jonge, Merijn and Visser, Eelco},
+  year         = 2004,
+  booktitle    = {Proceedings of the 18th USENIX Conference on System Administration},
+  location     = {Atlanta, GA},
+  publisher    = {USENIX Association},
+  address      = {USA},
+  series       = {LISA '04},
+  pages        = {79–92},
+  abstract     = {Existing systems for software deployment are neither safe nor sufficiently flexible. Primary safety issues are the inability to enforce reliable specification of component dependencies, and the lack of support for multiple versions or variants of a component. This renders deployment operations such as upgrading or deleting components dangerous and unpredictable. A deployment system must also be flexible (i.e., policy-free) enough to support both centralised and local package management, and to allow a variety of mechanisms for transferring components. In this paper we present Nix, a deployment system that addresses these issues through a simple technique of using cryptographic hashes to compute unique paths for component instances.},
+  numpages     = 14
+}
+
+@misc{courtes2013guix,
+  title        = {{Functional Package Management with Guix}},
+  author       = {Ludovic Courtès},
+  year         = 2013,
+  url          = {https://arxiv.org/abs/1305.4584},
+  eprint       = {1305.4584},
+  archiveprefix = {arXiv},
+  primaryclass = {cs.PL}
+}

doc/joss25/paper.md

@@ -0,0 +1,142 @@
+---
+title: "pythainer: composable and reusable Docker builders and runners for reproducible research"
+tags:
+  - Python
+  - Docker
+  - reproducibility
+  - software engineering
+  - research tooling
+  - system software
+authors:
+  - name: Antonio Paolillo
+    orcid: 0000-0001-6608-6562
+    # affiliation: 1
+affiliations:
+  - name: Software Languages Lab, Vrije Universiteit Brussel (VUB), Belgium
+    # index: 1
+    ror: 006e5kg04
+date: 16 September 2025
+bibliography: paper.bib
+---
+
+# Summary
+
+Software experiments today often depend on complex Linux environments that
+combine several toolchains, devices, and graphical interfaces. Many research
+projects [@nvblox; @robotcore], for instance, need to
+compose ROS 2 [@macenski2022ros2] with CUDA [@nvidiaCudaPg13], require non-root
+users, provide GPU and GUI access, and must be reproducible across time and
+machines. Docker [@docker] is a widely adopted substrate for packaging and
+running such environments, and is widely used to improve reproducibility in
+research software [@tani2020reproducible]. However, writing and maintaining
+Dockerfiles and project-specific `docker run` scripts becomes a burden as
+requirements grow.
+
+`pythainer` raises the level of abstraction while remaining Docker-native. It
+lets users describe images as small, testable Python *builders* that can be
+composed (e.g., ROS 2 + CUDA ) and executed with reusable *runners* that capture
+runtime policy (GPU, GUI, users, mounts). `pythainer` renders deterministic
+Dockerfiles, builds standard images, and centralizes run
+configuration—improving reuse and reducing duplication across repositories.
+
+# Statement of need
+
+Plain Dockerfiles are intentionally minimal: they offer sequential shell steps
+but no first-class functions, loops, or composition. This is adequate for simple
+images, yet it complicates reuse in research settings where environments must be
+combined and parameterized. In particular, merging two existing images (e.g.,
+community ROS 2 and NVIDIA CUDA) is not first-class; multi-stage builds help
+trim artifacts but require intimate knowledge of which files, environment
+variables, and paths must be copied and preserved. On the runtime side, real
+projects often need non-root users, persistent volumes, access to GPUs and GUIs
+(X11/Wayland), and device mappings. These concerns are typically maintained as
+long shell scripts that are copy-pasted and diverge across projects.
+
+`pythainer` addresses these pain points by adding a programmable front-end for
+image construction and a reusable abstraction for execution policy. Builders are
+Python objects and functions that support ordinary programming constructs
+(conditionals, loops, parameters) and can be composed with a simple operator.
+Runners encapsulate repeatable `docker run` policy, so launching a container is
+a matter of selecting presets rather than rewriting long commands. The target
+audience includes research groups and labs (robotics, vision, ML systems,
+compilers, systems), instructors who need reliable student environments, and
+continuous integration (CI) maintainers who prefer deterministic builds and
+centralized run policy over ad-hoc scripts.
+
+# Functionality
+
+`pythainer` is a lightweight Python package and CLI that provides a
+programmable front-end to Docker. Instead of writing raw Dockerfiles and shell
+scripts, users compose images with builders and control runtime behavior with
+runners. The library integrates naturally into Python workflows but remains
+Docker-native: it renders deterministic Dockerfiles, builds them with the
+Docker engine, and executes containers with reproducible runtime settings.
+`pythainer` provides:
+
+- **Builders (image construction).** A small API exposes common steps (e.g.,
+  FROM/RUN/ENV/WORKDIR, package installs). Builders can be composed via an
+  in-place operator to form larger images (e.g., ROS 2 + CUDA). Output
+  rendering is deterministic, which simplifies testing and review. The tool
+  remains Docker-native: it emits standard Dockerfiles and uses the Docker
+  engine to build images [@docker].
+
+- **Runners (execution policy).** A runner object assembles `docker run` flags
+  for typical research needs: non-root user mapping, volumes, devices, GPUs, and
+  GUI/X11 forwarding. Presets capture best practices (e.g., mapping the X socket
+  and `DISPLAY`, requesting `--gpus all` with the expected environment
+  variables), reducing duplication across repositories.
+
+- **CLI.** A command-line interface provides two convenience commands:
+  `scaffold` generates a starter Python script (builders + runners) and `run`
+  composes and executes directly for one-offs.
+
+- **Examples and tests.** The package ships small composition recipes (e.g.,
+  LLVM/MLIR, QEMU, Rust) [@llvm; @mlir; @qemu]. Unit tests lock down Dockerfile
+  rendering and CLI behavior; an opt-in integration test builds a tiny image to
+  validate the end-to-end flow. Continuous integration runs tests and linters.
+
+`pythainer` is designed to be naturally extensible: users can easily define
+their own builders or runners, or build on top of those provided in the
+library.
+
+# Research applications
+
+We have used `pythainer` to assemble environments for
+(i) robotics experiments combining ROS 2 with CUDA toolchains [@shen2025sentryrt1; @itf24safebot];
+(ii) compiler research that requires pinned LLVM toolchains [@degreef2025macros];
+(iii) systems evaluations using QEMU built from source; and
+(iv) GPU scheduling experiments where deterministic containerized environments
+are required [@discepoli2025computeKernels].
+
+In each case, the same small recipes are reused and composed across projects,
+which shortens setup time and reduces configuration drift. Because `pythainer`
+emits human-readable Dockerfiles, the resulting images remain transparent and
+easy to audit, and the approach integrates well with existing Docker-centric CI.
+
+# Relation to other work
+
+`pythainer` complements the Docker ecosystem by adding a programmable composition
+model on top of Dockerfiles. Unlike Docker Compose or the Docker SDK for Python,
+which focus on orchestrating multi-service deployments or driving the daemon
+[@docker_compose; @docker_sdk_python], `pythainer` focuses on single-image
+construction and single-container execution policy. This makes it especially
+suited for research projects where the goal is to provide a *single reproducible
+environment* for experiments rather than a full service-oriented stack.
+
+Compared with editor-centric templates such as VS Code devcontainers
+[@devcontainers] or domain-specific generators such as repo2docker [@repo2docker],
+`pythainer` treats environment recipes as code with tests and deterministic
+rendering. Functional package managers such as Nix and Guix offer deep
+system-level reproducibility but require adopting a different stack
+[@nix04lisa; @courtes2013guix]; `pythainer` stays Docker-native for easier
+adoption in labs and CI. Pragmatically, many third-party packages (e.g., CUDA and
+ROS 2) are primarily supported on Ubuntu, so staying Docker-native with
+Ubuntu-based images eases reproduction without changing the base distribution.
+
+# Acknowledgements
+
+We thank contributors for feedback and patches that improved early designs and
+examples, including Attilio Discepoli, Yuwen Shen, Aaron Bogaert, and Samuel
+Beesoon.
+
+# References