DAP Packaging guidelines
DevAssistant provides an easy extendability through Assistants. These assistants are normally distributed via the DevAssistant Package Index in the form of DAP (DevAssistant Package) files. If you want to include a DAP into the main Fedora repositories, you can do so. This document outlines the rules involved.
Note: Packaged DAPs only work with DevAssistant 0.10.0 and newer. They can not be used with DevAssistant versions 0.9.* packaged in Fedora 21 and earlier.
How to package a DAP
We recommend you use the tool dap2rpm, which creates a SPEC file from your DAP automatically. It is packaged in Fedora Rawhide and 21's repositories as dap2rpm.
Naming guidelines
- Every (RPM) package name must start with
devassistant-dap-
, which is followed by the name of the Assistant itself, all lowercase. For example, the DAP namedOpenscad
will be nameddevassistant-dap-openscad
in the SPEC file. In this document, the second part of the name (i. e. the substringopenscad
) will be referenced as%{shortname}
. - There is no difference between packages that provide Assistants, and those that provide only auxiliary files, snippets, metapackages etc.
Dependencies
- All packages must Require
devassistant-ui
. This means that the user has at least one user interface for DevAssistant installed, so they can use the DAP without futher installing anything. No version specification is necessary as DevAssistant 0.10.1 is the first version ever to providedevassistant-ui
. Requires: devassistant
is not allowed, as that would install more packages for DA than the user may intend or need.- All packages must have
BuildRequires: devassistant-devel
. (for macros, installation and checking) - Each package must Require packages that are specified in the file
/meta.yaml
in the sectiondependencies
. These names, of course, must contain thedevassistant-dap-
prefix. These Requires are generated automatically by dap2rpm.
Architecture
- All daps must be architecture independent, i. e.
BuildArch: noarch
.
Macros
- The macro denoting the parent directory where the package files go is
%{assistant_path}
. This currently expands to/usr/share/devassistant
. - The macro definitions of
%install_assistant
,%repack_assistant
, and%check_assistant
are provided by the packagedevassistant-devel
.
Prep section
- DAP must be unpacked with
setup
like other packages, it is not permissible to install the source DAP directly. - If needed, you may patch the source files in this section.
Build section
- You must re-pack the (optionally patched) DAP in the
%build
section using the macro%repack_assistant
. This is needed for installing and checking.
Install section
- Files are installed via the
%install_assistant
macro - Using the above macro automatically creates a list of files stored in the file
dap-list
, which can then be used in the%files
section. - If the package contains licensing files, they should be marked as such by running the
%install_assistant
macro with argument(s)-L LICENSE_FILE1 LICENSE_FILE2...
. The licensing files must be stored only in thedoc
directory of the DAP. - If installed manually, the package files are installed into
%{buildroot}%{assistant_path}
in subdirectories conforming to the DAP layout, i. e. theassistants/crt/foo
directory is installed into%{buildroot}%{assistant_path}/assistants/crt/foo
.
Check section
- You must run the
%check_assistant
macro in the%check
section, and it must pass. - If run manually, you must run the command
da pkg lint -w %{shortname}-%{version}.dap
(or similar, if your package's name differs). The run must produce no errors. Warnings are permissible.
Files section
- If the macro
%install_assistant
was used in the%install
section, it is sufficient to provide the list of files to the%files
section like this:%files -f dap-files
. This is the default situation when using dap2rpm. - If done manually:
- Package's files and directories are installed into
%{assistant_path}
. - Do not install everything like
%{assistant_path}/*
, list each folder separately. That includes subdirectories in%{assistant_path}/assistants
, as shown in these examples:- Bad:
%{assistant_path}/assistants/*
- Good:
%{assistant_path}/assistants/crt/%{shortname}
- Bad:
- The
doc
directory in the DAP should be installed via the%doc
macro, in the same%{assistant_path}
directory. - The
meta.yaml
file must be installed as%{assistant_path}/meta/%{shortname}.yaml
.
- Package's files and directories are installed into
Directory ownership
- The package
devassistant-core
owns the directory%{assistant_path}
itself and the following subdirectories:%{assistant_path}/{assistants,doc,files,icons,meta,snippets}
%{assistant_path}/{assistants}/{crt,twk,prep,extra}
%{assistant_path}/files/{crt,twk,prep,extra,snippets}
%{assistant_path}/icons/{crt,twk,prep,extra}
- The RPM-packaged DAP must own the following files/directories if and only if they are present in the upstream DAP:
- directories named
%{shortname}
in directories listed in point 2 and 3 of the previous bullet.- Example 1:
%{assistant_path}/assistant/crt/%{shortname}
- Example 2:
%{assistant_path}/files/snippets/%{shortname}
- Example 1:
- files named
%{shortname}.yaml
in the directories listed in point 2. - a directory named
%{shortname}
in the directory%{assistant_path}/doc/
- a file named
%{shortname}.yaml
in the directory%{assistant_path}/meta/
- a file named
%{shortname}.$SUFFIX
, where$SUFFIX
is an image file suffix (preferably PNG or SVG), in the directories listed in point 4.
- directories named
Sample SPEC
%global shortname openscad Name: devassistant-dap-%{shortname} Version: 0.0.2 Release: 1%{?dist} Summary: Create 3D printing projects for OpenSCAD BuildArch: noarch License: GPLv3+ and GPLv2 with exceptions URL: https://github.com/3DprintFIT/dap-openscad Source0: https://dapi.devassistant.org/download/%{shortname}-%{version}.dap BuildRequires: devassistant-devel Requires: devassistant-ui Requires: devassistant-dap-common_args Requires: devassistant-dap-git Requires: devassistant-dap-github %description This assistants helps you to create new OpenSCAD project for 3D printing. We use it in our 3D printing lab to store our 3D printers on Github. Projects created with this assistant have a `Makefile` to build the 3D models form OpenSCAD sources. To do so, run `make`. You can also generate the images by `make images` or print plates with `make arrange`. Observe the generated `Makefile` to see all available options. %prep %setup -q -n %{shortname}-%{version} %build %repack_assistant %install %install_assistant -L LICENSE NOTICE %check %check_assistant %files -f dap-files %changelog * Thu Dec 11 2014 Tomas Radej <tradej@redhat.com> - 0.0.2-1 - Initial package
Sample %files section when specified manually
%files %license %{assistant_path}/doc/LICENSE %license %{assistant_path}/doc/NOTICE %dir %{assistant_path}/doc/%{shortname} %doc %{assistant_path}/doc/%{shortname}/README.rst %{assistant_path}/assistants/crt/%{shortname}* %{assistant_path}/files/crt/%{shortname}* %{assistant_path}/icons/crt/%{shortname}* %{assistant_path}/meta/%{shortname}.yaml