Name
UPT.EXE (Intel® UEFI Packaging Tool (Intel® UEFIUPT)) - create, install or remove a UEFI Distribution Package.
Synopsis
upt [option] UEFI_PACKAGE_FILE
The Intel 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
Intel® 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 and its required content may be found in the Intel® UEFI Packaging Tool (Intel® UEFIPT) Quick Start guide. 
When entered on the command line, file locations are relative to the program execution path set in the OS environment variable WORKSPACE.
Intel 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, Intel 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 Intel® 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
  -f, --force  
Disable all user prompts
  -n, --custom-path
Enable user prompting for alternate installation directories
  -x, --free-lock
Skip the check for multiple instances
  -l, --list            
List the UEFI Distribution Packages that have been installed
  -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>
  -j TEST_INSTALL_DISTRIBUTION_PACKAGE_FILES, --test-install=TEST_INSTALL_DISTRIBUTION_PACKAGE_FILES
Specify the UEFI Distribution Package filenames to install
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 Intel 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 Intel® UEFIPT to unconditionally free the lock on the UPT database before any UPT operations are executed.
Background: While executing, the Intel UEFIPT locks the UPT database. This precludes any other instance of Intel UEFIPT from executing. If Intel 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 package 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 Intel 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 Intel UEFIPT will not allow using the Intel UEFIPT for other operations.
Files
Windows: %WORKSPACE%\BaseTools\Conf\Empty_Package_Information_Data_File.ini
Linux & OS/X: $(WORKSPACE)/BaseTools/Conf/Empty_Package_Information_Data_File.ini
Intel® UEFI Packaging Tool (Intel® 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 - 2017 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, 07th March 2017