Running Ogre3d locally (without installing it)

simple build systems, huh?
simple build systems, huh?

Hello there. In this post we will run the “Basic 1” example from the Ogre3d wiki without installing ogre in the system. For that, I’ll assume you’re using a *nix system.

First things first: grab the latest ogre version. At the time of this post, it is the 1.9 release, and you can find its repository here. Note: you want to download the 1.9 version using the tag download feature from Bitbucket; do not simply download the master branch. After that, extract it, create a build directory inside its directory, cd into it, and do a

cmake .. -DCMAKE_INSTALL_PREFIX=$HOME/.lib -DOGRE_INSTALL_SAMPLES=TRUE -DOGRE_INSTALL_DOCS=TRUE -DOGRE_INSTALL_SAMPLES_SOURCE=TRUE -DCMAKE_BUILD_TYPE=Release

This is a pretty much standard cmake build. If your system is missing some of its dependencies, you will be warned and you should install them. Then:

make OgreDoc install

Now it is a good moment to read xkcd.

The usual difference here is that we don’t do a normal make install. Why? Because we don’t want our stuff ending up on /usr/local. Instead, we want it somewhere where we have full access as a normal (non-root) user — in this example, $HOME/.lib/ogre.

Basic 1

Now, head to the basic 1 page of the ogre wiki and download its example. You should try to build it, but take care to change all ogre3d references from /usr/local to your new install directory ($HOME/.lib/ogre). Yeah, that’s it.

Note: if the basic 1 download doesn’t come with a CMakeLists.txt file, you can download it from here (clean ogre cmake project). You can use it verbatim; just put it in the same directory as the basic 1 files and — again — change any references to /usr/local to your new install directory. Also, copy the dist/ directory too (if it is missing from the Basic 1 project),

I’ll add a small observation: in the case cmake complains about pkg-config, try adding this line to the top of your CMakeLists.txt (but after the project version):

set(ENV{PKG_CONFIG_PATH} "$ENV{HOME}/.lib/ogre/lib/pkgconfig:$ENV{PKG_CONFIG_PATH}")

Credits: the build style I adopted here was derived from the Ogre Arch Linux package. Thanks Sven for your excellent packaging skills! 🙂

Update: in your plugins.cfgdo not use “$HOME” as your PluginFolder. This seems to cause issues when you run your ogre app. Instead, expand $HOME manually (in my case, to ‘/home/thiago’). This is not much portable, I know, but there must be some workaround for this I haven’t discovered yet.

Footnotes

  • Image credit: a screenshot from the “Clean Code” software engineering book by Robert C. Martin (a good one, by the way).
Advertisements
Running Ogre3d locally (without installing it)

Getting started with Ogre3d

I struggled a little[1] to get started with Ogre3d graphics, so here are a few notes. In this post we will be able to run some basic examples from the framework.

1. Get a distribution with a nice packaging system[2] and install ogre from it. I can cite two of them: Arch Linux family (pacman-based) or Gentoo family (portage-based). The point is: DON’T install the ogre package from deb-based distros (those include Debian and Ubuntu). They have a few problems:

1.1 Packages are usually outdated[3]. In the case of ogre, this is not a super problem. Its current version is 1.9, and the available one in Ubuntu is 1.8. Even if you can live with that, don’t install Ogre3d on Ubuntu. Keep reading.

1.2 Some files are missing from the packages. Yeah, and I’m pretty sure of that. I compared the upstream ogree tree (from mercurial/BitBucket) with the files that are installed on Ubuntu (dpkg-query -L libogre-1.8-dev), and some files were missing, period. One example I recall? SdkTrays.

1.3 Some files are installed in non-standard locations. I can’t list them because I’m not using an Ubuntu distro right now, but I remember, for example, ‘x86_64-linux-gnu’ (or something along these lines) being used as a directory. Really? This is non-standard. And what about /usr/lib/ogre? This folder doesn’t even exist on Ubuntu. And it should!

Worse yet? Ogre documentation assumes the default installation directory is /usr/local. In other words, it assumes you don’t use a package manager at all, plus you used make install after compiling it, which implies you must have sudo rights on the system. This is simply too restrictive. Also, we all know everything that ends up on /usr/local (=programs installed manually by the user, without a package manager) sooner or later turns into a mess.

Okay, that said, please notice I’m not trying to convince yourself not to use Ubuntu for ogre3d development. I’m just stating I had an awful experience with it. You do whatever you want, okay? Also, if you can handle ogre3d on Ubuntu, please leave a comment telling me how you did that.

I’m using Arch to do ogre3d development from now on; and, if I’m ever forced to use Ubuntu (for example, at work or at my lab at college), I’ll have to struggle to install ogre locally on the system. More on that later.

pacman -Syu ogre

Now, see if you can run the most basic pre-example from Ogre. It is here. This link will probably be broken in the future, so I’ll say those are the files from this example:

  • ogreapp
    • CMakeLists.txt (see below)
    • BaseApplication.h
    • BaseApplication.cpp
    • TutorialApplication.h
    • TutorialApplication.cpp

There is also a dist folder.

You see, it contains a CMakeLists.txt, so the build is (should be!) pretty straightforward. Well, not on Ubuntu…but I’m assuming we’re not using Ubuntu from this point, so, just create your build directory, cd into it, cmake .. and make.

Now, you’ll have to copy (manually) the OgreApp executable into the dist folder. This build system could be better, but…okay. Just do it. And it should work. Unless you’re using a virtual machine: this can cause problems if you forget to enable 3d acceleration. You have been warned.

Oh, just a little warning. See the plugins.cfg config file. You should probably change /usr/local/lib/OGRE to /usr/lib/OGRE.

Basic Example 1

You should get it from here. Now what? Manual work: uncompress it, move its files to a ‘basic1’ directory, and copy CMakeLists.txt and dist/ from the previous example to ‘basic1’.

Then you will have do copy and paste the code from the wiki to TutorialApplication::CreateScene on TutorialApplication.cpp. Done? Now build as usual, and copy the OgreApp executable to the dist/bin directory. And we’re done.

PS. It is likely I’ll write another post about Ogre.

Footnotes

[1]: Not really…a little? This must be a joke. Note: cmake wasn’t the problem, since I had experience with it. I think the problem is the documentation. Ogre’s wiki is way too scattered. There should be a single entry point on “getting started with ogre”, but there are several ones. A typical beginner (=me) will struggle to decide which one to begin with. Worse yet: documentation outside the ogre3d website is way too poor. Discussion forums, reddit, blog posts…no, all the ones that I’ve found are either inactive, old or poor. But now you know that: please don’t make the same mistakes I did.

[2]: Bias: I like (correction, love) both Arch and Gentoo.

[3]: PPAs? Please just don’t use them.

Getting started with Ogre3d