Fixing The Hugin Build - Revision history

Bruno: categorise

2010-11-12T22:18:33Z

categorise

Yuval: /* Debugging Your Build (work in progress) */

2010-11-04T23:36:23Z

‎Debugging Your Build (work in progress)

Yuval: initial draft (incomplete)

2010-10-17T02:29:52Z

initial draft (incomplete)

New page

Hugin is a work in progress, and so are most operating systems. The building processes [[Development_of_Open_Source_tools|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 [http://groups.google.com/group/hugin-ptx/ 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 [http://groups.google.com/group/hugin-ptx/ 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 [http://groups.google.com/group/hugin-ptx/ 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 with the error messages.

* use the -- Could not find XXXX message in CMake
* search with apt-cache for XXXX
* if after installing something that looks like XXXX, then look at Suggested packages too
* even after build files have been generated, read through the output, you may find about optional libraries such as lapack

← Older revision		Revision as of 22:18, 12 November 2010
Line 46:		Line 46:
	* 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.		* 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.		* Even after the build files have been successfully generated, read through the CMake output, you may find about optional libraries such as lapack.
		+
		+	{{clr}}
		+
		+	[[Category:Software:Hugin]]

@@ Line 36: / Line 36: @@
 == Debugging Your Build (work in progress) ==
-" Start with the error messages.
+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.
-* use the -- Could not find XXXX message in CMake
+* 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.
-* search with apt-cache for XXXX
+* On Debian / Ubuntu system, use '''apt-cache''' to search for XXXX.
-* if after installing something that looks like XXXX, then look at Suggested packages too
+* Most CMake error messages are detailed enough to identify the specific dependency.  Except '''-- Could NOT find Boost'''.  This error message is incomplete. [http://www.boost.org/ 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.
-* even after build files have been generated, read through the output, you may find about optional libraries such as lapack
+* 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: