Soar

This is the code base for Soar, a cognitive architecture for developing systems that exhibit intelligent behavior. For more information about this project, please visit:

• The Soar home page
• The GitHub project page

Note that the readme included with the Soar distribution for end-users is in the Release-Support repository.

Soar Builds

For binary builds of Soar you can get them in two places:

• Official Releases
• Latest Successful Development Build: click the latest run and scroll down to "Artifacts".
  • If the download for your platform isn't there, the build failed. You'll need to download the result of an earlier build.
  • GitHub cannot build for ARM64 (M-series Macs), so you'll need to build from source or use the release version instead.

Soar Performance

Some performance statistics are calculated automatically using the Factorization Stress Tests. You can see performance on a commit-by-commit basis either in Performance.md or here. The raw data used to generate the graphs for each build can be found here.

Disclaimer: These are worst case tests. Average performance is probably much higher. In addition, these show that even in worst case, Soar beats its goal of 50 msec reactivity (in these tests, the max is ~30msec per decision).

Development

The Soar project builds with scons, see build with scons, but an alternative build based on CMake, see CMake section, is under development.

The following table provides a comparison of supported build features for Soar between both build systems.

| Feature | Scons | CMake | | --------------------------------- | ----- | ----- | | Soar dynamic lib | ✅ | ✅ | | Soar static lib | ❌ | ✅ | | Soar CLI | ✅ | ✅ | | Unit tests | ✅ | ✅ | | Performance tests | ✅ | ✅ | | External lib test | ✅ | ✅ | | SVS | ✅ | ❌ | | SWIG Python | ✅ | ✅ | | SWIG Java | ✅ | ✅ | | SWIG JavaScript | ❌ | ✅ | | SWIG C# | ✅ | ❌ | | SWIG TCL | ✅ | ❌ | | Python package soar-sml | ✅ | ❌ | | Generate compile commands | ✅ | ✅ | | Release | ✅ | ✅ | | Debug | ✅ | ✅ | | Debug with address sanitizer | ❌ | ✅ | | Conan package manager integration | ❌ | ✅ | | MacOS | ✅ | ✅ | | Linux | ✅ | ✅ | | Windows | ✅ | ❌ | | Java builds (Debugger) | ✅ | ❌ |

Prerequisites

The instructions below are cursory and may be out of date; the most up-to-date instructions for compiling Soar from source will always be the CI build scripts. You can find them here.

To compile Soar, you will need the dependencies listed below. Note that the installation commands are not complete, e.g. missing instructions for Mac do not mean that the dependency is not needed on Mac, etc.:

• C/C++ compiler
  • Mac: xcode-select --install
  • Linux: sudo apt-get install build-essential
• Python
  • Mac: brew install python
• Java
  • We recommend using SDKMan. The debugger, etc. require Java 11 at a minimum, but it's best to install the latest LTS. Temurin is recommended.

To compile the extra SML wrapper libs, you will need the following:

• pkg-config
  • Mac: brew install pkg-config
  • Linux: sudo apt install pkgconf
• SWIG
  • Mac: brew install swig
  • Linux: sudo apt install swig
• Python development headers (only needed for Python wrapper)
  • Linux: sudo apt install python3-dev
• C# compiler (csc) (only needed for C# wrapper)
  • Mac: brew install mono
• Tcl (only needed for Tcl wrapper and TclSoarlib)
  • Mac: brew install tcl-tk

Build with Scons

The project supports generating compile_commands.json, which can be used by e.g. VSCode with the C/C++ plugin to provide IntelliSense. To generate this file, run scons with the cdb target:

   python3 scons/scons.py --scu --opt --verbose cdb

Note for M-series Mac users: you'll want to make sure you're compiling for ARM64, not x86_64. Sometimes users have Python installed in compatibility mode, leading to compiles for the wrong architecture. You can check which architecture your Python is built for using this:

import sysconfig
>>> print(sysconfig.get_config_vars())

You can also check your clang's default compile target using clang --version.

To compile everything for local development, you can use the following command:

   python3 scons/scons.py --scu --dbg --verbose all

Debug mode enables debugging, but also activates assertions, which are important for catching bugs early. --scu (single compilation unit) simplifies the debugging experience.

If you want an optimized build instead:

    python3 scons/scons.py --opt --verbose all

Build with CMake

The following prerequisites must be available:

• CMake
• Python3, including pip for the conan package manager.

Once the dependencies are set up, the project can be built with the build.sh script.

The VS Code extension for CMake should also work for triggering build and install commands, adding build problems to the warnings.

The CMake build system for Soar includes a set of build presets setting defaults for several build options. See CMakePrestes.json for options. Using these presets requires the installation of debug and release dependencies by Conan, due to the resolution of dependencies via CMake toolchains:

conan install . --build=missing
conan install . --build=missing -s build_type=Debug

Afterwards, different presets can be built with

cmake --preset Debug-test
cmake --build --preset Debug-test

or predefined workflows can be run with the following command, running configure, build and test stages:

cmake --workflow --preset Debug-test-workflow

The default options are covered through presets conan-release and conan-debug provided by Conan. Extensions, like VS Code CMake tools, integrate well with these presets. A list of all presets is availble via cmake --list-presets or for workflows with cmake --workflow --list-presets.

License

Soar is available under the following LICENSE. This license is BSD