Advanced: Install from Source

This is an optional section. It is not necessary to build Cappuccino from source just to write a basic app - the starter package already contains a ready to go version of Cappuccino. You can read about how to get started with the starter package in ’Get Started’.

You should install Cappuccino from source if you need:

  • To use XcodeCapp.
  • To get the latest version of Cappuccino.
  • To learn how things work.

If you’re happy with the starter package you may skip ahead to Learning Objective-J.

Get Developers Tools (Mac OS X only)

In order to use Xcode’s Interface Builder, and to compile Cappuccino itself, you need the Mac developer tools installed. You can get the latest version from the AppStore for free. Xcode 11 is the current version.


Apple no longer includes autoconf in the developer tools. You can check if you have it by entering the following command in your Terminal:

# autoconf --version
autoconf (GNU Autoconf) 2.69

If you don’t have it you can get it installed via Homebrew:

# brew install autoconf

More info here: How to install autoconf

Install Git

If you wish to install the Cappuccino sources you’ll need the source control management software Git.

Git has been included in the developer tools since Xcode 4. You can check you have it by entering the following command in your Terminal:

# git --version
git version

On other platforms you can grab the latest version of Git from the following URL: http://git-scm.com/download.


For the most part you don’t need Java to use Cappuccino. In particular you don’t need to know Java, and the users of your Cappuccino application won’t need it. But certain tools in the Cappuccino toolset depend on Java being installed.

On Mac OS X Java is installed automatically when you need it. On other platforms, please install Oracle’s JDK.

Info Java is needed to run the Rhino Engine, which is sometimes used to execute JavaScript outside of the browser.

Choose your folder

You must choose a place where to put the source code. It can be anywhere. We will assume you want to put the sources in ~/Documents/Sources/.

Clone the repository

Clone the Cappuccino source code repository. Open a Terminal window and type:

cd ~/Documents/Sources/
git clone https://github.com/cappuccino/cappuccino.git Cappuccino

After a brief download you will see a new folder named “Cappuccino” containing all the source code.

Run bootstrap.sh

Before being able to build Cappuccino, you need to install all the underlying components such as Narwhal. The Cappuccino repository contains a script that does everything for you. In your Terminal window, type:

cd Cappuccino

If you already have an installation of Cappuccino the script will ask you several additional question about removing the old installation. You should say “yes”.

The script will now start and will ask you several questions. Answer as follows:

                  / __/ _ `/ _ \/ _ \/ // / __/ __/ / _ \/ _ \
                  \__/\_,_/ .__/ .__/\_,_/\__/\__/_/_//_/\___/
                         /_/  /_/
                             Welcome to Cappuccino!
                                 Version 0.9.8
This script will install the Cappuccino environment for you. Continue?
Enter "yes" or "no":
=> yes [ENTER]

Leave the next question blank to install it in the standard path:

Enter an installation path, or hit enter/return to use "/usr/local/narwhal":
=> [ENTER]

Then bootstrap will download several packages.

If you are under Mac OS X, the script will ask you if you want to build the JavaScriptCore engine for Narwhal. Answer “yes”. (This is not displayed if you are under Linux).

Would you like to build the JavaScriptCore engine? This is optional but will
make building and running Cappuccino and Objective-J much faster.
Enter "yes" or "no":
=> yes [ENTER]

Then it will ask if you want to append bin folder to your \$PATH. Answer “yes”:

You must add Cappuccino's "bin" directory to your PATH environment variable.
Do this automatically now?
    "export PATH="/usr/local/narwhal/bin:$PATH"" will be appended to "~/.profile".
Enter "yes" or "no":
=> yes [ENTER]

Now it will ask you for the value of $CAPP_BUILD. Answer “yes”:

Before building Cappuccino we recommend you set the $CAPP_BUILD environment
variable to a path where you wish to build Cappuccino. This can be automatically
set to the default value of "/root/Build", or you can set $CAPP_BUILD yourself.
    "export CAPP_BUILD="/root/Build"" will be appended to "~/.profile".
Enter "yes" or "no":
=> yes [ENTER]

There will be some warnings when building narwhal, but these are mostly harmless. Finally, you will get:

Bootstrapping of Cappuccino and other required tools is complete.
NOTE: any changes made to the shell configuration files won't take place until
you restart the shell.

Forget about restarting the shell, we are adults, just re-source the .profile or .bashrc:

source ~/.profile


source ~/.bashrc

To be absolutely sure everything is ok, test if you have the jake command in your PATH:

jake --help
Usage: jake [OPTIONS] targets...

If you have this, you are done!

If you get “command not found”, well, something bad happened. You can try to re-run bootstrap and make sure there are no errors. Bootstrap gets its packages from GitHub.com and sometimes these downloads fail. If you can’t succeed, then you can send an email to the mailing list, or join us on our IRC channel at irc://irc.freenode.net/#cappuccino and ask for help. We will be happy to help you.

Now, the Cappuccino environment is ready! We just need to build Cappuccino itself, and you will be able to start playing.

Build Cappuccino

No question here. From the Cappuccino repository, just run:

jake install

To be sure everything runs fine, verify that you have the capp command in your PATH:

capp --help
capp [--version] COMMAND [OPTIONS] [ARGS]

Again, if you get a “command not found” error, please use the mailing list, or join us on our gitter and ask for help.

Wait! Don’t forget the documentation!

This is optional in a sense. It’s not required to build Cappuccino applications, but chances are you’re going to want the documentation. You will need Doxygen. Download the latest version, drag the Doxygen application into your Applications folder. Then, from the Cappuccino folder, run:

jake docs

This should also work with the HomeBrew version of Doxygen. But at the moment, the provided formula seems to have problems, so you may prefer the GUI Application. If you have no idea what we are talking about, no worries. You can view the documentation right here.

If you want the documentation to generate the images representing the class graphs, you need to install graphviz, a utility which provides dot. On the Mac you can use HomeBrew. Note this is optional.

Once built, you can open the documentation using the following command:

open $CAPP_BUILD/Documentation/html/index.html