As of version 9.3.2, Soar is built by a single SCons script for all operating systems. SCons tries to be smart and uses the appropriate compilers, linkers, and other commands for your OS. A version of SCons is distributed in the Soar source tree, so you don't need to install it separately. To run the builder, start a shell (Visual Studio Command Prompt in Windows, see below), cd into the SoarSuite directory and type

python scons/scons.py <options>

or if you want to use the SCons version you've installed separately,

scons <options>

<options> is a place holder for options we'll pass into the builder, and should not be typed literally.

For Windows users, we have provided a batch file called build.bat which will perform several functions before launching the SCons script. This file will search for the locations of the python, java, and swig installs, and set the PATH environment variable so that the various compilers can run. Windows users can simply type:

build <options>

The build script must be invoked from the Visual Studio Command Prompt so that scons can locate the VC++ compiler. A shortcut to launch this prompt can be found in the start menu under the Visual Studio program group.

For the rest of this document we'll be showing example build commands using the "scons <options>" form. Please substitute the appropriate command for "scons".

Build Targets

The builder can be directed to compile any number of targets, i.e. components of Soar. Any number of targets can be passed to the builder together. For example:

scons kernel debugger sml_python headers

The "all" target tells scons to build everything. To see a list of available targets, type

scons list

As of Soar 9.4, this will give you the following full list of targets: all cli debugger debugger_api headers kernel sml_java sml_python sml_tcl tclsoarlib tests

If a build is issued with no targets specified, the default targets will be built which are: kernel, cli, sml_java, debugger, debugger_api and headers.

The Soar suite has several individually buildable targets::
kernel: The Soar Kernel Library

This includes core Soar functionality as well as the Soar Markup Language (SML) interface. SML is the standard interface for hooking Soar up to external or virtual environments. The Java debugger and command line tools also rely on SML.
Windows: Soar.dll, Soar.lib
Linux: libSoar.so
OSX: libSoar.dylib
sml_java, sml_python, sml_tcl: SWIG Wrapper Libraries

These contain language-specific wrappers automatically generated by SWIG to allow languages other than C++ to interface with SML. The primary languages we use this for are Java, Tcl and Python, although an interface also exist for C#, but has not been tested for a while.
Common: Python_sml_ClientInterface.py (Python), sml.jar (Java)
Windows: _Python_sml_ClientInterface.pyd, Java_sml_ClientInterface.dll
Linux: _Python_sml_ClientInterface.so, libJava_sml_ClientInterface.so
OSX: _Python_sml_ClientInterface.dylib, libJava_sml_ClientInterface.dylib
debugger and debugger_api: Java Debugger

This is the primary way for users to run Soar and debug agents.
Common: SoarJavaDebugger.jar, soar-debugger.jar
cli: Command Line Interfaces
TestCLI: A multi-threaded command-line interface with history and several other features.
CLI: A minimalistic command-line interface which is more suitable for using in scripts or for low-level kernel debugging.
mCLI: A minimalistic, multi-agent command-line interface with ANSI-colored text.

Linux, OSX: testcli, cli, mcli
Windows: Same, with .exe suffixes
tests: Tests

This includes a program that runs many unit tests and other programs that run performance tests. The unit test program also requires a number of agent files that will be copied into your install directory.
Common: Many soar files under the TestAgents subdirectory
Linux, OSX: UnitTests, TestSoarPerformance, !TestSMLPerformance, !TestSMLEvents
Windows: Same, with .exe suffixes
tclsoarlib: Embedded Tcl Command Line Module

This builds a dynamically loadable library that adds tcl functionality to the Soar command line. This can be turned on with the command "cli tcl on".

headers: SML Headers

C++ header files needed by programs that use SML. "Building" these just involves copying the headers from various points in the source tree into a single directory. Note that Java and Python SML programs DO NOT need these headers, as the SWIG wrapper classes incorporate the definitions contained in them. A user who only wants to run Soar but not create new environments should build the kernel library, Java SWIG wrapper, and the Java debugger. Users who want to write new environments with SML will also need, depending on their language choice, the SML C++ headers, Java SWIG wrapper, or Python SWIG wrapper. The test and command line interface programs are mainly for internal development.

Output Directories

By default, the built libraries and executables will be placed into the "SoarSuite/out" subdirectory, while intermediates such as .o files will be placed in the "SoarSuite/build" subdirectory. You can change these using the --out=<dir> and --build=<dir> options.

scons all --out=/home/soar --build=build_linux

These directories can be located or moved anywhere in your file system. However, we recommend you not change the file structure inside the "out" directory, as the executables expect the libraries to be in certain places relative to them.

To clean up all the files you just built, type

scons -c all

Build Flags

You can modify building behavior by passing in a number of flags in the form '--<flagname>'.

To see the list of available flags, type

scons --help

and look under the "Local Options" section (the other flags are for scons itself).

Some flags of interest:
  • --opt will turn on compiler optimizations and strip debugging symbols from targets, resulting in slightly faster Soar agents and significantly smaller file sizes. By default optimizations are disabled for faster build times.
  • --verbose makes scons print out the full commands it uses to build each file. This is useful if the build doesn't succeed and you want to figure out what is happening under the hood.
  • --static will build a static version of the Soar library. The resulting library is normally named libSoar.a in Linux/OSX, and Soar.lib in Windows (there won't be a Soar.dll). This is necessary for running Soar in environments that don't support dynamic linking, such as iOS.
  • --no-scu will build without using single compilation units. This will make compile time longer for full builds, but shorter when only a small subset of files have been altered.
Other options:
--cc=COMPILER Use argument as the C compiler.
--cxx=COMPILER Use argument as the C++ compiler.
--cflags=CFLAGS Compiler flags
--lnflags=LNFLAGS Linker flags
--no-default-flags Do not pass any default flags to the compiler or linker
--out=DIR Directory to install binaries. Defaults to "out".
--build=DIR Directory to store intermediate (object) files. Defaults to "build".
--python=PYTHON Path to Python executable

Visual Studio Solution Generation

SCons can generate Visual Studio project and solution files that allow users to more easily modify and debug the kernel source code. You can generate these files by typing

scons msvs

Unfortunately, the generated projects are not stand-alone, they still call SCons under the hood to build targets. This is not yet a well-supported feature, so the resulting project files will probably require some hand-tweaking.