Windows Client Development Setup
From Mugshot Developer Wiki
How to set up your system to work on the Windows Client. See also Linux Client Development Setup, Server Development Setup, Client Code Overview, C Style Guide.
Contents |
Prerequisites
To check out and build the client on Windows you will need:
- Visual C++. We have tried Visual C++ 2003 and Visual C++ Express 2005.
- TortoiseSVN (shell integration for subversion)
- WiX is used to build the installer
- Optional: AnkhSVN (VS integration for Subversion, does not work with Visual Studio Express 2005)
Subversion Checkout
Subversion instructions are here - note you must check out "trunk/client" NOT "trunk/client/windows" because you need "trunk/client/common" as well.
WiX
The installer is built using WiX (http://wix.sourceforge.net). The recommended way to install WiX is to install the "Votive" package which is WiX integration for Visual Studio. Votive doesn't actually work as expected, as far as I can tell, but it installs the WiX command line tools in the right place and also puts a schema file for the WiX XML format in a place where Visual Studio finds it. Work so far as been done with the 2.0.3309 build of Votive.
If using Visual Studio Express 2005, instead of Visual Studio 2003, Votive will not work. You have to install the plain "WiX binaries" package, then go into Tools - Options - Projects and Solutions - VC++ Directories and add the unzipped WiX binaries folder.
If you have the non-Express VS2005, we don't know whether Votive works or not.
Gecko SDK
In order to build the Windows client, you need to have the Firefox SDK installed (it's called the "Gecko" SDK after the name of the Firefox HTML engine.)
The main files of the Gecko SDK are found the gecko-sdk zip file. The most recent version at the time of writing is http://releases.mozilla.org/pub/mozilla.org/xulrunner/releases/1.8.0.4/sdk/gecko-sdk-win32-msvc-1.8.0.4.zip, but you might want to poke around for a more recent one. The exact version shouldn't be critical. Once you download the zip file, open it up in the standard Windows archive manager, and copy the gecko-sdk subfolder to c:\Program Files\gecko-sdk. (Among other ways, using "Copy this folder" in the contextual links in the left pane will work.) Note that you want to copy only the subfolder, so you have c:\Program Files\gecko-sdk, not c:\Program Files\gecko-sdk\gecko-sdk.
Once you have these files, you need to add in a couple of DLLs. These can be found in the zip file: http://ftp.mozilla.org/pub/mozilla.org/mozilla/source/wintools.zip. (Yes, it dates from 1999. There are more recent versions of the DLLs around elsewhere. My experience with using them was crashes.) Open that in the archive manager and copy the files glib-1.2.dll and libIDL-0.6.dll from buildtools/windows/bin/x86 into c:\Program Files\gecko-sdk\bin.
At this point everything should be set up properly so that the Visual Studio project files will find and use the Gecko SDK files without further intervention.
Visual Studio
After you check out Mugshot from Subversion using TortoiseSVN, double-click on the solution file under client/windows and it should open in Visual Studio.
Right click on the solution (toplevel node) in the Solution Explorer, select Properties, and change the "Startup Project" to HippoUI.
Once you have everything set up, select Build/Build Solution from the menus, and if that succeeds Debug/Start. You should get an icon in your notification area and the client should be working. If not, ask for help.
Well, if you are using Visual Studio Express 2005 and the build fails, first double-check the 2005 caveats in the next section...
Visual Studio Express 2005
Visual Studio Express 2005 is available for free download from Microsoft, but you have to register.
The "Express" Visual Studio does not support add-ins so Ankh won't work. You have to do your Subversion stuff from Explorer, using TortoiseSVN.
In Express 2005, be sure you followed the instructions on microsoft.com when you downloaded it to also get the SDK and to add the bin, lib, and include dirs for the SDK in the VC++ Directories list under Tools - Options - Projects and Solutions - VC++ Directories
You will also need to add the WiX binaries directory to the binaries search list, and add the "mfc" subdir inside the SDK include directory so that afxres.h or something like that gets found.
When you open our 2003 solution, you'll have to let VS convert it to a 2005 solution.
After converting, you will have to right click on the HippoUI project, open Properties, and make two changes:
- remove thrownew.obj from "Additional Dependencies" under "Linker"/"Input"
- set "embed manifest" to "no" under "Manifest Tool"/"Input and Output"
- right underneath "embed manifest", set "Output Manifest File" to a name like "IgnoreThis.manifest"
Each time you update from Subversion in TortoiseSVN and the project files have changed, there will be conflicts and the easiest solution is to revert the project/solution files to the Subversion (VS2003) versions, and then convert to 2005 again.
If you find that VS2005 is eating a huge amount of CPU - this seems to be caused by converting to 2005 when an Intellisense database already exists. Exit VS2005 and delete the .ncb IntelliSense file (in the directory next to the solution file), then start VS2005 again, and it should be OK.
If you get a dialog about Windows XP required / common controls too old on running the app - there's probably a manifest file in SVNROOT\Debug\Mugshot.exe.manifest that is overriding the one we embed in the executable. In Visual Studio 2003, our setup is that we have a resource file which lists a checked-into-Subversion manifest file to be embedded in the executable. This same thing happens on Visual Studio 2005. However, VS2005 also has a "manifest tool" that generates a manifest for you. This needs to be told not to embed a manifest (which would conflict with ours), and then needs to be told not to create a Mugshot.exe.manifest (which is found in the working directory when you run the app, and overrides the embedded one). We haven't figured out how to just disable the manifest tool, so we tell it to generate a manifest with a name like IgnoreThis.manifest to keep it from being picked up. To fix the problem, delete Debug\Mugshot.exe.manifest and then make the changes in HippoUI Properties described above.
Alternative Client Instances
The client supports three simultaneous instances (production, dogfood, and debug). Right now the "dogfood" (shared test server) is not publicly accessible but it probably will be soon, or you can configure "dogfood mode" to point to any server you want. The "debug" server is intended to be a server you're running locally and working on (see Server Development Setup).
Select the "dogfood instance" with the --dogfood command line option, and "debug instance" with --debug. Each instance has its own registry keys so can be configured differently.
Dogfood Setup
- Make sure you have the client software installed
- Open the Programs menu (Start/All Programs), and with the control key held down (copy), drag the Mugshot icon and drop it in the Startup folder.
- Now right click on the new item in the startup folder, select Properties and change two things:
- In the Shortcut tab, add --dogfood to the end of 'Target' (after the quotes, not inside them)
- In the General tab, change the name from "Mugshot" To "Mugshot Dogfood"
- Click OK, reopen the Programs menu to Startup and click on your new launcher to start it
- Another Mugshot icon should appear in your tray; you can tell the Mugshot icons apart by their tooltip
- Control-right click on the icon to get the debug menu, and select Preferences...
- Change 'Message Server' to the server and port you want this instance to use, like "example.com:21020"
- Change 'Web Server' to the desired server and port, like "example.com:8080"
Debug Setup
- Follow the instructions for dogfood, but use --debug instead of --dogfood in the shortcut command.
Server Development Setup explains how to run a local instance of the Mugshot server for debugging.
Restrictions on Host Name
The Windows client involves an ActiveX control that's accessed by the web pages coming from the server instance. This ActiveX control is locked to a hardcoded domain determined when the Windows client was built. Otherwise any web site could use the control.
By default of course, the ActiveX control is locked to allow mugshot.org domains only.
There are two approaches to solving this.
First, you can edit the source code to lock your local build of the control to your server's domain. Your local build will no longer work with the mugshot.org main site. We haven't documented how to do this yet... if you figure it out please add some notes here.
Second, you can trick your local system into thinking your debug instance is a mugshot.org server. Here's how:
- In WINDOWS\System32\drivers\etc\hosts, make up a hostname ending in ".debug.mugshot.org", and point it to the IP address of your debug server.
- On Linux, edit .super.conf for the debug instance to use your chosen hostname instead of the IP address or localhost.
- Now open the prefs for your debug client, and set the server to your chosen hostname.
- When you browse to the debug instance, always use the whatever.debug.mugshot.org hostname.
We'll avoid using *.debug.mugshot.org for any real servers you might want to go to.
General Windows Sanity
SSH
To import your existing private key grab the PuTTYgen application and load in your private key. Save the key somewhere under your $HOME directory. This will allow you to continue using the same private/public key through PuTTY and WinSCP.
- PuTTY for shell access
- WinSCP for sftp access
- Pageant is an SSH agent, it can be run from the command line with your key as the only argument, or click on the tray icon and add the key from the menu
Check out SSH for Windows for more information
IE Developer Toolbar
You probably know about Firefox DOM Inspector and JavaScript console, the equivalent for IE is called the "Developer Toolbar," you DEFINITELY want this if trying to develop pages that work in IE: google search for it
Building A Windows Client Release
DO NOT RELEASE INSTALLER PACKAGES TO THE PUBLIC USING THE SAME PACKAGE NAME OR REGISTRY KEYS AS OFFICIAL MUGSHOT OR IT WILL MAKE A BIG MESS. These instructions are here in the spirit of openness and for local experimentation; if you want to make public releases you'll need to do more work to rename things and avoid conflicting with regular Mugshot.
- First, follow the steps for checking out and building the windows client.
- Change the version number in HippoUI/Version.h
- Go to WiXInstaller/DumbHippo.wxs and change the three instances of the version number (in the <Product> element, and twice below in the <Upgrade> element.
- Generate a new Product Id for the Product element ... start Tools/Create Guid, select Copy, paste over the existing Product Id, then delete the {}. DO NOT change UpgradeCode.
- If you don't have Create Guid, we aren't sure why, but you can go to Tools/External Tools, add a new one with the executable Common7/Tools/Bin/uuidgen, and check "use output window"
- Or see Create A GUID Macro for how to add an insert-a-guid key binding.
- Save and commit the changes.
- Rebuild the solution, and then right click on WiXInstaller, and select Project Only/Rebuild Only WiXInstaller; the dependencies aren't quite right in the Makefile, so forcing a rebuild is a good safety net.
- The last step generates a file Musghot.msi in the client/windows/Debug directory of your checkout.
Generating a source tarball
- Just run ./make-source-zip.sh on Unix in the client/windows directory.
