HOWTO.add_another_format

   1
   2 How to add another build format
   3 ===============================
   4
   5 To support yet another package format to be used with standalone build
   6 script and Open Build Service you need to follow these steps:
   7
   8 Let's call the new format "XYZ" here.
   9
  10 General notes about the implementations. There are two areas:
  11
  12 SAFE implementations:
  13  Some code runs outside of protected environments like KVM. Therefore
  14 this code must be implemented with security in mind. Special crafted
  15 build descriptions or binary files must not be able to exploit this code.
  16 What makes it even more interessting is that this code can also run
  17 on all kind of old or obscure systems. So any external dependency should
  18 be avoided as well.
  19 This means in short:
  20  - code must be as simple as possible.
  21  - code must not allow to execute random commands or to access random files.
  22  - avoid external dependencies. When you look for a simple XML parser
  23    check the kiwi support for this.
  24  - code must stay compatible for all versions
  25
  26 Build code running inside of environment.
  27  - using any tool is fine here. However, the tool must be installed
  28    somehow into the build system. In best case via some dependency.
  29  - Incompatible changes can be implemented inside of these packages
  30    pulled into the build environment.
  31  - network is not possible here.
  32
  33
  34 1) Implement the parse() function into Build/XYZ.pm
  35
  36    parse() extracts the build dependecies from the build specification.
  37    For RPM this would be the <package>.spec file for example.
  38
  39    Must be a SAFE implementation.
  40
  41 2) Add a query() function to Build/XYZ.pm
  42
  43    query() extracts information from built packages. In the rpm world
  44    these are the .rpm files.
  45    query returns a hash containing:
  46        name, epoch, version, release, arch, description,
  47        provides, requires, hdrmd5
  48
  49    hdrmd5 is some unique identifier of the package built, it might be
  50    just a md5 over the entire file.
  51
  52    Must be a SAFE implementation.
  53
  54 3) Add a queryhdrmd5() function
  55
  56    this functions is a specialized version of query(), it just returns
  57    the hdrmd5
  58
  59    Must be a SAFE implementation.
  60
  61 4) Add a verscmp() function
  62
  63    verscmp() compares two package version strings. For rpms, a version has
  64    the form [epoch:]version-release
  65
  66    Must be a SAFE implementation.
  67
  68 5) Implement build-pkg-xyz functions
  69
  70    Those functions are used to setup the build environment. I.e. they
  71    need to install/unpack the packages
  72
  73    Must be a SAFE implementation for the pre-installation part. Afterwards
  74    it is fine to use any tool to install the packages (like rpm itself).
  75
  76 6) Implement build-recipe-xyz functions
  77
  78    This functions are called to create the build result
  79
  80 7) For standalone build support (actually not needed for OBS integration, but
  81    it makes development easier) we need a "createxyzdeps" helper script.
  82    For xyz://<...> repos it needs to download the repository metadata
  83    and convert it to build's representation. See createyastdeps and createrepomddeps.
  84
  85
  86 Special notes for non-OSS systems
  87 =================================
  88
  89 Systems like MS-Windows, MacOSX or SunOS could be support as well. However, these
  90 systems can not be installed by packages from scratch. So using preinstallimages
  91 would be mandatory here. Support for that exists in general already inside of
  92 the code.
  93
  94 Special notes for image formats
  95 ===============================
  96
  97 Image formats can usually skip 2) 3) and 4) from the items above. At least as long
  98 as they do not want to build new images based on former created ones.
  99