Adding Programs to TBWinPE/RE Builds
This article covers several methods to add programs to the Image for Windows TBWinPE/RE boot media. Adding programs is supported using both TBWinPE/RE Builder and the scripts (TBWinPE.cmd, TBWinRE.cmd). Using TBWinPE/RE Builder is detailed here. The instructions would vary if using the scripts, but the general process is the same (see Appendix).
If you are unfamiliar with the process of creating the TBWinPE/RE boot media, you may find it helpful to create a standard build before attempting a custom build. Tutorials for creating the TBWinPE/RE boot media can be found in the following how-to articles:
Creating a TeraByte WinPE Boot Disc Containing Image for Windows (TBWinPE)
Requirements & Considerations
- The program being added must run in the standard WinPE/RE environment, which is very limited compared to normal Windows. Many programs many not run at all or have missing/broken features due to lack of support. If you are unsure if the program you wish to add will run in WinPE/RE you can try it using Method 1 (below) before creating a custom build that includes it.
- The program must be the correct architecture for the build. If creating a 64-bit (x64) build, the program being added must be 64-bit. If creating a 32-bit (x86) build, the program being added must be 32-bit. Many programs are still only available as 32-bit versions and since almost all current Windows installations are 64-bit this means that most TBWinRE builds would also be 64-bit. In this case, if you require a 32-bit (x86) build you will need to create a TBWinPE build using the appropriate AIK/ADK.
- In the methods below a USB flash drive (UFD) is used for the boot media as it offers more flexibility than read-only media (e.g., CD/DVD). Writable media, such as a UFD, is recommended when first creating and configuring the build even if it will eventually be put on read-only media when finalized.
- TBWinRE files are automatically installed with Image for Windows on Windows 7 or later. However, when creating a customized build, you may find copying the files to an alternate folder with standard user-level permissions will make the process easier. If creating multiple custom builds it may be beneficial to place each one in a separate folder. Using an alternate folder also gives you control over when the build files are updated since updating Image for Windows won't replace them. In the examples below, the TBWinRE files are located in C:\TBWinRE.
- The methods shown in this article are basic examples -- custom builds are not limited to these particular scenarios.
Contents
Method 1 - Standard Build with Program on UFD
Method 2 - Custom Build with Program on UFD
Method 3 - Custom Build with Program Included in Build
Method 1 - Standard Build with Program on UFD
This method provides an easy way to manually add a program to the boot media.
- Create the TBWinPE/RE build normally and save it to a UFD.
- Create a folder on the UFD to hold the program files.
- Copy the program files into the folder.
- Boot to the UFD.
- Browse to the program on the UFD and run it. This can be done directly from TBLauncher (File | Run) or you can open a Command Prompt and run it from there.
Alternatively, when just testing if the program will run from TBWinPE/RE you could skip copying the program files to the UFD and instead run the program directly from a local drive (e.g., a folder on your Windows partition or data partition).
Note: When using this method any files copied to the UFD will be lost when the UFD is updated to a new build using MakeDisk. To avoid this, update the UFD manually by copying the contents of the new build's ISO folder to the root folder of the UFD (replacing existing files) instead of running MakeDisk. Refer to the following KB article for more details: Manually Updating the TBWinPE/RE Boot Media
Method 2 - Custom Build with Program on UFD
This method is similar to Method 1, but with several enhancements:
- Program is added to TBLauncher's menu, which can optionally be tweaked/configured without recreating the build.
- Program files can be updated simply by copying the files to the UFD (recreating the build isn't necessary).
- Program files can optionally be updated automatically when a new build is created.
Instructions:
- Copy the files for the program being added to a sub-folder in the ISO folder of the TBWinRE folder. The ISO folder won't exist if a build hasn't previously been created. If necessary, create the ISO folder before creating the folder for the program. C:\TBWinRE\ISO\CustomProg is used here with the program consisting of program.exe and supporting files.
- Add the program to the TBLauncher menu:
- Run TBWinPE/RE Builder and go into Settings. Select the TBLauncher tab. Click the Edit TBLauncher.ini link at the bottom of the window. This will open the file in Notepad.
- Scroll through the file and locate the [Menu] section. A new menu entry will be added so increment the ItemCount value. In this example, there are already 10 menu items so the new one will be 11.
[Menu]
ItemCount=11
- Scroll to the end of the file and add the menu entry for the program being added.
[Menu_Item_11]
Name=Custom Program
Path=%TBDrive%\CustomProg\program.exe
WorkingDir=
Parameters=
Icon=0
Keeping the program name short is recommended due to limited space in the menu. If the program requires a working directory or parameters you can set those as well.
By default, the icon is retrieved from the program file. With TBLauncher 1.15+ you can use a custom icon by specifying the path to the file (supported file types: .ico, .exe, .dll). If the icon file is not found or there is an error the icon from the program will be used. For example:
Icon=0,%TBDrive%\CustomProg\program.ico
Note: The icon index value is specified (0, above), but is not applicable to .ico files. - Save TBLauncher.ini and close Notepad.
- Enable the Search for TBWinRE/PE boot media drive after booting option. This will locate the UFD once it's booted and set the %TBDrive% environment variable used for the menu item.
- Click OK to close Settings.
- Run TBWinPE/RE Builder and go into Settings. Select the TBLauncher tab. Click the Edit TBLauncher.ini link at the bottom of the window. This will open the file in Notepad.
- [Optional] Copy the TBLauncher.ini file from the build's config folder to the ISO\TBData folder. This allows changes to the menu items (descriptions, paths, etc.) to be made by editing the file in the boot media's TBData folder (no need to recreate the build). In this example, you would copy C:\TBWinRE\config\TBLauncher.ini to C:\TBWinRE\ISO\TBData. Keep in mind that if you edit the original file you will also need to update the copy (this could be scripted if you want it to happen automatically). If changes are made to the file on the boot media and you don't want them lost when recreating the media, copy the modified file to the build's ISO\TBData folder.
Note: The TBLauncher Search for TBWinRE/PE boot media drive after booting option must be enabled in the build for this feature to function (see Step 2e). For boot media that has already been created with this option enabled, the feature can be used by simply copying the TBLauncher.ini file to the TBData folder on the boot media.
- [Optional] Configure the BuildScript to copy the program files to the ISO\CustomProg folder. This allows the files to automatically be copied into the build each time it's created. For example, if the program files have been updated in the source location the build would include those updated files.
- Open Settings. Select the Scripts tab.
- Enable the Use BuildScript.cmd option.
- Click the Edit link next to the BuildScript option. If the script file doesn't already exist you will be prompted to create it. The script will open in Notepad for editing. Add the commands necessary to copy the program files from their source location to the ISO\CustomProg folder. In this example, the source folder is F:\CustomProgSource. The script will first create the sub-folder in the ISO folder (in case it doesn't exist) and then copy all the files from the source folder to the new program folder.
:: Add script commands after this line
md "%TBWinPE_BuildPath%\ISO\CustomProg" 2> nul
copy "F:\CustomProgSource\*.*" "%TBWinPE_BuildPath%\ISO\CustomProg"
- If configuring Step 3, you could have the script automatically copy the TBLauncher.ini file from the build's config folder to the ISO\TBData folder.
:: Copy TBLauncher.ini to TBData
copy "%TBWinPE_ConfigPath%\TBLauncher.ini" "%TBWinPE_BuildPath%\ISO\TBData"
- Save BuildScript.cmd and close Notepad.
- Click OK to close Settings.
- Open Settings. Select the Scripts tab.
- Finish creating the build normally and use MakeDisk to create the boot media on a UFD.
- Boot the UFD and verify the custom program shows up in the TBLauncher menu and runs properly. If any tweaks/corrections are required, edit the relevant files on the UFD and reboot to test. When finalized, update the affected build files with the revised versions so the next build will use them.
Method 3 - Custom Build with Program Included in Build
This method is similar to Method 2, but with several major differences:
- Program is added to TBLauncher's menu, but modifying the menu requires recreating the build.
- Program is included in the build (packed in the WIM file) and will exist on the WinPE RAM disk (drive X:) when booted.
- Updating Program files requires recreating the build.
Instructions:
- Make note of the folder containing the program files that will be added to the build. C:\TBWinRE\ISO\CustomProg is used here with the program consisting of program.exe and supporting files.
- Add the program to the TBLauncher menu:
- Run TBWinPE/RE Builder and go into Settings. Select the TBLauncher tab. Click the Edit TBLauncher.ini link at the bottom of the window. This will open the file in Notepad.
- Scroll through the file and locate the [Menu] section. A new menu entry will be added so increment the ItemCount value. In this example, there are already 10 menu items so the new one will be 11.
[Menu]
ItemCount=11
- Scroll to the end of the file and add the menu entry for the program being added.
[Menu_Item_11]
Name=Custom Program
Path=%ProgramFiles%\CustomProg\program.exe
WorkingDir=
Parameters=
Icon=0
Keeping the program name short is recommended due to limited space in the menu. If the program requires a working directory or parameters you can set those as well.
Since the drive letter of the booted RAM drive is known (X:) you could specify it instead of the %ProgramFiles% environment variable. For example:
Path=X:\Program Files\CustomProg\program.exe
By default, the icon is retrieved from the program file. With TBLauncher 1.15+ you can use a custom icon by specifying the path to the file (supported file types: .ico, .exe, .dll). If the icon file is not found or there is an error the icon from the program will be used. For example:
Icon=0,%ProgramFiles%\CustomProg\custom.ico
Note: The icon index value is specified (0, above), but is not applicable to .ico files. - Save TBLauncher.ini and close Notepad.
- Run TBWinPE/RE Builder and go into Settings. Select the TBLauncher tab. Click the Edit TBLauncher.ini link at the bottom of the window. This will open the file in Notepad.
- Configure the BuildScript to copy the program files to the mount\Program Files\CustomProg folder.
- While still in Settings, select the Scripts tab.
- Enable the Use BuildScript.cmd option.
- Click the Edit link next to the BuildScript option. If the script file doesn't already exist you will be prompted to create it. The script will open in Notepad for editing. Add the commands necessary to copy the program files from their source location to the mount\Program Files\CustomProg folder. In this example, the source folder is F:\CustomProgSource. The script will first create the CustomProg sub-folder and then copy all the files from the source folder to the new program folder.
:: Add script commands after this line
md "%TBWinPE_MountPath%\Program Files\CustomProg" 2> nul
copy "F:\CustomProgSource\*.*" "%TBWinPE_MountPath%\Program Files\CustomProg"
- Save BuildScript.cmd and close Notepad.
- Click OK to close Settings.
- While still in Settings, select the Scripts tab.
- Finish creating the build normally and use MakeDisk to create the boot media on a UFD.
- Boot the UFD and verify the custom program shows up in the TBLauncher menu and runs properly. If any tweaks/corrections are required, edit the relevant files and recreate the build and boot media.
Appendix
Custom Build Tips
- You can change the order of the items shown in the TBLauncher menu by changing the item number for the entry. For example, if you want your custom program to be the first menu item, use Menu_Item_1 for its section and renumber the other items (Image for Windows becomes Menu_Item_2, etc.).
- Use the Pause build before unmounting WIM file option (on Build Options tab in Settings) to verify the changes are correct in the build before it's unmounted. If necessary, you can tweak things before continuing. If browsing or working in the mount folder be sure to browse out of it, etc. before continuing so Windows doesn't prevent the unmount from succeeding.
Using Build Environment Variables
TBWinPE/RE Builder assigns several environment variables for use in BuildScript.cmd:
TBWinPE_Arch: The architecture of the build being created (x86, AMD64).
TBWinPE_x64: Will be assigned 64 if creating a 64-bit build. Unassigned for 32-bit.
TBWinPE_BuildPath: Complete path to project folder.
TBWinPE_ConfigPath: Complete path to project's config folder.
TBWinPE_MountPath: Complete path to project's mount folder.
TBWinPE_Mode: Build mode (TBWinPE, TBWinRE).
TBWINPE_Reg_DEFAULT: Default user registry hive mount path.
TBWINPE_Reg_SOFTWARE: Software registry hive mount path.
TBWINPE_Reg_SYSTEM: System registry hive mount path.There are also build-specific environment variables available to BuildScript.cmd when using the TBWinPE.cmd or TBWinRE.cmd scripts. However, these are the same variables used by the script and not grouped together by name. Several are listed here:
tbpath: Complete path to project folder.
tbx64: Will be assigned 64 if creating a 64-bit build. Unassigned for 32-bit.
WinREArch: The architecture of the build being created (x86, x64). TBWinRE only.
buildarch: The architecture of the build being created (x86, AMD64). TBWinPE only.Whether using Builder, TBWinPE.cmd, or TBWinRE.cmd, you can check which variables are available and their assigned values by creating a simple BuildScript.cmd that runs the set and pause commands to display them. When you create the build it will list all environment variables and values and wait for a keypress to continue. For example:
:: Add script commands after this line
set
pause
Using the TBWinPE.cmd or TBWinRE.cmd Scripts
While the general procedure to add a custom program to the build using the TBWinPE.cmd and TBWinRE.cmd scripts is similar to using Builder, there are some notable differences from the instructions detailed above:
- Be aware that using Saved Settings for the scripts prevents the normal customization options and files from being used. If you need (or prefer) to use Saved Settings, you can edit the SavedSettings.ini file instead. For example, if Saved Settings is enabled and you edit TBLauncher.ini to add your custom program to the menu, those changes will not be included in the build. Instead, the saved TBLauncher.ini settings will be used. You would need to either disable Saved Settings or edit the TBLauncher settings in SavedSettings.ini.
- The TBLauncher.ini file to edit is in the project folder (e.g., C:\TBWinRE\TBLauncher.ini). The file in the config folder is used by Builder.
- The BuildScript.cmd file to create/edit is in the project folder (e.g., C:\TBWinRE\BuildScript.cmd). The file in the config folder is used by Builder.
Adding/Editing Registry Settings
You can add or change registry settings for the build by using the reg program in BuildScript.cmd. It's also possible to pause the build and manually add/edit the mounted registry hives using Registry Editor, but care must be taken to browse out of the mounted hives or close Registry Editor before continuing with the build or errors may result due to Windows preventing the hive files from unmounting.
When using TBWinPE/RE Builder it's recommended to either use the appropriate environment variable (e.g., %TBWINPE_Reg_SOFTWARE%) or disable the Use DISM API if supported option (General tab in Settings) to have access to the short names for the mounted hive files (these names are the same as those used by the TBWinPE.cmd and TBWinRE.cmd scripts).
The registry hives are loaded under HKEY_LOCAL_MACHINE (names shown here are when the DISM API is not used):
TBWINPE_SYSTEM: System hive
TBWINPE_SOFTWARE: Software hive
TBWINPE_DEFAULT: Default user hiveNote: When BuildScript.cmd is used with TBWinPE/RE Builder, the exported environment variables (e.g. %TBWINPE_Reg_SOFTWARE%) can be used regardless of whether or not the DISM API is used.
Example command adding an environment variable to the SYSTEM hive (DISM API not used). Command should all be on one line:
reg add "HKLM\TBWINPE_SYSTEM\ControlSet001\Control\Session Manager\Environment" /v MyEnvVar /t REG_SZ /d "ABC" /f
Same command as above except using the exported environment variable for the SYSTEM hive. Command should all be on one line:
reg add "HKLM\%TBWINPE_Reg_SYSTEM%\ControlSet001\Control\Session Manager\Environment" /v MyEnvVar /t REG_SZ /d "ABC" /f
Example commands adding several custom program variables to the SOFTWARE hive. Each command should be on one line:
reg add "HKLM\TBWINPE_SOFTWARE\CustomProgram" /v Title /t REG_SZ /d "WinPE Custom Program" /f
reg add "HKLM\TBWINPE_SOFTWARE\CustomProgram" /v "Cache Size" /t REG_DWORD /d 1024 /f
reg add "HKLM\TBWINPE_SOFTWARE\CustomProgram" /v "Default Path" /t REG_SZ /d "X:\Custom Files" /f
While configuring and testing the build you may find it helpful to pause BuildScript after running the reg commands so you can start Registry Editor and verify the additions/changes are being applied as desired. Remember to browse out of the mounted hives or close Registry Editor before continuing.
For details and examples on using reg run reg /? from a Command Prompt.