Install the Prerequisites
  • XCode: Required.
    • XCode is the Mac OS development environment under which you'll build Soar. It is free with the latest version of MacOS. This is required.
    • Found on the app store or at here.
  • Java Development Kit: Required.
    • Needed for the Soar Debugger and the Java interface. The exact version doesn't matter. You can also use Sun's JDK.
    • Found here.
  • SWIG: Required.
    • Acts as a bridge between the Soar C++ libraries and the various other languages. Since nearly everyone uses the Soar Debugger, which is written in Java, you probably need this. It is also needed if you plan to interface with Soar using Tcl, C# or Python.
    • If you have homebrew installed (an excellent apt-get like utility for OSX), then you can install swig simply by issuing the command 'brew install swig'. Otherwise, you can download it here.
  • Python: Required, but should already be installed by default in OSX.
    • Note: Please make sure the installed version is 2.x (where x >= 5), as Python 3 doesn't work. To check your version, run python --version in a terminal.
  • ActiveTcl 8.6+: Optional.
    • Needed if you want to build the SWIG Tcl interface and TclSoarLib? (a module that adds tcl to the Soar command line.)
    • Found here.
Note: For all of these packages, make sure to download the 64-bit version if you are on a 64-bit machine.

Build Soar

Go into the SoarSuite folder and run:

python scons/ all

All of your resulting binaries will be in the /out folder. You can build specific components by specifying a different target than 'all'. There are also several settings to control how Soar is built. For example, the '--opt' setting will create a faster, optimized build instead of the default debug build. For more detailed information about the Scons script, see the SCons Script Documentation page. See the FAQ for common solutions to errors.

Troubleshooting Path Issues

(The following assumes that you're using the Bash shell)

Sometimes when building and running a program that uses Soar, your system may have trouble determining the locations of the Soar libraries and header files. If you don't have any issues, ignore this section. But if you do have problems, specify the library location by setting the DYLD_LIBRARY_PATH environment variable:


The exact path depends on where you put the Soar distribution. It should contain the file libSoar.dylib. Specify the headers location by setting the CPATH environment variable:

export CPATH=$HOME/SoarSuite/out/include:$CPATH

Please make sure that the include directory actually exists. If it does not, you need to build the headers target with SCons.
Certain functions in the kernel may also use the SOAR_HOME environment variable to find binaries. For example, SpawnDebugger uses it to find SoarDebugger.jar. Set it like this:

export SOAR_HOME=$HOME/SoarSuite/out

You can add these commands to the .bashrc file in your home directory to automatically set these variables each time you start a Bash shell.

For more detailed information about library search paths, see the wiki page on how library search paths work.