Build Information Files (.bif)


Build Information Files are XML files which define build targets. This information is a list of source code directories (CVS modules), their dependencies (other CVS modules), and special attributes. Some of these special attributes are a listing of platforms the module will build under. There are also attributes with can define witch CVS branch the module will be taken from.

Build informatation files normally have .bif extension, but some files will have a .biif extention, which means 'build information include file'. BIIF files are inteded to be inherited by other BIF files and not used directly

A BIF file begins with a standard XML header, and basic information about the build:

<?xml version="1.0" ?>

Build Definitions

<build id="build_id"></build>

The <build></build> contain all the data for defining a build. The build's id (name) is set by the id field, and MUST BE UNIQUE THROUGHOUT ALL .BIF FILES IN THE DIRECTORY. If a .bif file is checked in with the same id as another .bif file, it will break the build system.

Below is the header for the RealMedia-Beta2 branch. The id field for the build tag, which encompasses the entire file, is the text name given to this build branch. The cvs tag specifies the default CVS branch modules should come from.

<build id="RealMedia-Beta2">
  <cvs tag="g2beta2"/>
The <build> tag can contain the following sub-tags:

<inherit id="BIF ID">

This tag will inherit all module, cvs and default tags from the named BIF file. The name of the BIF file can contain square brackets to indicate which AddBIFPath the BIF file comes from. The inherited modules can be re-defined by a <module> or <inherit< tag later.

Example:
<inherit id="[common]helix">

<default [target="default target"] [profile="default profile"] [options="default options"] [for="system_id glob"] ></default>

The default tag allows you to specify what default target, profile and options will be selected in the build menu when selecting this BIF file. You can specify several <default> tags, each with a different for attributes, only the tag(s) whos for matches the current SYSTEM_ID will be taken into consideration.

<targets> module tags </targets>

All BIF files should contain this tag, all <module> tags should be contained within this tag. See below for a description of <module> tags.

Module Definitions

<module id="module_id" [name="name"] [type="type"] [group="group"]> module definition </module>

Modules are specified within the <targets></targets> tags. There are several kinds of modules defined in .bif files:

Here is an example of the rmacore module. This is a CVS module which has dependencies on several other CVS modules:

<!-- RMACORE -->
<module id="rmacore" group="core">
  <description>
    This is the target for the client core.
  </description>
  <dependlist>
     rmartsp  comlib  pnpasswd  pncont  pnaudio 
     pndebug  pnio  pnprot  pnmisc  pndepr 
  </dependlist>
</module>

Module tags can have the following attributes:

Tags Used Within <module> Definitions

<description></description>

The text within the description tags is a free-form text description of the module

<cvs [ tag="cvstag" ] [ branch="cvsbranch" ] [ root="cvsroot" ] [ path="path-in-cvs" ] />

Set the CVS tag/branch/root this module should come from. Note that the root is only the name of a CVS repository, the CVSROOT itself must be added in your buildrc file. This tag can also be placed outside of all module tags, which makes this the default for all modules without a cvs tag.

If the path attribute is present, it tells the build system where in CVS to find the module.

<cvstag id="cvstag/branch"/>

Set the CVS tag/branch ID this module should come from. This tag is obsolete, use the <cvs> tag instead.

<sdk name="sdk name" [ for="platform glob" ] [ ifexists="path" ] [ path="default path" ] /> [ message <sdk/> ]

This tag informs the ribosome build system that an SDK is needed for this build. The SDK may be located anywhere on your file system, or could even be a part of the checked out source. The actual location for the SDK can be specified in four different ways:

  1. With an environment variable with the same name
  2. With a call to SetSDKPath in your buildrc file.
  3. The path attribute in the BIF file (see below)
  4. With a call to SetSDKPath in your umakerc file (Only use this if you are using umake without running 'build' first.)
If the build system is unable to locate the SDK with any of the first three methods, a large warning will be printed when you try to build something which requires that SDK, and those modules which requires the SDK will fail to build. If a message is supplied, it will be a part of that large warning.

If the for attribute is present, it should be a glob pattern matching the SYSTEM_ID or an entry in the family list for that platform. If it does not match, the sdk tag will be ignored. This makes it possible to specify different default locations for the same sdk depending on the SYSTEM_ID.

If the ifexists attribute is present, this tag will be ignored if that path does not exist. This can be used to automatically find SDKs in shared locations, such as /usr. This could look like this: <sdk name="jpeglib" path="/usr" ifexists="/usr/include/jpeglib.h">

The path attribute designates a default path for the given SDK. If the path is relative, it is relative to the source root. It is possible to have several sdk tags with different path attributes in order to specify multiple search paths. If more than one default path exist on the file system, the first will be used.

Please note that if an SDK is found to be not available, but a module present in the same BIF file can provide it, that module will be included in the build even if no actual dependancy exists for that module. This can be particularly useful in combination with the AddBIFShadow function.

<checkout_error_message>Message</checkout_error_message/>

If the module fails to check out, this message will be written if present. If not present, a default error message will be printed.

<attribute id="random attribute"/>

A way to pass generic attributes in for the module. This was a bad XML design decision, as each of these should have just had their own tag, since XML skips unknown tags by default. However, attribute the build system understands are:

<halt priority="red|yellow|green(default)"/>

Sets the halt priority of the module. If a error occurs while building this module, the build system will check against the halt priority selected by the build system user when the build system was invoked. If the developer selected the build system should halt on "yellow" priority modules, then a error on a "red", or "yellow" priority module would halt the build. The default priority is "green".

<includeplatforms></includeplatforms>

This is a space-separated list of platforms this module should be included, and built on. It excludes all other platforms.

<excludeplatforms></excludeplatforms>

This is a space-separated list of platforms this module should not be built on. It will be built on all platforms not listed.

<includeprofiles></includeprofiles>

This is a space-separated list of profiles for which this module should be included, and built. It excludes all other profiles. You may also use stars as wild cards.

<excludeprofiles></excludeprofiles>

This is a space-separated list of profiles for which this module should not be built. It will be built for all profiles not listed. You may also use stars as wild cards.

<ifdef></ifdef>

This is a space-separated list of defines, and this module will be omitted from the build unless at least one of these defines are defined with a <defines> tag somewhere inside the BIF.

<ifndef></ifndef>

This is a space-separated list of defines, and this module will be omitted from the build if any of these defines have been defined with a <defines> tag somewhere inside the BIF.

<dependlist></dependlist>

This is a space-separated list of module ids within the .bif file that this module depends on. These modules are guaranteed to be build before this module. Because of this, there can be no cyclic dependencies.

<source_dependlist></source_dependlist>

This is a space-separated list of module ids within the .bif file that this module has source-file dependencies on. These modules will be checked out, but only be built if other modules require it.

<checkin_dependlist></checkin_dependlist>

This works a lot like <source_dependlist>, but these dependencies are only followed if the one of the options distribute or make_distributions are used.

<defines></defines>

This is a space-separated list of defines. These defines will be added globally to the compilation of all modules, but only if this module is one of the modules selected for building or is the selected profile. See also the <ifdef> tag

<umake_includefiles></umake_includefiles>

This is a space-separated list of files for umake to include. These files (and any relevant .pcf files) will be included for all modules in this build. This can be used when the interface this module provides, requires certain modifications to the compiler environment. For instance, it can be used to add *.il (inline assembler) files to the compiler command line when using the Sun Forte compiler.