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


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.


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

https://sprout.hp.com/developer/publish/


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.


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.).

https://msdn.microsoft.com/en-us/library/ie/ms537361(v=vs.85).aspx

https://msdn.microsoft.com/en-us/library/ie/aa379872(v=vs.85).aspx

http://www.verisign.com/code-signing-sem/

http://wixtoolset.org/

https://visualstudiogallery.msdn.microsoft.com/9abe329c-9bba-44a1-be59-0fbf6151054d


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.


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)”.


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:


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>


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:


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:


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.


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.


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.

https://wix.codeplex.com/releases/view/610859


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.

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.


<Product

Id="*"

Name="SampleAppSetup"

Language="1033"

Version="0.0.0.1"

Manufacturer="Sample Manufacturer Name"

UpgradeCode="f9098764-a6d1-41ed-8316-d2adac0c5ca9"> 

</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.

18

The WiX file not looks like this:


<Product

Id="*"


Language="1033"

Version="0.0.0.1"


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">



</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.

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.


<Product

Id="*"


Language="1033"

Version="0.0.0.1"



<Package


Compressed="yes"








</Feature>

</Product>

<Fragment>





</Directory>

</Directory>

</Directory>

</Fragment>

</Wix>

https://msdn.microsoft.com/en-us/library/aa370905(v=vs.85).aspx

https://msdn.microsoft.com/en-us/library/aa370905(v=vs.85).aspx

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"/> 

</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).

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.


<Product

Id="*"


Language="1033"

Version="0.0.0.1"



<Package


Compressed="yes"






<ComponentGroupRef Id = "ProductComponents" />

</Feature>

</Product>

<Fragment>





</Directory>

</Directory>

</Directory>

</Fragment>



<Fragment>



0B423FBB85E5">

<File Source="SampleApp.exe" KeyPath="yes"/>



</Component>

<Component Id="SampleAppDat" Guid="5334DF5E-5A82-44B8-A4C5-

9C2DD397C69D">

<File Source="appinfo.hpspdat" KeyPath="yes"/>

22



</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"/> 

</Component>

</Fragment>

<Fragment>

<DirectoryRef Id="TARGETDIR">

<Component Id="RegistrySub”" Guid="3EE2DD7F-8A79-4C52-BBC7-

D72454C306FC" KeyPath="yes" Win64="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>


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.):


<Product

Id="*"


Language="1033"

Version="0.0.0.1"


UpgradeCode="1342cf48-5b83-4e25-8461-b03dc3105fce"

<Package


Compressed="yes"

InstallScope="perMachine”" Platform="x64"/>

<MajorUpgrade DowngradeErrorMessage="A newer version of [ProductName] is already

installed." />




</Feature>

<ComponentRef Id="RegistrySub"/>

<ComponentRef Id=" SampleIcon "/>

</Feature>

</Product>

<Fragment>




24


</Directory>

</Directory>

</Directory>

</Fragment>


<Fragment>


<Component Id="SampleAppExe" Guid="7EFFB651-2309-4786-9925-0B423FBB85E5">

<File Source="SampleApp.exe" KeyPath="yes"/>


</Component>

<Component Id="SampleAppDat" Guid="5334DF5E-5A82-44B8-A4C5-9C2DD397C69D">



</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>



<File Source="icon.png" KeyPath="yes"/>



</Component>

</Fragment>

<Fragment>


<Component Id="RegistrySub”" Guid="3EE2DD7F-8A79-4C52-BBC7-D72454C306FC"

KeyPath="yes" Win64="yes">


25






</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:


<Product

Id="*"


Language="1033"

Version="0.0.0.1"


UpgradeCode="1342cf48-5b83-4e25-8461-b03dc3105fce"

<Package


Compressed="yes"

InstallScope="perMachine”" Platform="x64"/>

<MajorUpgrade DowngradeErrorMessage="A newer version of [ProductName] is already

installed." />




</Feature>

<ComponentRef Id="RegistrySub"/>

<ComponentRef Id=" SampleIcon "/>

</Feature>

</Product>

<Fragment>





</Directory>

</Directory>

</Directory>

</Fragment>


<Fragment>


26

<Component Id="SampleAppExe" Guid="7EFFB651-2309-4786-9925-0B423FBB85E5">

<File Source="App.exe" KeyPath="yes"/>


</Component>

<Component Id="SampleAppDat" Guid="5334DF5E-5A82-44B8-A4C5-9C2DD397C69D">



</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>

</Fragment>

<Fragment>


<Component Id="RegistrySub”" Guid="3EE2DD7F-8A79-4C52-BBC7-D72454C306FC"

KeyPath="yes" Win64="yes">








</RegistryKey>

</Component>

</DirectoryRef>

</Fragment>

</Wix>


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;”.


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.


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”.


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="INSTALLFOLDER" Name="YourCompanyName">

<Directory Id="APPFOLDER" Name="SampleApp">


</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">


</Feature>


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="APPFOLDER" Name="SampleApp">


</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" >



</Component>

</Fragment>

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:



<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="ProgramFilesFolder"> <!—It is

%ProgramFiles(x86)% -->


<Directory Id="APPFOLDER" Name="YourAppFolder">

<!—Executable will be contained inside this folder -->


</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>



0B423FBB85E5">



<File Source="YourApp.exe" KeyPath="yes"/>

</Component>

</ComponentGroup>

</Fragment>


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”:


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:



<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:


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):

Sprout App Installer Guide - HP Developer Portal Sprout... · Sprout App Installer Guide DATE: July...

Documents

Transcript of Sprout App Installer Guide - HP Developer Portal Sprout... · Sprout App Installer Guide DATE: July...