soar-sml 9.6.4
Raw SML Bindings to the Soar Cognitive Architecture
License: BSD
Requires Python: >=3.5
Keywords: soar, sml, cog-arch, cognitive architecture, cognitive, soar-sml, ai


# Soar

[![Build/Test](https://github.com/SoarGroup/Soar/actions/workflows/build.yml/badge.svg)](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                 | ✅     | ✅     |
| Exnternal lib test                | ✅     | ✅     |
| SVS                               | ✅     | ❌     |
| SWIG                              | ✅     | ❌     |
| 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)