Using Common Sense and Configuration Options
A reasonable number of problems can be solved by a suitable application of common sense. The biggest problem with this is that users appear to have a difficult time figuring out what sense is common, and what is not. I repeatedly have seen users who were convinced their problems were the fault of a program or machine, and were hopping mad at the system for treating them poorly. Most frequently, however, it turns out that they've mistyped some command or entered an incorrect parameter and fixing this also fixes the problem. Conversely, I've seen users who have spent hours fighting with a problem, firmly convinced that they were making some trivial error and were simply incapable of seeing it. Almost to the user, these cases turn out to be actual machine or software errors rather than user errors. If you're new to the Unix environment, watch for this tendency if you think something is the system's fault, stop to consider whether you really have done everything properly. If you think you're doing something wrong but can't figure out what it is after suitable inspection, don't forget that the people who wrote the software are users too and could have made an error.
That being said, we'll provide a general list of things that might help you figure out what's going wrong with a piece of compiled software. There is no such thing as a complete list, but these are relatively good places to start.
The absolute first thing to try, if software doesn't install, is reading the instructions. I know, you've already read the instructions. Read them again.
Try taking out a marker and highlighting the specific places where it says "type this" and "enter that." I've been coding on Unix machines for, good grief, I think it's 20 years now, and I still religiously highlight all relevant sections of installation and configuration instructions. Get into the habit it's good for you.
Make sure while reading the instructions that you've read any sections dealing specifically with Mac OS X. If there's nothing that deals specifically with Mac OS X or Darwin, the instructions for BSD, NextStep, or OpenStep installation might be of interest.
Examine the evidence of a problem. Error messages are generally trying to tell you something beyond the simple fact that there was an error. They sometimes do an abysmally bad job of it, but the average error message contains at least some clue as to what the error is and how to fix it.
If the error involves something going wrong well after the compile for example, when the program is running check whether the program outputs log files. Many programs write progress reports and debugging information into log files. The location of these files is frequently defined in the program's configuration options, but programs can also log via the SYSLOG facility and write log information into files in the /var/log/ directory.
I can't stress strongly enough how important or useful log entries can be. I know, in the throes of fighting with an error it's difficult to remember to look at the logs, but at least 50% of the time I'm having a problem, if I remember to look, the logs have an answer for me.
If the program doesn't have a log file, check to see whether it has a Debug or Verbose mode (usually invoked with -d or -debug and -v or -verbose, respectively). Adding these to the program's invocation either enables log output to a file or causes the program to produce useful output to the terminal.
If the problem is that at the compilation step, the program makes a complaint that it can't find a library (typically a file ending in .o, .so, or .dylib), it might be because the compiler doesn't know where to find it, not because it doesn't exist. If you can find the file it's complaining about, you can attempt to fix the problem in one of two ways. The first approach involves editing the makefile. If you can find where the library is used in the makefile (look for the <filename>.o string in the makefile), you can try adding -L<pathtodirectory> to the makefile. <pathtodirectory> should be the full path to the directory that the library was found in. The second approach is to copy the library file to the directory where the compilation is going wrong (be careful sometimes the compiler wanders down into subdirectories of the directory where you actually typed make, and it's the subdirectory where it's working that you'll need to put the library). This is a clunky attempt, and prone to failure if the library was a shared (.so or .dylib) library, but sometimes, in a fix, it's easier than trying to do it right especially if you're not sure that the compile is even possible, and all the work of fixing a possibly quite cryptic makefile could be in vain for other reasons.
Similarly, at runtime, you might occasionally find programs that refuse to execute with errors that indicate an inability to find a dynamically loaded library (typically <filename><revision>.dyld or <filename><revision>.so). If you encounter this, you need to search your system (use find from the root directory) for a version of the missing library (anything with the same major version should work fine dynamic and shared libraries have a number of revision levels, typically indicated by a triple of dot-separated numbers appended to the filename <major>.<minor>.<bugfix>). Add the path to directory containing the library to your DYLD_LIBRARY_PATH and/or LD_LIBRARY_PATH. The DYLD_LIBRARY_PATH setting should typically be sufficient (set this to a colon-separated list of paths to the directories where you've found the missing files), but some software might require the LD_LIBRARY_PATH instead. At the command line, enter DYLD_LIBRARY_PATH=<paths_to_libraries>, or (setenv DYLD_LIBRARY_PATH <paths_to_libraries> if you're using tcsh) to make the setting.
The configure script frequently pulls some options and makes some decisions based on the contents of two files in the current directory where it's run. Because not everyone has updated their scripts to correctly handle Darwin-based systems, sometimes it helps to copy the versions that Apple provides in cp /usr/share/automake-1.6/config.* into the current directory before running configure.
A syntax error from the compiler that indicates a line number is a warning from the compiler that invalid code has been found in the file. This is an indication that there's something wrong with the program, or perhaps that you've downloaded it incorrectly, or that it has become corrupted on your local machine. Sometimes these are fixable without too much trouble for example, something you can easily repair in the syntax is the damage that's done when a Mac-OS-side editor has saved a file with Macintosh end-of-line characters rather than Unix end-of-line characters (or has accumulated an assortment of each through the use of different editors).
"Downloaded incorrectly" problems can frequently be traced to the fact that Unix and Macintosh applications use two different symbols to indicate the end of a line of text. Apple is trying to rewrite many command-line utilities so that they're platform agnostic with respect to the carriage-return versus linefeed issue, but Apple can't do it for every application that you might compile. If you use Macintosh applications such as text editors or web browsers to download or modify code or configuration files, expect to see the occasional compilation or execution error as a result of having the line endings changed (it happens to all of us, more frequently than we like to admit).
Similar problems pop up from time to time when you've used a text editor that saves state information along with the data. If you find yourself in a situation in which a compiler or program complains that the syntax of a file is incorrect, or the software just plain dies while reading files, check your line endings, and then check to see whether your editor has saved metadata regarding the file in its first few bytes. Pure plain text editors such as BBedit and Alpha both include the option to save files with Unix line endings in their Save As dialogs. Both also include the option to discard state information. The command-line emacs editor tells you whether your file has Macintosh line endings in its status line. If you use the emacs M-x find-file-literally option to load a file, it loads with the Mac's control-M line endings as control-M, and you can use M-x replace-string to switch them to Unix line endings (control-J).
Apple has supplied make as a version of GNUmake. Some software makefiles are designed for the BSD version of make instead and break when GNU's make is used. If you get weird errors during compilations that seem to indicate a syntax error with the makefile itself, try using bsdmake rather than make.
A number of the configure scripts and makefiles out there assume that if they're using GNU's make, it'll be named gmake, or gnumake, and that if make is named just plain make, it's a BSD-derived version. Calling GNUmake make on Mac OS X can cause problems with makefiles that are (poorly) designed to detect which make system they're running under, and that try to automatically use the correct syntax for the version of make that's in use. Sometimes it helps to put a gmake link in /usr/local/bin and point it to /usr/bin/make or to invoke your compilations explicitly with gmake.
Yet another inconsistency results in the occasional inability for make to proceed properly through the entire hierarchy of directories where it needs to be run. One of the first things to try, if you're seeing messages from make that say entering directory <dirname> followed shortly by a compilation error, is to manually cd to that directory and run make in it by hand. You might need to do this several times, with directories at each level in the hierarchy. If make turns out to work properly when manually run in the subdirectory where it was previously breaking, repeat this step as necessary throughout the directory structure of the program, return to the top-level directory for the compile, and then run make there again. This should use all the subparts you've hand-assembled and correctly finish the process. Occasionally, it'll find yet something else wrong in a subdirectory due to some cross-dependency with another subdirectory. If that's the case, try stepping through the process again and see whether the final make at the top level gets further the next time. If it does, you're making progress. If it doesn't, it's time to look elsewhere for the source of the trouble.
Due to differences between compiler and linker versions, and the fact that any given compilation process could have been designed for something other than what you've got on your system, it's sometimes necessary to add certain flags to compile and link steps. These are usually defined in the makefile as CFLAGS and LDFLAGS variables. The most common flags of interest are -flat_namespace, -undefined suppress, -no-cpp-precomp, and -fno-common. The exact combination of flags that you need to either add or remove from the CFLAGS and LDFLAGS definitions varies from package to package. In general, if you get complaints regarding undefined symbols, try adding -undefined suppress and, potentially, -flat_namespace. -fno_common makes the compiler more strict about certain things but also makes it behave more like the default behavior on some other systems, which allows certain "smart" makefiles to recognize what's going on and adjust properly, where they'd fail under more lenient settings. Unless the software was designed for Darwin, -no-cpp-precomp is usually safe to add and is a good try if you're seeing complaints about syntax.
Many of the recommendations we've made in this section amount to what a programmer would consider to be cargo-cult compilation (the uneducated application of various "magic" incantations to a problem, with no real understanding of what any of them do, in the hopes that one or more might solve the problem). The term comes from the story of primitive island cultures that supposedly picked up the habit of building mock airstrips, radio shacks, and barracks in an attempt to induce planes and ships to land there, having once seen planes and ships land near similar structures during wartime occupations.
In the world of real programmers, cargo-cult programming is generally looked down on. Programming is a precise art, and those who denigrate that art by cutting and pasting bits of code that they don't understand, but that they believe has some functionality, aren't real programmers regardless of what they've put on their resume.
You, however, aren't expected to be a real programmer. It's great if you are, but if you're not and you're not trying to be, using cargo-cult techniques to try to solve a compilation error is a valid approach to the problem. We've given you some of the best general-purpose incantations we know. If you're not trying to be a real programmer, and you have software that won't compile, try out some of them. The worst that can happen is that the compile still doesn't work. And never let a real programmer knock the result if you get something working. If he'd done his job, you wouldn't have had to fix it!