From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: David Pirotte Newsgroups: gmane.lisp.guile.devel,gmane.comp.programming.g-wrap.devel Subject: g-wrap, master: g-wrap reference manual introduction review and xref fixes Date: Wed, 2 Jul 2014 17:19:23 -0300 Message-ID: <20140702171923.687234f5@capac> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; boundary="Sig_/d0/5nzDeqEb/D9ybeeUuHDt"; protocol="application/pgp-signature" X-Trace: ger.gmane.org 1404332421 5463 80.91.229.3 (2 Jul 2014 20:20:21 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Wed, 2 Jul 2014 20:20:21 +0000 (UTC) To: g-wrap-dev , guile-devel Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Wed Jul 02 22:20:15 2014 Return-path: Envelope-to: guile-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1X2R0o-0004Om-Vw for guile-devel@m.gmane.org; Wed, 02 Jul 2014 22:20:15 +0200 Original-Received: from localhost ([::1]:56339 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1X2R0o-00071N-IB for guile-devel@m.gmane.org; Wed, 02 Jul 2014 16:20:14 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:46301) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1X2R0d-0006BK-Lj for guile-devel@gnu.org; Wed, 02 Jul 2014 16:20:08 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1X2R0W-00017K-DV for guile-devel@gnu.org; Wed, 02 Jul 2014 16:20:03 -0400 Original-Received: from maximusconfessor.all2all.org ([79.99.200.102]:40322) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1X2R0W-00013r-3E for guile-devel@gnu.org; Wed, 02 Jul 2014 16:19:56 -0400 Original-Received: from localhost (unknown [192.168.0.2]) by maximusconfessor.all2all.org (Postfix) with ESMTP id 6D0AEA04C0E8; Wed, 2 Jul 2014 22:19:34 +0200 (CEST) Original-Received: from maximusconfessor.all2all.org ([192.168.0.1]) by localhost (maximusconfessor.all2all.org [192.168.0.2]) (amavisd-new, port 10024) with ESMTP id BOlS5CKaNtbS; Wed, 2 Jul 2014 21:59:51 +0200 (CEST) Original-Received: from capac (unknown [189.60.115.53]) by maximusconfessor.all2all.org (Postfix) with ESMTPSA id 788B4A04C0F0; Wed, 2 Jul 2014 22:19:26 +0200 (CEST) X-Mailer: Claws Mail 3.9.3 (GTK+ 2.24.23; x86_64-pc-linux-gnu) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 79.99.200.102 X-BeenThere: guile-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Developers list for Guile, the GNU extensibility library" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Original-Sender: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.lisp.guile.devel:17275 gmane.comp.programming.g-wrap.devel:168 Archived-At: --Sig_/d0/5nzDeqEb/D9ybeeUuHDt Content-Type: multipart/mixed; boundary="MP_/zw16rZXjiw64RuXuK0u2vpL" --MP_/zw16rZXjiw64RuXuK0u2vpL Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: quoted-printable Content-Disposition: inline Hello, g-wrap master: g-wrap reference manual introduction review and xref fixes Attached... Cheers, David --MP_/zw16rZXjiw64RuXuK0u2vpL Content-Type: text/x-patch Content-Transfer-Encoding: quoted-printable Content-Disposition: attachment; filename=0002-g-wrap-reference-manual-introduction-review-and-xref.patch =46rom d20375ef6d1d2f01f3ff25e172d25cbe8583ad2e Mon Sep 17 00:00:00 2001 From: David PIROTTE Date: Wed, 2 Jul 2014 17:14:36 -0300 Subject: [PATCH 2/2] g-wrap reference manual introduction review and xref fixes * doc/g-wrap.texi: last section of the introduction, 'A Simple Example' needed a bit of a structure to help the reader, I think. So I added a couple of subheadings and made small changes preeceding and following these. xref fixes related to the guile reference manual, (goops and the GC mainly). * doc/.gitignore: added with a g-wrap entry, since we don't want to track html pages. --- doc/.gitignore | 1 + doc/g-wrap.texi | 57 +++++++++++++++++++++++++++++++----------------------= ---- 2 files changed, 32 insertions(+), 26 deletions(-) create mode 100644 doc/.gitignore diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000..3ede455 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1 @@ +g-wrap diff --git a/doc/g-wrap.texi b/doc/g-wrap.texi index abc95f0..3181cc5 100644 --- a/doc/g-wrap.texi +++ b/doc/g-wrap.texi @@ -70,7 +70,7 @@ for use with G-Wrap @value{VERSION} @set example-dir guile/examples =20 @ifnottex -@node Top, Introduction, (dir), (dir) +@node Top, Preface, (dir), (dir) @top The G-Wrap Reference Manual =20 @insertcopying @@ -125,11 +125,11 @@ programmatic one. You tell G-Wrap about your functio= ns and types, and ask it to generate wrappers for you by calling the functions exported from the @code{(g-wrap)} module. =20 -G-Wrap heavily uses -@uref{http://www.gnu.org/software/guile/manual/html_node/GOOPS.html#GOOPS, -GOOPS} Guile's object orientation framework. This is what makes -G-Wrap highly customizable: each code generation methods may be -overloaded or redefined in order to meet the user's particular needs. +G-Wrap heavily uses GOOPS, Guile's object oriented extension +(@pxref{GOOPS,,, guile, The GNU Guile Reference Manual}) . This +is what makes G-Wrap highly customizable: each code generation methods +may be overloaded or redefined in order to meet the user's particular +needs. =20 @menu * Why Create a Wrapper Generator?:: @@ -179,9 +179,10 @@ just have a translator from that to native G-Wrap call= s. @node A Simple Example @section A Simple Example =20 +@subheading Defining and exporting your wrapset class =20 As a simple example, if you wanted to wrap a C API that contained only -one function with a prototype like this +one function with a prototype like this: =20 @example int frob(int x, double y); @@ -193,16 +194,13 @@ a complete G-Wrap specification would look like this: @lisp (define-module (my-wrapset) #:use-module (oop goops) - - #:use-module (g-wrap) ;; the core of G-Wrap - #:use-module (g-wrap guile) ;; defines `' - - #:use-module (g-wrap guile ws standard) ;; the `standard' wrapset + #:use-module (g-wrap) ;; the core of G-Wrap + #:use-module (g-wrap guile) ;; defines `' + #:use-module (g-wrap guile ws standard) ;; the `standard' wrapset =20 #:export ()) =20 -;; Define a wrapset for Guile, and specify the wrapsets -;; it depends on. +;; Define a wrapset for Guile, and specify the wrapsets it depends on. (define-class () #:id 'my-wrapset #:dependencies '(standard)) @@ -234,6 +232,8 @@ globally unique identifier, and declares a dependency o= n the @code{initialize} method, the @code{frob} function is wrapped, providing all relevant data such as return and argument types. =20 +@subheading Further customizations for Guile + To refine the above wrapset for Guile, you derive from it and add the necessary information: =20 @@ -261,7 +261,8 @@ We derive our Guile-specific wrapset from the generic w= rapset the wrapset should eventually reside in the Guile module @code{my-module}. =20 -@noindent +@subheading Let's generate the C code, compile and use it + Once G-Wrap has seen this specification, the code for the wrappers can be generated with this code: =20 @@ -272,7 +273,7 @@ be generated with this code: (generate-wrapset 'guile 'my-wrapset "my-wrapset") @end lisp =20 -@noindent + This will produce the C file @file{my-wrapset.c}, that can be compiled into a shared library which will, when loaded by Guile, define a Scheme function named @code{frob} which you can call as expected: @@ -281,6 +282,8 @@ Scheme function named @code{frob} which you can call as= expected: (frob 4 2.3) @end lisp =20 +@subheading G-wrap is very flexible! + When it comes to defining how C types should be handled, G-Wrap is very flexible. G-Wrap provides a fairly generic underlying infrastructure which can then be customized for particular purposes by @@ -295,8 +298,11 @@ At the lowest level, there is a "wrapping protocol" fo= r types, which you can plug into to describe how a type is converted from and to the target language as well as other aspects of the type. G-Wrap comes with a few of these more types pre-defined. This set should cover -most of the common cases, but you can extend this set if needed. The -wrapper types currently available by default include: +most of the common cases, but you can extend it if needed. + +@subheading Predefined wrapper types + +The wrapper types currently available by default include: =20 @table @samp =20 @@ -645,14 +651,13 @@ recommended since it describes concepts used througho= ut G-Wrap. * G-Wrap's Code Generation API:: @end menu =20 -@node Basic Concepts, G-Wrap's High-level API, API Reference, API Reference +@node Basic Concepts @section Basic Concepts =20 G-Wrap's APIs are centered around a few basic concepts that one should know before using them. Basically, each concept has a corresponding -GOOPS class (@pxref{Introduction, an introduction to GOOPS,, goops, -The Goops Reference Manual}) usually exported by the @code{(g-wrap)} -module. +GOOPS class usually exported by the @code{(g-wrap)} module +(@pxref{GOOPS,,, guile, The GNU Guile Reference Manual}). =20 @menu * Wrapsets:: @@ -717,8 +722,8 @@ know them, except @code{initialize}. @deffn method initialize (wrapset ) . args Initialize @var{wrapset}, an newly created instance of @var{}. This method is part of the GOOPS meta-object -protocol (@pxref{Instance Creation, GOOPS MOP specification,, goops, -The GOOPS Reference Manual}). +protocol (@pxref{Instance Creation Protocol,,, guile, +The GNU Guile Reference Manual}). =20 @cindex module @cindex Guile module @@ -1167,7 +1172,7 @@ relevant only to wrapsets targeting Guile. @cindex mark and sweep @cindex memory management Guile's garbage-collector uses a @dfn{mark and sweep} algorithm -(@pxref{Garbage Collecting Smob, the description of Guile's GC +(@pxref{Conservative GC, the description of Guile's GC mechanism,, guile, The GNU Guile Reference Manual}). This parameter allows to direct the mark phase for the specific C type being wrapped, using the same protocol as the one used for SMOBs in Guile. @@ -1356,7 +1361,7 @@ generation interface, @xref{G-Wrap's Code Generation = API}. =20 =20 @node G-Wrap's Code Generation API -@section G-Wrap's Code Generation Interface +@section G-Wrap's Code Generation API =20 When creating Scheme bindings for a C programming interface with G-Wrap, one first needs to create a @dfn{wrapset} (@pxref{Wrapsets}). --=20 2.0.0 --MP_/zw16rZXjiw64RuXuK0u2vpL-- --Sig_/d0/5nzDeqEb/D9ybeeUuHDt Content-Type: application/pgp-signature; name=signature.asc Content-Disposition: attachment; filename=signature.asc -----BEGIN PGP SIGNATURE----- Version: GnuPG v2 iD8DBQFTtGlLRyh0zCtz6qsRAqlUAJ9OEZVnX/UUu9O11oI4wDBX+nQsrACgwwcs TI2lA/eTTnpKeYfPBzTf16U= =4vWt -----END PGP SIGNATURE----- --Sig_/d0/5nzDeqEb/D9ybeeUuHDt--