... can be quite messy. This webpage details several recurring problems I had while installing Ogre3D from scratch from a clean Ubuntu (Hoary 5.0.4) distribution, and how to fix them or work around them otherwise. Please read through it fully before you do anything. As a sort of dubious consolation (at best), if you ever seriously hurt your system, you lose relatively little by reinstalling Ubuntu.

Needed packages

You'll need to apt-get (or install with synaptic) the following packages. The names should be exact - I'm crosschecking them with synaptic as I type. Note: it's assumed that you'll install any necessary requisite packages that make these work.

• build-essential, cvs - you definitely should have these basics)
• kdevelop - has some things you need, but keep track of which versions of automake it installs.
• automake-1.7 - you may want to check where 'automake' points to. It should be version 1.7
• libssl-dev, libtool, libdevil1, libdevil-dev
• libzzip-0-12, libzzip-dev, zziplib-bin - because Ogre liberally uses .zip archives to store its libraries and other information
• libsdl1.2debian, libsdl1.2-dev, libcppunit-1.10-0, libcppunit-dev
• freetype2, libfreetype6, libfreetype6-dev - OgreFont.h will complain about lacking these later on, even though ./configure will let you off with a mild warning.
• libpng12-0, libpng12-dev, libjpeg62, libjpeg62-dev, libtiff4, libtiff4-dev - make will throw errors unless these image libraries are installed.
• Anything else ogre3d complains about missing.

Missing libraries

How you can tell if you are missing a library:

• 'aclocal' throws errors. It will tell you that your aclocal.m4 or acinclude.m4 is not finding the right libraries. You may have to crossreference the tags with the correct library online. Also, double check to make sure you have the correct version of any libraries it mentions.
• './configure' throws errors. Luckily, these are the most easily interpretable.
• 'make' throws errors and stops (or keeps going anyway!). This is the most common way. It has done this with me in particular for the lib[image format] and freetype libraries. Note that if you didn't install the freetype, libfreetype, etc. libraries the correct way, you may end up with a freetype/freetype2 directory in your /usr/include, where the compiler is looking for files in /usr/include/freetype2 library and coming up short. If this is the case, you can create a symbolic link between freetype/freetype2 and freetype2 in that directory. Note that on my last (successful) install of ogre3d, this did not occur.

STLPort and the nVidia Cg Toolkit

If you are using gcc3.3 or higher, which you will be, you can feel free to ignore everything the internet says about you needing STLport. You don't. You will, however, need a certain Cg Toolkit from nVidia. you can find it here:

A word on drivers

A word on drivers: for the love of linux, don't just install random ones that the internet suggests. I grabbed the nvidia-glx package while looking for the Cg Toolkit, and it caused my glx to die. Luckily, there is a very easy way to tell if you have just destroyed your system's OpenGL rendering capabilities. Run 'glxgears' and see if it still works. Note that if you really screw up, X won't even open the next time you restart it. So it shouldn't need repeating that playing with your videocard drivers without knowing what you're doing can be disastrous. If you've botched your system, you should work to reverse this immediately. Sometimes, however, it's not worth the time and effort, and a clean reinstall of Ubuntu is the correct course of action.

Getting ogre3d

Okay, now that we've been installing libraries and other utilities for the last hour, let's get our hands dirty. There are two main ways of getting the ogre3d source. You can check it out from CVS following the directions here:

The ogre3d make process

Sidenote: The ogre3d make process is, uh, "tempestuous" to say the least. it will not cooperate. you will have to do it several times over. it will hate you and tell dirty lies about you, but at the end of the day you will have wrestled it into submission.

The process is as follows. If any of these steps fails, you will typically get an error that hints at what is not yet correctly set up. Be persistent, and patient.

• './bootstrap' - do this if you checked out from CVS.
• 'aclocal' - this should run cleanly, with no error output
• './configure' - once you get through this, you're halfway home. Things it may complain about: freetype2, Cg Toolkit, correct versions of automake, gcc (if for some forsaken reason you haven't done 'sudo apt-get install build-essential').
• 'make' - This will go through and attempt to g++ the core ogre engine. Many things are likely to break. A common error you may get is that 'ld' didn't find an appropriate library. This will be grueling. Anyway, 'make' will compile the core ogre engine first, and then move on to a bunch of rendering systems and other libraries, and then to examples. If you have to repeat this step several times, which is not unlikely, you should 'make clean' in between the attempts.
• 'make install' - should have essentially no problems if 'make' works fine.

Running the ogre3d demos

Now, even after all this, you need to be wary. Try running some of the compiled demos in ogrenew/Samples/Common/bin . Here's a rather annoying error: ogre may complain that it's missing certain ogre-built libraries from the /usr/local/lib directory. Examples of these are 'libOgrePlatform.so' and the following from /usr/local/lib/OGRE : 'Plugin_BSPSceneManager.so', 'Plugin_CgProgramManager.so', 'Plugin_OctreeSceneManager.so', 'Plugin_ParticleFX.so', 'RenderSystem_GL.co', 'resources.cfg'.

Anyway, what kept happening to me is that the 'make' process would create these libraries, but because of some silly error, would never actually copy them over before the cleanup phase of 'make' and 'make install' removed them. So what I had to do was interrupt my make process after it had built these libraries, grep for the necessary files (they will be in some strange *.soU format, and you will have to rename them when you move them to your /usr/local/lib/) and manually put them where the ogre executables were looking. Needless to say, this was extremely annoying, but in the end it all worked out.

Another common error you may have: you run an ogre demo, and the terminal output (as a side note: always, always, always run your ogre demos and your make processes on the command line. I can't stress this enough. You need to be able to know what's going on if you expect ogre to work.) complains that you're missing some demo-specific file like 'resources.cfg' or 'media.cfg' or 'terrain.cfg', as the case may be, this is because you are running the wrong version of the demo. You'll want to run it from ogrenew/Samples/Common/bin/ and not from ogrenew/Samples/[name of demo]/src/ because that way all the include paths are correct.

Anyway, it took me many, many hours but I finally got the demos up and running. Be patient, resourceful and clever, and you should succeed.