The dump plugin

doc
1

The dump plugin makes all files from a specified source available to a part. It copies the contents of a source into the root directory of the snap without changing the files. It provides an easy way to add pre-built binaries, scripts and other assets to a snap.

It’s equivalent to running the following command in a source’s directory:

cp --archive --link --no-dereference . "${CRAFT_PART_INSTALL}"

:white_check_mark: Tip

If you aren’t using the source files directly in the package, but want to run some custom commands to generate them, then you should instead use the nil plugin so no files are copied unnecessarily.

The source and other source-* properties specify the location from where to retrieve the files, or if the source is a git repository, the branch, tag, or commit to clone.

For a simple example of the plugin that copies the contents of a .deb package:

parts:
    my-remote-part:
        plugin: dump
        source: https://www.example.com/builds/example.deb
        source-type: deb

Modify the files after copying

Certain keys in the part can be configured to filter which files are copied, and modify, rename, or alter the files after they’re copied. Doing so is especially suitable when building a snap from multiple parts, where the main app expects to find supporting binaries, libraries, and assets such as themes or plugins in special locations. They also help when the source contains components for multiple architectures, and it’s only necessary to copy files for one architecture into the snap.

The applicable keys are:

  • organize moves and deletes the copied source files in the final payload. For example, you could use it to keep libraries but exclude binaries and headers from SDKs.

  • stage and prime specify which files and directories to copy into the snap.

    These keys take effect after organize. This means that any stage and prime entries should refer to the final paths of the files, and not their initials.

  • override-build, override-stage, and override-prime run custom shell scripts during the build process. For example, they can change the formats of files.

Example

The following example manipulates the files from a source tarball that contains directories named binaries, docs, etc, in addition to README and COPYRIGHT files.

The organize key moves the binaries directory and COPYRIGHT to usr/bin and usr/share/doc/my-app/COPYRIGHT, respectively. The stage key copies everything other than the docs directory and README into the snap.

parts:
    my-app-part:
        plugin: dump
        source: https://www.example.com/builds/latest-build.tar.gz
        organize:
            binaries: usr/bin
            COPYRIGHT: usr/share/doc/my-app/COPYRIGHT
        stage:
            - -README
            - -docs

See also

For more samples of the dump plugin, see Pre-built apps, or search GitHub for snaps that use it.

1 Like
2

Since the target destination is never mentioned in these dump/organize examples, is it true that the target is the /root/prime virtual machine directory during the build process (which ends up as the root of the snap)?

Thus the dump command above copies the files from local-source/ into prime and the organize moves them into subdirs of prime, so that for example:

  • local-source/*.png ends up in /prime and then they all get moved into /prime/images/
  • local-source/launch.wrapper ends up in /prime and then gets moved into /prime/usr/bin/launcher/launch.wrapper
3

It is true that the target will end up be placing at the root of the snap file hierachy, what is unnecessarily true that it will always match the /root/prime virtual machine directory since that’s a Snapcraft internal implementation details.

Also the plugins only affect what will be contained in the SNAPCRAFT_PART_INSTALL directory in the part’s build step, whether the file will end in SNAPCRAFT_PRIME directory will also be determined by the stage and prime step.

4

I don’t understand this completely.

The presented options are:

  • fileset: filesets appear to be a way to group files and operate on the group at once.
  • stage: no clue what this does. “A list of files from to stage.” This tells me very little.
  • snap: I can’t find anything called snap in the common keywords link.
  • organize: I think I understand from the example that organize will rename files.

I am specifically here looking how to insert only a specific file into the snap. I just want foo/bar.sh included in my snap. I have learned from trial and error that source: ./foo will include ALL files from foo in the snap, dumped into the base directory of the snap. It would be nice to have this called out.

“This plugin just dumps the content from a specified source(directory, url, git link, etc) into the base directory of the resulting snap.”?

I then started to dig through the example and look things up. Looking up prime doesn’t result in any information about what it does. It just says “A list of files from to prime.” and prime links to a page that says “Migrate this part’s staged material into the final priming area”. What is my staged material? Where is the final priming area? Why do I need to know that? This doesn’t make sense unless you have a lot of internal knowledge about how snaps work.

I’m just trying to make a zip of my application here. I don’t need to know how zip works or what temporary directories are used. I’ve now clicked on 3 links going back and forth to try and decrypt how to say “copy random filename to snap”. It is very easy at this point for a potential user to be confused and give up at this point.

Could we add some more examples and document the one that is there? I assume ‘*.png’: images/ will move all png images into a img directory, but leave all jpg files for example. That stuff seems intuitive and maybe include this single file is as well, but unless it is shown I don’t see how a user can find it easily.

1 Like
5

I’m struggling to understand where the files go with this plugin. Where do they go? How do I change the destiny? Can I chose if they go to $SNAP or $SNAP_COMMON?

6

It goes to the part’s install directory(/root/parts/part_name/install), then to /stage, then to /prime, then to the snap’s root directory($SNAP) if not moved or pruned by the organize, stage, or prime keywords.

Can I chose if they go to $SNAP or $SNAP_COMMON?

You can organize the files to your preferred paths under $SNAP but not $SNAP_COMMON

1 Like
7

How to copy only certain specified files and not the whole source?

Also, Would be nice to have the documentation updated of this plugin with the definition of all the keywords used with their meaningful use case.

Thanks :slight_smile:

8

This document says

This plugin uses also common plugin keywords.

But if you check the link there’s no such information.

9

Hi

Does setting source-type to deb also stage its dependencies?

10

Apologies, it should be prime

11

This example seems confusing in that the second part, “remote-part”, doesn’t seem to be contributing any information about the dump plugin as it doesn’t even specify a plugin. I would delete that second part entirely for clarity.

12

Indeed, it doesn’t even work as stated. Needs plugin: dump added.

(which like a swift ninja in the night, I just added)

1 Like
13

@degville

Hello, I think this topic is also not authored by me, it seems that the initial edit history is lost somehow…

14

Incorporated some wording from @mr_cal’s latest documentation.

1 Like
15

After trying to do this (building seems to work but file is missing when running the app):

    source: libstdc++6_14.2.0-8_i386.deb
    source-type: deb

Instead of this:

    source: http://ftp.fr.debian.org/debian/pool/main/g/gcc-14/libstdc++6_14.2.0-8_i386.deb
    source-type: deb

I think that a warning may be put somewhere in the doc.