wiki.mbirth.de/software/autohotkey/u3helper/_posts/2009-09-12-tutorial.md

---
title: U3Helper Tutorial
language: en
alternatives:
  - language: de
    url: /software/autohotkey/u3helper/tutorial-de.html
layout: default
created: 2009-09-12 02:27:18 +0200
updated: 2009-09-12 09:29:27 +0200
toc: false
tags:
  - software
  - autohotkey
  - u3helper
---
[Diese Seite auf Deutsch.]({% post_url 2009-09-12-tutorial-de %})

You might want to read the [U3 Basics]({% post_url 2009-07-22-basics %}) first.

How to convert an application to U3
===================================

*Example Application:* [IVOS](http://ivos.comunx.com/)  
*Tools used:* [Sandboxie](http://www.sandboxie.com/), regedit, [Total Commander](http://www.ghisler.com/) (for file management and compression), notepad

Let's start with installing IVOS into the sandbox. Since it's using Microsoft's Installer, you have to first start it
inside the Sandbox.

Open *Sandboxie Control* (the yellow icon in your systray) and select menu *Function* → *Run Sandboxed* → *Windows
Installer Service*. Now search the setup_ivos.exe, right-click and select *Run sandboxed*. This should install IVOS
into the sandbox.

After installation, find your Sandboxes contents. In Sandboxie Control select menu *Function* → *Contents of sandbox*
→ *Explore contents*. An Explorer-window should pop up and you should see two directories `drive` and `user` as well as
two files `RegHive` (maybe only one of them is shown). Below `drive` is the changed(!) content of your local drives.
Every file a sandboxed program changes or writes goes there. All other files stay in their regular locations. So you
can easily see, what files the installation of IVOS added or changed.

Most interesting there is everything below `drive\C\Program Files\CommunX` - these are the main files of IVOS. There's
one `.xml` file, which might be modified by IVOS (`.xml`-files are often used for configuration data), but the other
files seem static (`.dll` and `.exe`).

Now create an empty directory somewhere and in there, create 3 other folders: `data`, `host` and `manifest`. The
`.xml`-file goes to the newly created `data` directory. Those 4 other files go to `host`.

So far for the file-part. Let's get to the tricky part: Finding out, which registry entries the program uses. 99,9% of
all programs use a branch like `HKEY_LOCAL_MACHINE\Software\<company>` or `HKEY_CURRENT_USER\Software\<company>`. Since
we installed it to the Sandbox, in Sandboxie Control, select menu *Function* → *Run Sandboxed* → *Any Program…* and
enter `regedit` into the field before clicking *OK*. Now regedit pops up and you can start browsing the registry.
Looking under `HKEY_LOCAL_MACHINE\Software`, there's nothing like `ComunX` or even `IVOS`. So let's take a look at
`HKEY_CURRENT_USER\Software` … and there it is: a key (registry-term for "folder") named `ComunX`.

Let's export this initial data for our U3-package: click once on the `ComunX`-key and select menu *File* → *Export*.
Now name the file `regdata1` and save it to the root folder of drive `C:`. Since we're inside the Sandbox, you'll find
that file by the *Explore contents* option in Sandboxie Control. It's in `\drive\C\regdata1.reg` . Copy that file to
our `data`-folder.

Now right-click the file (in the `data`-folder) and select *Edit*. Notepad will open with the registry file loaded.

Find the line:

    "apppath"="C:\\Program Files\\ComunX\\IVOS\\"

Now some U3-basics: The U3 LaunchPad stores some paths inside environment variables. This is, so that applications can
find their data although it is stored in different locations on different PCs. The most important are
`%U3_HOST_EXEC_PATH%` which contains the path to the directory, where **application** files go to and
`%U3_APP_DATA_PATH%` which is the directory on the U3 stick which contains **data** for that application.

So since U3 doesn't install the application to `C:\Program Files\ComunX\IVOS`, we have to insert the correct path
there, which is `%U3_HOST_EXEC_PATH%`. So change the line to:

    "apppath"="%U3_HOST_EXEC_PATH%\\"

Leave everything else as it is. Save the file.

Now copy `U3Helper.exe` to the `host`-directory. Also put the `U3Helper.ini` in there. I usually copy one from another
application and modify it. I already made all necessary modifications for IVOS. Take a look at the ini-file. First
comes the line `[U3Helper]` followed by a friendly name of the application and the executable file which should be
started. This is `Launcher.exe` for IVOS. The next interesting entry is that below `[RegBackup]`. As you can see this
is the registry path, we just found out. U3Helper imports these from the `regdata1.reg` file upon launch of the
application and exports them back to that file, when you "eject" the U3-stick. All U3-environment-variables found in
these registry entries get resolved to their actual data. So the `%U3_HOST_EXEC_PATH%\\` we added gets resolved to
`C:\Documents and Settings\<username>\Application Data\U3\Apps\{12345678-1234-1234-143123123}\Exec` - so that IVOS will
see the real path to itself. The first line below `[RegBackup]` gets saved to a file `regdata1.reg`, the second entry
(if there) to `regdata2.reg`, and so on.

Some lines further down you'll find `[DataToExecDir]` and the entry `ivos.xml`. This is the `.xml`-file we put into the
`data` (`%U3_APP_DATA_PATH%`) directory. And this line tells U3Helper to copy it over to the executables directory
(`%U3_HOST_EXEC_PATH%`) upon IVOS-launch and back to the `data`-directory on the stick, when ejecting.

These are all configuration lines in `U3Helper.ini`. The remaining lines are mostly default data and some explanations.

Now extract IVOS' application icon so that it can be shown in LaunchPad. You may use [Icon Sucker](http://www.portablefreeware.com/?id=420).
I for myself use a [plugin](http://www.totalcmd.net/plugring/iclview.html) for Total Commander. Put the Icon-file (.ico)
into the `manifest`-directory.

Save the attached (see below) `manifest.u3i` to that same directory. I already prepared it. Usually I'd copy a manifest
from another program and modify it accordingly. Most important is to generate a unique GUID (the long number in the
seconds line). There's a nice web tool to do so: [UUIDgen](http://www.famkruithof.net/uuid/uuidgen). Also, Microsoft
provides some tool somewhere and the U3 Manifest creator (from <http://www.u3.com>) also generates such GUIDs.

After changing the GUID (or UUID as it is sometimes called), fill in the rest of the data. The version number can be
found by right-clicking the `ivos.exe` and selecting *Properties*. There you have a *Version*-tab, which shows version
2.0.2.0 - so set the string in the manifest to it.

Set the webpage, developer name and description. And now, most important, set the file to launch the application. This
is the line with the appStart-command. You start IVOS with the `Launcher.exe` and this file will be in
`%U3_HOST_EXEC_PATH%` as we learned. So to start IVOS, the computer has to start `%U3_HOST_EXEC_PATH%\Launcher.exe`.
This is, what the line says.

The other lines can remain untouched. These are U3Helper-commands. Since we told U3Helper what to do through the
`U3Helper.ini` file, there's nothing left to change here. Oh, one single thing: the `minFreeSpace`-value should be the
storage space required on the U3-drive to install IVOS. Since the whole package gets smaller after compression, just
guess a value based upon the size of the `host`-directory.

I think we're ready now. Use a ZIP-utility (like WinZip) to compress the 3 folders `host`, `data` and `manifest` into a
ZIP file. Make sure, the ZIP file only has those 3 folders (and it's subfolders, if any). The directory structure
should look like this:

  * 📂 data (Directory)
    * 📄 ivos.xml (File)
    * 📄 regdata1.reg (File)
  * 📂 host (Directory)
    * 📄 ivos.chm (File)
    * 📄 Ivos.exe (File)
    * 📄 ivossapi.dll (File)
    * 📄 Launcher.exe (File)
    * 📄 U3Helper.exe (File)
    * 📄 U3Helper.ini (File)
  * 📂 manifest (Directory)
    * 📄 IVOS.ico (File)
    * 📄 manifest.u3i (File)

The only thing left to do is to rename the `.zip`-file to `.u3p`, so that you have a file `IVOS.u3p` or maybe
`IVOS_U3.u3p`. You should be able to install this to the U3 stick. I attached everything so that you may play around. I
hope that IVOS stores the registration info in the registry in that key we found out otherwise we have to look into it
to find out, how to retain the registration info between different PCs. And remember that IVOS only works, if the
*Speech API 5.1* is installed on the host PC.

  * **all config files:** [configfiles.zip]({{ site.url }}/assets/configfiles.zip)