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"> expires="YYYY-MM-DD" [version="major.minor"] </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 expiration date should be set to some time in the future, but no more than 3 years in the future. Expired BIF files will eventually be hidden or moved so they won't clutter up the build menues. If no expiration date is given, 2005-01-01 is assumed. The version attribute specifies what version of ribosome this BIF file was written for. Normally you should put the current version of ribosome here when writing a BIF file. Ribosome will then attempt to be as compatible as possible with the specified version of ribosome when reading this BIF file. The <build> tag can contain the following sub-tags:

<inherit id="BIF ID" [version="major.minor"]/>

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. The "version" attribute is optional, and is only used if the inherited BIF file doesn't actually specify a version in the <build> tag. In such a case, it would act as if the inherited bif file had specified the version given here.

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

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

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"] [inherit="id"] [type="type"] [version="major.minor"] [group="group"]> module definition </module>

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

CVS(default): These are CVS modules (directories). They usually contain source code and Umakefil/*.pcf files for generating Makefiles to build the source code.
distribution: These modules are platform-specific binaries, kept in the distribution module of the /home/source CVS repository. The idea was to have a single module name automatically map to the correct platform binary, by the build system discovering what platform it was running on. It turns out to be a bad idea, and distribution modules should no longer be used. Just check the binaries into their own platform-specific areas.
name_only: A name-only target, used to aggregate several other modules together under a single name.
profile: This is similar to a name_only module, but it is primarily meant to contain <defines> tags. Profile modules show up in the profile selection menu, and can also be selected using -P on the command line when running build.
code archive: This is a special kind of module. It looks like a CVS module, but the name field has a .rna extension. These are large archives of the entire source tree that was built. They are stored on http://archive.dev.prognet.com/archive, and are sometimes used as a base for patch builds from a released product.

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:

id: A unique string to identify the module within the .bif file. This is the default CVS module name, but can be overridden with the name attribute.
name: If the CVS module name is different than the module's id, this sets the real CVS module name.
group: A string to help identify which group in the company owns the module.
type: Not all module entries in the .bif file are CVS modules. CVS is the default, but there are other types of modules. The type distribution is still used for platform-specific binaries, but is being deprecated. The module type name_only is used to define a fake module with aggregates several other modules.
inherit: This allows you to modify an inherited module. Basically, the module specified will be copied and any the contents of this tag will be added to the copied module. If the inherit attribute is used, id, name, type and group are not required. (But you may use them if you want.)
version: By specifying the current version of ribsome here, you will guarantee that the semantics of this module will not change as new features are added to ribosome. Normally you will want to use the version attribute in the build tag instead of in the module tag.

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:

With an environment variable with the same name

With a call to SetSDKPath in your buildrc file.
The path attribute in the BIF file (see below)
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:

build_number: Deprecated.
has_version_file: Increment any version files found in the top-level module directory, and commit them when running a build farm build.
update_platform_header: Indicates that this module has a platform.h which should be updated to reflect the current platform when building.
static_build: Build this module, and all its dependencies twice. Once with the Umake "-t static" option, and once normally. This only works on Win32, and is a total screwed up hack.
static_build_only: Like static_build, but only builds the module statically on Win32.
no_build: Do not try to build this module, only check it out.
always: This will make this module get considered for checking out and building regardless of dependencies. This is primarily useful in conjunction with <umake_includefiles>

<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.

<default [profile="default profile"] [options="default options"] />

The default tag allows you to specify what default profile and options will be selected in the build menu when selecting this target.