|
Packit |
bc1512 |
Development
|
|
Packit |
bc1512 |
===========
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
image::images/GEGL.png[GEGL]
|
|
Packit |
bc1512 |
*#Development#*
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
This document describes some handy things to know when developing the gegl internals.
|
|
Packit |
bc1512 |
Parts of it is copy-paste of emails on the gegl developer list.
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
== Setting up
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
=== Ubuntu 8.10
|
|
Packit |
bc1512 |
Setup instructions for Ubuntu 8.10 Intrepid Ibex
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
To install the mandatory dependencies:
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
$ sudo apt-get install libtool automake glib libglib2.0-dev libpng12-dev libgtk2.0-dev git
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
Some of the other dependencies:
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
$ sudo apt-get install asciidoc enscript libjpeg62 libopenraw graphviz-dev
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
For running gegl the GEGL_PATH, which is used for dynamically loading the
|
|
Packit |
bc1512 |
operations, has to be set:
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
$ export GEGL_PATH=~/Dev/gegl-dev/operations/
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
=== BABL
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
When using a development version of babl, gegl has to know from where to get it.
|
|
Packit |
bc1512 |
This is done by setting the BABL_LIBS environment variable before (or during
|
|
Packit |
bc1512 |
as shown below) running gegl's autogen.sh:
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
$ ./autogen.sh BABL_LIBS=~/Dev/babl/babl/.libs/libbabl-0.0.so.0.23.0 CFLAGS="-O0"
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
Then when running the program, the babl library automatically loads extensions
|
|
Packit |
bc1512 |
that are either located in the BABL_HOME directory or in the default installation
|
|
Packit |
bc1512 |
directory, in mentioned order of preference.
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
$ export BABL_HOME=~/Dev/babl/extensions
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
=== Netbeans 6.5
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
There are some key points to consider when setting up GEGL in an IDE
|
|
Packit |
bc1512 |
(tested on Netbeans):
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
- have to configure the IDE to use the autogen.sh as configure script
|
|
Packit |
bc1512 |
- normally have to use gegl/bin/.libs/gegl as the executable,
|
|
Packit |
bc1512 |
not gegl/bin/gegl which is a script.
|
|
Packit |
bc1512 |
- in some (?) case has to use bin/.libs/lt-gegl as the executable, which is some
|
|
Packit |
bc1512 |
kind of relinked gegl binary
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
== Debugging
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
By default gegl and babl uses the flag -g for debug instrumentation, but however
|
|
Packit |
bc1512 |
it doesn't use the -O0 flag for turning off optimisations. This leads to unexpected
|
|
Packit |
bc1512 |
jumps in the code when stepping in a debugger. You have to feed this flag to
|
|
Packit |
bc1512 |
autogen:
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
$ ./autogen.sh CFLAGS="-O0"
|
|
Packit |
bc1512 |
$ make
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
=== Debug output
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
GEGL has built in mechanisms for logging debug information.
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
GEGL_NOTE (CACHE, "foo %s", bar);
|
|
Packit |
bc1512 |
GEGL_TIMESTAMP(PROCESSOR);
|
|
Packit |
bc1512 |
GEGL_MARK()
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
Where CACHE and PROCESSOR is used the following logging domains are available:
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
PROCESS, CACHE, BUFFER_LOAD, BUFFER_SAVE, TILE_BACKEND and PROCESSOR
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
Actual printing of these can be enabled by setting the GEGL_DEBUG
|
|
Packit |
bc1512 |
environment variable like:
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
GEGL_DEBUG=processor,cache
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
or even
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
GEGL_DEBUG=all
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
There are also a few functions that are useful as you debug from
|
|
Packit |
bc1512 |
within a debugger such as GDB. In GDB for example, you call a function
|
|
Packit |
bc1512 |
interactively in the prompt, while a breakpoint is hit for example, by
|
|
Packit |
bc1512 |
typing
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
print function_name(args)
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
Some useful functions are:
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
* *gegl_dot_node_to_png_default()* Writes a PNG to /tmp/node.png with
|
|
Packit |
bc1512 |
the dependency graph for the passed node
|
|
Packit |
bc1512 |
* *gegl_node_dump_depends_on()* Dumps to stdout the nodes that the
|
|
Packit |
bc1512 |
passed node depends on. With this you can work yourself backwards in
|
|
Packit |
bc1512 |
a dependency graph.
|
|
Packit |
bc1512 |
* *gegl_node_get_debug_name()* Prints a debug string representation of
|
|
Packit |
bc1512 |
a node.
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
=== Graphviz export
|
|
Packit |
bc1512 |
The gegl library has a utility that permits to export the DAG into a graphviz
|
|
Packit |
bc1512 |
format. Graphviz is a library that converts graph descriptions in textual format
|
|
Packit |
bc1512 |
into an image. See http://www.graphviz.org/[graphviz website]
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
It is done using:
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
#include "../gegl/gegl-dot.h"
|
|
Packit |
bc1512 |
/* for printing the dot output, note that gegl_node is a GeglNode pointer */
|
|
Packit |
bc1512 |
gchar *dot_output = gegl_to_dot( gegl_node );
|
|
Packit |
bc1512 |
printf( "%s\n", dot_output );
|
|
Packit |
bc1512 |
g_free( dot_output );
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
For creating the graph image:
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
$ gegl --file gaussian-blur.xml --output out.png | dot -Tpng > gb.png
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
This is the gaussian-blur.xml file:
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
<gegl>
|
|
Packit |
bc1512 |
<node operation='gegl:gaussian-blur'>
|
|
Packit |
bc1512 |
<params>
|
|
Packit |
bc1512 |
<param name='std-dev-x'>0.999</param>
|
|
Packit |
bc1512 |
<param name='std-dev-y'>0.999</param>
|
|
Packit |
bc1512 |
</params>
|
|
Packit |
bc1512 |
</node>
|
|
Packit |
bc1512 |
<node operation='gegl:load'>
|
|
Packit |
bc1512 |
<params>
|
|
Packit |
bc1512 |
<param name='path'>in.png</param>
|
|
Packit |
bc1512 |
</params>
|
|
Packit |
bc1512 |
</node>
|
|
Packit |
bc1512 |
</gegl>
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
link:images/gaussian-blur-graph.png[Resulting graph].
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
You can also just call the function gegl_dot_node_to_png() directly
|
|
Packit |
bc1512 |
from within gdb to show the graphviz graph of a node and its
|
|
Packit |
bc1512 |
dependencies.
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
== Tests
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
There are regression tests in the subfolder `tests`. These are run
|
|
Packit |
bc1512 |
with `make check`
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
=== Composition tests
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
The tests under `tests/compositions` are easy-to-write high-level
|
|
Packit |
bc1512 |
system tests for GEGL and its operations. Together with our
|
|
Packit |
bc1512 |
http://gimptest.flamingtext.com:8080/job/gegl-distcheck/[Jenkins
|
|
Packit |
bc1512 |
server] that runs all our tests each night, the composition tests make
|
|
Packit |
bc1512 |
a powerful framework for detecting regressions.
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
==== Adding a composition test
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
To add a composition test for a operation called `gegl:new-operation`,
|
|
Packit |
bc1512 |
do the following:
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
. Create a GEGL XML file `tests/compositions/new-operation.xml` (will
|
|
Packit |
bc1512 |
typically look approximately like `tests/compositions/pixelise.xml`)
|
|
Packit |
bc1512 |
. Produce a reference image: `cd tests/compositions; gegl -o
|
|
Packit |
bc1512 |
/tmp/new-operation.png new-operation.xml` (make sure your operation
|
|
Packit |
bc1512 |
is installed so `gegl` finds it)
|
|
Packit |
bc1512 |
. Manually inspect the reference image `/tmp/new-operation.png` and
|
|
Packit |
bc1512 |
move it to `tests/compositions/reference` if it looks like you expect
|
|
Packit |
bc1512 |
. Add `run-new-operation.xml.sh` to the `TESTS` variable in
|
|
Packit |
bc1512 |
`tests/compositions/Makefile.am`
|
|
Packit |
bc1512 |
. Run `make check` in `tests/compositions` to verify that your test
|
|
Packit |
bc1512 |
works (note that you must have configured GEGL with `autogen.sh` in
|
|
Packit |
bc1512 |
order for your change to the `TESTS` variable to be taken into
|
|
Packit |
bc1512 |
account)
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
And you're done. Do not manually create `run-new-operation.xml.sh`, it
|
|
Packit |
bc1512 |
will be created automatically for you during build time. It will run
|
|
Packit |
bc1512 |
`gegl` with `tests/compositions/new-operation.xml` and compare the
|
|
Packit |
bc1512 |
result with `tests/compositions/reference/new-operation.png`. If the
|
|
Packit |
bc1512 |
result differs, the test will fail, and mails will be sent to the GEGL
|
|
Packit |
bc1512 |
maintainers. As stated above, this test will run each night, so if
|
|
Packit |
bc1512 |
someone breaks your contributed GEGL operation, it will be discovered
|
|
Packit |
bc1512 |
at most 24 hours later, making it easy to fix, either by reverting the
|
|
Packit |
bc1512 |
bogus commit or by adjusting it.
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
An example of a commit that adds a composition test for a GEGL
|
|
Packit |
bc1512 |
operation is
|
|
Packit |
bc1512 |
http://git.gnome.org/browse/gegl/commit/?id=13e17712529fb714edcfd67e559bf46b622ff31d[Add
|
|
Packit |
bc1512 |
composition test for gegl:gamma].
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
== Documentation
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
This document describes how to document GEGL using it's build system.
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
There are three utilities used:
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
. http://www.methods.co.nz/asciidoc/[asciidoc] - used for generating html from text files
|
|
Packit |
bc1512 |
. http://www.codento.com/people/mtr/genscript/[enscript] - used for converting source files (.c/.h) to html
|
|
Packit |
bc1512 |
. a home-made ruby script - used for generating api documentation (not yet documented here)
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
All documentation resources are placed in /doc and the generation is controlled by the file Makefile.am
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
=== asciidoc
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
This example will show how this howto was added.
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
- Add in `Makefile.am` a new target named `documentation-howto.html` in
|
|
Packit |
bc1512 |
the existing list of html files to generate:
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
if HAVE_ASCIIDOC
|
|
Packit |
bc1512 |
HTML_FILES += index.html documentation-howto.html
|
|
Packit |
bc1512 |
endif
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
- Add in `Makefile.am` the target:
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
documentation-howto.html: documentation-howto.txt
|
|
Packit |
bc1512 |
if HAVE_ASCIIDOC
|
|
Packit |
bc1512 |
@echo "HTML: $@"
|
|
Packit |
bc1512 |
cp $< $@
|
|
Packit |
bc1512 |
$(ASCIIDOC) --unsafe -o $@ -a stylesdir=`pwd` -a toc -a theme=gegl -a quirks! $<
|
|
Packit |
bc1512 |
else
|
|
Packit |
bc1512 |
@echo "*** asciidoc must be available in order to make dist"
|
|
Packit |
bc1512 |
@false
|
|
Packit |
bc1512 |
endif
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
- Create a new `documentation-howto.txt` file with this content:
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
== Documentation howto
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
This document describes how to document GEGL using it's build system.
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
- Type `make` and the `documentation-howto.txt` will be converted into `documentation-howto.html`
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
=== enscript
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
TODO
|
|
Packit |
bc1512 |
This example will show how a new c/h file is converted into html using enscript
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
== Inheritance tree
|
|
Packit |
bc1512 |
|
|
Packit |
bc1512 |
Here is an automatically generated inheritance tree of the gobjects used by gegl:
|
|
Packit |
bc1512 |
link:images/inheritance.png[GEGL inheritance tree]
|
|
Packit |
bc1512 |
Note that the operations are also gobjects, but they are not included in the inheritance tree.
|