libs/cassowary/README

   1 Cassowary Constraint Solving Toolkit for C++, Java, and Smalltalk
   2 Version 0.60
   3
   4 Web Page: http://www.cs.washington.edu/research/constraints/cassowary
   5 Contact: cassowary@cs.washington.edu
   6
   7 Greg J. Badros <gjb@cs.washington.edu> and
   8 Alan Borning <borning@cs.washington.edu>
   9 University of Washington
  10 Computer Science and Engineering
  11 Seattle, WA 98195-2350
  12 12-March-2000
  13
  14 with Constraint Drawing Applet (CDA) by Michael Noth <noth@cs.washington.edu>
  15
  16 See ANNOUNCE for a brief description and announcement of this distribution.
  17 See NEWS for a history of user-visible changes.
  18 See ChangeLog for a detailed listing of the changes to each source file.
  19 See LICENSE for legalese regarding use of this distribution.
  20
  21 The Smalltalk implementation is in the public domain -- see smalltalk/README.
  22
  23 Please send bug reports to cassowary@cs.washington.edu
  24
  25 Also, send mail to cassowary@cs.washington.edu if you would like to be
  26 informed about bug fixes, feature enhancements, etc.  Let us know what
  27 implementation(s) you are using, too.
  28
  29 ------------------------------------------------------------------
  30
  31 HOW TO GET STARTED
  32
  33 The Cassowary library uses GNU autoconf to permit easy building on
  34 various platforms.  You should be able to do:
  35
  36 ./configure
  37 make
  38
  39 and everything will work.  A more complex, but realistic example is:
  40
  41 ./configure --with-prefix=/usr/contrib \
  42             --with-guile-prefix=/usr/contrib \
  43             --with-python-headers=/usr/include/python1.5 \
  44             --enable-java-build \
  45             --with-gtl=/usr/contrib \
  46             --with-java-class-path=/usr/contrib/share/java/site \
  47             --enable-warnings
  48 make -k
  49
  50 Be sure to give the extra --enable-permissive flag to configure if
  51 you are building with gcc-2.95 or more recent.
  52
  53 As yet another data point, I build Cassowary with:
  54
  55 ./configure --with-guile-exec-prefix=/uns/bin \
  56             --with-guile-prefix=/uns/share --prefix=/uns/share \
  57             --exec-prefix=/uns --enable-maintainer-mode
  58
  59 See the file "INSTALL" for more details about
  60 autoconf support and the options that the "configure" takes.  You can
  61 also do "./configure --help" for the list of the options that configure
  62 accepts.
  63
  64 If the make in any of the subdirectories fails, you can turn on the "-k"
  65 option to make, or just do make in the subdirectories that you want
  66 build.  E.g., if you do not have the JDK installed, the Java version of
  67 Cassowary might not compile; if you still want the guile version, just
  68 "cd guile; make -k".
  69
  70 Be sure that configure detects the validity of using the "-fpermissive"
  71 flag of more recent g++/egcs compilers to work around some
  72 const-discrepancies between the const-challenged guile header files and
  73 Cassowary's more const-correct usage.  You should get a message like:
  74
  75   checking whether gcc understands -fpermissive option... yes
  76
  77 when running configure if you're using, e.g., gcc-2.95 or later.
  78
  79 You need to apply GTL.h.patch to the installed GTL.h header file for
  80 Cassowary to compile with recent versions of egcs/gcc (e.g., gcc-2.95).
  81
  82 Also, you may need to change libguile/gsubr.h from:
  83
  84      extern SCM scm_make_gsubr SCM_P ((char *name, int req, int opt,
  85                                        int rst, SCM (*fcn)()));
  86    to
  87
  88      extern SCM scm_make_gsubr SCM_P ((char *name, int req, int opt,
  89                                        int rst, void*));
  90
  91 or patch guile's snarf.h to insert the appropriate case at each call to
  92 SCM_PROC and SCM_PROC1.  (Thanks to Alexandre Duret-Lutz for the above
  93 information about more recent g++/egcs compilers).
  94
  95 Note that the generated Makefiles depend upon features of GNU Make.  See:
  96
  97 ftp://ftp.gnu.org/pub/gnu/
  98
  99 for a version of make that you can build first to then build Cassowary.
 100
 101 Example applications exist in subdirectories of the top-level
 102 implementation subdirectories (e.g., c++/qdemos contains demos for C++
 103 that use the Qt Widget toolkit).
 104
 105 Please send mail to cassowary@cs.washington.edu if you are using this
 106 toolkit so we know how to reach you for bug fixes, updates, etc.
 107
 108 ------------------------------------------------------------------
 109
 110 WHAT THE DISTRIBUTION CONTAINS
 111
 112 This distribution contains 3 implementations of the Cassowary constraint
 113 solving toolkit:
 114
 115 o C++
 116 o Java
 117 o Smalltalk
 118
 119 For each implementation language, there is at least one example program;
 120 for some there are many.
 121
 122 There is a wrapping of the C++ solver in Guile-Scheme -- see the guile/
 123 subdirectory.  Also, Anthony Beuriv� has wrapped Cassowary for
 124 STk/Scheme.  His code is available at:
 125
 126   http://dept-info.labri.u-bordeaux.fr/~beurive/Code
 127
 128 and the STk Scheme system is available at:
 129
 130   http://kaolin.unice.fr/STk/
 131
 132 There is also a SWIG-generated wrapper of the C++ library making the
 133 solver available from the Python language.
 134
 135 A technical report describing the solver, its interface, and its
 136 implementation is in cassowary-tr.ps (pdf version in cassowary-tr.pdf).
 137 This paper is required reading if you intend to use the solver in your
 138 own project(s).
 139
 140 See also the Scwm (Scheme Constraints Window Manager) web page:
 141
 142 http://scwm.mit.edu/scwm/
 143
 144 Scwm, also by Greg Badros (and Maciej Stachowiak), is the most
 145 substantial application using this toolkit that we are aware of.
 146
 147 ------------------------------------------------------------------
 148
 149 VARIOUS IMPLEMENTATION NOTES
 150
 151 Cassowary/C++ needs to be compiled using a modern C++ compiler.
 152 At one time or another, it has compiled using:
 153   o egcs-1.0.1
 154   o egcs-1.0.3a
 155   o egcs-1.1b
 156   o egcs-1.1.1
 157   o gcc-2.8.1 (needs libstdc++-2.8.x, too)
 158   o Visual C++ 5.0 (not tried recently)
 159
 160 In particular, Cassowary will *not* build with gcc-2.7.x.x!
 161
 162 See c++/README for more details about building the C++ version.
 163
 164 The C++ implementation of the toolkit also has an optional finite domain
 165 subsolver.  You need to build and install the GTL -- the Graph Template
 166 Library -- and use the "--with-gtl=DIR" configure option for the finite
 167 domain subsolver to be built.  GTL is available from:
 168
 169 http://www.fmi.uni-passau.de/Graphlet/GTL/
 170
 171 Cassowary was tested against GTL-0.3.1;  it may work with later
 172 versions, but I have not tried it.  You need to apply GTL.h.patch to
 173 the installed GTL.h header file for Cassowary to compile with recent
 174 versions of egcs/gcc (e.g., gcc-2.95).
 175
 176 Cassowary/Java was developed using Sun's JDK-1.1.x, ported to Linux
 177 More recent versions should work fine.
 178
 179 See java/README for more details about building the Java version.
 180
 181
 182 Cassowary/Smalltalk was written under OTI Smalltalk-- other versions of
 183 smalltalk will likely require (possibly significant) changes.
 184
 185 See smalltalk/README for more details about the Smalltalk version.
 186
 187 See guile/README for details about the Guile Scheme wrapper of the C++
 188 implementation, and for a pointer to SCWM, the Scheme Constraints Window
 189 Manager which uses Cassowary.
 190
 191 The Python bindings (by Tessa Lau) bindings for the Cassowary library
 192 are in the wrappers/ subdirectory.  SWIG was used in wrapping the
 193 library.  These bindings may no longer work, and are provided only for
 194 your hacking pleasure (please send back useful patches if you do get the
 195 code working).
 196
 197 For more information about SWIG, see:
 198
 199 http://www.swig.org/
 200
 201
 202 For more information about the Python language, see:
 203
 204 http://www.python.org/
 205
 206
 207 For more information about the Guile-Scheme language, see:
 208
 209 http://www.red-bean.com/guile/
 210 http://www.fsf.org/software/guile/guile.html
 211
 212
 213 ------------------------------------------------------------------
 214
 215 DEMONSTRATION APPLICATION
 216
 217 A standard demonstration application is included for each implementation
 218 of the Cassowary solver.  The application builds a quadrilateral and
 219 connects the neighboring midpoints of each of the outer edges to form an
 220 interior quadrilateral which is provably a parallelogram.  The
 221 constraint solver manages the constraints to keep the outer
 222 quadrilateral inside the window, keep the midpoints properly positioned,
 223 and keep the outer quadrilateral from turning "inside out."
 224
 225 The user is able to select points (draggable boxes) and move them around
 226 within the window (both midpoints and endpoints can be selected, of
 227 course).  The solver updates the figure, and redraws.
 228
 229
 230 ------------------------------------------------------------------
 231
 232 FUNDING ACKNOWLEDGEMENTS
 233
 234 This work has been funded in part by the National Science Foundation under
 235 Grants IRI-9302249 and CCR-9402551, by Object Technology International, and
 236 by a Fulbright Award from the Australian-American Educational
 237 Foundation.
 238
 239 Additionally, Greg Badros is supported by a National Science Foundation
 240 Graduate Research Fellowship.  Parts of this material are based upon
 241 work supported under that fellowship.