.. _how_to_include_files_and_resources:

******************************************
Including local files and remote resources
******************************************

Craft-parts provides the built-in :ref:`dump plugin <craft_parts_dump_plugin>`
for all kinds of projects that need to include local files and remote resources 
as is.
This plugin uses the :ref:`source <source>` property 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
:ref:`python plugin <craft_parts_python_plugin>` and the
:ref:`rust plugin <craft_parts_rust_plugin>`.


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.

For supported source types please refer to :ref:`source_type`.


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

Given the following project structure:

.. code-block:: text

  .
  └── 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:

.. code-block:: yaml

  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:

.. code-block:: text

  .
  └── 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:

.. code-block:: yaml

  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:

.. code-block:: text

  .
  ├── 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``.

.. code-block:: yaml

  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:

.. code-block:: text

  .
  └── 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.

.. code-block:: yaml

  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:

.. code-block:: text

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