https://github.com/SoarGroup/Soar
Soar, a general cognitive architecture for systems that exhibit intelligent behavior.
https://github.com/SoarGroup/Soar
Last synced: about 2 months ago
JSON representation
Soar, a general cognitive architecture for systems that exhibit intelligent behavior.
- Host: GitHub
- URL: https://github.com/SoarGroup/Soar
- Owner: SoarGroup
- License: other
- Created: 2014-06-25T14:50:12.000Z (almost 12 years ago)
- Default Branch: development
- Last Pushed: 2025-12-31T20:48:02.000Z (4 months ago)
- Last Synced: 2026-01-05T07:35:48.077Z (4 months ago)
- Language: C++
- Homepage: http://soar.eecs.umich.edu
- Size: 236 MB
- Stars: 392
- Watchers: 35
- Forks: 82
- Open Issues: 173
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
- awesome-java - Soar
README
# Soar
[](https://github.com/SoarGroup/Soar/actions/workflows/build.yml)
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](http://soar.eecs.umich.edu/)
- [The GitHub project page](https://github.com/SoarGroup/Soar)
Note that the readme included with the Soar distribution for end-users is in the
[Release-Support](https://github.com/SoarGroup/Release-Support/blob/master/txt/README)
repository.
## Soar Builds
For binary builds of Soar you can get them in two places:
- [Official Releases](http://soar.eecs.umich.edu/articles/downloads/soar-suite)
- [Latest Successful Development Build](https://github.com/SoarGroup/Soar/actions/workflows/build.yml?query=branch%3Adevelopment): 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](https://github.com/SoarGroup/Soar/blob/development/Performance.md)
or [here](http://soar-jenkins.eecs.umich.edu/Performance/). The raw data used to
generate the graphs for each build can be found
[here](http://soar-jenkins.eecs.umich.edu/Performance/).
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](#build-with-scons),
but an alternative build based on `CMake`, see
[CMake section](#build-with-cmake), 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](.github/workflows/build.yml).
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](https://sdkman.io/). 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:
```shell
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:
```python
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:
```shell
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:
```shell
python3 scons/scons.py --opt --verbose all
```
### Build with CMake
The following prerequisites must be available:
- CMake
- Python3, including pip for the [conan](https://conan.io) package manager.
Once the dependencies are set up, the project can be built with the
[`build.sh` script](./build.sh).
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](./CMakePresets.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:
```shell
conan install . --build=missing
conan install . --build=missing -s build_type=Debug
```
Afterwards, different presets can be built with
```shell
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:
```shell
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](https://github.com/SoarGroup/Soar/blob/development/LICENSE.md). This
license is [BSD](http://opensource.org/licenses/BSD-2-Clause)