Skip to content

Latest commit

 

History

History
 
 

docker

README.md

Dyninst Containers

This is a testing set of Dockerfile for building a Dyninst base container.

Strategy

For development, we want to be able to:

  1. Pull a container with dyninst ready to go (for development or dyninst or another library)
  2. Quickly update with our own source code without needing to build everything.

And for testing, we want to be able to:

  1. Have a set of base containers that make dependency preparation minimal
  2. Use those base containers to quickly test a PR's dyninst and report results

These are both achieved using a single workflow based on a set of base images with each containing a minimal OS environment and the package-provided versions of the various Dyninst dependencies. There is no source for Dyninst or any of its components. The development image is a small layer on top of a base and contains the Dyninst source and binaries. They are named by both the base OS and the hardware architecture. For example, the base container for Ubuntu 20.04 on x86_64 is dyninst-amd64-base:ubuntu-20.04. The corresponding development container is named dyninst-amd64:ubuntu-20.04.

Usage

The Dockerfiles provided are intended for building the base and development containers from scratch. We don't recommend using these directly as images are provided as packages.

Build

A Dockerfile is provided that makes it easy to bring up a development environment. The following builds the Ubuntu 20.04 images.

$ cd path/to/Dyninst/source

# Base image (Ubuntu 20.04 needs a newer elfutils)
$ docker build -f docker/Dockerfile.ubuntu -t dyninst-base:ubuntu-20.04 --build-arg version=20.04 --build-arg build_elfutils=yes .

# Development image
$ docker build -f docker/Dockerfile -t dyninst:ubuntu-20.04 --build-arg build_jobs=16 --build-arg base=dyninst-base:ubuntu-20.04 .

In the development container, Dyninst is installed in /dyninst/install.

Develop

You can then shell inside to interact with dyninst:

$ docker run -it dyninst:ubuntu-20.04 bash

For a more interactive development environment, you can bind the present working directory with the Dyninst source code bound to /code instead:

$ docker run -it -v $PWD:/code dyninst:ubuntu-20.04

And again navigate to the bound source code - this time the files are on your local machine, so you can edit them locally and build in the container!

# This is bound to your host - edit files there
$ cd /code

Maintainers

Adding a new OS image

  1. Add the relevant information to 'build_base_images.sh'. For example, make_image ubuntu 24.10.

  2. Run build_base_images.sh --push to build and push all container images.

  3. Running the script above will print a complete list of supported OSes. These need to be added to the GitHub "os:" fields in the workflow files dev-containers.yaml and pr-tests.yaml. Make a PR to add these updated files.

  4. After committing the PR above, the 'Build and Deploy Development Containers' workflow will update/generate the associated development containers automatically on the next committed PR. It can be run manually via the Github interface, if preferred.

Adding a dependency

Assuming all of the requisite CMake files are in place, a new dependency can be added to the container images. If the dependency can be installed by the package provider, add it to the Dockerfile.<OS> file, and run build_base_images.sh --push. If it needs to be built from source, add a new build script (e.g., build_foo.sh) and call it from the Dockerfile.<OS> files. If the dependency only sometimes needs to be built from source, see the usage of 'build_elfutils.sh' for guidance.