Soufflé

https://souffle-lang.github.io/
Admin
Soufflé is a logic-based programming language designed for rapid prototyping of static analysis...
Tokens:56,750
Snippets:793
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Soufflé

Source: https://souffle-lang.github.io/build

Builds and installs Soufflé to the specified installation directory after configuration. This makes the Soufflé executable available in the system's PATH.

```bash
cmake --build build --target install
```

--------------------------------

### Install Ubuntu/Debian Dependencies

Source: https://souffle-lang.github.io/build

Installs the necessary dependencies to compile and build Soufflé on Ubuntu/Debian systems using apt.

```bash
sudo apt install \
  bison \
  build-essential \
  clang \
  cmake \
  doxygen \
  flex \
  g++ \
  git \
  libffi-dev \
  libncurses5-dev \
  libsqlite3-dev \
  make \
  mcpp \
  python \
  sqlite3 \
  zlib1g-dev

```

--------------------------------

### Install Soufflé on Fedora

Source: https://souffle-lang.github.io/install.html

Installs Soufflé on Fedora systems using DNF. This method is compatible with Fedora 36 and later. For older versions, building from source is recommended.

```bash
dnf install https://souffle-lang.github.io/ppa/fedora/36/x86_64/souffle.fedora36repo.rpm
dnf install souffle
```

--------------------------------

### Soufflé Program Example

Source: https://souffle-lang.github.io/program

This example demonstrates the basic structure of a Soufflé program, including relation declarations, facts, rules, and an output directive. Relations must be declared before use, and facts represent unconditional truths. Rules define conditional relationships between relations.

```Soufflé
.decl A(x:number, y:number)  // declaration of relation A
A(1,2).                      // facts of relation A
A(2,3).

.decl B(x:number, y:number)  // declaration of relation B
B(x,y) :- A(x,y).            // rules of relation B
B(x,z) :- A(x,y), B(y,z).

.output B                    // Output relation B 

```

--------------------------------

### Install Fedora Dependencies

Source: https://souffle-lang.github.io/build

Installs the necessary dependencies to compile and build Soufflé on Fedora systems using dnf.

```bash
sudo dnf install bison flex libffi-devel sqlite-devel zlib-devel

```

--------------------------------

### Install Soufflé on MAC OS X using Homebrew

Source: https://souffle-lang.github.io/install.html

Installs Soufflé on macOS using the brew package manager. This command automates the build and installation process.

```bash
brew install --HEAD souffle-lang/souffle/souffle
```

--------------------------------

### Install Soufflé on Debian/Ubuntu Systems

Source: https://souffle-lang.github.io/install.html

Installs Soufflé using the souffle-lang repository. Ensure your system is Ubuntu 20.04 or later. Older versions may require building from source.

```bash
sudo wget https://souffle-lang.github.io/ppa/souffle-key.public -O /usr/share/keyrings/souffle-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/souffle-archive-keyring.gpg] https://souffle-lang.github.io/ppa/ubuntu/ stable main" | sudo tee /etc/apt/sources.list.d/souffle.list
sudo apt update
sudo apt install souffle
```

--------------------------------

### Input Facts for Pathfinding Example

Source: https://souffle-lang.github.io/simple

Provides sample tab-separated facts for the `edge` relation, representing direct connections in a graph.

```text
1	2
2	3

```

--------------------------------

### Example Adornment Calculation

Source: https://souffle-lang.github.io/magicset

Illustrates the adornment process for a given query and its body atoms, showing how initial free variables become bound through constraints and intermediate atoms.

```souffle
query(x) :- a(x,y,z), c(z,y), y = "foo".
```

```souffle
query_f(x) :- a_fbf(x,y,z), c_bb(z,y), y = "foo".
```

--------------------------------

### Configure Soufflé Installation Path

Source: https://souffle-lang.github.io/build

Sets the installation directory for Soufflé using CMake. Replace '<install-dir>' with your desired absolute path. This ensures executables and headers are placed correctly.

```bash
cd souffle
cmake -S . -B build -DCMAKE_INSTALL_PREFIX=<install-dir>
```

--------------------------------

### Install Build Dependencies on macOS

Source: https://souffle-lang.github.io/build

Installs necessary tools like cmake, bison, libffi, mcpp, and pkg-config using Homebrew. It also ensures the correct versions are linked and sets up the PKG_CONFIG_PATH.

```bash
brew update
brew install cmake bison libffi mcpp pkg-config
brew reinstall gcc
brew link bison --force
brew link libffi --force
export PKG_CONFIG_PATH=/usr/local/opt/libffi/lib/pkgconfig/
```

--------------------------------

### Soufflé Performance Tuning Example

Source: https://souffle-lang.github.io/tutorial

Illustrates performance tuning by defining an 'Edge' relation with recursive generation and a 'Path' relation. The commented-out lines show different strategies for computing paths, which can be benchmarked.

```souffle
.decl Edge(x:number, y:number)
Edge(1,2).
Edge(500,1).
Edge(i+1,i+2) :- Edge(i,i+1), i < 499.

.decl Path(x:number, y:number)
.printsize Path
Path(x,y) :- Edge(x,y).
// Path(x,z) :- Path(x,y), Path(y,z). .strict
// Path(x,z) :- Path(x,y), Edge(y,z). .strict
// Path(x,z) :- Edge(x,y), Path(y,z). .strict

```

--------------------------------

### Constraint Normalisation Example

Source: https://souffle-lang.github.io/magicset

Demonstrates constraint normalization where constants in atoms are replaced by variables and constrained.

```souffle
a(x) :- b("foo", x).

```

```souffle
a(x) :- b(var, x), var = "foo".

```

--------------------------------

### Soufflé Program with Cross-Product

Source: https://souffle-lang.github.io/handtuning

This example demonstrates a Soufflé program that uses a cross-product, leading to quadratic complexity. It defines relations A, B, C, and D, where C is a cross-product of A and B.

```souffle
#define N 10000
.decl A,B(x:number)
A(1).
A(x+1) :- A(x), x < N.
B(x) :- A(x).

.decl C(x:number, y:number) 
C(x, y) :- A(x), B(y).

.decl D(x:number, y:number) 
D(x,x) :- C(x,x).
.printsize D

```

--------------------------------

### Complete Souffle Program Execution Example

Source: https://souffle-lang.github.io/interface

Demonstrates the full lifecycle of a Souffle program: instantiation, loading data, inserting tuples, running the program, retrieving results, and printing output. Includes error handling for key operations.

```cpp
#include <souffle/SouffleInterface.h>

int main() {
    if (souffle::SouffleProgram *prog = souffle::ProgramFactory::newInstance("<name>")) {
        prog->loadAll("<dir>");

        if (souffle::Relation *rel = prog->getRelation("<in-rel>")) {
            souffle::tuple myTuple(rel);
            myTuple << "Hello" << souffle::RamSigned(10);
            rel->insert(myTuple);
        } else {
            std::cerr << "Failed to get input relation\n";
            return 1;
        }

        prog->run();

        if (souffle::Relation *rel = prog->getRelation("<out-rel>")) {
            souffle::RamSigned myInt;
            std::string mySymbol;
            for (auto &output : *rel) {
                output >> mySymbol >> myInt;
            }

            souffle::tuple myTuple(rel);
            myTuple << "A" << souffle::RamSigned(123);
            if (rel->contains(myTuple)) {
            }
        } else {
            std::cerr << "Failed to get output relation\n";
            return 1;
        }

        prog->printAll();

        delete prog;
    } else {
        std::cerr << "Failed to create instance\n";
        return 1;
    }
    return 0;
}


```

--------------------------------

### Soufflé Program for Provenance Example

Source: https://souffle-lang.github.io/provenance

A simple Soufflé program defining 'edge' and 'path' relations to demonstrate provenance features.

```souffle
.decl edge, path(x:number, y:number)
edge(1, 2).
edge(2, 3).
edge(3, 4).
edge(4, 5).

path(x, y) :- edge(x, y).
path(x, z) :- edge(x, y), path(y, z).

```

--------------------------------

### Component Instantiation with Type Parameters

Source: https://souffle-lang.github.io/components

Shows how type parameters can control component instantiation, enabling different behaviors based on the selected parameter. The example illustrates how `Case<One>` results in specific internal code.

```souffle
.decl R(x:number)
.comp Case<Selector> {
   .comp One { 
     R(1). 
   } 
   .comp Two { 
     R(2). 
   } 
   .init selection = Selector // instantiation depending on type parameter "Selector"
} 
.init myCase = Case<One> 
.output R
```

```souffle
.decl R(x:number) 
R(1). 
.output R
```

--------------------------------

### Build Soufflé with Docker

Source: https://souffle-lang.github.io/build

Use this Dockerfile to build a Soufflé image and then run it to compile Soufflé from sources. The resulting package can be installed using the system's package manager.

```bash
# Build the image that will build souffle from sources
#
# For Fedora 41:
# Other distributions are available too.
docker build . -f ./.github/images/fedora-41/Dockerfile -t souffle-builder-image

# Actually build souffle and create a package
#
# Look for message 'CPack: - package: /souffle/build/souffle-VERSION-OS.EXTENSION'
#
docker run --name souffle-builder -e DOMAIN_SIZE="64bit" -t souffle-builder-image

# Copy the package onto your system
docker cp souffle-builder:/souffle/build/souffle-VERSION-OS.EXTENSION .

# Use your system package manager to install souffle from the package.
#
# For DNF package manager (.rpm package extension):
dnf install souffle-VERSION-OS.rpm

```

--------------------------------

### Inlining Transformation: Unification and Substitution

Source: https://souffle-lang.github.io/relations

Illustrates the inlining process, including unification of arguments and substitution of rule bodies. This example shows how 'a(y,z)' is replaced in the rule for 'b(x)'.

```souffle
.decl a(x:number, y:number) inline
a(x,y) :- d(x,x), e(y).
a(x,y) :- f(y,x).

```

```souffle
b(x) :- c(x,z), b(y), a(y,z).

```

```souffle
a(x0,y0) :- d(x0,x0), e(y0).
a(x0,y0) :- f(y0,x0).

```

```souffle
d(y,y), e(z).
f(z,y).

```

```souffle
b(x) :- c(x,z), b(y), d(y,y), e(z).
b(x) :- c(x,z), b(y), f(z,y).

```

--------------------------------

### Instantiate a Soufflé Component

Source: https://souffle-lang.github.io/components

Instantiate a declared component using `.init` followed by an instance name and the component declaration name. This example shows how to instantiate and then use the component's relations in a rule.

```souffle
.init myInstance1 = MyComponent

.decl Test(x:number)
Test(x) :- myInstance1.TheAnswer(x).
.output Test
```

--------------------------------

### Expected Output for Pathfinding Example

Source: https://souffle-lang.github.io/simple

Shows the computed `path` relation results after evaluating the Datalog program with the given input facts. Includes direct edges and transitive paths.

```text
1	2
2	3
1	3

```

--------------------------------

### Printsize Directive Example

Source: https://souffle-lang.github.io/directives

Prints the name and the number of tuples in a relation. The output is separated by a tabulator symbol.

```Datalog
.decl A(x:number)
A(1).
A(2).
.printsize A

```

--------------------------------

### Rule Specialization Example

Source: https://souffle-lang.github.io/magicset

Illustrates how the magic set transformation specializes a rule based on constraints in its body and dependencies.

```souffle
a(x,y) :- b(x,z), c(y,z).
query(x) :- a("foo", x), !g(x).

```

```souffle
a("foo", y) :- b("foo", z), c(y,z).
query(x) :- a("foo", x), !g(x).

```

--------------------------------

### Soufflé Rule Example with Relations

Source: https://souffle-lang.github.io/rules

Defines relations A and B, inputs A, and establishes rules for B based on A and recursive calls to B. This demonstrates basic rule definition and recursion.

```souffle
.decl A, B(x:number, y:number)
.input A
B(x,y) :- A(x,y).
B(x,z) :- A(x,y), B(y,z).
.output B
```

--------------------------------

### Inlining Example: Natural Numbers and Pairs

Source: https://souffle-lang.github.io/relations

Demonstrates inlining 'natural_pairs' to avoid computing a large intermediate relation. The transformed program replaces 'natural_pairs' with its definition.

```souffle
.decl natural_number(x:number)
natural_number(0).
natural_number(x+1) :- natural_number(x), x < 10000.

.decl natural_pairs(x:number, y:number) inline
natural_pairs(x,y) :- natural_number(x), natural_number(y).

.decl query(x:number)
query(x) :- natural_pairs(x,y), x < 5, y < x.

```

```souffle
.decl natural_number(x:number)
natural_number(0).
natural_number(x+1) :- natural_number(x), x < 10000.

.decl query(x:number)
query(x) :- natural_number(x), natural_number(y), x < 5, y < x.

```

--------------------------------

### Optimized Soufflé Program without Cross-Product

Source: https://souffle-lang.github.io/handtuning

This is the manually optimized version of the previous example. By removing the cross-product and directly relating A and B in the rule for D, the runtime complexity is reduced to linear.

```souffle
#define N 10000
.decl A,B(x:number)
A(1).
A(x+1) :- A(x), x < N.
B(x) :- A(x).


.decl D(x:number, y:number) 
D(x,x) :-  A(x), B(x).
.printsize D

```

--------------------------------

### Soufflé Aggregate Function Syntax Examples

Source: https://souffle-lang.github.io/aggregates

Demonstrates syntactically correct uses of min, max, sum, and count aggregate functions in Soufflé rules. Ensure variables in numeric expressions are grounded.

```souffle
B(y) :- y = max z : A("A", z).
B(z) :- z = min x+y : { A(x), A(y), C(y) }.
B(s, c) :- W(s), c = count : { C(s, _) }.
B(s, count : { C(s, _) }) :- W(s).
B(n, m) :- A(n, m), B(m, s), 2 * s = 2 * sum s : { A(n, s) } + 2.
C(n) :- D(n), B(n, max p : { A(n, p) }).
```

--------------------------------

### Soufflé Program with Inline Qualifier

Source: https://souffle-lang.github.io/handtuning

This example shows how to apply the 'inline' qualifier to a relation to avoid materializing a cross-product, thus reducing computation and storage complexity. Relation C is marked as inline.

```souffle
...
.decl C(x:number, y:number) inline 
...

```

--------------------------------

### Declare a Soufflé Component

Source: https://souffle-lang.github.io/components

Use the `.comp` keyword to declare a new component, followed by its name and a block of elements. This example shows a component with a type, relation, and fact.

```souffle
.comp MyComponent {
    .type myType = number
    .decl TheAnswer(x:myType)    // component relation
    TheAnswer(42).               // component fact
}
```

--------------------------------

### Transitive Closure Example in Soufflé

Source: https://souffle-lang.github.io/tutorial

Defines a directed graph and computes its transitive closure using Soufflé's Datalog syntax. Includes base and inductive rules for reachability.

```Soufflé
.decl edge(n: symbol, m: symbol)
edge("a", "b"). /* facts of edge */
edge("b", "c").
edge("c", "b").
edge("c", "d").
.decl reachable (n: symbol, m: symbol)
.output reachable // output relation reachable
reachable(x, y):- edge(x, y). // base rule
reachable(x, z):- edge(x, y), reachable(y, z). // inductive rule

```

--------------------------------

### Using Wildcards in Soufflé Aggregates

Source: https://souffle-lang.github.io/aggregates

Shows how to use wildcards to compute statistics over a subset of columns. This example finds the overall smallest value of the second attribute, ignoring the first. Fails if the relation is empty.

```souffle
min Z : a(_,Z).
```

--------------------------------

### Defining and Using Records

Source: https://souffle-lang.github.io/tutorial

Records provide a way to structure data beyond simple relations. This example defines a `Pair` record and then maps it to a flat relation `Flatten` for output, simulating record output before official support.

```souffle
// Pair of numbers
.type Pair = [a:number, b:number]

.decl A(p: Pair)  // declare a set of pairs
A([1,2]).
A([3,4]).
A([4,5]).

.decl Flatten(a:number, b:number) output
Flatten(a,b) :- A([a,b]).

```

--------------------------------

### Configure and Build Soufflé

Source: https://souffle-lang.github.io/build

Navigates to the Soufflé directory, configures the build using CMake, and then builds the project. Ensure you are in the 'souffle' directory before running these commands.

```bash
cd souffle
cmake -S . -B build
cmake --build build
```

--------------------------------

### Install Soufflé on Oracle Linux 8

Source: https://souffle-lang.github.io/install.html

Installs Soufflé on Oracle Linux 8 using DNF. This package is likely compatible with CentOS 8. If installation fails, consider building from source.

```bash
dnf install https://souffle-lang.github.io/ppa/ol/8/x86_64/souffle.ol8repo.rpm
dnf install souffle
```

--------------------------------

### Enable Provenance with Explain Interface

Source: https://souffle-lang.github.io/provenance

Use the -t explain command-line option to enable the provenance system with a standard output interface for debugging.

```bash
souffle -t explain foo.dl
```

--------------------------------

### Soufflé Comments

Source: https://souffle-lang.github.io/program

Soufflé supports C/C++ style inline comments starting with // and block comments starting with /* and ending with */.

```souffle
// an inline comment

/* this is
 * a comment block
 */
```

--------------------------------

### Multiple Component Instantiations

Source: https://souffle-lang.github.io/components

Demonstrates instantiating the same component multiple times. Each instance maintains its own namespace, allowing for distinct data and rules.

```souffle
.init myInstance1 = MyComponent
.init myInstance2 = MyComponent
myInstance2.TheAnswer(33).

.decl Test(x:number)
Test(x) :- myInstance1.TheAnswer(x). 
Test(x) :- myInstance2.TheAnswer(x).
.output Test
```

--------------------------------

### Explain Tuple Proof Tree

Source: https://souffle-lang.github.io/provenance

Use the 'explain' command to print the proof tree for a specific tuple, showing all input and intermediate tuples required for its derivation.

```bash
> explain path(1, 3)
         edge(2, 3)
         -------(R1)
edge(1, 2) path(2, 3)
-------------------(R2)
    path(1, 3)

```

--------------------------------

### Instantiate and Run Soufflé Program in Python

Source: https://souffle-lang.github.io/swig

Create an instance of a Datalog program, load input, run it, and print outputs in Python using the SWIG interface.

```python
p = SwigInterface.newInstance("<name of .dl file without extension>")

p.loadAll('.')

p.run()

p.printAll('.')
```

--------------------------------

### Loading a program

Source: https://souffle-lang.github.io/interface

Create an instance of a Soufflé program using the `ProgramFactory`.

```APIDOC
## Loading a program

### Description
Creates an instance of a program by name. Returns `nullptr` if the program could not be found.

### Method Signature
`souffle::SouffleProgram* souffle::ProgramFactory::newInstance(std::string)`

### Example
```cpp
if (souffle::SouffleProgram *prog = souffle::ProgramFactory::newInstance("<name>")) {
    // Run the program...

    // Clean up
    delete prog;
} else {
    std::cerr << "Failed to create instance\n";
    exit(1);
}
```
```

--------------------------------

### Instantiate and Run Soufflé Program in Java

Source: https://souffle-lang.github.io/swig

Create an instance of a Datalog program, load input, run it, print outputs, and finalize in Java using the SWIG interface.

```java
SWIGSouffleProgram p = SwigInterface.newInstance("<name of .dl file without extension>")

p.loadAll(".")

p.run()

p.printAll(".")

p.finalize()
```

--------------------------------

### Run Soufflé Profiler in Offline Mode

Source: https://souffle-lang.github.io/profiler

Starts the text-user interface in offline mode by default, processing a specified log file.

```bash
souffleprof <file>

```

--------------------------------

### Get Souffle Relation Size

Source: https://souffle-lang.github.io/interface

Returns the total number of tuples currently stored in a relation. This is useful for understanding the state of the relation.

```cpp
rel->size();

```

--------------------------------

### Same Generation Example in Soufflé

Source: https://souffle-lang.github.io/tutorial

Defines relations to find nodes on the same level in a tree structure. Requires relations for parent-child relationships and person identification.

```souffle
.decl Parent(n: symbol, m: symbol)
Parent("d", "b"). Parent("e", "b"). Parent("f","c").
Parent("g", "c"). Parent("b", "a"). Parent("c","a").
.decl Person(n: symbol)
Person(x) :- Parent(x, _).
Person(x) :- Parent(_, x).
.decl SameGeneration (n: symbol, m: symbol)
SameGeneration(x, x):- Person(x).
SameGeneration(x, y):- Parent(x,p), SameGeneration(p,q), Parent(y,q).
.output SameGeneration

```

--------------------------------

### Get Souffle Relation Signature

Source: https://souffle-lang.github.io/interface

Retrieves the signature of a relation, which describes the types of its attributes. The format is '<primitive type>:<type name>,...'.

```cpp
rel->getSignature();

```

--------------------------------

### Run Soufflé Executable Help

Source: https://souffle-lang.github.io/development

Run the main Soufflé executable with the --help option to view usage information. The executable is located at `//src/souffle` relative to the repository root.

```bash
./src/souffle --help
```

--------------------------------

### Soufflé Variable Definition

Source: https://souffle-lang.github.io/arguments

Defines variables, which can be named identifiers or unnamed underscores. Identifiers starting with an underscore are also considered unnamed named variables.

```souffle
variable ::= IDENT | '_'

```

--------------------------------

### Finding the Maximum Value

Source: https://souffle-lang.github.io/tutorial

The `max` functor returns the maximum value of a variable across all tuples in a sub-goal. This example finds the maximum number in relation `A`.

```souffle
.decl A(n:number)
A(1). A(10). A(100).
.decl MaxA(x: number)
MaxA(y) :- y = max x:{A(x)}.
 .output MaxA

```

--------------------------------

### Counting Elements in a Relation

Source: https://souffle-lang.github.io/tutorial

The `count` functor calculates the number of tuples in a sub-goal. This example counts the number of cars with the color 'blue' from the `Car` relation.

```souffle
.decl Car(name: symbol, colour:symbol)
Car("Audi", "blue").
Car("VW", "red").
Car("BMW", "blue").

.decl BlueCarCount(x: number)
BlueCarCount(c) :- c = count:{Car(_,"blue")}.
 .output BlueCarCount

```

--------------------------------

### Soufflé Program with Range Functor

Source: https://souffle-lang.github.io/aggregates

Example of using the range functor to populate a relation with numbers from 1 to 4. The output relation 'A' will contain these values.

```souffle
.decl A(x:number)
A(x) :- x = range(1,5,1). 
.output A
```

--------------------------------

### Compile Datalog Program to C++

Source: https://souffle-lang.github.io/simple

Transforms the Datalog program into a C++ source file and an executable. The `-oexample` option names the output C++ file and executable.

```bash
./src/souffle -F. -D. -oexample example.dl

```

--------------------------------

### Disallowed Nested Aggregates in Soufflé

Source: https://souffle-lang.github.io/aggregates

Shows an example of disallowed nested aggregates. Soufflé does not permit nesting aggregate functions within other aggregate functions.

```souffle
D(s) :- s = sum y : { Prime(n), y = sum z : { Prime(z), z < n }, y < 10 }.
```

--------------------------------

### Soufflé Input/Output Directives

Source: https://souffle-lang.github.io/tutorial

Illustrates how to declare relations and specify input/output operations using .input, .output, and .printsize directives.

```souffle
.decl A(n: symbol)
.input A // facts are read from file A.facts

.decl B(n: symbol)
B(n) :- A(n).

.decl C(n: symbol)
.output C // output appears in C.csv
C(n) :- B(n).

.decl D(n: symbol)
.printsize D // the number of facts in D is printed
D(n) :- C(n).

```

--------------------------------

### Get Relation by Name in Souffle

Source: https://souffle-lang.github.io/interface

Retrieves a relation from the program by its name. Returns nullptr if the relation is not found. Use this to access and manipulate relation data.

```cpp
if (souffle::Relation *rel = prog->getRelation("<out-rel>")) {
    int myInt;
    std::string mySymbol;
    for (auto &output : *rel) {       // Iterate through the tuples in the output relation
      output >> mySymbol >> myInt; // Read symbols and integers from each tuple
                                      // (Data-types must match those of <out-rel>)
    }
} else {
    std::cerr << "Failed to get output relation\n";
    exit(1);
}

```

--------------------------------

### Naive Rule Scheduling Translation in Soufflé

Source: https://souffle-lang.github.io/handtuning

Illustrates a naive translation of a Datalog rule into nested loops, highlighting potential inefficiencies.

```souffle
C(X,Z) :- A(X,Y), B(Y,Z).

```

```c++
for( e1 : A ) {
    for( e2 : B ) {
        if ( e1[1] == e2[0] ) {
            C.insert( e1[0], e2[1] );
        }
    }
}

```

--------------------------------

### Soufflé Profiler Help

Source: https://souffle-lang.github.io/simple

Displays the help message for the `souffleprof` tool, listing available options for analyzing profiling data.

```bash
./src/souffleprof -h

```

--------------------------------

### Configure and Build Soufflé on Linux

Source: https://souffle-lang.github.io/build

Configures the Soufflé project using CMake and then builds it. C++17 support is required. Options can be specified during the CMake configuration step.

```bash
cd souffle
cmake -S . -B build ## example of options: -DCMAKE_BUILD_TYPE=Release -DSOUFFLE_DOMAIN_64BIT=ON
cmake --build build

```

--------------------------------

### Use Union Type for Relation in Soufflé

Source: https://souffle-lang.github.io/types

This example shows how a union type 'Place' can be used in a relation declaration, allowing it to accept values from its constituent subtypes.

```souffle
.type City <: symbol
.type Town <: symbol
.type Village <: symbol
.type Place = City | Town | Village
.decl Data(c:City, t:Town, v:Village)
Data("Sydney", "Ballina", "Glenrowan").

.decl Location(p:Place)
.output Location
Location(p) :- Data(p,_,_); Data(_,p,_); Data(_,_,p).
```

--------------------------------

### Datalog Declaration for Pure Functors

Source: https://souffle-lang.github.io/functors

Declare pure functors in Soufflé's Datalog syntax. This example shows the declaration for the C++ functors 'f' and 'g'.

```datalog
.functor f(x:number):number
.functor g():symbol
```

--------------------------------

### Invoke a User-Defined Functor

Source: https://souffle-lang.github.io/functors

User-defined functors are invoked using prefix notation with the '@' symbol. This example shows a functor 'f' used within a Soufflé rule.

```souffle
// introduce new functor f: number -> number
.functor f(x:number):number


.decl A(x:number) 
.output A
A(1). 
A(@f(i)) :- A(i), @f(i) < 100.

```

--------------------------------

### List Directory

Source: https://souffle-lang.github.io/development

Verify that the Soufflé directory has been created after cloning.

```bash
ls
souffle
```

--------------------------------

### Component Declaration with Type Parameterization and Inheritance

Source: https://souffle-lang.github.io/components

Demonstrates how to declare a component with a type parameter and how another component can inherit from it, specifying the type parameter.

```souffle
.comp A<T> { .... }
.comp B<K> : A<K> { ... }
```

--------------------------------

### Soufflé Rule with Disjunctions in Body

Source: https://souffle-lang.github.io/tutorial

This example showcases syntactic sugar for disjunctions in rule bodies, simplifying complex rule definitions. It presents the concise version and its expanded equivalent.

```Soufflé
.decl edge(x:number, y:number)
edge(1,2). edge(2,3).
.decl path(x:number, y:number)
path(x,y) :-
  edge(x,y);
  edge(x,q), path(q,y).
.output path
```

```Soufflé
.decl edge(x:number, y:number)
edge(1,2). edge(2,3).
.decl path(x:number, y:number)
path(x,y) :- edge(x,y).
path(x,y) :- edge(x,q), path(q,y).
```

--------------------------------

### Running the program

Source: https://souffle-lang.github.io/interface

Execute the loaded Soufflé program.

```APIDOC
## Running the program

### Description
Executes the program, without any loads or stores.

### Method Signature
`void souffle::SouffleProgram::run()`

### Example
```cpp
prog->run();
```
```

--------------------------------

### Soufflé Rule with Grounded Variable

Source: https://souffle-lang.github.io/rules

Corrects the previous example by shifting the index, ensuring the variable 'idx' is grounded in a positive predicate argument. This program is guaranteed to have grounded variables.

```souffle
.decl fib(idx:number, value:number)
fib(1,1).
fib(2,1).
fib(idx+1, x + y) :- fib(idx, x), fib(idx-1, y), idx <= 9.
.output fib
```

--------------------------------

### Haskell Type Error for Unknown Fact

Source: https://souffle-lang.github.io/haskell.html

Example of a Haskell compiler type error when attempting to add a fact that is not defined within the Soufflé program's known facts.

```haskell
Example.hs:33:3: error:
    • You tried to perform an action with a fact of type 'UnknownFact' for program 'Path'.
      The program contains the following facts: '[Edge, Reachable]'.
      It does not contain fact: UnknownFact.
      You can fix this error by adding the type 'UnknownFact' to the ProgramFacts type
 in the Program instance for Path.
    • In the expression: Souffle.addFact handle
      In the expression: Souffle.addFact handle $ UnknownFact 42
      In an equation for ‘Example.example’:
          Example.example handle
            = Souffle.addFact handle $ UnknownFact 42
   |
33 |   Souffle.addFact handle $ UnknownFact 42
   |   ^^^^^^^^^^^^^^^^^^^^^^
```

--------------------------------

### Run Soufflé Tests

Source: https://souffle-lang.github.io/build

Executes the test suite for Soufflé after building. Navigate to the 'build' directory first. This command runs all configured tests.

```bash
cd build
ctest
```

--------------------------------

### Build Soufflé with Parallel Jobs

Source: https://souffle-lang.github.io/build

Speeds up the Soufflé build process by utilizing multiple CPU cores. Adjust the number '8' based on your system's core count for optimal performance.

```bash
cmake --build build -j8
```

--------------------------------

### Create Soufflé Program Instance

Source: https://souffle-lang.github.io/interface

Instantiate a Soufflé program by its name using the ProgramFactory. Ensure proper error handling if the program cannot be found. Remember to delete the program instance when done.

```cpp
if (souffle::SouffleProgram *prog = souffle::ProgramFactory::newInstance("<name>")) {
    // Run the program...

    // Clean up
    delete prog;
} else {
    std::cerr << "Failed to create instance\n";
    exit(1);
}

```

--------------------------------

### Calculating Sum of Primes with Soufflé

Source: https://souffle-lang.github.io/aggregates

Example of using the sum aggregate to compute the sum of all primes stored in a relation named 'Prime'. The result is stored in a single-valued relation 'S'.

```souffle
.decl S(x:number)

S(n) :- n = sum y : Prime(y).
```

--------------------------------

### Soufflé Number Literals

Source: https://souffle-lang.github.io/tutorial

This example illustrates how to use different number literal formats (decimal, binary, hexadecimal) in Soufflé declarations. Note that only decimal numbers are permitted in fact files.

```Soufflé
.decl A(x:number)
A(4711).
A(0b101).
A(0xaffe).
```

--------------------------------

### Soufflé Legacy Input/Output Syntax

Source: https://souffle-lang.github.io/relations

Demonstrates the legacy syntax for declaring input and output relations, which is now superseded by I/O directives.

```souffle
.decl A(x:number) input 
.decl B(x:number) output
B(x) :- A(x). 

```

--------------------------------

### Soufflé Rule Example

Source: https://souffle-lang.github.io/program

A simple rule stating that a pair (x,y) is in relation A if it is present in relation B. Rules define conditional logic, where the head of the rule is true if the body is true.

```Soufflé
A(x,y) :- B(x,y).

```

--------------------------------

### Modern I/O Directive Syntax

Source: https://souffle-lang.github.io/directives

Shows the recommended way to declare input and output relations using separate .input and .output directives, replacing the legacy syntax.

```souffle
.decl A(x:number, y:symbol)
.input A
.decl B(x:number, y:symbol) 
.output B

```

--------------------------------

### Datalog Declaration for Stateful Functor

Source: https://souffle-lang.github.io/functors

Declare a stateful functor in Soufflé's Datalog syntax. This example declares 'mycat' which can access and manipulate Soufflé's symbol and record tables.

```datalog
.functor mycat(a:symbol, b:symbol):symbol stateful
```

--------------------------------

### Overriding Relations in Soufflé Components

Source: https://souffle-lang.github.io/components

Illustrates how a sub-component can override relations declared as `overridable` in a super-component. The example shows `Sub` overriding `R` from `Base`, discarding super-component facts/rules and applying its own.

```souffle
.comp Base {
    .decl R(x:number) overridable
    R(1).
    R(x+1) :- R(x), x < 5. 
    .output R
}
.comp Sub : Base {
    .override R
    R(2).
    R(x+1) :- R(x), x < 4. 
}
.init mySub = Sub
```

```souffle
.decl mySub.R(x:number)overridable 
mySub.R(2).
mySub.R((x+1)) :-
   mySub.R(x),
   x < 4.
```

--------------------------------

### Load Soufflé Interface in Java

Source: https://souffle-lang.github.io/swig

Load the SWIG interface library in a Java program. MAC users may need to use an alternative loading path.

```java
System.loadLibrary("SwigInterface")
```

```java
System.load(System.getProperty("java.library.path") + "/" + "libSwigInterface.so")
```

--------------------------------

### Minimizing Sum of Two Values in Soufflé

Source: https://souffle-lang.github.io/aggregates

Example of an aggregate function that computes the minimum sum of two values, where these values are derived from different elements within a relation and must be distinct.

```souffle
min Z+Y : { a(A,Z), a(B,Y), A!=B }.
```

--------------------------------

### Load Input Facts from Directory

Source: https://souffle-lang.github.io/interface

Load all input facts for the Soufflé program from CSV files located in a specified directory.

```cpp
prog->loadAll("<dir>"); // load facts from CSV files stored in <dir>

```

--------------------------------

### Extreme Case Rule Scheduling in Soufflé

Source: https://souffle-lang.github.io/handtuning

Demonstrates an extreme case where two relations with identical arguments are joined, leading to significant optimization by eliminating a loop.

```souffle
C(X,Y) :- A(X,Y), B(X,Y).

```

```c++
for( e1 : A ) {
    for( e2 : B ) {
        if ( e1[0] == e2[0] && e1[1] == e2[1] ) {
            C.insert( e1[0], e1[1] );
        }
    }
}

```

```c++
for( e1 : A ) {
    if ( e1 in B ) {
        C.insert( e1[0], e1[1] );
    }
}

```

--------------------------------

### Enable SWIG Java Bindings

Source: https://souffle-lang.github.io/swig

Enable Java bindings for SWIG during Soufflé configuration.

```bash
cmake -DSOUFFLE_SWIG_JAVA=ON
```
Tokens:
Raw