================
BDD Scout README
================

Biddy is a multi-platform academic Binary Decision Diagrams package.

bddview is a pure Tcl/Tk script for visualization of BDDs.

BDD Scout is a demo application demonstrating the capability of
Biddy and bddview.

BDD Scout depends on Tcl/Tk, BWidget, and Biddy library.

Homepage: http://lms.uni-mb.si/biddy/

========================================
RUNNING precompiled version of BDD Scout
========================================

BDD Scout is started by interpreting the file bddscout.tcl.

Zip packages include statically linked program which should run even
if Biddy library is not installed on your computer (and it will not
use your Biddy library if you have one).

Deb and rpm files include dynamically linked program, thus you will
also need appropriate libbbiddy package. 

If your system cannot find BWidgets uncomment and edit line 6 in
the file bddview.tcl.

Optionally,
- you can install Graphviz package to be able to visualize BDDs
  created by Biddy package (http://www.graphviz.org/)
- you can install Ghostscript package to be able to export BDDs as
  PNG images and PDF documents. (http://pages.cs.wisc.edu/~ghost/)

The path to the executables from Graphviz and Ghostscript package
is given in file bddscout.tcl, lines 20-41. Please, check it!

======================================
BUILDING your own version of BDD Scout
======================================

Zip packages includes complete source code, thus it serves as a good
starting and reference example. 

BDD Scout is free software and your are welcome to change it
(please, respect GPL)!

To build your own version of BDD Scout you have to take the following steps:

1. Obtain zip package of BDD Scout and development version of Biddy

Available on http://lms.uni-mb.si/biddy/

2. Obtain development version of Tcl/Tk and a version of BWidget

Ask Google :-)

3. Use make 

$ make -f Makefile.OS "BIDDYDIR = ..." "BIDDYLIB = ..." "BDDVIEWDIR = ..." "BINDIR = ..." 
$ make clean "BINDIR = ..."

OS = Linux, SunOS, MINGW, or Darwin
BIDDYDIR = the folder containing header biddy.h
BIDDYLIB = the folder containing Biddy library
BDDVIEWDIR = the folder containing bddview script and examples
BINDIR = the folder for binary files

In any case, all arguments ARE required!

Examples:

make -f Makefile.Linux "BIDDYDIR = /usr/include" "BIDDYLIB = /usr/lib" "BDDVIEWDIR = ." "BINDIR = `pwd`/bin"

make -f Makefile.Linux "BIDDYDIR = /home/meolic/est/biddy" "BIDDYLIB = /home/meolic/est/biddy/bin" "BDDVIEWDIR = /home/meolic/est/bddview" "BINDIR = /home/meolic/est/bddscout/bin"

make clean "BINDIR = `pwd`/bin"

Please note:
- Supplied makefiles are tricky and not easy to understand (the author is using them to
  do many different things on different systems :-)
- Your version of BDD Scout will be dynamically linked with your Biddy library.

Check README for your OS to get more detailed instructions.

Support for MacOS is very experimental and even the documentation can be wrong. 

Please, send your comments and questions to meolic@uni-mb.si (Robert Meolic).

==============================
FILE FORMATS USED IN BDD Scout
==============================

BDD Scout is builded on bddview thus the native
data format used in Open/Save is bddview format,
which uses the followin keywords:

label <n> <name> <x> <y>
node <n> <name> <x> <y>
terminal <n> 1 <x> <y>
connect <n1> <n2> <type>

<n> is the unique number (integer)
<name> is a string
<x> and <y> are coordinates (integer)
<type> is one of the following:
s : single line
si : inverted single line
r : line to 'then' succesor
l : line to 'else' successor
li : inverted line to 'else' successor
d : double line

REMARKS:
1. (0,0) is top left corner.
2. Only one label is supported.
3. Single line (or inverted single line) should be
   used to connect a label and a node.
4. Line to the right successor can not be inverted.
5. When using double line, the line to the left succesor
   is always inverted.

Example (example.bddview):
---
label 0 "Biddy" 100.0 10
node 1 "B" 100 60
node 2 "i" 100 125
node 3 "d" 50 175
terminal 4 1 50 240
node 5 "y" 100 225
terminal 6 1 100 290
node 7 "d" 150 175
terminal 8 1 150 240
connect 0 1 s
connect 1 2 d
connect 2 3 l
connect 2 7 r
connect 3 4 l
connect 3 5 r
connect 5 6 d
connect 7 5 l
connect 7 8 r
---

BDD Scout can import BDD given in prefix form:
1. the first word is the name of BDD
2. the second word is the name of top variable
3. any non-terminal variable is followed by two
   supgraphs in parenthesis, e.g. VAR (...) (...)
4. the name of terminal node is "1"
5. symbol * is used to denote complement edges.

Example (example.bdd):
---
Biddy
B (* i (d (1) (y (* 1) (1))) (d (y (* 1) (1)) (1)))
  (  i (d (1) (y (* 1) (1))) (d (y (* 1) (1)) (1)))
---

BDD Scout can import Boolean functions given in prefix form:
1. the file is started with the set of variables given
   in parenthesis - this is optional and is used
   to give variable ordering
2. there can be many Boolean functions in the same file
3. one Boolean function can go over many lines, the only
   requirement is that the function name and symbol "=" are
   given in the same line 4. supported operators are NOT, OR,
   AND, and EXOR

Example (example.bf):
---
(B i d y)
s1 = (or B (not y))
s2 =  (or B i d)
s3 = (or B (not i) (not d))
s4 = (or (not B) i (not d) y)
s5 = (or (not B) (not i) d y)
Biddy = (and s1 s2 s3 s4 s5)
---
