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

For packages with XB-Plugin set to eula, you can prevent the EULA package from being installed on disk by setting this value to ni-package-manager.

 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.

You can optionally specify localized text. See Localized Attributes.

 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. 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 (.)
  • Start with an alphanumeric character
  • 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. 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
  • Add-Ons
  • Drivers
  • Runtime
  • Utilities
  • Documentation
  • Infrastructure

For packages that set XB-Plugin to eula, you must set this value to Infrastructure. See Assembling a EULA Package for more information about creating EULA packages.

 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.

Use the debian format. For more information, visit https://www.debian.org.

 Version: 17.1.0.1
XB-DisplayName No String NULL User friendly package name.

You can optionally specify localized text. See Localized Attributes.

 XB-DisplayName: NI LabVIEW 2017
XB-DisplayVersion No String NULL User friendly display version. XB-DisplayVersion: 15.0.0
XB-Eula No String relationship array NULL Declares which EULA packages the package requires. XB-Eula: eula-mycompany, eula-ni-standard
XB-EulaTitle No String NULL Specifies the displayed title of the EULA package. Use this attribute only in packages that have XB-Plugin set to eula XB-EulaTitle: My Software Name
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.

You can optionally specify localized text. See Localized Attributes.

 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:
  • eula
  • file
  • wininst
  • relative-file
 XB-Plugin: file
XB-ReleaseNotes No Multi-line NULL Release notes for the package.

You can optionally specify localized text. See Localized Attributes.

 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:
  • no
  • yes
 XB-StoreProduct: no
XB-UserVisible No Boolean no Specifies whether Package Manager displays the package.
Expected values:
  • no
  • yes

You must set the value to no for packages that set XB-Plugin to eula. See Assembling a EULA Package for more information about creating EULA packages.

 XB-UserVisible: no
XB-VisibleForRuntimeDeployment No Boolean no Specifies whether NI Package Builder displays the package by default when dependencies are added.
Expected values:
  • no
  • yes
 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:
ExampleResulting Requirement
XB-OsRequires: >=6.3
Requires Windows 8.1 or newer
XB-OsRequires: >=10.0, !=10.0.18363
Requires Windows 10 or newer, but not Windows 10 version 1909
XB-OsRequires: >=6.3, <10 | >=10.0.18363
Requires Windows 8.1 or newer and either the OS is older than Windows 10, or it is Windows 10 version 1909 or newer

Localized Attributes

Description, display name, release notes, and message text appears localized in the Package Manager user interface when you include versions of the attributes that are appended with a language-specific suffix.

The Package Manager GUI displays localized text for the Description, XB-DisplayName, XB-ReleaseNotes, and XB-MessageText attributes when you include localized versions of these attributes. Localized versions of these attributes are appended with a hyphen and a language-specific suffix to the attribute name. If there is no language-specific attribute that matches the language of the Package Manager GUI, the non-localized attribute text is used.

For example, a LabVIEW control file could include the following XB-DisplayName attributes:
DisplayName: LabVIEW (64-bit) English
DisplayName-de: LabVIEW (64 Bit) – Englisch
DisplayName-es: LabVIEW (64 bits) – Español
DisplayName-fr: LabVIEW (64 bits) – Anglais
DisplayName-it: LabVIEW (64 bit) – Italiano
DisplayName-ja: LabVIEW (64ビット) 英語版
DisplayName-ko: LabVIEW (64비트) 영어 버전
DisplayName-zh-CN: LabVIEW（64位）英语版