Sprout App Installer Guide - HP Developer Portal Sprout... · Sprout App Installer Guide DATE: July...
Transcript of Sprout App Installer Guide - HP Developer Portal Sprout... · Sprout App Installer Guide DATE: July...
Sprout App Installer Guide
DATE: July 17, 2015
Sprout Developer Guide
2
Table of Contents
Introduction ................................................................................................................................................................. 3
Steps to Upload an App to Sprout Marketplace ............................................................................................. 3
Signing Digital Binaries .............................................................................................................................................. 6
Steps to Create an MSI (Microsoft Installer Package) ............................................................................................ 6
MSI Installation Using the Visual Studio Installer ............................................................................................... 6
Steps to Create an MSI Installer in Visual Studio 2013 ................................................................................. 7
Set up the Properties of Your Application Folder ........................................................................................ 10
Add the Key Value to the Registry ................................................................................................................. 11
Remove GUI Elements ......................................................................................................................................... 14
MSI Installation Using WiX Toolset ..................................................................................................................... 15
Design of a WiX (.wxs file) ............................................................................................................................... 16
Components of a WiX Source File .................................................................................................................. 16
Creating a WiX File ........................................................................................................................................... 17
Sample WiX File ............................................................................................................................................... 23
Sample WiX File for JavaScript Node-Webkit ............................................................................................... 25
Making MSI Installer Silent .................................................................................................................................. 27
Creating an MSI Installer Using Visual Studio and WiX ................................................................................ 27
Creating an MSI Installer Using WiX and the Command Prompt................................................................ 27
Test Your Results ................................................................................................................................................. 28
Troubleshooting ....................................................................................................................................................... 29
Troubleshooting a WiX Installer ......................................................................................................................... 29
Troubleshooting a Visual Studio Installer ......................................................................................................... 33
Sprout Developer Guide
3
Introduction
A Sprout app is a native operating system (OS) application taking advantage of Sprout hardware using the
HP Projective Computing Platform or the innovative multi-screen layout. An example of a “native” OS app
is a Windows® desktop application built to run on the Windows Operating System.
Marketplace Developers (an app developer or company registered with the Sprout Developer Portal) must
provide app metadata, icon files, and the Microsoft Installer Package (MSI) for their apps to appear in
Sprout Marketplace.
The following sections explain how to create an MSI installer, app metadata, and custom actions to include
as part of the MSI install or uninstall sequence to facilitate the Sprout Workspace app promotion
mechanism.
Steps to Upload an App to Sprout Marketplace
When you have finished building your app, perform the following steps to submit the app to HP:
Note: If you are building an app installer to work with Sprout Emulator, you need only follow steps 3 and 6, i.e. creating the market provisioning file for appinfo.xml and using it to create your MSI installer.
1. Digitally sign all your binaries for verifying trust of the app. See Signing Digital Binaries for more
information.
2. Create a “Sprout Marketplace Partner provisioning XML manifest file” in a text editor. Sprout
Marketplace encrypts this XML manifest file to create the “appinfo.hpspdat” file included as part of
your installer. See the sample file given here: Sample HP Sprout Marketplace Provisioning XML File
and the procedures given on page 5 for more information.
3. The table on the following page explains all the parameters you need to create your XML manifest file.
Sprout Developer Guide
4
XML Tag Name Description Details and Requirements
AppDisplayName Display name of the app
as it appears in Sprout
Marketplace.
This field is the name that users see in Sprout
Marketplace. Its maximum size is 20
characters.
AppDescription Short description of the
app.
This field is the description of your app that
users see in Sprout Marketplace.
DeveloperDisplayName Display name of app
developer
This field shows users the publisher,
developer, or company name that created the
app.
AppVersion Version number Use this format for the version number:
Major.Minor.Revision.Build
e.g: 1.0.1.0
AppLaunchPath Full Install path for the
app, including the
filename
Use environment variables in the path, e.g:
%ProgramFiles(x86)%. Place the executable
to launch in the root of the Install directory.
AppCategory App category in Sprout
Marketplace
Refer to the Sprout Marketplace Category List,
e.g. “Photography”, select one or more
categories in which to list your app, and then
tag the categories here.
AppID Reserve a unique app ID
to identify an app launch
point in Sprout
Workspace.
To generate an app ID, create an entry in the
Management Portal
(https://sprout.hp.com/developer/publish/).
Start with version 0.0.0.1 to create a pre-
approved entry. (The final version can be
updated after the app approval process.)
Create the app ID using the reverse DNS of
your company followed by the app name. For
example, if your app is SampleApp, and the
company’s DNS name is example.com, the
app ID should be com.example.sampleapp.
DeveloperID Reserve a Globally Unique
Identifier (GUID) to
identify an app developer
or publisher.
To generate a GUID, use Microsoft’s
“guidgen.exe” tool, which comes with Visual
Studio 2013 (Go to Tools > Create GUID).
Sample format: DB72D2EE-32DA-4742AA4E-
5A79F1761D83
Sprout Developer Guide
5
Sample HP Sprout Marketplace Provisioning XML File
<?xml version="1.0" encoding="utf-8"?>
<AppMetadata spec="1.0">
<AppDisplayName>Display Name for Your
App</AppDisplayName>
<AppDescription>Description for your app</AppDescription>
<DeveloperDisplayName>Your Company
Name</DeveloperDisplayName>
<AppVersion>1.0.0.0</AppVersion>
<AppLaunchPath>%ProgramFiles(x86)%\YourCompany\YourAppExecu
table.exe</AppLaunchPath>
<AppCategory>Your App Category (e.g.
Photography)</AppCategory>
<AppID>com.example.sampleapp</AppID>
<DeveloperID>DB72D2EE-32DA-4742-AA4E-
5A79F1761D83</DeveloperID>
</AppMetadata>
Note: If you are creating an appinfo.xml file for a JavaScript app, point the AppLaunchPath tag to nw.exe. To do this, follow the procedures given in Steps to Create an MSI (Microsoft Installer Package).
4. After authoring the Sprout Marketplace Partner provisioning XML manifest file, attach the file and
send it to Sprout App Review ([email protected]) for encryption. Remember to start the
Subject line of your email with “[Encrypt]”.
5. You will receive an email reply with the encrypted file “appinfo.hpspdat” attached. Use this file as
part of your MSI Installer package, as explained in Steps to Create an MSI (Microsoft Installer
Package).
6. Create an MSI Installer, making sure your installer is silent. Follow the procedures in sections MSI
Installation Using WiX Toolset and Making MSI Installer Silent of this guide to make your installer
silent.
7. Upload the MSI package to the HP Sprout Management Portal for review by the HP Sprout
Application Certification team.
Sprout Developer Guide
6
Signing Digital Binaries
You need to digitally sign your binaries for trust verification. Create a digital certificate and then sign all your
binaries before submitting them to Sprout Marketplace.
These links are helpful in creating digital signatures:
Introduction to Code Signing
Creating, Viewing and Managing Certificates
VeriSign Code Signing
Steps to Create an MSI (Microsoft Installer Package)
You can create your MSI installer using tools such as Microsoft Visual Studio (VS) installer, which comes as
an installer plugin for VS 2013. Microsoft Visual Studio Installer is a GUI-based tool for creating installers.
Alternatively, you can use the WiX Toolset available at http://wixtoolset.org. This xml-based tool is an
open-source, XML-based descriptive tool for creating installers for Windows.
MSI Installation Using the Visual Studio Installer
The Visual Studio installer provides an easy-to-use, GUI-based set up for creating the installer for your
app. You need Visual Studio 2013 and a plugin for the Installer extension located at:
https://visualstudiogallery.msdn.microsoft.com/9abe329c-9bba-44a1-be59-0fbf6151054d. These
procedures assume that you have installed Visual Studio 2013,
Close Visual Studio, download and install the plugin, and then re-open Visual Studio. Select File > New >
Project. In the New Projects window, select Templates > Other Project Types. The “Visual Studio Installer”
project type appears in that folder.
The installer requires that you have an icon. You can have other libraries and files as well as the
executable and icon. Assuming your app has an executable and an icon, create your directory structure
following these steps:
1. Create a directory structure within C:\Program Files (x86) for your installation files (executable,
libraries, images, etc.).
Sprout Developer Guide
7
2. Place the appinfo.hpspdat file in the main folder of your directory created in step 1.
3. Make your icons folder a subfolder under the main application folder, and place your icons there. Bw
sure the folder contains an icon named icons.png.
4. Add the registry value under HKLM\ SOFTWARE\Hewlett-Packard\HP.PC.SproutAppList\<Your App Id>
with the value pointing to the appinfo.hpspdat file contained in your main folder.
Steps to Create an MSI Installer in Visual Studio 2013
Follow these steps to create the set-up project for the installer and to build the MSI installer itself:
1. Inside your application in Visual Studio, go to File > New > Project
2. Either select Templates > Other Project Types > Visual Studio Installer or navigate to the Visual Studio
Installer if it appears outside Other Project Types in your Visual Studio instance.
3. Enter the name for your set-up project. In the illustration below, the set-up project is named
SampleAppSetup.
4. Select Location and choose either to create your set-up project under a new solution or to add it to an
existing solution. In the illustration below, we have added it to an existing solution.
5. Tap or click OK.
Sprout Developer Guide
8
6. As shown in the illustration below, you now see “File System on Target Machine”, which includes these
subfolders:
Application Folder
User’s Desktop
User’s Programs Menu
The Application Folder represents “C:\Program Files (x86)”.
Sprout Developer Guide
9
7. Create your directory structure using “Application Folder” as your root folder. In the example below, it
is set to C:\ProgramFiles (x86)\SampleApp.
8. Right-click on the Application Folder and add a folder named SampleApp.
9. Right-click on SampleApp, select Add File, and point to both your app executable (for this example,
SampleApp.exe) and appinfo.hpspdat.
10. Create a subfolder named “icons” inside SampleApp,
11. Right-click on the “icons” subfolder, select Add File, and add your icons to the folder in .png format.
For a JavaScript node-webkit, your application folder will looks something like the illustration below,
including required files:
Sprout Developer Guide
10
Set up the Properties of Your Application Folder
After completing the steps in Steps to Create an MSI Installer in Visual Studio 2013, right-click on the
Application Folder and select Properties. You should see something like this:
“[ProgramFilesFolder][Manufacturer]\[ProductName]”.
ProgramFilesFolder is a predefined property that points to “C:\Program Files (x86)”.
Manufacturer is your company name.
Product Name is what you would like to name your app folder.
For this example, we installed the app folder directly under “C:\ProgramFiles (x86)”, so it looks like
“C:\ProgramFiles (x86)\SampleApp”. You might want to set the Manufacturer name to your company
name (e.g. if your company is ABCompany, the Default Location is
“[ProgramFilesFolder][ABCompany]\[YourAppFolder]”). For this example, we set the Default Location to
“[ProgramFilesFolder][SampleApp]”
Note: Make sure that the Default Location for the AppInfo.xml that you submit to Sprout Marketplace
to get appinfo.hpspdat points to the same location as <AppLaunchPath>. For this example, the
default location is:
<AppLaunchPath>%ProgramFiles(x86)%\SampleApp\SampleApp.exe</AppLaunchPath>
Sprout Developer Guide
11
Add the Key Value to the Registry
The properties of the Application folder are now set. Next, generate a unique GUID for your app to be used
as the key value to the registry within SOFTWARE\Hewlett-Packard\HP.PC.SproutAppList; that displays the
app in Sprout Marketplace. To do this:
1. In Visual Studio, go to Solution Explorer and locate the Registry Editor icon at the top of the window.
Click that icon to open the Registry Editor in the main window:
Sprout Developer Guide
12
2. The GUID you created earlier will become a unique key that points to the encrypted appinfo.hpspdat
file. In the Illustration above:
The key is SOFTWARE\Hewlett-Packard\HP.PC.SproutAppList\74A3E7C1-F272-4EB4-9A43-
E4636B169
The value for the key is Value="%ProgramFiles(x86)%\SampleApp\appinfo.hpspdat. The following
steps will create the required key and value for your app.
3. Expand HKEY_LOCAL_MACHINE and right-click on Software.
4. Select New > Key. Name this key Hewlett-Packard.
5. Right-click on Hewlett-Packard.
6. Select New > Key and name this key HP.PC.SproutAppList.
7. Right-click on HP.PC.SproutAppList to create your final key. Set this key to the GUID for your app. In
this example, the GUID is 74A3E7C1-F272-4EB4-9A43-E4636B169EC6.
8. To add value to this key, right-click on your GUID (74A3E7C1-F272-4EB4-9A43-E4636B169EC6 in this
example) and then select New > String Value.
9. In the Properties Window, set the name to “metadata” and the value for the location of the
appinfo.hpspdat file. In this example, the value is
%ProgramFiles(x86)%\SampleApp\appinfo.hpspdat). You should see something like this in your
Registry Editor:
Sprout Developer Guide
13
10. Right-click on your Setup Project (SampleAppSetup in this example).
11. In the Properties window, set Target Platform to x64:
Note: The registry will not work unless the Target Platform is set to x64.
12. Build your project. A successful build allows you to see the MSI installer for your project
(SampleAppSetup.msi in the illustration above) in the Release or Debug folder, depending upon your
configuration settings.
13. Run your project and see if it works.
Sprout Developer Guide
14
Remove GUI Elements
A “silent installer” requires no user input. To make your installer run silently, you must remove the GUI
elements that VS adds to your installer. Follow these procedures to do this.
1. Right-click on your Setup project (for this example, SampleAppSetup) and then select View -> user
Interface. It should look like this:
2. In the Install folder, right-click on each GUI element (such as Welcome, Installation Folder, Progress
etc.) in the Start, Progress, and End folders and delete them.
Sprout Developer Guide
15
3. Repeat step 2 for the Administrative Install folder. When you have finished, it should look like the
illustration below:
4. Build the project again and run the MSI installer from the Debug or Release folder. You should see a
progress bar that appears and vanishes without requiring any user input. If so, your installation is
silent, as required.
MSI Installation Using WiX Toolset
WiX is an xml-based descriptive mechanism for creating the MSI Installer package. You can download and
install the WiX Toolset v3.9 from https://wix.codeplex.com/releases/view/610859. Once you have written
your WiX file, you must create an object file and then use linker to link your object file to create an .msi
installer file. Visual Studio can do this on your behalf as you build the project. You can also use WiX
command-line features to create an .msi file.
Sprout Developer Guide
16
Design of a WiX (.wxs file)
An installer installs the files (such as executable, icons, images, library files etc.) to a specified location on
your computer (i.e. for Windows: “C:\Program Files”).
WiX uses xml-based declarative language to describe what your installation will look like. That means you
use xml tags to specify how the directory structure will look, where installed files go, what is updated in
the registry, etc.
A WiX source file (.wxs file extension) uses three main elements to install files to the specified location:
File - a reference to an individual file (executable, dll, document etc.). Files must be contained in a
Component element, which is the smallest unit to be installed. For example, if you have a
component containing several files, and you install that component, all of its contained files are
installed. However, if that component is not installed, none of the files are installed. We do not
recommend creating components that contain a large number of files.
Component - Components are always contained in a Feature element, and can be contained in
more than one feature.
Feature - a set of components. If your installer has a graphical interface that allows you to select
which items to install, you are actually selecting features.
Components of a WiX Source File
The outermost tag in a WiX source file is <Wix> </Wix>. All other elements are contained within this tag.
<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
</ Wix >
A WiX element contains Product and Fragment tags. A WIX element can also contain two other tags—
Module and PatchCreation—but for building a MSI installer, you need at least a Product tag and
Fragments as building blocks.
Sprout Developer Guide
17
Product Tag
The Product tag represents the product to be installed and contains the features to be installed. For a
program written in C, the main function is equivalent to the Product tag. There can be only one Product
tag. The linker uses it to create a MSI file successfully.
Fragment
A Fragment is like an installer building block. The whole fragment can be either included in or excluded
from the product. Fragments are included in the Product tag using Ref elements.
Creating a WiX File
The steps in this procedure build a sample file. Substitute your application’s characteristics as needed.
1. Add the Product tag.
<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
<Product
Id="*"
Name="SampleAppSetup"
Language="1033"
Version="0.0.0.1"
Manufacturer="Sample Manufacturer Name"
UpgradeCode="f9098764-a6d1-41ed-8316-d2adac0c5ca9"> <!-- Insert your
own generated GUID -->
</Product>
</Wix>
2. Add Package, MajorUpgrade, MediaTemplate, and Feature tags to the Product tag.
The Package tag contains information about the installer package, such as InstallScope and
Platform. InstallScope is per machine. Make sure that Platform is set to x64.
The Feature tag contains the features to be installed. We will add features to this later.
Sprout Developer Guide
18
The WiX file not looks like this:
<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
<Product
Id="*"
Name="SampleAppSetup"
Language="1033"
Version="0.0.0.1"
Manufacturer="Sample Manufacturer Name"
UpgradeCode="f9098764-a6d1-41ed-8316-d2adac0c5ca9">
<Package
InstallerVersion="200"
Compressed="yes"
InstallScope="perMachine" Platform="x64"/>
<MajorUpgrade DowngradeErrorMessage="A newer version of [ProductName] is
already installed." />
<MediaTemplate EmbedCab="yes" />
<Feature Id="SampleFeatures" Title="Sample Feature Setup" Level="1">
<!--Features to be added later -->
</Feature>
</Product>
</Wix>
3. Start adding Fragments. Include fragments for required files—such as .exe, appinfo.hpspdat, dlls, doc,
etc.—for the icons, and for adding registry information about the app. Link these fragments inside
Product using the *Ref parameter.
First, add fragments for creating the directory structure under the program file that will contain your
files:
<Fragment>
<Directory Id="TARGETDIR" Name="SourceDir">
<Directory Id="ProgramFilesFolder">
<Directory Id="INSTALLFOLDER" Name="SampleApp">
<Directory Id="ICONSFOLDER" Name="icons"/>
</Directory>
</Directory>
</Directory>
</Fragment>
The WiX installer requires users to specify directories, starting from the root folder that contains
the tree structure for files such as .exe and icons. The root directory always has the ID
“TARGETDIR”, and is named “SourceDir”. The IDs are unique throughout the WiX file; “Name” is
what a user will see as a folder name.
Sprout Developer Guide
19
Inside “TARGETDIR”, the first directory has the predefined ID “ProgramFilesFolder”, i.e.
“C:\Program Files (x86)”. The other pre-defined System Folder Properties resolve to their path on
the Windows system. They can be found under https://msdn.microsoft.com/en-
us/library/aa370905(v=vs.85).aspx
The next directory under “C:\Program Files (x86)” is named SampleApp, and contains the
executable and dlls. A folder named “icons” resides under SampleApps. The “icons” folder
contains the icon for your app that appears in Sprout Marketplace. Keep the ID for the icons folder
as “ICONSFOLDER” so that Sprout Marketplace can recognize it.
The WiX file now looks like this.
<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
<Product
Id="*"
Name="SampleAppSetup"
Language="1033"
Version="0.0.0.1"
Manufacturer="Sample Manufacturer Name"
UpgradeCode="f9098764-a6d1-41ed-8316-d2adac0c5ca9">
<Package
InstallerVersion="200"
Compressed="yes"
InstallScope="perMachine" Platform="x64"/>
<MajorUpgrade DowngradeErrorMessage="A newer version of [ProductName] is
already installed." />
<MediaTemplate EmbedCab="yes" />
<Feature Id="SampleFeatures" Title="Sample Feature Setup" Level="1">
<!--Features to be added later -->
</Feature>
</Product>
<Fragment>
<Directory Id="TARGETDIR" Name="SourceDir">
<Directory Id="ProgramFilesFolder">
<Directory Id="INSTALLFOLDER" Name="SampleApp">
<Directory Id="ICONSFOLDER" Name="icons"/>
</Directory>
</Directory>
</Directory>
</Fragment>
</Wix>
Sprout Developer Guide
20
4. Next, add the Fragment tag for adding executable and appinfo.hpspdat files to the SampleApp folder.
<Fragment>
<ComponentGroup Id="ProductComponents" Directory="INSTALLFOLDER">
<Component Id="SampleAppExe" Guid="7EFFB651-2309-4786-9925-
0B423FBB85E5">
<File Source="SampleApp.exe" KeyPath="yes"/> <!-- Make sure path to
file Sample.exe is correct-->
</Component>
<Component Id="SampleAppDat" Guid="5334DF5E-5A82-44B8-A4C5-
9C2DD397C69D">
<File Source="appinfo.hpspdat" KeyPath="yes"/> <! -- Make sure path
to file appinfo.hpspdat is correct-->
</Component>
</ComponentGroup>
</Fragment>
The Fragment tag contains the ComponentGroup element that comprises the Components to be
installed. We have two components. One installs the executable for the app; the second installs the
encrypted appinfo.hpspdat file. The ComponentGroup has the Directory attribute set to
“INSTALLFOLDER”, which is the ID assigned to folder “C:\Program Files (x86)\SampleApp”, created
earlier as part of the Directory structure. Hence, components within “ProductComponents”
ComponentGroup are installed under “C:\Program Files (x86)\SampleApp”.
You might need to add other files, such as dlls. If you are making an installer for JavaScript node-
webkit, you must add some extra files to the app folder (See below).
Sprout Developer Guide
21
5. Link this Fragment to the Product. Notice the Feature tag inside the Product referring to the newly
created ComponentGroup in the WiX file built so far.
<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
<Product
Id="*"
Name="SampleAppSetup"
Language="1033"
Version="0.0.0.1"
Manufacturer="Sample Manufacturer Name"
UpgradeCode="f9098764-a6d1-41ed-8316-d2adac0c5ca9">
<Package
InstallerVersion="200"
Compressed="yes"
InstallScope="perMachine" Platform="x64"/>
<MajorUpgrade DowngradeErrorMessage="A newer version of [ProductName] is
already installed." />
<MediaTemplate EmbedCab="yes" />
<Feature Id="SampleFeatures" Title="Sample Feature Setup" Level="1">
<ComponentGroupRef Id = "ProductComponents" />
</Feature>
</Product>
<Fragment>
<Directory Id="TARGETDIR" Name="SourceDir">
<Directory Id="ProgramFilesFolder">
<Directory Id="INSTALLFOLDER" Name="SampleApp">
<Directory Id="ICONSFOLDER" Name="icons"/>
</Directory>
</Directory>
</Directory>
</Fragment>
<!-- First Feature -->
<Fragment>
<ComponentGroup Id="ProductComponents" Directory="INSTALLFOLDER">
<Component Id="SampleAppExe" Guid="7EFFB651-2309-4786-9925-
0B423FBB85E5">
<File Source="SampleApp.exe" KeyPath="yes"/>
<!-- Make sure path to file Sample.exe is correct-->
</Component>
<Component Id="SampleAppDat" Guid="5334DF5E-5A82-44B8-A4C5-
9C2DD397C69D">
<File Source="appinfo.hpspdat" KeyPath="yes"/>
Sprout Developer Guide
22
<!-- Make sure path to file appinfo.hpspdat is correct-->
</Component>
<!— Next component adds other files like your dlls etc. or Files
required by JavaScript node-webkit. We Set KeyPath to yes in the component
that applies to all files -->
<Component Id="SampleAppDat" Guid="FDFB5B4E-81C5-41BD-B3E6-
5C556072D387" KeyPath="yes" >
<!—Add here all the files e.g. files you need to add for
JavaScript node-webkit-->
</Component>
</ComponentGroup>
</Fragment>
</Wix>
6. Add the Fragment for the icon file and for adding registry information. We will refer to the directory to
install again through the Directory attribute. The registry information makes your app appear in
Sprout Marketplace.
<Fragment>
<Component Id="SampleIcon" Guid="BCD5A097-6B30-4CA9-8CDE-89451C25A9C3"
Directory="ICONSFOLDER" >
<File Source="icon.png" KeyPath="yes"/> <!-- The name of the icon
folder has to be icon.png -->
</Component>
</Fragment>
<Fragment>
<DirectoryRef Id="TARGETDIR">
<Component Id="RegistrySub”" Guid="3EE2DD7F-8A79-4C52-BBC7-
D72454C306FC" KeyPath="yes" Win64="yes">
<!-- make sure Win64 is set to yes -->
<RegistryKey Root="HKLM" Key="SOFTWARE\Hewlett-
Packard\HP.PC.SproutAppList\74A3E7C1-F272-4EB4-9A43-E4636B169EC6"
ForceDeleteOnUninstall="yes">
<RegistryValue Type="string”" Name="metadata"
Value="%ProgramFiles(x86)%\SampleApp\appinfo.hpspdat"/>
</RegistryKey>
</Component>
</DirectoryRef>
</Fragment>
Sprout Developer Guide
23
In the Fragment for installing icons, name your icon file icon.png. The dimensions for the Icon are:
600 pixels in width x 600 pixels in height.
For the Fragment adding registry information, make sure the Win64 parameter is set to yes.
Otherwise, it will not be added to the registry. Inside the RegistryValue, point to the encrypted
appinfo.hpspdat file.
Make sure you include attribute ForceDeleteOnUninstall="yes" in the RegistryKey to remove the
Registry subkey (GUID) from the Registry hive automatically.
Link new Fragments to the product. The final WiX file will look like the example shown in Sample
WiX File. Remember to create your own GUIDs and set them. You can use Visual Studio or any
other tool to create your GUID.
Sample WiX File
This is the final sample WiX file, which you can populate with your app’s installation information (files,
images etc.):
<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
<Product
Id="*"
Name="SampleAppSetup"
Language="1033"
Version="0.0.0.1"
Manufacturer="Sample Manufacturer Name"
UpgradeCode="1342cf48-5b83-4e25-8461-b03dc3105fce"
<Package
InstallerVersion="200"
Compressed="yes"
InstallScope="perMachine”" Platform="x64"/>
<MajorUpgrade DowngradeErrorMessage="A newer version of [ProductName] is already
installed." />
<MediaTemplate EmbedCab="yes" />
<Feature Id="SampleFeatures" Title="Sample Feature Setup" Level="1">
<ComponentGroupRef Id = "ProductComponents" />
</Feature>
<ComponentRef Id="RegistrySub"/>
<ComponentRef Id=" SampleIcon "/>
</Feature>
</Product>
<Fragment>
<Directory Id="TARGETDIR" Name="SourceDir">
<Directory Id="ProgramFilesFolder">
<Directory Id="INSTALLFOLDER" Name="SampleApp">
Sprout Developer Guide
24
<Directory Id="ICONSFOLDER" Name="icons"/>
</Directory>
</Directory>
</Directory>
</Fragment>
<!-- First Feature -->
<Fragment>
<ComponentGroup Id="ProductComponents" Directory="INSTALLFOLDER">
<Component Id="SampleAppExe" Guid="7EFFB651-2309-4786-9925-0B423FBB85E5">
<File Source="SampleApp.exe" KeyPath="yes"/>
<!-- Make sure path to file Sample.exe is correct-->
</Component>
<Component Id="SampleAppDat" Guid="5334DF5E-5A82-44B8-A4C5-9C2DD397C69D">
<File Source="appinfo.hpspdat" KeyPath="yes"/>
<!-- Make sure path to file appinfo.hpspdat is correct-->
</Component>
<!— Next component adds other files like your dlls etc. or Files
required by JavaScript node-webkit. We Set KeyPath to yes in the component
that applies to all files -->
<Component Id="SampleAppFiles" Guid="FDFB5B4E-81C5-41BD-B3E6-
5C556072D387" KeyPath="yes" >
<!—Add here all the files e.g. files you need to add for
JavaScript node-webkit-->
</Component>
</ComponentGroup>
</Fragment>
<Fragment>
<Component Id="SampleIcon" Guid="BCD5A097-6B30-4CA9-8CDE-89451C25A9C3"
Directory="ICONSFOLDER" >
<File Source="icon.png" KeyPath="yes"/>
<!-- The name of the icon folder has to be icon.png -->
</Component>
</Fragment>
<Fragment>
<DirectoryRef Id="TARGETDIR">
<Component Id="RegistrySub”" Guid="3EE2DD7F-8A79-4C52-BBC7-D72454C306FC"
KeyPath="yes" Win64="yes">
<!-- make sure Win64 is set to yes and create your own GUID for
RegistryKey-->
Sprout Developer Guide
25
<RegistryKey Root="HKLM" Key="SOFTWARE\Hewlett-
Packard\HP.PC.SproutAppList\74A3E7C1-F272-4EB4-9A43-E4636B169EC6"
ForceDeleteOnUninstall="yes">
<RegistryValue Type="string”" Name="metadata"
Value="%ProgramFiles(x86)%\SampleApp\appinfo.hpspdat"/>
</RegistryKey>
</Component>
</DirectoryRef>
</Fragment>
</Wix>
Sample WiX File for JavaScript Node-Webkit
This is the final sample WiX file that you use to create the working installer for a JavaScript node-webkit:
<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
<Product
Id="*"
Name="SampleAppSetup"
Language="1033"
Version="0.0.0.1"
Manufacturer="Sample Manufacturer Name"
UpgradeCode="1342cf48-5b83-4e25-8461-b03dc3105fce"
<Package
InstallerVersion="200"
Compressed="yes"
InstallScope="perMachine”" Platform="x64"/>
<MajorUpgrade DowngradeErrorMessage="A newer version of [ProductName] is already
installed." />
<MediaTemplate EmbedCab="yes" />
<Feature Id="SampleFeatures" Title="Sample Feature Setup" Level="1">
<ComponentGroupRef Id = "ProductComponents" />
</Feature>
<ComponentRef Id="RegistrySub"/>
<ComponentRef Id=" SampleIcon "/>
</Feature>
</Product>
<Fragment>
<Directory Id="TARGETDIR" Name="SourceDir">
<Directory Id="ProgramFilesFolder">
<Directory Id="INSTALLFOLDER" Name="SampleApp">
<Directory Id="ICONSFOLDER" Name="icons"/>
</Directory>
</Directory>
</Directory>
</Fragment>
<!-- First Feature -->
<Fragment>
<ComponentGroup Id="ProductComponents" Directory="INSTALLFOLDER">
Sprout Developer Guide
26
<Component Id="SampleAppExe" Guid="7EFFB651-2309-4786-9925-0B423FBB85E5">
<File Source="App.exe" KeyPath="yes"/>
<!-- Make sure path to file Sample.exe is correct-->
</Component>
<Component Id="SampleAppDat" Guid="5334DF5E-5A82-44B8-A4C5-9C2DD397C69D">
<File Source="appinfo.hpspdat" KeyPath="yes"/>
<!-- Make sure path to file appinfo.hpspdat is correct-->
</Component>
<!— Following component adds Files required by JavaScript node-webkit. We
Set KeyPath to yes in the component that applies to all files. If there are any
other files that goes with your app like mat.html or any other JavaScript too -
->
<Component Id="JSNodeWFiles" Guid="FDFB5B4E-81C5-41BD-B3E6-5C556072D387"
KeyPath="yes" >
<File Source="icudtl.dat" />
<File Source="nw.exe" />
<File Source="nw.pak"/>
</Component>
</ComponentGroup>
</Fragment>
<Fragment>
<Component Id="SampleIcon" Guid="BCD5A097-6B30-4CA9-8CDE-89451C25A9C3"
Directory="ICONSFOLDER" >
<File Source="icon.png" KeyPath="yes"/>
<!-- The name of the icon folder has to be icon.png -->
</Component>
</Fragment>
<Fragment>
<DirectoryRef Id="TARGETDIR">
<Component Id="RegistrySub”" Guid="3EE2DD7F-8A79-4C52-BBC7-D72454C306FC"
KeyPath="yes" Win64="yes">
<!-- make sure Win64 is set to yes and create your own GUID for RegistryKey-->
<RegistryKey Root="HKLM" Key="SOFTWARE\Hewlett-
Packard\HP.PC.SproutAppList\74A3E7C1-F272-4EB4-9A43-E4636B169EC6"
ForceDeleteOnUninstall="yes">
<RegistryValue Type="string”" Name="metadata"
Value="%ProgramFiles(x86)%\SampleApp\appinfo.hpspdat"/>
</RegistryKey>
</Component>
</DirectoryRef>
</Fragment>
</Wix>
Sprout Developer Guide
27
Making MSI Installer Silent
Your installer must be silent. To make your installer silent while using WiX, do not include any UI elements.
The WiX source file created earlier in this guide has no UI elements, so it is already silent. Run your
installer. If it requires no user input, it is silent.
Creating an MSI Installer Using Visual Studio and WiX
To create an MSI installer, you need the WiX plugin for Visual Studio (VS) that was automatically added to
VS when you installed WiX. If you do not see it, you can download and install it online. Once completed,
follow the steps below:
1. In VS, select File > New > Project.
2. In the New Project window, located on the left side under Templates, find and select “Windows
Installer XML”.
3. Select Setup Project. Enter the name of your project and click OK.
4. In your project, find the Product.wxs file. Update this file with your own .wxs content for the installer.
5. Build and run the project in Debug or Release configuration mode, as intended.
6. Find the installer file in the Debug or Release folder, as configured in step 5.
Creating an MSI Installer Using WiX and the Command Prompt
To create an MSI installer from the command prompt, add the path to the WiX installer
executable in your PATH variable. To do this:
1. Right-click My Computer. The Properties window opens.
2. Click Advanced System Settings.
3. Go to the Advanced tab and click the Environment Variables button.
4. Under System Variables, click on “PATH”. At the end of the Variable Value, after the semi-
colon (;), add “C:\Program Files (x86)\WiX Toolset v3.9\bin;”.
Sprout Developer Guide
28
Generate the MSI Installer File
Follow these steps to generate the MSI installer file.
1. Open the command prompt from the Start menu.
2. Change directory (CD) into the folder containing your WiX file (.wxs). Make sure the paths to
files (exe, encrypted appinfo.hpspdat, icon, etc.) are correct.
3. Run “candle.exe Product.wxs”. This creates the object file with the .wixobj extension for your
product file.
4. Run “light.exe Product.wixobj” to link your object file; create the final MSI installer.
Test Your Results
Once you have successfully created the MSI Installer, you can test it with Sprout, if you have one, or use
Sprout Emulator for testing, if you do not have a Sprout. Follow these steps to test your app.
1. Double-click the MSI Installer. It should run showing only a progress bar, without requiring any user
input.
2. Select Control Panel hhh> Programs and Features. Click on Date Modified to make sure the most
recent installations appear at the top. Your app should be the most recent installation. In the example
above, the app name would be SampleAppSetup.
3. Go to “C:\Program Files (x86)” and locate the folder containing your app as you named it. In the
example above, it is named SampleApp. If you added your company’s name as the Manufacturer, the
folder under “C:\Program Files (x86)” should be named “Your Company’s Name\Your App Name”.
4. Look inside the folder “C:\Program Files (x86)\Your Company’s Name\Your App Name”. (In our
example, the folder is named “C:\Program Files (x86)\SampleApp”). You should see the executable for
your app and any other files (like dlls and docs) that you added. Additionally, you should see a folder
named “icons” containing the icon.png file for your app.
5. Search for regedit.exe using the Windows App Search bar, and then open it.
6. Inside Regedit, go to HKEY_LOCAL_MACHINE -> SOFTWARE -> Hewlett-Packard ->
HP.PC.SproutAppList, where you should see your app’s GUID inside the Registry Key that appears in
the list.
Sprout Developer Guide
29
7. Click on the Registry Key. You should see the registry value in the list with the name you set. The Data
field should display the path to your appinfo.hpspdat file.
In our example, the registry value is “metadata”.
8. Run the Sprout Workspace on your Sprout machine, if you have one, or on Sprout Emulator. Look for
your app’s icon in the Applications pane.
9. Drag your app to the touch mat (Sprout) or second monitor (Emulator) and run it. It should run well.
Troubleshooting
If you do not see the expected result, or your app does not work properly after installation, make sure you
completed each step correctly. This section explains some of the scenarios you might run into and
provides troubleshooting tips under the respective headings for the WiX and Visual Studio Installers.
Troubleshooting a WiX Installer
Problem Your app’s GUID does not appear in HKEY_LOCAL_MACHINE > SOFTWARE > Hewlett-Packard > HP.PC.SproutList, or you cannot see your app in Sprout Marketplace
Solution Make sure the Key attribute in the RegistryKey is set to “SOFTWARE\Hewlett-Packard\HP.PC.SproutAppList\GUID generated by you”, and that the Component that contains it has the Win64 property set to “yes”.
Make sure the Package element (inside the Product element) has the Platform attribute set to “x64”.
Sprout Developer Guide
30
Problem You cannot see the directory for your app or your company containing app.
Solution For example, if your company’s name is ABCompany, and your app folder is SampleApp, make sure the first directory shown in the Directory element with ID “ProgramFilesFolder” (i.e. C:\Program Files (x86)) includes your company’s name. That directory, in turn, should include the directory containing the folder with your app’s name.
Make sure that the ID for each element is unique. It should look something like this:
<Fragment>
<Directory Id="TARGETDIR" Name="SourceDir">
<Directory Id="ProgramFilesFolder">
<Directory Id="INSTALLFOLDER" Name="YourCompanyName">
<Directory Id="APPFOLDER" Name="SampleApp">
<Directory Id="ICONSFOLDER" Name="icons"/>
</Directory>
</Directory>
</Directory>
</Directory>
</Fragment>
Make sure that you have installed the files inside INSTALLFOLDER:
<Fragment>
<ComponentGroup Id="ProductComponents"
Directory="INSTALLFOLDER">
<!—Files to be installed inside the INSTALLFOLDER-->
</ComponentGroup>
</Fragment>
Make sure the app is referenced inside the Product as a feature to be installed.
<!—Inside Product-->
<Feature Id="SampleFeatures" Title="Sample Feature Setup"
Level="1">
<ComponentGroupRef Id = "ProductComponents" />
</Feature>
Sprout Developer Guide
31
Problem Your app is installed, but its icon does not appear in Sprout Marketplace
Solution Make sure your icons folder is specified in INSTALLFOLDER or APPFOLDER, whichever contains the executable. Put the icons folder at the same level as your app’s executable.
<Fragment>
<Directory Id="TARGETDIR" Name="SourceDir">
<Directory Id="ProgramFilesFolder">
<Directory Id="INSTALLFOLDER" Name="YourCompanyName">
<Directory Id="APPFOLDER" Name="SampleApp">
<Directory Id="ICONSFOLDER" Name="icons"/>
</Directory>
</Directory>
</Directory>
</Directory>
</Fragment>
Make sure that you are installing the icons file inside the icons directory. To do this, check that the Directory attribute for the Component containing the icon file is set to “ICONSFOLDER”.
<Fragment>
<Component Id="SampleIcon" Guid="BCD5A097-6B30-4CA9-8CDE-
89451C25A9C3" Directory="ICONSFOLDER" >
<!-- The name of the icon folder has to be icon.png -->
<File Source="icon.png" KeyPath="yes"/>
</Component>
</Fragment>
Sprout Developer Guide
32
Problem Clicking on the icon does nothing. Your app does not start or run at all.
Solution Make sure all paths pointing to your app executable are correct. Check the appinfo.xml that you sent to HP for encryption. The encrypted file
appinfohpsp.dat points to the correct location of your executable. Make sure the AppLaunchPath tag points to the folder that contains the executable. To verify this, tally against the directory structure created in the WiX file, as shown below:
<?xml version="1.0" encoding="utf-8"?>
<AppMetadata spec="1.0">
<AppLaunchPath>%ProgramFiles(x86)%\YourCompanyName\YourAppFol
der\YourAppExecutable.exe</AppLaunchPath>
</AppMetadata>
Check that the path
“%ProgramFiles(x86)%\YourCompanyName\YourAppFolder\” in above
file is created inside WiX file inside the first fragment.
<Fragment>
<Directory Id="TARGETDIR" Name="SourceDir">
<Directory Id="ProgramFilesFolder"> <!—It is
%ProgramFiles(x86)% -->
<Directory Id="INSTALLFOLDER" Name="YourCompanyName">
<Directory Id="APPFOLDER" Name="YourAppFolder">
<!—Executable will be contained inside this folder -->
<Directory Id="ICONSFOLDER" Name="icons"/>
</Directory>
</Directory>
</Directory>
</Directory>
</Fragment>
As a final step, make sure that you add your executable file to be installed when creating the WiX file inside that Fragment. Verify that you have given the correct path to the executable on this system and that you are creating the installer using WiX.
<Fragment>
<ComponentGroup Id="ProductComponents" Directory="INSTALLFOLDER">
<Component Id="SampleAppExe" Guid="7EFFB651-2309-4786-9925-
0B423FBB85E5">
<!-- Make sure path to file YourApp.exe is correct on your system-->
<File Source="YourApp.exe" KeyPath="yes"/>
</Component>
</ComponentGroup>
</Fragment>
Sprout Developer Guide
33
Troubleshooting a Visual Studio Installer
Problem Your App’s GUID does not appear in HKEY_LOCAL_MACHINE > SOFTWARE > Hewlett-Packard > HP.PC.SproutList, or you cannot see your app in Sprout Marketplace.
Solution Make sure the Key attribute in the RegistryKey is set to “SOFTWARE\Hewlett-Packard\HP.PC.SproutAppList\your generated GUID”. Also make sure that the target platform is set to x64. See the images below to make sure both are correct.
Problem You cannot see the directory for your app or your company containing app.
Solution Make sure you have created the directory structure under “C:\Program Files (x86)”, as shown below:
Make sure that the default location for the Application folder is within “C:\Program Files
(x86)”, i.e. identified by its property name “ProgramFilesFolder”:
Sprout Developer Guide
34
Problem Your app is installed, but the icon does not appear in the Sprout Marketplace pane.
Solution Make sure you have created the icons folder within the path to your application folder, It should be something like “C:\Program Files (x86)\Your App Folder” or “C:\Program Files (x86)\Your Company Name\Your App Folder”.
Make sure there is an image named “icon.png” inside the icons folder, as shown below:
Problem Clicking on the icon does nothing. Your app does not start or run at all.
Solution Make sure all paths pointing to your app executable are correct. One is in the appinfo.xml that you sent to HP for encryption. The encrypted
appinfohpsp.dat file must point to the correct location of your executable.
Make sure the AppLaunchPath tag points to the correct folder that contains the executable, as shown in the xml below:
<?xml version="1.0" encoding="utf-8"?>
<AppMetadata spec="1.0">
<AppLaunchPath>%ProgramFiles(x86)%\YourCompanyName\YourAppFol
der\YourAppExecutable.exe</AppLaunchPath>
</AppMetadata>
Additionally, make sure that the path defined in AppLaunchPath, above, is the one you created under the directory structure. See the illustration below:
Sprout Developer Guide
35
Solution (continued)
Confirm that the Application Folder’s default location is under “C:\Program Files (x86)\SampleApp”. Note that in this example we placed SampleApp (Your app folder) directly under “C:\Program Files (x86)”. The path could include your company name, as defined in the AppLaunchPath above: “ProgramFiles(x86)%\YourCompanyName\YourAppFolder\YourAppExecutable.exe”. In that case, make sure you have created the correct directory structure (i.e. a folder named after your company under C:\Program Files that contains your app folder):