------------------------
README FOR BIDDY PROJECT
------------------------

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

Biddy is maintained by Robert Meolic (meolic@uni-mb.si) at University
of Maribor, Slovenia.

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

--------------
1. AN OVERVIEW
--------------

Biddy is free software released under GPL.

Biddy uses ROBDDs with complement  edges as described in "K. S. Brace,
R.L.   Rudell,  R.  E.   Bryant.  Efficient  Implementation  of a  BDD
Package. 27. ACM/IEEE DAC, pages 40-45, 1990."

Biddy is not  optimized for efficiency, it is  rather oriented towards
readable and  comprehensible source  code in C.  As it, it  is primary
intended for educational purposes.

Biddy  is  currently  used  in  the following  project:
1. BDD Scout, demo project
2. Efficient Symbolic Tools (EST), http://lms.uni-mb.si/EST/

--------------
2. SOURCE CODE
--------------

The short name of Biddy package is 'biddy'. This name should be placed
in front of  all filenames and external identifiers.  It may appear in
all  lowercase,  or with  its  first  letter  capitalized, written  as
'biddy' and 'Biddy', respectively.

There are three categories of C functions:
- exported functions are visible outside the package,
- internal functions are visible to all files within the package,
- static functions are visible to the file only.

Biddy consists of the following files:

  README		- this file
  CHANGES		- history of changes
  COPYING		- license file
  VERSION		- version file
  Makefile		- Makefile
  Makefile.Linux	- Makefile definitions for GNU/Linux
  Makefile.SunOS	- Makefile definitions for Solaris
  Makefile.MINGW	- Makefile definitions for Win32
  Makefile.Darwin	- Makefile definitions for MacOS
  biddy.def		- symbol definition for Win32
  biddy.h		- header
  biddyInt.h		- header
  biddyMain.c		- main functions and definitions
  biddyStat.c		- statistic about used memory
  package-source	- script used to build distribution
  package-bin		- script used to build distribution
  package-bin.bat	- script used to build distribution
  package-tgz		- script used to build distribution
  package-deb		- script used to build distribution
  package-rpm		- script used to build distribution
  debian/*		- used when creating deb files
  rpm/*			- used when creating rpm files

There are  two C headers,  external and internal. The  external header
file,  named  'biddy.h', defines  features  visible  from outside  the
package. The internal header file, named 'biddyInt.h' defines features
used in multiple files inside the package, but not outside.

There  are two  aditional packages  included into  Biddy distribution:
bddview and Bdd Scout.

bddview is  a pure Tcl/Tk  script for visualization of  BDDs.  bddview
consists of the following files:

  CHANGES		- history of changes
  VERSION		- version file
  bddview.tcl		- program
  example.bddview	- example file

BDD Scout is a demo  application demonstrating the capability of Biddy
and bddview.   It is easy  extendable! An interesting  extension (IFIP
benchmark) is part of the package. BDD Scout consists of the following
files:

  README		- some notes (general)
  README.*		- some notes (for different systems)
  CHANGES		- history of changes
  COPYING		- license file
  VERSION		- version file
  Makefile		- Makefile
  Makefile.Linux	- Makefile for GNU/Linux
  Makefile.SunOS	- Makefile for Solaris
  Makefile.MINGW	- Makefile for Win32
  Makefile.Darwin	- Makefile for MacOS
  bddscout.def		- symbols definition for Win32
  bddscout-biddy.def	- symbols definition for Win32
  bddscout.h		- header
  bddscout.c		- main functions
  pkgIndex.tcl		- tcl specific file
  bddscout.tcl		- tcl/tk GUI (an extension of bddview)
  bddscout.decls	- stub mechanism allows binary extensions
  bddscoutDecls.h	- stub mechanism allows binary extensions
  bddscoutStubInit.c	- stub mechanism allows binary extensions
  bddscoutStubLib.c	- stub mechanism allows binary extensions
  bddscoutIFIP.def	- bddscout extension (IFIP benchmark)
  bddscoutIFIP.c	- bddscout extension (IFIP benchmark)
  bddscoutIFIP.tcl	- bddscout extension (IFIP benchmark)
  pkgExtensionIFIP.tcl	- bddscout extension (IFIP benchmark)
  example.bdd		- example file
  example.bf		- example file
  package-bin		- script used to build distribution
  package-bin.bat	- script used to build distribution
  package-tgz		- script used to build distribution
  package-deb		- script used to build distribution
  package-rpm		- script used to build distribution
  debian/*		- used when creating deb files
  rpm/*			- used when creating rpm files

--------------------
3. BUILDING PACKAGES
--------------------

biddy> make "BINDIR = ./bin"
biddy> make clean "BINDIR = ./bin"

This should compile Biddy library.

---

biddy> ./package-bin

This should create biddy library as  a zip package.  You install it by
extracting  libraries  to the  appropriate  directory  (may be  local,
e.g. user's home dircetory).

You need a zip program.

On MS Windows, you  need 7-Zip (and it has a strange  use of -x!). You
also   need   file   7zsd.sfx    that   you   should   download   from
http://7zsfx.info/en/ and put in the directory containing 7z.exe.

---

biddy> ./package-tgz biddy> ./package-deb biddy> ./package-rpm

./package-tgz should  create orig.tar.gz file  and prepare directories
for creating debian  and RPM packages. You can  run ./package-tgz only
if version changes.

./package-deb   should    create   debian   packages    (libbidy   and
libbiddy-dev).  They are tested on Ubuntu system.

./package-rpm should create RPM packages (libbidy and libbiddy-devel).
They are tested on SUSE system (SLED 11).

These scripts needs release  number as an argument. Script package-tgz
must be  invoked before running package-deb.  Debian  packages must be
created before RPM packages.

---

IF YOU HAVE COMPLETE SOURCES ( folders biddy, bddview, and bddscout )
YOU CAN ALSO USE THE FOLLOWING SCRIPTS

biddy> ./package-source

This should create zip file with source code of complet Biddy project
(including source code of bddview and BDD Scout).

---

bddscout> ./package-bin

This should  create BDD Scout  (staticaly linked with  Biddy library).
The script  will produce a zip  file. You install BDD  Scout by simply
unzip to the target directory.

You need a zip program.

On MS Windows, you  need 7-Zip (and it has a strange  use of -x!). You
also   need   file   7zsd.sfx    that   you   should   download   from
http://7zsfx.info/en/ and put in the directory containing 7z.exe.

---

bddscout> ./package-tgz
bddscout> ./package-deb
bddscout> ./package-rpm

./package-tgz should  create orig.tar.gz file  and prepare directories
for creating debian  and RPM packages. You can  run ./package-tgz only
if version changes.

./package-deb should create  debian packages (bddscout, bddscout-ifip,
and bddscout-ifip-data).  They are tested on Ubuntu system.

./package-rpm should create RPM packages (bddscout, bddscout-ifip, and
bddscout-ifip-data).  They are tested on openSUSE system.

These scripts needs release  number as an argument. Script package-tgz
must be  invoked before running package-deb.  Debian  packages must be
created before RPM packages.

---------------------------------
4. HISTORY
---------------------------------

Biddy is based on a BDD package written in Pascal in 1992 as a student
project.  At that time, it was a great work and the paper about it won
a  second place  at  IEEE Region  Student  Paper Contest  (Paris-Evry,
1993).  The  paper was  published by IEEE  as "A.  Casar,  R.  Meolic.
Representation of  Boolean functions with ROBDDs.   IEEE Student paper
contest :  regional contest  winners 1990-1997 :  prize-winning papers
demonstrating student excellence  worldwide, Piscataway, 2000" and can
be obtained from http://lms.uni-mb.si/~meolic/papers/robdd.pdf

In 1995, this BDD package was  rewritten in C. Later, this BDD package
become an  integral part of EST  package, a prototype  tool for formal
verification of  concurrent systems.  The homepage for  EST project is
http://lms.uni-mb.si/EST/

In 2003, BDD package from EST  was included in the report presented at
16th Symposium  on Integrated Circuits and  Systems Design (SBCCI'03).
The report is available as a paper "G.  Janssen.  A Consumer Report on
BDD Packages.  IBM T.J.  Watson  Research Center.  2003".  Get it from
http://doi.ieeecomputersociety.org/10.1109/SBCCI.2003.1232832

In 2006, BDD package in EST got the name Biddy.

In 2007, a main part of Biddy package was extracted from EST forming a
separate package called Biddy. The code has been reorganized in such a
way,  that EST  is not  using  internal structures  (e.g. node  table)
directly but using the provided API only.

In 2007,  we created local  svn repository for maintaining  the source
code.  http://altair.uni-mb.si:8080/viewvc/

On  May 15,  2008, Biddy  v1.0  was  released containing  also bddview
v0.95 (Tcl/Tk BDD viewer) and Bdd Scout v0.90 (demo application).

On Jul  15, 2009,  updated version of  Biddy v1.0 was  released, which
includes support for debian packaging.

On Jul 22,  2010, another updated version of  Biddy v1.0 was released,
which includes support for RPM packaging.

On May 21,  2012, another updated version of  Biddy v1.0 was released,
which fixed error in Biddy_E and Biddy_A.

Afterwards, repackaging releases could appear which fix and improve
details of documentation, packaging, and Tcl/Tk GUI, but not change
the Biddy library itself.

In 2012, a research paper about Biddy library appear in Journal
of Software (doi:10.4304/jsw.7.6.1358-1366)
http://ojs.academypublisher.com/index.php/jsw/article/view/jsw070613581366/
