the Fiddler's picture

[OpenTK] Create MSI packages for Windows (help wanted)

Project:The Open Toolkit library
Version:1.x-dev
Component:Miscellaneous
Category:task
Priority:minor
Assigned:Unassigned
Status:open
Description

While zip releases are good enough in most cases, it would be beneficial to provide msi packages for Windows users.

Advantages:

  1. we can install OpenTK into the GAC
  2. we can provide project templates to simplify development with OpenTK
  3. we can (potentially) integrate OpenTK documentation with the VS help viewer or MonoDevelop MonoDoc

If possible, package creation should be integrated into the build process.

WIX is an open-source tool that can create such packages. Anyone willing to help with this?


Comments

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.
charles's picture

#1

Hi there,
I'd be interested in giving this a go if you like.

Note: I don't have the full version of VisualStudio (2008 or 2005) but I think SharpDevelop WIX support is compatible with VisualStudio but I will probably need someone else to double check the solution still compiles and the installer works as expected.

Also if I'm to do this I'll need the following points clarified:
1. Do we want to install over existing installations (i.e. update), for example 1.0.0 replaces the 0.9.4 installation? Another alternative might be to install over existing installations with the same major version, in this case 1.0.1 would update 1.0.0 but 1.1 would create a side by side installation (so you could use either 1.1 or 1.0). This would also have the benefit of being able to install a beta version and a release version concurrently.
2. Would I be correct in assuming this is for the version 1.0 branch and thus work in 1.0 branch and merge the changes into trunk when done?
3. If I'm to do this then it probably make sense for me to handle the (visual studio templates as well) though I only have the express edition (I might make some templates for SharpDevelop too).
4. As you mention it might be worth integrating the OpenTk documentation with VS help viewer but for now I think I'll just focus on getting the installer up and running.

charles's picture

#2

OK I've been doing a little more investigations and thought I'd test this using MSBuild instead of SharpDevelop that way it should defiantly work with OpenTKs build process as described here "Automatic building of OpenTK trunk". Also I'd assume that I'd need to modify the Build project so it generates the new setup project (more specifically OpenTK.Prebuild.xml)?

charles's picture

#3

I've made some progress and have attached a patch that adds a new Setup project to OpenTK. I did try to integrate it into OpenTK's solution but failed as Prebuild doesn't appear to support Wix projects, this just means for now we'll have to build the installer separately.

Features:

  1. Checks for .net 2.0
  2. Supports concurrent major versions (but see note 3 bellow)
  3. Supports registering the assemblies with the GAC (should this be optional?)
  4. Creates a nice little context menu with a web link and shortcut to the Examples app.

Todo:

  1. Add option to install source, but first what's your opinion on this as this will increase the file size and isn't straightforward as I'd probably need to put together a small script to ensure all files are included as doing this by hand is too error prone. Perhaps a separate zipped file would be sufficient?
  2. Documentation, I think putting together a script that built the wiki and API would be the best approach, again any thoughts?
  3. Improve version handling, The current version scheme OpenTK appears to use is one where we work towards a major version (i.e. 0.9.0, 0.9.1, 0.9.2, ... 1.0). Rather than starting at a major and appending a build number (i.e. 1.0.). If we could use such a scheme this would make handling versioning a lot easier since it guaranties the major version number won't change between alpha\beta and RTM (final) releases. This seems to work well for SharpDevelop if that helps.
  4. Support for Visual studio, Mono Develop, and SharpDevelop templates.
  5. Consider moving the Examples to a new Examples folder at the root level like Tao does but this might require having a copy of the OpenTK assemblies there as well unless the Examples project uses the ones installed into GAC. Anyway this probably isn't to much of a problem.
AttachmentSize
Setup support.patch31.77 KB
the Fiddler's picture

#4

Status:open» in progress

Many thanks! I'm away on a trip to Switzerland, so I cannot test this right now, but I will do so as soon as I get back. :)

I think the best way to automate this is to add a new target to Build.exe ("msi") that bootstraps everything (point #1 in the todo) and runs wix automatically.

  1. Running "svn export" will do this automatically (but would add a dependency on svn). Build.exe also used to have code to do this, but it wasn't as robust - we can add this back if necessary.
  2. Documentation - this is a sticking point. For an API reference, our best bet is MonoDoc to convert OpenTK.xml into html (that can then be converted to chm). Unfortunately, the generated reference is not perfect (missing summaries), so we'd either have to preprocess OpenTK.xml to fix that (should be easy) or modify MonoDoc and try to get the patch included upstream.

    The wiki can be exported with a little work, but I haven't got around to doing that yet. Once we have that, we can simply include the file into the repository and add it to the setup script.

  3. Version handling - we can certainly do that. If I understand correctly, it should be enough to make the upcoming "1.0-rc1" = "1.0.0", "1.0-rc2" = "1.0.1", right?

    What happens with unstable releases, however? (e.g. 1.1-alpha-1 may not be binary compatible with 1.1-alpha-2). I guess the correct approach would be to avoid the GAC for unstable releases?

About the examples project, we have discussed about moving it into a separate, top-level solution, with each example being a separate sub-project (similar to how Tao packages it). This would do away with the sample browser application and generally make things more discoverable. I'm not sure how to handle the case when OpenTK isn't in the GAC, however - simplest solution would be to add a second copy.

zahirtezcan's picture

#5

IIRC you need to sign an assembly to install it into GAC. But it is easy to have an .snk file with VisualStudio (Project Properties -> Signing -> [Tick]Sign The Assembly -> [Select]<New...> ->[Untick] Protect my key file with a password -> [Press]Ok) In case i created one and attached.

IIdontRC, drive your way:)

AttachmentSize
OpenTK.zip714 bytes
the Fiddler's picture

#6

Starting with 1.0 beta-1, all OpenTK releases are signed. A private key already exists (no, it's not in the repository).

If you wish to sign a modified version of OpenTK, you can simply copy your personal key to the OpenTK directory as "OpenTK.snk" and Build.exe will pick it up automatically.

charles's picture

#7

Hi Fiddler,
I agree with you that the best way would be to add a a new 'msi' target (I'll have a look when I've next got some time free), anyway here are my thoughts on the msi target procedure.

Procedure (msi target):
1. Generates 'vs9' target though the normal procedure.
2. Builds the solution, using MSBuild, thereby generating the required assemblies and help files.
3. Build the API reference file using Sand Castle.
4. Build the Documentation file from the wiki (investigate).
5. Modify the Setup project to include the require source references.
6. Build the Setup project using WIX (perhaps though MS Build though I'm not sure about this).

API documentation:
As mentioned above, I recommend using Sand Castle as in my experience it seems to do a good job with API documentation provided the code has been documented according to MS standards and can easily handle generating chm files.

Wiki documentation:
Not sure what is involved here but as you suggest we should be able to export it from the wiki, though this will require more investigation.

Source inclusion:
As I've mentioned previously it's not straight forward to include the source files this is because each file requires a corresponding component in the "Files.wxs" file and a matching reference in the "Setup.wxs" file (see these files in the Setup folder for a few examples of what I mean). Anyway I've been given this some though and think the best solution is to write a little script that basically includes the source folder and automatically adds these entries.

Examples:
I think that if we are to split of the Examples folder of into a new directory then we might as well include duplicate copies there as well (this is how Tao does it I believe) and this shouldn't increase distribution file size as it's capable of recognizing the duplicate files.

Version handling:
Yes your correct though there is a slight improvement possible where instead of manually incrementing the number whenever we need to do a new build we just use the current revision number though this does require introducing a svn dependency. For now it's probably better to just do it manually whenever we need to create a new release.

Anyway I'll focus on getting this up and running when I can (I've got work during the week) so It'll probably take while, but let me know what you think of the current plan.

charles's picture

#8

I've made a bit more progress and added support for building the MSI entirely through MSBuild (yay) and API generation though Sand Castle (see bellow for build procedure).

Prerequisites:

  1. Sandcastle 2.4.10520 "http://wix.sourceforge.net/"
  2. Sandcastle Help File Builder 1.8.0.2 Beta "http://www.codeplex.com/SHFB" (required for MSBuild support)
  3. Wix 3.0 "http://wix.sourceforge.net/"

Usage instructions:

  1. Apply the attached patch to the 1.0 branch (Setup support 2.patch).
  2. Create a OpenTK.snk key file (#566: Support for signed assembly).
  3. Run "Build msi" or "Build" and enter 'msi' for the target when prompted.
  4. Run "MSBuild BuildMSI.proj" (note your command prompt must be setup for .net, the easiest method is to just use the VS Command Prompt [1]).
  5. Go get a coffee (takes ~30min mostly with building the API help file).
  6. The MSI is deployed into the new Installer directory.

TODO:

  • Improve versioning
  • Documentation generation (from wiki)
  • Add some templates for SharpDevelop and Visual Studio.
  • Include source code.
  • Move the Examples into its own directory (cleanup).

References:
[1] MSBuild availability, http://social.msdn.microsoft.com/Forums/en/msbuild/thread/027f7ce5-4c85-45aa-b1ef-20f92bb24f63

AttachmentSize
Setup support 2.patch60.64 KB
charles's picture

#9

Hi just thought I'd let you know that I haven't forgotten about this, just been real bussy with other stuff :) Anyway I'll get back to this sometime in the next few weeks. By the way what's the plan with the API reference as I noticed you've generated a version using doxygen (http://www.opentk.com/news/opentk-function-reference-now-available-online). I can switch over to using this tool rather than sandcastle if prefered, but what is the build time when using doxygen (since sandcastle seems real slow)?

the Fiddler's picture

#10

Heh, same thing here, too little time to work on OpenTK the last couple of months. Doxygen is pretty fast here, less than 120'' on my desktop and around 60'' on my laptop (which uses a SSD). It is also cross-platform and very easy to setup/use, which is a significant advantage over sandcastle.

Coming next week, I hope to find the time to (a) integrate doxygen into the build system (simple for html output, slightly more involved for pdf) and (b) do a proper review of the msi packages (deployment/upgrade/uninstallation policies). Your patch seems to work fine, although sandcastle did give me some trouble.

I wish I could move things faster (have had this patch in the back of my mind since December) but real life takes precedence right now... This is the last significant change left for 1.0.