GNOME.org
 

gegl r2994 - in trunk: . docs docs/images tools

Author: martinn
Date: Thu Mar 26 20:04:13 2009
New Revision: 2994
URL: http://svn.gnome.org/viewvc/gegl?rev=2994&view=rev

Log:
Add initial how-to-hack-on-GEGL documentation

Apply patch from Henrik Akesson that adds initial how-to-hack-on-GEGL
documentation, including a ruby script to generate a graphviz graph of
the class inheritance trees in the core.

Added:
   trunk/docs/development.txt
   trunk/docs/images/.gitignore
   trunk/docs/images/gaussian-blur-graph.png
   trunk/tools/gobj2dot.rb   (contents, props changed)
Modified:
   trunk/ChangeLog
   trunk/docs/.gitignore
   trunk/docs/Makefile.am
   trunk/docs/index-static.txt.in

Modified: trunk/docs/.gitignore
==============================================================================
--- trunk/docs/.gitignore	(original)
+++ trunk/docs/.gitignore	Thu Mar 26 20:04:13 2009
@@ -1,18 +1,10 @@
 /Makefile
 /Makefile.in
-/gegl.devhelp
 /TODO.html
 /api.html
-/index-static.html
-/index-static.txt
-/index.html
-/class-hierarchy.html
-/operations.html
-/runinfo
 /brightness-contrast.c.html
-/gegl-operation.h.html
-/gegl-plugin.h.html
-/gegl.h.html
+/class-hierarchy.html
+/development.html
 /gegl-operation-area-filter.h.html
 /gegl-operation-composer.h.html
 /gegl-operation-filter.h.html
@@ -23,3 +15,12 @@
 /gegl-operation-sink.h.html
 /gegl-operation-source.h.html
 /gegl-operation-temporal.h.html
+/gegl-operation.h.html
+/gegl-plugin.h.html
+/gegl.devhelp
+/gegl.h.html
+/index-static.html
+/index-static.txt
+/index.html
+/operations.html
+/runinfo

Modified: trunk/docs/Makefile.am
==============================================================================
--- trunk/docs/Makefile.am	(original)
+++ trunk/docs/Makefile.am	Thu Mar 26 20:04:13 2009
@@ -12,7 +12,7 @@
 	class-hierarchy.html
 
 if HAVE_RUBY
-HTML_FILES += api.html
+HTML_FILES += api.html images/inheritance.png
 endif
 
 # dummy target to force the operations be available for scanning when
@@ -40,7 +40,7 @@
 endif
 
 if HAVE_ASCIIDOC
-HTML_FILES += index.html
+HTML_FILES += index.html development.html
 endif
 
 EXTRA_DIST= 			\
@@ -152,6 +152,11 @@
 	    $@
 endif
 
+images/inheritance.png: $(top_srcdir)/docs/Makefile
+if HAVE_RUBY
+	$(top_srcdir)/tools/gobj2dot.rb $(top_srcdir) | dot -Tpng > $(top_srcdir)/docs/images/inheritance.png
+endif
+
 index.html: index-static.txt		\
 	$(top_srcdir)/AUTHORS		\
 	gegl.css			\
@@ -168,6 +173,16 @@
 	@false
 endif
 
+development.html: $(top_srcdir)/docs/development.txt
+if HAVE_ASCIIDOC
+	@echo "HTML: $@"
+	cp $< $@ 
+	$(ASCIIDOC) --unsafe  -o $@ -a stylesdir=`pwd` -a toc -a theme=gegl -a quirks! $<
+else
+	@echo "*** asciidoc must be available in order to make dist"
+	@false
+endif
+
 clean-local:
 	if test $(srcdir) = .; then :; else 	\
 	    rm -f gegl.devhelp;	\

Added: trunk/docs/development.txt
==============================================================================
--- (empty file)
+++ trunk/docs/development.txt	Thu Mar 26 20:04:13 2009
@@ -0,0 +1,178 @@
+Development
+===========
+
+image::images/GEGL.png[GEGL]
+*#Development#*
+
+This document describes some handy things to know when developing the gegl internals.
+Parts of it is copy-paste of emails on the gegl developer list.
+
+== Setting up
+
+=== Ubuntu 8.10
+Setup instructions for Ubuntu 8.10 Intrepid Ibex
+
+To install the mandatory dependencies:
+
+ $ sudo apt-get install libtool automake glib libglib2.0-dev libpng12-dev libgtk2.0-dev subversion
+
+Some of the other dependencies:
+
+ $ sudo apt-get install asciidoc enscript libjpeg62 libopenraw graphviz-dev
+
+For running gegl the GEGL_PATH, which is used for dynamically loading the 
+operations, has to be set:
+
+ $ export GEGL_PATH=~/Dev/gegl-dev/operations/
+
+=== BABL
+
+When using a development version of babl, gegl has to know from where to get it.
+This is done by setting the BABL_LIBS environment variable before (or during
+as shown below) running gegl's autogen.sh:
+
+ $ ./autogen.sh BABL_LIBS=~/Dev/babl/babl/.libs/libbabl-0.0.so.0.23.0 CFLAGS="-O0"
+
+Then when running the program, the babl library automatically loads extensions
+that are either located in the BABL_HOME directory or in the default installation
+directory, in mentioned order of preference.
+
+ $ export BABL_HOME=~/Dev/babl/extensions
+
+=== Netbeans 6.5
+
+There are some key points to consider when setting up GEGL in an IDE
+(tested on Netbeans):
+
+- have to configure the IDE to use the autogen.sh as configure script
+- normally have to use gegl/bin/.libs/gegl as the executable,
+ not gegl/bin/gegl which is a script.
+- in some (?) case has to use bin/.libs/lt-gegl as the executable, which is some
+ kind of relinked gegl binary
+
+== Debugging
+
+By default gegl and babl uses the flag -g for debug instrumentation, but however
+it doesn't use the -O0 flag for turning off optimisations. This leads to unexpected
+jumps in the code when stepping in a debugger. You have to feed this flag to
+autogen:
+
+ $ ./autogen.sh CFLAGS="-O0"
+ $ make
+
+=== Debug output
+
+GEGL has built in mechanisms for logging debug information.
+
+ GEGL_NOTE (CACHE, "foo %s", bar);
+ GEGL_TIMESTAMP(PROCESSOR);
+ GEGL_MARK()
+
+Where CACHE and PROCESSOR is used the following logging domains are available:
+
+ PROCESS, CACHE, BUFFER_LOAD, BUFFER_SAVE, TILE_BACKEND and PROCESSOR
+
+Actual printing of these can be enabled by setting the GEGL_DEBUG
+environment variable like:
+
+ GEGL_DEBUG=processor,cache
+
+or even
+
+ GEGL_DEBUG=all
+
+=== Graphviz export
+The gegl library has a utility that permits to export the DAG into a graphviz
+format. Graphviz is a library that converts graph descriptions in textual format
+into an image. See http://www.graphviz.org/[graphviz website]
+
+It is done using:
+
+ #include "../gegl/gegl-dot.h"
+ /* for printing the dot output, note that gegl_node is a GeglNode pointer */
+ gchar *dot_output = gegl_to_dot( gegl_node );
+ printf( "%s\n", dot_output );
+ g_free( dot_output );
+
+For creating the graph image:
+
+ $ gegl --file gaussian-blur.xml --output out.png | dot -Tpng > gb.png
+
+This is the gaussian-blur.xml file:
+
+ <?xml version='1.0' encoding='UTF-8'?>
+ <gegl>
+ 	<node operation='gegl:gaussian-blur'>
+ 		<params>
+ 			<param name='std-dev-x'>0.999</param>
+ 			<param name='std-dev-y'>0.999</param>
+ 		</params>
+ 	</node>
+ 	<node operation='gegl:load'>
+ 		<params>
+ 			<param name='path'>in.png</param>
+ 		</params>
+ 	</node>
+ </gegl>
+
+link:images/gaussian-blur-graph.png[Resulting graph].
+
+
+== Tests
+
+There are regression tests in the subfolder "tests". These are run using:
+ make check
+
+== Documentation
+
+This document describes how to document GEGL using it's build system.
+
+There are three utilities used:
+
+. http://www.methods.co.nz/asciidoc/[asciidoc] - used for generating html from text files
+. http://www.codento.com/people/mtr/genscript/[enscript] - used for converting source files (.c/.h) to html
+. a home-made ruby script - used for generating api documentation (not yet documented here)
+
+All documentation resources are placed in /doc and the generation is controlled by the file Makefile.am
+
+=== asciidoc
+
+This example will show how this howto was added.
+
+- Add in `Makefile.am` a new target named `documentation-howto.html` in
+the existing list of html files to generate:
+
+  if HAVE_ASCIIDOC
+  	HTML_FILES += index.html documentation-howto.html
+  endif
+
+- Add in `Makefile.am` the target:
+
+ documentation-howto.html: documentation-howto.txt
+ if HAVE_ASCIIDOC
+ 	@echo "HTML: $@"
+ 	cp $< $@
+ 	$(ASCIIDOC) --unsafe  -o $@ -a stylesdir=`pwd` -a toc -a theme=gegl -a quirks! $<
+ else
+ 	@echo "*** asciidoc must be available in order to make dist"
+ 	@false
+ endif
+
+- Create a new `documentation-howto.txt` file with this content:
+
+ == Documentation howto
+
+ This document describes how to document GEGL using it's build system.
+
+- Type `make` and the `documentation-howto.txt` will be converted into `documentation-howto.html`
+
+=== enscript
+
+TODO
+This example will show how a new c/h file is converted into html using enscript
+
+== Inheritance tree
+
+Here is an automatically generated inheritance tree of the gobjects used by gegl:
+link:images/inheritance.png[GEGL inheritance tree]
+Note that the operations are also gobjects, but they are not included in the inheritance tree.
\ No newline at end of file

Added: trunk/docs/images/.gitignore
==============================================================================
--- (empty file)
+++ trunk/docs/images/.gitignore	Thu Mar 26 20:04:13 2009
@@ -0,0 +1,2 @@
+/inheritance.png
+/inheritance.png

Added: trunk/docs/images/gaussian-blur-graph.png
==============================================================================
Binary files (empty file) and trunk/docs/images/gaussian-blur-graph.png	Thu Mar 26 20:04:13 2009 differ

Modified: trunk/docs/index-static.txt.in
==============================================================================
--- trunk/docs/index-static.txt.in	(original)
+++ trunk/docs/index-static.txt.in	Thu Mar 26 20:04:13 2009
@@ -162,7 +162,7 @@
       * asciidoc
 
 Compiling
-~~~~~~~~
+~~~~~~~~~
 To build GEGL type the following in the toplevel source directory:
 
  $ ./configure  # or: ./autogen.sh if building from svn
@@ -181,6 +181,9 @@
 a composited and processed image. It is possible to request rectangular regions
 in a wide range of pixel formats from any node.
 
+Development
+-----------
+This link:development.html[howto] describes good-to-know things for developing gegl
 
 Public API
 ~~~~~~~~~~

Added: trunk/tools/gobj2dot.rb
==============================================================================
--- (empty file)
+++ trunk/tools/gobj2dot.rb	Thu Mar 26 20:04:13 2009
@@ -0,0 +1,85 @@
+#!/usr/bin/ruby
+
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, see <http://www.gnu.org/licenses/>.
+#
+# Copyright (C) 2009 Henrik Akesson
+
+require 'find'
+
+if ARGV[0] == nil or ARGV.count != 1 or ARGV[0] == "-h"
+  puts "Utility for generating inheritance diagrams from c-code using "
+  puts "the gobject library"
+	puts "Usage: gobjviz.rb path"
+  puts "       or"
+  puts "       gobjviz.rb path | dot -Tpng > output.png"
+	exit;
+end
+
+dir = ARGV[0]
+
+header = <<HDR
+digraph G {
+        rankdir = RL
+
+        fontname = "Bitstream Vera Sans"
+        fontsize = 8
+
+        node [ shape = "record" ]
+
+        edge [ arrowhead = empty ]
+HDR
+
+footer = <<FTR
+}
+FTR
+
+def tocamelcase( underscored )
+  underscored.gsub!( /^[a-z]|_[a-z]/ ) { |a| a.upcase }
+  underscored.gsub!( /_/, '')
+end
+
+def gegltocamelcase( gegltype )
+  gegltype =~ /([a-zA-Z0-9_]+)_TYPE_([a-zA-Z0-9_]+)/
+  gegltype = tocamelcase( $1.downcase + "_" + $2.downcase )
+end
+
+def inheritance( from, to )
+  puts "\t" + from + " -> " + to if ( to != "GObject")
+end
+
+def implementation( klass, interf )
+  puts "\t" + klass + " -> " + interf + " [ style = dashed ]"
+end
+
+def interfacedecl( interf )
+  puts "\t" + interf + " [ label = \"{\\<\\<interface\\>\\>\\l" + interf + "}\" ]"
+end
+
+puts header
+Find.find( dir ) do |path| 
+  Find.prune if File.basename(path) == '.svn' 
+  if ( ( File.extname(path) == '.c' or File.extname(path) == '.h' ) and File.file? path )
+    open( path ) do |file| 
+      content = file.read
+      if( content =~ /G_DEFINE_TYPE\s*\(\s*\w+,\s*(\w+),\s*(\w+)\s*\)/m )
+        inheritance( tocamelcase( $1 ), gegltocamelcase( $2 ) )
+      elsif( content =~ /G_DEFINE_TYPE_WITH_CODE\s*\(\s*(\w+).*G_IMPLEMENT_INTERFACE\s*\s*\(\s*(\w+)/m )
+        implementation( $1, gegltocamelcase( $2 ) )
+      elsif( content =~ /G_TYPE_INTERFACE\s*,\s*\"([^\"]+)\"/m )
+        interfacedecl( $1 )
+      end
+    end
+  end
+end
+puts footer
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]