Tutorial for building projects from source

Please note that this is a rough outline as projects can vary very much.

Probably the most common cause of failure is indeed dependencies, or lack of code portability.

First be sure to have the latest XCode installed.

I'd recommend using either MacPorts or Homebrew at first. This will give you access to many open-source packages out of the box.

Then, if your project is not in the provided package list, the aforementioned package managers will allow you to install its direct dependencies (and in turn their dependencies, recursively) much more easily than building said dependencies from source by hand.

Next two choices are offered to you:

1. you build and manage the project by hand
2. you create a portfile (MacPorts) or a formula (Homebrew), allowing for the package management to fetch, build, install and manage your project

How to build your project very much depends on the project itself and the language it is written in. Instructions generally lie in a INSTALL or README file.

Since you talk about header files I suppose it's a program written in C or C++. In that case the build process is generally as follows:

./configure --prefix=/usr/local
make

Be sure to set a prefix so as not to overwrite system stuff in /usr/bin for projects using insane defaults.

If all dependencies are satisfied the configure script should proceed successfully, and so should do make. If problems occur, you can point to or disable dependencies with the configure script, relevant flags given by ./configure --help.

Once the compilation has succeeded, you can proceed to either install via sudo make install.

Alternatively, try to build a portfile or a formula which will do the building steps, but managed by the package manager.

The package manager route has many advantages:

• the build commands are easily reproduced for a newer version of the project
• the uninstallation is quite easily handled
• you can contribute back the portfile/formula
• you can take inspiration from an existing portfile/formula written for a similar project to successfully build your project

Resist the temptation to build Universal binaries. It can be a tricky matter which you should only attempt if you succeed and master regular builds first.

Be aware though that some projects are not written in a portable way (either by necessity, irrelevance, or lack of will) and will just fail to build on Mac OS X. Although not trivial, this could be an opportunity to learn and port the code to a new platform...