Skip to content

Added clarification to the README #447

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jcd288 wants to merge 2 commits into
base: master
Choose a base branch
from
+23 −4
Open

Added clarification to the README #447

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4407134
Add files via upload
jcd288 Apr 25, 2026
dad06fe
Merge pull request #1 from jcd288/jcd288-readme-clarification
jcd288 Apr 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 23 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,8 @@ deepstate-afl ./TCAS_AFL -o fuzz_afl --fuzzer_out --timeout 120
llvm-cov-9 gcov TCAS_driver.cpp -b
```

For more information on running DeepState with a Docker, go to the "Docker" section at the bottom of the README

This runs the AFL++ fuzzer on the TCAS code (https://en.wikipedia.org/wiki/Traffic_collision_avoidance_system), a long-used example program in software testing. After two minutes of fuzzing, we run a version of the test driver that collects code coverage, and see how much of the code AFL has managed to cover in two minutes.

NOTE 1: The above docker is built using AFL++ instead of AFL for "AFL" fuzzing. You can use agroce/deepstate_examples instead if for some reason you prefer "classic" AFL.
Expand Down Expand Up @@ -114,10 +116,10 @@ yet, without a painful cross-compilation process). No current support for ARM64

Build:

- CMake
- GCC and G++ with multilib support
- Python 3.6 (or newer)
- Setuptools
- CMake: Available on most Linux distros, Windows 8, 10, and 11, and MacOS 10.10 or later
- GCC and G++ with multilib support: Available on Ubuntu 18.04 or later, Debian, Fedora, and Arch Linux. For Windows, MinGW and MSYS2 can be used as alternatives
- Python 3.6 (or newer): Available on almost all major Linux distros, Windows 8.1 or later, and MacOS 10.9 or later
- Setuptools: Available on all OS's that can run Python 3.6 or newer

Runtime:

Expand Down Expand Up @@ -309,6 +311,23 @@ ERROR: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is th
systemctl start docker
```

## Troubleshooting

**I am getting an error when trying to intall DeepState on Linux**

Make sure that you have sudo/installation priveleges on your current system. Additionally, ensure that your
system has multilib compiler support. Check the file permissions to make sure that you are even able to access
DeepState in the first place.

**I am on macOS and am getting an "Architecture not supported" error when trying to run DeepState**

This means that you are likely using a system with an ARM CPU, which is not currently supported by DeepState.

**Where can I find all of the fail states that DeepState discovered?**

DeepState creates a .fail file when it runs and saves it in an output directory within the current folder. This can be used to find bugs or errors
in your code.

## Documentation

Check out [docs](/docs) folder:
Expand Down