Cowboy Programming Game Development and General Hacking by the Old West

It’s a timeless tale; you find some useful looking code sample on the internet, you download it, you try to build it and it does not build. This is such a common occurrence that non-building code samples seem to greatly outnumber correctly building code samples on the internet by a factor of ten to one.

So I was incredibly surprised when yesterday I attempted to build the programming language Ruby from scratch on my Vista Desktop. As was expected, it did not build, but the amount of fiddling I had to do was actually incredibly small – pretty all I had to do was figure out one cryptic line in the instructions: “Execute win32\configure.bat on your build directory”, and I was nearly good to go.

Then I tried the same thing on my XP laptop, and I got an error (“cl error 0x2”, which is not incredibly helpful), and I’m stuck (well, I was programming in bed, so I was not strongly motivated to figure it out).

NMAKE : fatal error U1077: ‘cl’ : return code ‘0x2’

But it got me thinking, why do hardly any code samples build? Well, in my experience it is always because something is either A) The Wrong Version or B) Missing. Problem B is generally the easier to solve, except in the rather unfortunately common case where something being missing means that another version is used, and it ends up being A – wrong.

1) Wrong or Missing Paths
Paths tell the tools where to look for things. If the paths are wrong, or missing, then the tools will look for things in the wrong place, and might find the wrong version, or they might find nothing. Unless your paths are correct, it does not matter what else it correct. The order of paths is very important, as the build tools (or Windows, if just running a tool) will look through them in that order.

2) Wrong or Missing Tools
Tools build things in a particular way. If you have the wrong tools, then things might build differently, or not at all. If a tool is missing, then hopefully the build will just stop, but sadly it might just find another (older, newer, or just wrong) version of the tool, and use that.

3) Wrong or Missing source
No every sample includes all the source you need. You might need another bunch of code, perhaps DirectX, TK, or the Windows SDK. Not everyone tells you this. The code might even require a particular version. If it does not find what it is looking for, it might use nother version. This can depend on your paths, but the source you need (usually header files), might simply be missing.

4) Wrong or Missing Library
Likewise with libraries, it might not be linking because it’s the wrong version. Symbol not found? What exactly is being linked here?

5) Wrong or Missing Environment Variables
Paths are one specific example here, but you often get things like compile and link options in environment variable, and symbols may be defined, and various other build flags. Perhaps a batch file is included that sets these? Perhaps there is a text file that describes how you should set them manually.

So of these, what is going on with my laptop build of Ruby? I’d only got as far as trying to do the “configure” step when I got the error. Now in this case I’m rather luck in that I have a working version, and an non-working version, so I can hopefully just play “what’s the difference”. Let’s check things one at a time:

1) Paths: I build from the “Visual Studio 2005 Command Prompt” that is part of Visual C++ 2005 Express edition. This sets up various paths and variables for me. Any difference here? Well, I have a different version of the DirectX SDK, but it’s after the visual studio stuff which is all the same.

2) Tools, check the version numbers, usually you can just run the tool and it will tell you, or run it with /h, –help, -v, /v or somesuch option.
Version for cl.exe – (desktop) 14.00.50727.762, (laptop) 14.00.50727.42 So that’s different. looks like I have a slightly older version of Visual Studio on my Laptop. Try to install the latest version? (Hmm, looks like Visual Studio 2008 Betas are out – must resist the urge to try it…). 200MB of downloads and two dubious restarts later and nothing has changed.

At this point I’m suspecting some configuration problem, based on scant clues from the internet, so I go straight for the environment variable, and realize I missed off the paths that are set in the environment variable, so I check those (just run SET in the command prompt you are using to build) and……

Laptop has
INCLUDE=C:\Program Files\Microsoft Visual Studio 8\VC\INCLUDE;

Desktop has:
Include=C:\Program Files\Microsoft Visual Studio 8\VC\INCLUDE;C:\Program Files\Microsoft Platform SDK\Include

It looks at first like the Microsoft Platform SDK is missing, but it turns out I had it. I just need to hard wire in the missing path to INCLUDE (and another for LIB) and it worked!

(Note you’ll get the same error if you simply did not have Microsoft Platform SDK installed, make sure you have that first. )

You know, it would be very helpful if the ruby configuration batch file (win32\configure.bat) had attempted to diagnose some common problems, instead of simply letting it run until a cryptic error. And why are other errors being suppressed? There would probably have been a more useful error, like “file xxxxxx not found”.