Occasionally a build step fails mysteriously, that has succeeded before. The main cause of this is a file being marked in the Windows filesystem as in use when a tool tries to open it. On a slow, heavily loaded machine, the filesystem may not update a closed file's status quickly enough -- solution: reduce the load. On any machine, Google Desktop Search (or other automatic indexer) may grab a recently updated file and really have it open -- solution: pause or disable indexing and retry the build step.

Occasionally a build step fails mysteriously, that has succeeded before. The main cause of this is a file being marked in the Windows filesystem as in use when a tool tries to open it. On a slow, heavily loaded machine, the filesystem may not update a closed file's status quickly enough -- solution: reduce the load. On any machine, Google Desktop Search (or other automatic indexer) may grab a recently updated file and really have it open -- solution: pause or disable indexing and retry the build step.

Revision as of 15:42, 23 January 2008

This article gives step-by-step instructions for building hugin from a source code snapshot using Visual C++ 2008 Express Edition and precompiled dependencies. That is the recommended way to build hugin for Windows, and the only way that has worked for me. It also shows how to build enblend 3, which hugin now requires, with the same tools.

Contents

Background

The hugin build is based on cmake, a cross platform makefile generator. On Windows, cmake can generate project files for various Microsoft Visual Studio toolsets, from the same specifications it uses to create makefiles on other platforms. The current release (cmake 2.4.7) only supports VC 2003 and 2005; the unreleased 2.4.8 and the current development trunk (2.5) support VC 2008 too, so you will need one of those.

Pablo has recently published an sdk containing all the support components needed to build hugin and enblend (and AutoPano-SIFT-C) on Windows. Version 1 of the sdk has two flavors, one built with Visual C++ 2003 Express, the other with VC 2008 Express. Version 2, which is more complete, is only for VC 2008 at present.

If if you already have VC 2003 (and the corresponding Windows Platform SDK) installed you might want to try that. Otherwise use VC 2008, which is currently available and easier to install because the Platform SDK is bundled. You can install VC 2008 Express beside other Microsoft compiler versions, even professional ones, without damaging either toolset.
The enblend source tree has projects for building with both the 2003 and 2008 tools (also 2005 but there is no sdk for that).
The following instructions are for starting from scratch on a Windows PC without any software building tools installed. If you already have some of these things installed, you will need to take care that the right tools and components are used. It is vitally important that all object code is generated by the same compiler version and targeted to the same VC runtime library.

The recommended Tortoise archive clients work through the Windows File Explorer: right-click a target directory and follow the popup menus.

Build hugin

8) Start the cmake gui (cmakesetup.exe). To ensure that the environment is set right, run cmakesetup.exe from the VC 2008 command shell (available under the Windows Start Menu) - essential if you have other compilers installed. You might want to create a desktop shortcut that does this with one click.
Set cmake's source code directory to huginbase/hugin and its build directory to huginbase/hugin-build (this will create a new directory for the build). Click Configure and tell it to use Visual C++ 2008. Cmake then checks the build tools and if that goes well does the first round of searching for components. When done it displays a list of configuration variable settings, on a red background. Click "Show Advanced Values" to display all of them.
This is when you get to correct anything that needs correcting. First, if HUGIN_WC_REVISION is blank, set it to the SVN revision number (this should be automatic but currently is not on Windows). Next, check that all component pathnames start at huginbase. Cmake may have found some things installed in standard places on your system; but it should only be using the ones in the sdk. To correct a pathname, click on it and either type in the right one or click '...' to pop a fileselector. Look out for values with "_NOT_FOUND" in them; these may indicate problems with your directory names or structure.
When you are satisfied the paths are right, click Configure again, and Cmake will try to validate the variables. That might set some new ones, which will appear in red. Recheck all values, even the grey ones. If a variable keeps coming up wrong try deleting it from cache (right click on name pops menu) and configure again; this is often necessary to trigger a new search. Keep fixing and clicking Configure until everything is OK. Then click OK to generate the project files.

9) Open hugin.sln in the build directory with Visual Studio 2008 Express and wait while it loads and checks all the projects. Then select a target configuration and click "build solution". After a long time, and many warnings, you should get a successful build.

10) Build the INSTALL project. This should put a full hugin installation in a directory tree rooted at huginbase/hugin-build/INSTALL/FILES.
NOTE any missing file stops the install script, leaving the installation more or less incomplete. If this happens, first look at the install scripts, cmake_install.cmake (several places in the hugin-build tree) to identify all the files that were not found (paths with "_NOT_FOUND" in them). If you can find all of them,
put them where the install script expects them -- hugin/cmakemodules/winbundle.cmake will help indentify those places. You can't just build INSTALL again, because the files are searched for at configuration time, so the install scripts will still contain invalid pathnames until you run cmakesetup again. Exit Visual Studio first, since all project files must be rebuilt. It may be necessary to delete pathnames of the failed places (such as enblend-3.1) from cache to ensure everything gets regenerated. Then Configure, OK, open the new hugin.sln and build INSTALL.

Updating the hugin build

You have to run cmakesetup again after updating the hugin source tree from SVN. Proceed as in 8) above, but click "Delete Cache" before "Configure", so that the new configuration gets built from scratch.

Before rebuilding, check if there is a new release of the sdk.

Installing hugin on Windows

The sdk contains support for building a Windows Installer (.msi) package with warsetup and the WIX toolkit (files in hugin-build/INSTALL). At present this is under active development and does not work perfectly; when it does, I'll put the instructions here. Meanwhile you can just copy the contents of hugin-build/INSTALL/FILES to a directory of your choice and use the Windows GUI to create desktop shortcuts and associate hugin.exe with the .pto (hugin project) file type. Note since this does not register hugin as an installed product you would have to delete those things by hand before installing from a proper installer package.

Some things that don't work

Trying to target the dll versions of the Visual C runtimes. Only the static C libraries (libcmt, libcmtd) will do. You can't mix static and dll runtimes, so all (static) dependencies must also have been compiled with /MT or /MTd. While it might be possible to use dll versions of some of the support libraries, such as tiff or OpenEXR, it is safest to keep a strict policy of "static libraries only".

Trying to use dependencies built with a different compiler. For all practical purposes, Microsoft runtime libraries are now usable with only one compiler version. Although linking code built with more than one compiler sometimes seems to work, the resulting program is likely to fail.

Trying to link Boost libraries of a different source version than the Boost headers. Boost takes some trouble to lock object code to source version as well as compiler version, so it is rarely possible (and always a mistake) to do this.

Occasionally a build step fails mysteriously, that has succeeded before. The main cause of this is a file being marked in the Windows filesystem as in use when a tool tries to open it. On a slow, heavily loaded machine, the filesystem may not update a closed file's status quickly enough -- solution: reduce the load. On any machine, Google Desktop Search (or other automatic indexer) may grab a recently updated file and really have it open -- solution: pause or disable indexing and retry the build step.