X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~mdw/git/clg/blobdiff_plain/e3e38b419c6b26b3339b1975facad875ce5955bc..5884be5c1dd5f6dfa460088a9332230fe1a1d7af:/README

diff --git a/README b/README
index 5cd78c9..ade5bdc 100644
--- a/README
+++ b/README
@@ -1,47 +1,127 @@
-This package contains Common Lisp bindings to GTK+ v2.0. It currently
-only works with CMUCL, but ports to other CL implementations may be
-added later.
+This package contains Common Lisp bindings to GTK+ v2.x. It currently
+only works with CMUCL 19 and SBCL 0.9, but ports to other CL
+implementations may be added later.
 
 
 New versions
 ------------
 
-The most recent version of this package can be found at:
+The most recent version of this package can be downloaded from
+http://sourceforge.net/projects/clg.
 
 
 
 Build instructions
 ------------------
 
-1. When building for CMUCL, first obtain a matching binary and source
-   tree (the only source file you will actually need is lisp.h, which
-   have to be copied or linked to your CMUCL_LIB directory).  On ELF
-   systems you may also have to rebuild lisp with -rdynamic added to
-   OS_LINK_FLAGS.
+1. When building for SBCL you first need to add callback support,
+   since SBCL does not yet has a native callback facility. The
+   following instructions are borrowed from the Common Music
+   installation guide:
 
-2. Edit clg.system to reflect the paths on your system:
+   1. Download Thomas Burdick's Alien Function package¹ and restore it 
+      to a directory on your machine.
+   2. Compile the Alien Function package and save a new sbcl.core image:
 
-   - Edit the logical-pathname-translations to point to the
-     place where the sources actually are, or set the translations
-     somewhere else, like ~/.cmucl-init.lisp.
+      $ cd sbcl-af
+      $ sbcl --load "system"
+      * (sb-ext:save-lisp-and-die "/tmp/sbcl.core")
+      $ cd /usr/local/lib/sbcl
+      $ cp sbcl.core sbcl.core.orig
+      $ mv /tmp/sbcl.core .
 
-   - Edit the pkg-config search path if your gtk+ installation is in 
-     unusual place.
 
-   - Edit *cmucl-include-path* to point to the directory where the
-     lisp.h file resides, if it is not auto detected.  Try "locate 
-     '*/lisp.h'" if you don't know the location.
+   ¹ A slightly modified version which works with SBCL 0.8.21 or newer
+     could be found at 
+     http://jupiter.td.org.uit.no/lisp/sbcl-0.8.21-af.tar.gz
+
+
+2. Set up paths to match your system:
+
+   - Add a logical-pathname-translation to the clg root directory in
+     ~/.cmucl-init.lisp, ~/.sbclrc or some other startup file, like
+     this:
+
+       (setf
+         (logical-pathname-translations "clg")
+         '(("**;*.*.*" "/home/espen/src/clg/**/")))
+
+   - Set the correct pkg-config search path if your Gtk+ installation
+     is in an unusual place, by adding it to the PKG_CONFIG_PATH
+     environment variable before starting lisp.
+
+   - Make sure ASDF finds the system definition files:
+       
+       (push 
+	#+sbcl(truename #p"clg:systems") 
+	#+cmu(concatenate 'string (unix-namestring #p"clg:systems") "/")
+	asdf:*central-registry*)
+
+     When checking out of CVS also do the following:
+     $ cd <clg toplevel>
+     $ mkdir systems && cd systems
+     $ find .. -name '*.asd' -exec ln -s {} . \;
+
+
+3. Compile and load the system:
+   
+     (asdf:oos 'asdf:load-op :gtk)
+
+   In CMUCL 19a this will fail with:
+
+   Error in function KERNEL::%REDEFINE-DEFSTRUCT:
+     Redefining class PCL::SLOT-INFO incompatibly with the current definition.
+
+   Just accept the redefinition (restart 1) to continue building or
+   loading. To avoid doing this every time clg is loaded, compile
+   and load glib/pcl.lisp in newly started CMUCL process and save a
+   new core image.
+
+   If you are running SBCL with Slime you need to put the following
+   in ~/.swank.lisp to prevent Slime from spawning multiple
+   threads, since GTK+ is not really thread safe:
+
+     #+sbcl(setq swank:*communication-style* :fd-handler)
 
-3. Compile and load clg:
-   (load "clg.system")
-   (mk:oos :clg :compile)
-   (mk:oos :clg :load)
 
 4. If everything worked, try (load "hello-world") to see a small
-   window pop up.
+   window pop up, and then run testgtk.lisp in the example directory.
+
+
+
+Guidelines for using the GTK+ API documentation 
+-----------------------------------------------
+
+Here are some brief guidelines for using the GTK+ API documentation. A
+lot of (both intentional and unintentional) inconsistencies exists,
+so it is also wise to check the source code.
+
+- library prefixes are stripped from all symbols
+
+- the get/set part are removed from regular accessors, but retained
+  in functions which set or retrieve multiple values
+
+- predicate functions follow the normal convention of ending
+  with '-P'
+
+- if there are multiple similar named functions which only differ in
+  the type of argument they accept, only one function accepting any
+  kind of valid argument types is provided
+
+- there are no gtk_*_new functions, use MAKE-INSTANCE to create widgets
+
+- all object properties are available as virtual slots. A lot of
+  "missing" properties are manually defined as slots
+
+- use CHILD-PROPERTY-VALUE or automatically defined accessors to
+  access child properties
+
+- use STYLE-PROPERTY-VALUE to access style properties
 
-Send comments and patches to clg-devel@lists.sourceforge.net
+- the only function used to connect signals is SIGNAL-CONNECT
 
 
 
 
+Send comments and patches to clg-devel@lists.sourceforge.net or
+espen@users.sourceforge.net.