UPT.exe

Name

UPT.EXE - UEFI Packaging Tool (UEFIUPT) used to create, install or remove a UEFI Distribution Package.

Synopsis

upt [option] UEFI_PACKAGE_FILE

The UEFIPT command set has an associated order of execution precedence. For example: -v takes precedence over -q which has precedence over -d which has precedence of -s.

Execution precedence is defined as follows:

upt -h | --help | --version
upt [-v|-q|-d DEBUG_LEVEL|-s] [-f] [-x] -c DistFile -t DistInfo
upt [-v|-q|-d DEBUG_LEVEL|-s] [-f] [-x] -c DistFile -t DistInfo [-m INF_File]+
upt [-v|-q|-d DEBUG_LEVEL|-s] [-f] [-x] -c DistFile -t DistInfo [-p DEC_File]+
upt [-v|-q|-d DEBUG_LEVEL|-s] [-f] [-x] -c DistFile -t DistInfo [-m INF_File]+ [-p DEC_File]+
upt [-v|-q|-d DEBUG_LEVEL|-s] [-f|-n] [-x] -i DistFile
upt [-v|-q|-d DEBUG_LEVEL|-s] [-f] [-x] -r DistFile

Description

UEFIPT is used to create, install or remove a UEFI Distribution Package.

A "package information data" file (".ini") comprised of a "Distribution header" (required), and optional "Miscellaneous File Header, and/or "Tools Header" is required to create a distribution package. Instructions on how to create a package information file with required content may be found in the UEFI Packaging Tool (UEFIPT) Quick Start guide. (http://www.tianocore.org EDK II Documentation)

The command line file names are relative to the program execution path set in the OS environment variable WORKSPACE.

UEFIPT provides development environment support for the EDK II development tree.

Windows Development Workstations

The working directory for the EDK II build tree (containing distribution packages) is defined as a first level folder from the root directory for drive C.

For example:

C:/EDKII>

In this example, the OS environment variable WORKSPACE is set to the working directory for EDK II development.

For example:

C:/>set WORKSPACE=C:/EDKII

Windows 7 Development Workstations

For Windows 7 users, it is recommended that you use the subst command, keeping your edk2 downloads in your home directory. Windows 7 only allows administrators to create folders in the root directory. If you can remember to always open the cmd.exe using run as administrator ...*, the directions above can be used. Otherwise, if you sources are located in a directory path such as the following:

C:/Users/myname/Documents/Work/edk2>
subst z: C:/Users/myname/Documents/Work/edk2

Then set the OS environment variable WORKSPACE to the newly created drive:

C:/Users/myname/Documents/Work/edk2>z:
z:/>set WORKSPACE=z:/

Linux and OS/X Development Workstations

The working directory for the EDK II build tree (containing distribution packages) is defined as a first level folder from your home directory.

For example:

[/home/myname/edk2] #

In this example, the OS environment variable WORKSPACE is set to the working directory for EDK II development. For example:

[/home/myname/edk2] # export WORKSPACE=/home/myname/edk2

The OS environment variable WORKSPACE is now set to the EDKII WORKSPACE

To create a distribution package:

upt -c test.dist -p MdePkg/MdePkg.dec -t Package_Information_Data_File.ini
  • "test.dist" is the target distribution package that will be generated. If a destination path is not supplied, the test.dist will be created in the current working directory,

  • "MdePkg/MdePkg.dec" is the path and the source file used to generate the distribution package,

  • Package_Information_Data_File.ini is the file which specifies the information not included in MdePkg/MdePkg.dec but is required by the packaging specification. If a source path for the Package_Information_Data_File.ini is not provided, UEFIPT will attempt to locate the file in the current working directory or, failing that, the tool will attempt to locate it in $(WORKSPACE) directory.

UPT User Extensions

User extensions are provided so meta-data files can be created which provide functionality identical to the original meta-data. Details about user extensions are located in the UEFIPT Quick Start Guide.

Options

--version show program's version number and exit
-h, --help show this help message and exit
-d DEBUG_LEVEL, --debug=DEBUG_LEVEL
Print DEBUG statements, where DEBUG_LEVEL is 0-9
-v, --verbose Print informational statements
-s, --silent Returns only the exit code, informational and error
messages are not displayed
-q, --quiet Returns the exit code and displays error messages
only
-i INSTALL_DISTRIBUTION_PACKAGE_FILE, --install=INSTALL_DISTRIBUTION_PACKAGE_FILE
Specify the UEFI Distribution Package filename to
install
-c CREATE_DISTRIBUTION_PACKAGE_FILE, --create=CREATE_DISTRIBUTION_PACKAGE_FILE
Specify the UEFI Distribution Package filename to
create
-r REMOVE_DISTRIBUTION_PACKAGE_FILE, --remove=REMOVE_DISTRIBUTION_PACKAGE_FILE
Specify the UEFI Distribution Package filename to
remove
-t PACKAGE_INFORMATION_DATA_FILE, --template=PACKAGE_INFORMATION_DATA_FILE
Specify Package Information Data filename to create
package
-p EDK2_DEC_FILENAME, --dec-filename=EDK2_DEC_FILENAME
Specify dec file names to create package
-m EDK2_INF_FILENAME, --inf-filename=EDK2_INF_FILENAME
Specify inf file names to create package
-l, --list List the UEFI Distribution Packages that have been
installed
-f, --force Disable user prompts for removing modified files.
Valid only when -r is present
-n, --custom-path Enable user prompting for alternate installation
directories
-x, --free-lock Skip the check for multiple instances
-u REPLACE_DISTRIBUTION_PACKAGE_FILE, --replace=REPLACE_DISTRIBUTION_PACKAGE_FILE
Specify the UEFI Distribution Package file name to
replace the existing file name
-o ORIGINAL_DISTRIBUTION_PACKAGE_FILE, --original=ORIGINAL_DISTRIBUTION_PACKAGE_FILE
Specify the UEFI Distribution Package file name to be
replaced
--use-guided-paths Install packages to the following directory path by
default:
<PackageName>_<PACKAGE_GUID>_<PACKAGE_VERSION>

Examples

In the examples below, the "\" character is used to indicate line extension. On Microsoft* Windows based workstations, the command-line must appear on a single line, while under Linux and OS/X, the shell will correctly handle the "\" line extension character and the command can appear on separate lines.

All EDK II tools allow the user to specify a forward slash "/" character in directory names on the command-line.

The command-line prompt in the following UEFIPT examples is ">"; command-line prompt character may vary based on the operating system.

  1. Option -c, --create Create a distribution package.

    The command showing the proper syntax used to create a distribution package.

    >upt -c test.dist -p MdePkg/MdePkg.dec -t Package_Information_Data_File.ini
    • test.dist is the target distribution package to be generated,

    • MdePkg/MdePkg.dec is the path and source used to generate the

      distribution package,

    • Package_Information_Data_File.ini is the file which specifies the

      information not included in MdePkg\MdePkg.dec but is required by the

      packaging specification

    The extended version of the commands:

    >upt --create=test.dist --dec-filename=MdePkg/MdePkg.dec \
    --template=Package_Information_Data_File.ini
  2. Option -m, --inf-filename

    Specifying the module file name for inclusion in the distribution package.

    >upt -c testm.dist \
    -m MdeModulePkg/Universal/Acpi/AcpiPlatformDxe/AcpiPlatformDxe.inf \
    -t Package_Information_Data_File.ini

    The extended version of the command:

    >upt --create=testm.dist \
    --inf-filename=MdeModulePkg/Universal/Acpi/AcpiPlatformDxe/AcpiPlatformDxe.inf \
    --template=Package_Information_Data_File.ini
    • testm.dist is the target distribution package to be generated,

    • MdeModulePkg/Universal/Acpi/AcpiPlatformDxe/AcpiPlatformDxe.inf is the

      path and filename for the module to be included in the distribution

      package, and

    • Package_Information_Data_File.ini is the file which specifies the

      information not included in AcpiPlatformDxe.inf but is required by the

      packaging specification

  3. Option -i, --install

    Install a UEFI package file

    File locations are relative to the program execution path set in the OS environment variable WORKSPACE. WORKSPACE is set to the working directory for the EDK II development tree (containing distribution packages).

    Windows Development Workstations

    The working directory of the EDKII development tree is a first level folder from the root directory for drive C.

    For example:

    C:\EDKII>

    In this example, the OS environment variable WORKSPACE is set to the working directory for EDK II.

    For example:

    C:\>set WORKSPACE=C:\EDKII

    Windows 7 Development Workstations

    For Windows 7 users, it is recommended that you use the subst command, keeping your edk2 downloads in your home directory. Windows 7 only allows administrators to create folders in the root directory. If you can remember to always open the cmd.exe using "run as administrator ...", the directions above can be used. Otherwise, if you sources are located in a directory path such as the following:

    C:\Users\myname\Documents\Work\edk2>
    subst z: C:\Users\myname\Documents\Work\edk2

    Then set the OS environment variable WORKSPACE to the newly created drive:

    C:\Users\myname\Documents\Work\edk2>z:z:\>set WORKSPACE=z:\

    Linux and OS/X Development Workstations

    The working directory for the EDK II build tree (containing distribution packages) is defined as a first level folder from your home directory.

    For example:

    [/home/myname/edk2] #

    In this example, the OS environment variable WORKSPACE is set to the working directory for EDK II development.

    For example:

    [/home/myname/edk2] # export WORKSPACE=/home/myname/edk2

    The OS environment variable WORKSPACE is now set to the EDKII WORKSPACE. Copy the distribution package file to the location to which the OS variable "WORKSPACE" has been defined.

    For example:

    Windows Development Workstations

    >copy test.dist %WORKSPACE%

    Linux and OS/X Development Workstations

    # cp test.dist $WORKSPACE

    Execute the UPT command to install the distribution package.

    For example:

    >UPT -i test.dist

    The extended version of the command:

    >UPT --install=test.dist

    If the distribution package target folder is already present (for example, MdePkg already exists), Intel UEFIPT will inform you that the specified target already exists and will prompt you to enter another location. If no additional locations are required, pressing [ENTER] will exit the tool. The following is an output display example:

    Windows Development Workstations

    C:\EDKII>upt -i test.dist
    Unzipping and parsing distribution package XML file
    Dist.content -> C:\EDKII\dist.content
    Installing package MdePkg Version 1.02
    This directory already exists: MdePkg.
    Please select another location. Press [Enter] with no input to quit:
    MyDistributionPackageSource\

    Linux and OS/X Development Workstations

    # upt -i test.dist
    Unzipping and parsing distribution package XML file...
    Dist.content -> /home/myname/edk2/dist.content
    Installing package ... MdePkg Version 1.02
    This directory already exists: MdePkg.
    Please select another location. Press [Enter] with no input to quit:
    MyDistributionPackageSource/
  4. Option -r, --remove

    Remove a UEFI package file

    >upt -r test.dist

    The extended version of the command using a second version of a distribution that was also installed:

    >upt --remove=test_80c92dc3-3a9c-42e9-9b92-4d2b82f0025b_1.0.dist

    Where test.dist and test_80c92dc3-3a9c-42e9-9b92-4d2b82f0025b_1.0.dist are the names of installed UEFI distribution packages that will be removed.

  5. Option -n, --custom-path

    Prompt for the source path for each package in the distribution

    upt -i test.dist -n

    The extended version of the command:

    upt --install=test.dist --custom-path

    You will be presented with a display similar to the following:

    Windows Development Workstations

    C:\EDKII>upt -i test.dist -n
    Unzipping and parsing distribution package XML file...
    dist.pkg -> c:\EDKII\dist.pkg
    Dist.content -> C:\EDKII\dist.content
    Installing package ... MdePkg Version 1.02
    Please select package location. Press [Enter] with no input to quit:
    MyDistributionPackageSource\

    Linux and OS/X Development Workstations

    # upt -i test.dist -n
    Unzipping and parsing distribution package XML file...
    dist.pkg -> /home/myname/edk2/dist.pkg
    Dist.content -> /home/myname/edk2/dist.content
    Installing package ... MdePkg Version 1.02
    Please select package location. Press [Enter] with no input to quit:
    MyDistributionPackageSource/
  6. Option -x, --free-lock

    Instructs the UEFIPT to unconditionally free the lock on the UPT database before any UPT operations are executed.

    Background: While executing, the UEFIPT locks the UPT database. This precludes any other instance of UEFIPT from executing. If UEFIPT should be stopped for some reason (for example, you press CTRL+C) the UPT database will remain locked. The -x, --free-lock option is used to skip the lock check.

    >upt -i test.dist -x

    The extended version of the command:

    >upt --install=test.dist --free-lock

    If the UPT database is locked, you will be presented with a display similar to the following:

    >upt -c test28.dist -p MdePkg/MdePkg.dec -t Package_Information_Data_File.ini
    upt...
    : error D003: UPT is already running. Only one instance is allowed

    NOTE: Error message format varies based on the Development Workstation operating system.

Bugs

During stress testing under Microsoft* Windows 7 with anti-virus software enabled, the tool failed after successfully completing 400 create pack.age operations

An EDK II binary module that uses binary file types of UNI_VER, UNI_UI, LIB and UEFI_APP cannot be distributed using the standard features, however the contents may be distributed using MiscellaneousFiles portion of the UPT.

When installing a UEFI Distribution Package generated by other tools that allow absolute path names for files, the error messages on Windows are different than the error messages on *NIX systems. The UEFIPT does not support absolute path names for files and directories.

If an EDK II Meta-data file is incorrectly formatted, information from the header comment block, such as copyright and license may be lost. Manually removing or renaming a directory tree that was installed by the UEFIPT will not allow using the UEFIPT for other operations.

Report bugs to [email protected]

Files

Windows:

%WORKSPACE%\BaseTools\Conf\Empty_Package_Information_Data_File.ini

Linux & OS/X:

$(WORKSPACE)/BaseTools/Conf/Empty_Package_Information_Data_File.ini

UEFI Packaging Tool (UEFIPT) Quick Start guide (www.tianocore.org, edk2/Documents)

The Distribution Package (.dist) for install and create, along with the Package Information Data File (.ini) are not required to be in the EDK II WORKSPACE. All other files are required to be in the directory tree pointed to by the system environment variable: WORKSPACE. (The Distribution Package file name used during removal is in the $(WORKSPACE)/Conf directory tree, placed there during package installation by the tool.)

See also

None

License

Copyright © 2011 - 2016, Intel Corporation. All rights reserved.

This program and the accompanying materials are licensed and made available under the terms and conditions of the BSD License which accompanies this distribution. The full text of the license may be found at:

http://opensource.org/licenses/bsd-license.php

THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

Revision 1.6, 14 March, 2016