34 Build Constraints #

The information from the _statistics file can be found in the Build Service web UI, by clicking on the build target we are interested in and then clicking on "Show resources". Alternatively, the _statistics file itself can be downloaded from the Build Service, either from the command line or using the OBS API.

34.1.1.2 Downloading the _statistics file using the OBS API #

 

If you are using the OBS API, the relevant call is:

GET /build/{project_name}/{repository_name}/{architecture_name}/{package_name}/_statistics

Important

When reviewing the build statistics, it's important to be aware that the numbers can vary significantly from build to build depending on build parallelism (e.g. make -j).

Build constraints for an entire project, or for specific repositories within it, or for specific architectures within those repositories, are defined in the project config by adding lines as so:

Constraint: <QUALIFIER> <VALUE>

The QUALIFIER syntax is the same as used in RPM spec files, documented in Section 34.4, “Constraint syntax”. Within the project configuration, individual Constraint lines can be enclosed in guards to make a constraint apply only to certain architectures or repositories. For example:

%ifarch ppc ppc64 ppc64le
Constraint: hardware:cpu:flag power8
%endif

or

%if "%_repository" == "images"
Constraint: hardware:disk:size unit=M 4000
%endif

Important

Constraints set in project configuration affect not only the project itself, but also all projects that build against it.

For a full treatment of constraint syntax, see Section 34.4, “Constraint syntax”.

Setting constraints at the package level is achieved by including an XML file called _constraints in the package sources. The Build Service will attempt to validate this file when it is committed (from the osc command line) or saved (in the web UI) to prevent invalid XML from reaching the Build Service.

Here is a simple example showing what a _constraints file might look like:

<?xml version="1.0"?>
<constraints>
  <hardware>
    <physicalmemory>
      <size unit="M">2000</size>
    </physicalmemory>
    <disk>
      <size unit="G">5</size>
    </disk>
  </hardware>
  <sandbox>kvm</sandbox>
  <hostlabel exclude="true">SLOW_CPU</hostlabel>
</constraints>

For details on constraint qualifiers and how to specify them in a _constraints file, see Section 34.4, “Constraint syntax”.

At the build recipe level, constraints are set by embedding lines containing constraint qualifiers and values directly in RPM spec files or Dockerfiles. Such lines take the form

#!BuildConstraint: <QUALIFIER> <VALUE>

The # character at the beginning of the line causes the build recipe parser (RPM, Docker, podman) to ignore the whole line, but in combination with the ! character signifies an OBS-specific directive that is picked up by a pre-processor within the OBS back-end.

Instead of specifying subqualifiers by nesting directives like in XML, colons are used. For example:

#!BuildConstraint: linux:version:min 3.0

In this example, "linux:version:min" is the constraint qualifier and "3.0" is the value.

As described for project-scoped conditionals, above, #!BuildConstraint lines can be guarded with various conditionals to limit their effect to certain architectures or, e.g., multibuild flavors.

Important

Be careful when setting build constraints. The idea is to use them to express minimum values for the various parameters, below which builds are likely to fail. If you set a constraint too high, you risk reducing the pool of compliant build workers down to a very low number, or even to zero. (A low number of compliant build workers means your build may not start for a long time, and no compliant workers at all will cause the build to fail. See Section 34.5, “Constraint Handling” for details.)

Important

By default, constraints applied to build workers regardless of architecture. However, you may only be interested in certain architectures and not in others. See Section 34.6, “Checking Constraints with osc” for how to get architecture-specific information on which workers satisfy your constraints.

The "hostlabel" qualifier is any string which can be assigned to build workers when starting the bs_worker process. Since its intended use is to restrict a build to specific workers, it should only be used after consultation with OBS administrators who have detailed knowledge of the build farm, and ideally as a negative definition, using the exclude=true attribute. Even then, keep in mind that hostlabel settings are not portable, since the always specific to a given OBS instance and should therefore only be used as a last resort in situations that cannot be addressed by any of the other qualifiers.

An example use case is to run benchmarks in a reproducible way.

Example for _constraints file:

<constraints exclude="false">
   <hostlabel>benchmark_runner</hostlabel>
</constraints>

Example for project configuration:

Constraint: hostlabel benchmark_runner

Example for RPM spec file or Dockerfile:

#!BuildConstraint: hostlabel benchmark_runner

Defines the "sandbox" which is used for the build. The "sandbox" is the virtual environment in which the build takes place: each build worker is configured with a fixed sandbox type.

The configuration of this build constraint is typically left to OBS administrators, and there is usually no reason for a project or package maintainer to set it.

Example for _constraints file:

<constraints>
   <sandbox exclude="true">kvm</sandbox>
</constraints>

Example for project configuration:

Constraint: sandbox exclude="true" kvm

Example for RPM spec file or Dockerfile:

#!BuildConstraint: sandbox exclude="true" kvm

This is a category of constraints specific to the Linux kernel, applied to the kernel running on the build worker.

<constraints>
   <linux><version>
     <min>3.0</min>
     <max>4.0</max>
   </version></linux>
</constraints>

Constraint: linux:version:min 3.0
Constraint: linux:version:max 4.0

#!BuildConstraint: linux:version:min 3.0
#!BuildConstraint: linux:version:max 4.0

<constraints>
    <linux>
      <flavor>default</flavor>
    </linux>
</constraints>

Constraint: linux:flavor default

#!BuildConstraint: linux:flavor default

To specify that build workers must meet certain minimum hardware specifications or possess certain hardware features.

<constraints>
   <hardware><cpu>
     <flag>mmx</flag>
     <flag>sse2</flag>
   </cpu></hardware>
</constraints>

Constraint: hardware:cpu:flag mmx
Constraint: hardware:cpu:flag sse2

#!BuildConstraint: hardware:cpu:flag mmx
#!BuildConstraint: hardware:cpu:flag sse2

Constraint: hardware:cpu:flag exclude=true EL0

#!BuildConstraint: hardware:cpu:flag exclude=true EL0

<constraints>
   <hardware>
     <processors>4</processors>
   </hardware>
</constraints>

Constraint: hardware:processors 4

#!BuildConstraint: hardware:processors 4

34.4.4.3 jobs #

 

Each build worker is configured with a given default for the JOBS environment variable, which expresses how many parallel build processes the worker should be able to sustain. To require a minimal number of pre-confiured parallel jobs for the build, use this qualifier.

Note

This specifies the number of parallel jobs the build tooling should use, so even though it is under hardware it is not actually a hardware requirement.

Example for _constraints file:

<constraints>
   <hardware>
     <jobs>4</jobs>
   </hardware>
</constraints>

Example for project configuration:

Constraint: hardware:jobs 4

Example for RPM spec file or Dockerfile:

#!BuildConstraint: hardware:jobs 4

<constraints>
  <hardware>
     <disk>
       <size unit="G">4</size>
     </disk>
  </hardware>
</constraints>

Constraint: hardware:disk:size unit=G 4

#!BuildConstraint: hardware:disk:size unit=G 4

<constraints>
   <hardware>
     <memory>
       <size unit="M">1400</size>
     </memory>
   </hardware>
</constraints>

Constraint: hardware:memory:size unit=M 1400

#!BuildConstraint: hardware:memory:size unit=M 1400

<constraints>
   <hardware>
     <physicalmemory>
       <size unit="M">1400</size>
     </physicalmemory>
   </hardware>
</constraints>

Constraint: hardware:physicalmemory:size unit=M 1400

#!BuildConstraint: hardware:physicalmemory:size unit=M 1400

After determining which build workers satisfy the defined constraints for a given build, the scheduler checks if any of them are available to start building. If at least one is available, the build begins. The rest of this section describes the OBS's behavior when no compliant build workers are free to start building a given package.

The build will stay in state "scheduled" until one of the compliant workers becomes available. No further notification is set.

The build will stay in state scheduled until one of the compliant workers becomes available. In addition, the dispatch details are set to tell the user that this build might take a long time to complete. The notification looks like this:

waiting for 4 compliant workers (4 down)

In this case, all four compliant workers are down. The notification helps the user understand why the build is not starting. The dispatch details can also be retrieved using the OBS API or, e.g., using the command osc results -v).

If no worker can handle the constraints defined by the package or project, the build fails. In such cases, the build log will mention why the build failed:

package build was not possible:

no compliant workers (constraints mismatch hint: hardware:processors sandbox)

Please adapt your constraints.