Fixing The Hugin Build

Hugin is a work in progress, and so are most operating systems. The building processes documented on this site have worked for a specific version of Hugin and a specific version of the operating system concerned at some point in the past. However this is no guarantee that they will work now and in your speific situation. The purpose of this document is to raise awareness of potential build problems and mitigate their impact. Moreover it should help contributors maintaining the documents for their specific platforms.

Who Is This Document For

This document is for

• Developers
• Maintainers
• The General Building Public

Developers

As a developer you not only need a working build, you change it. And your changes affect everybody else.

Before adding a new dependency, consider the implications.

• If the dependency can't be satisfied on all supported mainstream platforms, don't add it.
• Every dependency adds an obstacle to the building process. Is it really necessary?
• In borderline cases, consider the added value of the dependency vs. the extra effort required. For example, OpenMP (used by Enblend) is supported on all mainstream platforms. It makes the power of modern multi-core CPUs easily accessible. But it has a negative impact on Windows because it requires a more expensive version of the MSVC compiler. The advantages (for everybody, including Windows users) outweigh the disadvantages (affecting Windows builders and developers only), hence OpenMP should be considered OK.
• Seek the help/feedback from builders on other platforms to make sure the consequences are known.

When you add a dependency or upgrade an existing one to a newer version:

• Document it in the commit log.
• Communicate it publicly on Hugin-PTX.
• Document and communicate when it happens in a development branch; and repeat when it is merged into the main default branch.
• Document it in the README file, on this wiki, on the Hugin website.

Spread the information broadly to mitigate the impact. Spread it as early as possible to give enough time to everybody else to adapt.

Maintainers

If you follow a platform / operating system more closely than the average contributor, you know ahead of time of changes in upstream dependencies to Hugin. When you learn about such a change, please communicate it publicly on Hugin-PTX and if possible edit the documentation in this wiki relative to the platform. Early knowledge mitigates the impact and gives everybody a chance to adapt.

General Building Public

There are many reasons why you would want to build Hugin. It may be a step on the way to become a developer or a maintainer. Even if you are experienced in other areas of IT, start with the assumption that the problem is on your end, not with the documentation. It can happen even to the most experienced builders. Follow the instructions below to debug your build. If you need help, ask on Hugin-PTX, always assuming that the instructions are correct and something else is wrong. Relax that assumption only when a bug with the instructions is confirmed, ideally by experienced builders.

Debugging Your Build (work in progress)

Start building according to the build instructions for your platform. When the build fails, note the error message. This is the starting point to debug.

• The most common build errors are missing dependencies. CMake will stop with a -- Could not find XXXX message. You want to find the XXXX dependency.
• On Debian / Ubuntu system, use apt-cache to search for XXXX.
• Most CMake error messages are detailed enough to identify the specific dependency. Except -- Could NOT find Boost. This error message is incomplete. Boost is a very large and growing collection of C++ libraries. Instead of cluttering your system with a monolithic gigantic package, boost libraries are delivered in smaller packages on most systems.
• If the missing library is a boost library, you will have to look into the top level CMakeLists.txt file in your Hugin source tree and read what boost components are required. At the time of writing, the line looks like:

FIND_PACKAGE(Boost 1.34 COMPONENTS thread date_time regex filesystem iostreams system signals)

• You will want to use your package manager search function to search for the specific Boost component, e.g. `boost-signals`
• It's an interative process: after you installed a dependency that you think was missing, run CMake again. If it stops at the same place with the same error message, you likely installed the wrong dependency (exception: boost - you can't really know). If it continues past the previous error, you installed the right dependency. Consider updating the instructions for your platform. If it stops again later on, repeat the process.
• Even after the build files have been successfully generated, read through the CMake output, you may find about optional libraries such as lapack.