HOWTO.add_another_format

How to add another build format
===============================

To support yet another package format to be used with standalone build
script and Open Build Service you need to follow these steps:

Let's call the new format "XYZ" here.

General notes about the implementations. There are two areas:

SAFE implementations:
 Some code runs outside of protected environments like KVM. Therefore
this code must be implemented with security in mind. Special crafted
build descriptions or binary files must not be able to exploit this code.
What makes it even more interessting is that this code can also run
on all kind of old or obscure systems. So any external dependency should
be avoided as well. 
This means in short:
 - code must be as simple as possible.
 - code must not allow to execute random commands or to access random files.
 - avoid external dependencies. When you look for a simple XML parser
   check the kiwi support for this.
 - code must stay compatible for all versions

Build code running inside of environment.
 - using any tool is fine here. However, the tool must be installed
   somehow into the build system. In best case via some dependency.
 - Incompatible changes can be implemented inside of these packages
   pulled into the build environment.
 - external network access is not possible here.


1) Implement the parse() function into Build/XYZ.pm

   parse() extracts the build dependecies from the build specification.
   For RPM this would be the <package>.spec file for example.

   Must be a SAFE implementation.

2) Add a query() function to Build/XYZ.pm

   query() extracts information from built packages. In the rpm world
   these are the .rpm files.
   query returns a hash containing:
       name, epoch, version, release, arch, description,
       provides, requires, hdrmd5

   hdrmd5 is some unique identifier of the package built, it might be 
   just a md5 over the entire file.

   Must be a SAFE implementation.

3) Add a queryhdrmd5() function

   this functions is a specialized version of query(), it just returns
   the hdrmd5

   Must be a SAFE implementation.

4) Add a verscmp() function

   verscmp() compares two package version strings. For rpms, a version has
   the form [epoch:]version-release

   Must be a SAFE implementation.

5) Implement build-pkg-xyz functions

   Those functions are used to setup the build environment. I.e. they
   need to install/unpack the packages

   Must be a SAFE implementation for the pre-installation part. Afterwards
   it is fine to use any tool to install the packages (like rpm itself).

6) Implement build-recipe-xyz functions

   This functions are called to create the build result

7) For standalone build support (actually not needed for OBS integration, but
   it makes development easier) we need a "createxyzdeps" helper script.
   For xyz://<...> repos it needs to download the repository metadata
   and convert it to build's representation. See createyastdeps and createrepomddeps.


Special notes for non-OSS systems
=================================

Systems like MS-Windows, MacOSX or SunOS could be support as well. However, these
systems can not be installed by packages from scratch. So using preinstallimages
would be mandatory here. Support for that exists in general already inside of 
the code.

Special notes for image formats
===============================

Image formats can usually skip 2) 3) and 4) from the items above. At least as long
as they do not want to build new images based on former created ones.

Special notes for new recipe types to the backend
=================================================

Note that in order to find the new recipe type on the backend when scheduling jobs,
it will most likely be necessary to teach the scheduler implementation how to match
on it. Check the expandandsort() and findfile() functions in OBS' backend:
https://github.com/openSUSE/open-build-service/tree/master/src/backend