# Control File Attributes

A control file is a text file without an extension that contains metadata describing properties and relationships of the package, such as its name, version, type, and dependencies. Both File packages and WinInst packages require a control file. Package Manager generates the package according to the metadata in the control file.

Attribute Name Required Type Default Description Details Example
Architecture Yes String N/A

Indicates the OS architecture supported by the package.

Expected values:
• windows_x64 (Installable only on a 64-bit Windows)
• windows_all (Deprecated with the removal of 32-bit Windows)
Architecture: windows_all
Note

You can only specify one architecture per package.

Conflicts No String relationship array NULL

Declares a conflict between one binary package and another.

Package Manager does not install conflicting packages on a system at the same time.

See the String Relationship Array section for an example.
Depends No String relationship array NULL

Declares an absolute dependency.

• windows_x64 packages should only depend on windows_x64 and windows_all packages.
• windows_all packages should only depend on windows_all packages.
• Special package system-windows-x64 can be used as a placeholder for 64-bit dependencies.
See the String Relationship Array section for an example.
Description Yes Multi-line N/A

Provides a description of the binary package.

Consists of two parts: the single-line synopsis and the multi-line long description.

NI recommends using two white space characters between the synopsis and the long description to improve readability.

See the Multi-line Attributes section for an example.
Enhances No String relationship array NULL

Declares that a package enhances the functionality of another package.

Only use this attribute in packages that have XB-UserVisible set to yes.

See the String Relationship Array section for an example.
Homepage No String NULL

The URL that the package vendor uses to provide more detailed information about the package.

N/A Homepage: http://www.ni.com
Installed-Size No Long integer 0

Provides an estimate of the total amount of disk space required to install the package.

Expected value: an integer value of the estimated install size in bytes, divided by 1024 and rounded up.

Installed-Size: 25485141
Maintainer Yes String N/A

The package maintainer's name and email address.

Expected values: the name of the maintainer followed by the email address inside angle brackets.

Maintainer: National Instruments <support@ni.com>
Package Yes String N/A

Specifies a unique identification for a package.

A package name must be a unique, user friendly string that a customer would type on the command line and meet the following requirements:

• Consist only of lower case letters (a-z), digits (0-9), plus (+) and minus (-) signs, and periods (.)
• Must not contain uppercase letters
• Have a min length of two characters
• Have a max length of 58 characters

Expected values:

• Match the regular expression ^[a-z0-9][a-z0-9.+-]{2,}\$
• NI recommends that you start the name of your package with your company name followed by a dash (ex: ni-testpackage)

Good syntax:

• Package: ni-labview-2015
• Package: ni-daqmx
• Package: ni-daqmx-labview-2015-support

Incorrect syntax:

• Package: LabVIEW_2015
• Package: NationalInstrumentsGPIB
• Package: labview
Provides No String relationship array NULL

Declares that the package satisfies an absolute dependency of another package.

N/A See the String Relationship Array section for an example.
Recommends No String relationship array NULL

Declares a strong dependency that is not absolute.

Lists packages that would be installed with this one in most situations.

Only recommend packages with XB-UserVisible set to yes.

See the String Relationship Array section for an example.
Replaces No String relationship array NULL

Declares that the package replaces other packages.

Conflicts should be used in conjunction with Replaces.

See the String Relationship Array section for an example.
Section No String NULL

Specifies the category in which the package is classified.

Expected values:

• Programming Environments
• Application Software
• Drivers
• Runtime
• Utilities
• Documentation
• Infrastructure
Section: Application Software
Suggests No String relationship array NULL

Declares that one package may be more useful with one or more other packages.

Notifies Package Manager and the user that the listed packages are related to this one, but not required.

Only suggest packages with XB-UserVisible set to yes.

See the String Relationship Array section for an example.
Supplements No String relationship array NULL

Declares that a package supplements the functionality of another package.

Only use this attribute in packages that have XB-UserVisible set to yes.

See the String Relationship Array section for an example.
Version Yes String N/A

Specifies the version number of the package.

Version: 17.1.0.1
XB-DisplayName No String NULL

User friendly package name.

N/A XB-DisplayName: NI LabVIEW 2017
XB-DisplayVersion No String NULL

User friendly display version.

N/A XB-DisplayVersion: 15.0.0
XB-MessageCondition-#

For example:

XB-MessageCondition-1, XB-MessageCondition-2, etc.

No String N/A

Specifies a condition for when the corresponding message will show in Package Manager.

Only MSI conditions are accepted and should be enclosed in <msi>...</msi> tags. Unless enclosed in a CDATA block, text within the tags needs to have '<' and '>' characters escaped as '&lt' and '&gt'.
XB-MessageCondition-1:
<msi>VISA32COMPANYNAME ~&lt;&gt; "National Instruments"</msi>

XB-MessageCondition-2:
<msi><![CDATA[VISA32COMPANYNAME ~<> "National Instruments"]]></msi>


XB-MessageText-#

For example:

XB-MessageText-1, XB-MessageText-2, etc.

No Multi-line N/A

Contains an important message that Package Manager displays before installing the package.

Consists of two parts, a header and a body.

You can specify a condition for displaying this message by using the corresponding MessageCondition attribute below. If you do not specify a condition, this message will always show when you install this package.

NI recommends you create preformatted text for each line of the body using two spaces at the beginning of each line.

XB-MessageText-1: This is my message header.
This is my message body.
There are multiple lines.
XB-OsRequires No String N/A

Declares which OS versions the package requires.

If you do not specify XB-OsRequires, all OSs Package Manager currently supports are allowed.

Define the OS bitness restriction using the Architecture attribute.

If the OS of a system cannot satisfy XB-OsRequires for a package, the Package Manager GUI does not display the package.

If a package has a dependency with a more restrictive XB-OsRequires, the package inherits the more restrictive OS requirement.

See the OS Requirement section for an example.
XB-Plugin Yes String NULL

The Agent used to install the package.

Expected values:

• file
• wininst
• relative-file
XB-Plugin: file
XB-ReleaseNotes No Multi-line NULL

Release notes for the package.

N/A See the Multi-line Attributes section for an example.
XB-StoreProduct No Boolean no

Specifies whether the package is a product in Package Manager.

You must set the value to yes for your package to appear in the Installed and Packages tabs when Products Only is checked.

Expected values:

XB-StoreProduct: no
XB-UserVisible No Boolean no

Specifies whether Package Manager displays the package.

Expected values:

XB-UserVisible: no
XB-VisibleForRuntimeDeployment No Boolean no

Specifies whether Package Builder displays the package by default when dependencies are added.

Expected values:

XB-VisibleForRuntime: yes

## String Relationship Array

Package Manager expects a string relationship array, or a list of package names separated by commas, as the value of control file attributes that declare relationships.

Format these attribute values according to the following syntax rules:

• Separate package names using commas.
• Separate alternative package names for any dependency using vertical bars. This indicates that any one of the alternative packages listed satisfies the dependency.
• Include version requirements for a package in parenthesis following the name of the package. You can restrict the applicability of each package to particular versions in all of the string relationship array fields except for Provides.
• Inside the parenthesis, use one of the following operators followed by a version number to indicate the relationship between the package and version. You can use white space in the version specification.
Operator Relationship
<< strictly earlier
<= earlier or equal
= exactly equal
>= later or equal
>> strictly later
!= excluding

In the following example, the Depends attribute declares a dependency on package01 version 2.2.1 or later, and states that package03 is an alternative package that satisfies the dependency on package02.

Depends: package01 (>= 2.2.1), package02 | package03

## Multi-line Attributes

The value of a multi-line attribute consists of a single-line synopsis followed by additional lines that provide an extended description.

The first line of a multi-line attribute is reserved for the attribute name followed by a single-line synopsis. Provide a short description or heading for this portion of the attribute. XB-ReleaseNotes attributes do not use a single-line synopsis.

The extended description contains additional details you provide for the attribute. Format the extended description of a multi-line attribute according to the following rules:

• Create a paragraph using a single space at the beginning of a line. When displaying this text, the displaying program removes the leading space and uses word wrapping. A paragraph must contain at least one non-whitespace character.
• Preserve whitespace and line breaks within text using two or more spaces at the beginning of a line. If the display area does not scroll horizontally and a line is too long to fit, the displaying program creates line breaks where necessary.
• Create a blank line using a single space followed by a period.

The following text provides an example of how you can use the formatting rules for multi-line attributes to enter text for the Description element:

Description: Example of multi-line attribute contents.
The single space at the beginning of this line creates a paragraph.
.
The double space at the beginning of these lines creates preformatted
text that preserves whitespace and line breaks.

## OS Requirement

The XB-OsRequires version contains up to three integer fields for Windows operating system versions. The first two fields correspond to Windows operating system versions as specified by Microsoft on Operating System Version. The third field is only applicable to the Windows 10 operating system builds as specified by Microsoft on Windows 10 release information.

Format the attribute fields according to the following syntax rules:

• Separate fields using periods.
• Separate multiple requirements using commas.
• Specify alternative requirements using vertical bars. Vertical bars take precedence over commas.
• The following operators are supported by this attribute:
Operator Relationship
<< less than
<= less than or equal to
= equal to
>= greater than or equal to
>> greater than
!= excluding
The following table shows examples of how to use XB-OsRequires:
Example Resulting Requirement
XB-OsRequires: >=6.3
XB-OsRequires: >=10.0, !=10.0.18363
XB-OsRequires: >=6.3, <10 | >=10.0.18363