Artifacts are used to configure what actually gets installed with a package. Anything that needs to be installed needs an entry in the artifacts section.
There are different types of artifacts which are installed to different locations on the target system. What location this is depends on the target OS/distro and the kind of artifact.
Most artifact types share a common data type so can be configured similarly. It is shown here as a reference which is linked to in the artifact descriptions where it is pertinent.
Configuration options shared by most artifacts:
- subpath(string): The provided path is joined to the typical install path,
e.g.
/usr/bin/<subpath>, where the artifact will be installed to. - permissions(octal): file permissions to apply to the artifact.
Binaries are binary files that may be executed.
On Linux these would typically get installed into /usr/bin.
Binaries are a mapping of file path to artifact configuration. The file path is the path to a file that must be available after the build section has finished. This path is relative to the working directory of the build phase before any directory changes are made.
Example:
artifacts:
binaries:
src/my_bin:
subpath: ""
permissions: 0o755You may use a trailing wildcard to specify multiple binaries in a directory, though behavior may differ between different OS's/distros.
Libexec files are additional executable files that may be executed by one of
the main package executables. On Linux these would typically get installed into
/usr/libexec/ or /usr/libexec/<main-executable-name>.
Files under libexec are a mapping of file path to artifact configuration.
If subpath is not supplied, the artifact will be installed in /usr/libexec
directly. The file path is the path to a file that must be available after the
build section has finished. This path is relative to the working directory of
the build phase before any directory changes are made.
Example:
name: my_package
artifacts:
# the following config will install my_bin at /usr/libexec/my package/my_bin
libexec:
src/my_bin:You may use a trailing wildcard to specify multiple binaries in a directory, though behavior may differ between different OS's/distros.
Manpages is short for manual pages.
On Linux these are typically installed to /usr/share/man
Manpages are a mapping of file path to artifact configuration. The file path is the path to a file that must be available after the build section has finished. This path is relative to the working directory of the build phase before any directory changes are made.
artifacts:
manpages:
src/man/*:
subpath: ""
permissions: 0o644You may use a trailing wildcard to specify multiple binaries in a directory, though behavior may differ between different OS's/distros.
Data dirs are a list of read-only, architecture-independent data files.
On Linux these typically get placed into /usr/share.
Data dirs are a mapping of file path to artifact configuration. The file path is the path to a file that must be available after the build section has finished. This path is relative to the working directory of the build phase before any directory changes are made.
artifacts:
data_dirs:
build_output/my_bin:
subpath: ""
permissions: 0o755Directories allows you to create new directories when installing the package. Two types of directory artifacts are supported:
- config: This is a directory where configuration files typically go, e.g. /etc/my_package2. State: This is directory for persistent state, typically in
/var/libon Linux.
Unlike many other artifact types, this does not reference any file produced by build. Instead these are created as empty directories.
Example:
artifacts:
createDirectories:
state:
mystate:
mode: 0o755
config:
myconfig:
mode: 0o755Config files are, depending on the package manager, specially marked as configuration.
Typically these go under /etc on Linux.
Config files are a mapping of file path to artifact configuration. The file path is the path to a file that must be available after the build section has finished. This path is relative to the working directory of the build phase before any directory changes are made.
artifacts:
configFiles:
src/my_config.json:
subpath: ""
permissions: 0o644Docs are general documentation, not manpages, for your package.
On Linux these typically go under /usr/share/doc/<package name>
Docs are a mapping of file path to artifact configuration. The file path is the path to a file that must be available after the build section has finished. This path is relative to the working directory of the build phase before any directory changes are made.
artifacts:
docs:
src/doc/info.md:
subpath: ""
permissions: 0o644You may use a trailing wildcard to specify multiple binaries in a directory, though behavior may differ between different OS's/distros.
Licenses are license files to be installed with the package.
Licenses are a mapping of file path to artifact configuration. The file path is the path to a file that must be available after the build section has finished. This path is relative to the working directory of the build phase before any directory changes are made.
artifacts:
licenses:
src/LICENSE.md:
subpath: ""
permissions: 0o644Systemd artifacts are used for installing systemd unit configurations. Two different types of systemd configurations are currently supported:
- Unit files - including services, sockets, mounts, or any other systemd unit type.
- Drop-ins - Adds customization to an existing systemd unit
See the systemd documentation for more details on these types.
Example:
artifacts:
systemd:
units:
src/contrib/init/my_service.service:
enable: false
name: ""
dropins:
src/contrib/init/customize-a-thing.service:
enable: false
name: ""Libs are library files to be included with your package.
On Linux these typically go under /usr/lib/<package>.
Libs are a mapping of file path to artifact configuration. The file path is the path to a file that must be available after the build section has finished. This path is relative to the working directory of the build phase before any directory changes are made.
artifacts:
libs:
my_output_dir/lib.o:
subpath: ""
permissions: 0o644You may use a trailing wildcard to specify multiple binaries in a directory, though behavior may differ between different OS's/distros.
Links are a list of symlinks to be included with the package. Unlike most other artifact typtes, links do not reference any specific build artifact but rather a literal source-to-target mapping for the symlink.
Example:
This creates a symlink at /usr/bin/go pointing to /usr/lib/golang/go.
artifacts:
links:
- source: /usr/lib/golang/go
dest: /usr/bin/goHeaders are header to be included with the package. On Linux these typically go
under /usr/include/.
Headers are a mapping of file path to artifact configuration. The file path is the path to a file or directory that must be available after the build section has finished. This path is relative to the working directory of the build phase before any directory changes are made.
artifacts:
headers:
src/my_header.h:or for a directory:
artifacts:
headers:
src/my_headers/:Note that headers are not installed within a subdirectory of /usr/include/
with the name of the package. They are installed directly into /usr/include/.
For instance, for the above examples, the headers would be installed to
/usr/include/my_header.h and /usr/include/my_headers/ respectively.
Users allow you to specify a list of users to be created when installing the package. In most cases this will require a shell to be available on the target system.
Example:
artifacts:
users:
- name: myuserGroups allow you to specify a list of groups to be created when installing the package. In most cases this will require a shell to be available on the target system.
Example:
artifacts:
groups:
- name: mygroupSome builds may not work with binary stripping, in which case you can disable
automatic stripping by setting disable_strip: true
This is a global setting that applies to all artifacts only.
If you want some binaries stripped and others not, you will need to manually strip them in the build phase.