Build & Packaging Utility Programs

32

32.1 Overview

This chapter describes utilities that UDI build environments and UDI runtime environments must provide. The build environment consists of the tools and utilities used to create driver binaries (the udibuild utility) and to create driver source and/or binary installation packages (the udimkpkg utility). The runtime environment consists of the tools necessary to install driver packages (the udisetup utility), as well as the software modules necessary to configure and execute UDI drivers.

Many environments will be a combination of both build and runtime environment.

32.2 The udibuild Utility

All UDI build environments, and all runtime environments that support source distributions, shall include a utility called udibuild. This utility, when invoked with no command-line arguments, will search the current working directory for a udiprops.txt file and source files, then attempt to build a driver binary using build rules from udiprops.txt, placing the resultant binary object modules in the bin/<abi> subdirectory of the current directory (creating the subdirectories as needed) where the name for the current ABI is substituted for <abi>.

The binary object modules produced by the udibuild utility must not export any global symbols for a portable UDI module except for the udi_init_info symbol and any symbols associated with any provides declarations in the module's static properties specification.

The behavior of udibuild when given any command-line arguments is implementation-dependent. The command "udibuild -h" shall cause a usage message to be displayed, which will list the parameters specific to this implementation.

32.3 The udimkpkg Utility

All UDI build environments shall include a utility called udimkpkg. This utility uses the static driver properties file, udiprops.txt, to find the various pieces of a UDI driver or library component (including message files, readable files, as well as source and/or object files), and gathers them into a UDI package file, ready for distribution or installation. For binary distributions, udimkpkg also attaches the content of the udiprops.txt file to the primary binary module (typically a relocatable object file) of the driver, in an ABI-specific fashion, stripping out any build-only properties in the process.

The output of udimkpkg is a UDI package file, as described in Section 31.3, "Archive Format". Additional environment-specific tools may be required to copy this package file onto physical media or to upload it to a network server.

When run in the directory containing all of the input files, with no command-line arguments, the udimkpkg utility will create a UDI package file in the current working directory, named "nnnnnnnn.udi", where "nnnnnnnn" is replaced by the <name_string> from the "shortname" declaration in udiprops.txt.

When stored in the UDI package file, the component must have associated driver, alternate, and component names. By default, udimkpkg takes these from the "shortname", "release", and "module" declarations, respectively, from udiprops.txt. (If there are multiple "module" declarations for a component, the first one is used.) All udimkpkg utilities must also provide a way to specify other values for each of these names, but the command syntax for doing so is implementation-defined, as is the syntax for selecting source vs binary distributions. By default, udimkpkg will include both source and binary files in the package, if both are present in the input directory.

For binary distributions, udimkpkg will use a build environment general value for the <abi> subdirectory name, but shall provide an implementation-defined way to override this default to specify ABI variations such as processor-specific subclasses (see Section 31.2.1, "Directory Structure").

The udimkpkg utility may also support additional implementation-defined arguments. The command "udimkpkg -h" shall cause a usage message to be displayed, which will list the parameters specific to this implementation.

32.4 The udisetup Utility

All UDI build environments shall include a utility called udisetup. This utility extracts driver files from the UDI package file, installs them in environment-specific locations, and prepares the driver for use on the target system.

With no command-line arguments, udisetup shall search the current working directory for all files ending in ".udi" or ".UDI", and either install all of the drivers in all of the packages, or provide the user a way to interactively pick and choose amongst them if there are more than one. With a single command-line argument, udisetup shall interpret that argument as the filename of a single UDI package file to use, and either install all of the drivers in the package, or provide the user a way to interactively pick and choose amongst them if there are more than one.

udisetup may have additional implementation-specific parameters for items such as distribution package location, driver versions and alternates to be installed, and so forth. The command "udisetup -h" shall cause a usage message to be displayed, which will list the parameters specific to this implementation.