Including local files and remote resources

The Dump plugin is handy for all kinds of projects that need to include local files and remote resources as-is. This plugin uses the source key in the part to download, unpack, and copy files and directories from the given source to the build environment, then do some organizing if needed, and include them in the final payload.

If you don’t need to copy these files, consider using the Nil plugin. If you need to download and build them from source, consider using plugins for the corresponding languages, such as the Python and Rust plugins.

The typical use cases for the Dump plugin:

• Include static files in the final payload, such as scripts, configurations, services, documentation, media files, or other resources that are not generated by the build process.

• Include pre-built third-party packages, libraries, binaries, or other artifacts that are not available in the system’s package manager or in the project’s source code.

Example: To include a local directory and move files to the correct locations

Given the following project structure:

.
└── misc
    ├── fonts
    │   └── good.otf
    └── services
        ├── README
        └── hello.service

The following dump part can be used to include the hello.service and good.otf files from the misc directory, then move them to the correct locations, keeping only /usr in the final payload:

parts:
  my-part:
    plugin: dump
    source: ./misc
    source-type: local
    organize:
      'services/*.service': usr/lib/systemd/system/
      'fonts/*': usr/share/fonts/
    stage:
      - usr/

The resulting payload will look like this:

.
└── usr
    ├── lib
    │   └── systemd
    │       └── system
    │           └── hello.service
    └── share
        └── fonts
            └── good.otf

Example: To include a remote third-party deb package from a URL

The following dump part downloads a busybox-static deb package from a remote URL and includes it in the final payload:

parts:
  my-part:
    plugin: dump
    source: http://archive.ubuntu.com/ubuntu/pool/main/b/busybox/busybox-static_1.30.1-7ubuntu3_amd64.deb
    source-type: deb

The resulting payload will look like this:

.
├── bin
│   ├── busybox
│   └── static-sh -> busybox
└── usr
    └── share
        ├── doc
        │   └── busybox-static
        │       └── ...
        └── man
            └── ...

Example: To include a remote third-party pre-compiled archive from a URL

The following dump part downloads a pre-compiled git version of the ffmpeg tar archive (xz compressed) from a remote URL and only includes the ffmpeg and ffprobe binaries in the /usr/bin.

parts:
  my-part:
    plugin: dump
    source: https://johnvansickle.com/ffmpeg/builds/ffmpeg-git-amd64-static.tar.xz
    source-type: tar
    organize:
      'ffprobe': usr/bin/
      'ffmpeg': usr/bin/
    stage:
      - usr/

The resulting payload will look like this:

.
└── usr
    └── bin
        ├── ffmpeg
        └── ffprobe

Example: To include a remote git repository with a specific branch

The following dump part will clone a theme from a remote git repository and move the theme files to the correct location.

parts:
  my-part:
    plugin: dump
    source: https://github.com/snapcore/plymouth-theme-ubuntu-core.git
    source-type: git
    source-branch: main
    source-depth: 1
    organize:
      ubuntu-core: usr/share/plymouth/themes/ubuntu-core

The resulting payload will look like this:

.
├── README.md
├── copyright
└── usr
    └── share
        └── plymouth
            └── themes
                └── ubuntu-core
                    ├── throbber-1.png
                    └── ...