Re: [igraph] integrating new C files into igraph

[Gábor Csárdi]

Hi Minh,

On Mon, May 2, 2011 at 4:29 AM, Minh Nguyen <address@hidden> wrote:
> Hi folks,
>
> I'm working on a new C module that, when it is in good enough shape, I
> would like to push to the igraph mainline tree. (I'll try not to dump
> a patch bomb when the module is ready, but would do incremental
> contributions instead.) What I don't understand is the process whereby
> I could incrementally integrate new C files in this module with my
> local igraph tree. To concretize my question, consider this patch [1]
> which is based on igraph trunk revision #2428. The patch provides a
> skeleton of a new C module with only documentation for one function:
>
> * The patch creates the following new files:
> include/igraph_microscopic_update.h and src/microscopic_update.c
> * It patches the following file: include/igraph_constants.h
>
> I have written API documentation for the only one function in
> src/microscopic_update.c.
>
> (1) Now what steps do I take in order to get the igraph documentation
> builder to also build the documentation in src/microscopic_update.c?
> For example, when I build the documentation with release.sh, I also
> want the documentation in src/microscopic_update.c parsed and output
> to a HTML file as per other C modules in igraph.
>

the structure of the C docs is defined in the file
doc/igraph-docs.xml, this contains the main chapters. Each chapter has
a .xxml file, that defines the further substructure. If you want to
add your own chapter, then do it in this file, also modify
doc/Makefile.am accordingly. In this you'll need to add
'microscopic.xml' to DOCINCLUDES at the beginning, and a part like
this towards the end (among the similar entries for the other .xxml
files):

microscopic.xml: microscopic.xxml $(SRCDIR)/microscopic_update.c
         $(DOXROX) -t $< -e $(REGEX) -o $@ $(SRCDIR)/microscopic_update.c

(The second line starts with a tab, as this is a file for make.)
Then, create the 'microscopic.xxml' file, with a contents like this:

<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"; [
<!ENTITY igraph "igraph">
]>

<chapter id="igraph-Microscopic">
<title>Microscopic updates</title>

<!-- doxrox-include igraph_deterministic_optimal_imitation -->

</chapter>

You can add your functions and other documentation to microscopic.xxml
in the desired order. This is an XML file, and the
doxrox-include lines will be replaced by the corresponding
documentation from the source code. You can only include a given
function once.

> (2) The same question goes for a new example usage file I want to
> create called, say, examples/simple/my_new_example.c. That is, what do
> I need to do in order to get the igraph documentation builder to input
> the examples in examples/simple/my_new_example.c into the generated
> documentation for src/microscopic_update.c?

Put this at the end of the documentation section:

 * \example examples/simple/my_new_example.c

> (3) Suppose I have fleshed out the body of the one function in
> src/microscopic_update.c and the test suite for this function is
> provided in examples/simple/my_new_example.c. What steps do I need to
> take in order to integrate the examples in
> examples/simple/my_new_example.c into the igraph test suite? That is,
> what do I need to do so that when I issue the following commands:
>
> $ cd tests
> $ ./testsuite
>
> the test suite in examples/simple/my_new_example.c would be executed?

First create a new test suite section. This needs an entry in
'tests/Makefile.am', add the name of your .at file (say
'microscopic.at') to TESTSUITE_AT, and also add a line
m4_include([microscopic.at])
to the end of the tests/testsuite.at file.

See an existing .at file (e.g. hrg.at) for how microscopic.at should
look like. The key is the AT_COMPILE_CHECK line, this can have many
arguments. It the simplest case it has just one, the name of the C
file that is compiled and run. The test passes if it has a zero exit
value. You can give a second argument which is the expected output of
the test program, this is required to match exactly. An optional third
argument can list files that are copied to the test directory before
the test program is run, see 'foreign.at' for examples of this.

You can add all your functions related to this topic to 'microscopic.at'.

Please tell me of something is not clear.

Best Regards,
Gabor

> [1] http://sage.math.washington.edu/home/mvngu/patch/microscopic_update.diff
>
> --
> Regards
> Minh Van Nguyen
>
> _______________________________________________
> igraph-help mailing list
> address@hidden
> https://lists.nongnu.org/mailman/listinfo/igraph-help
>



-- 
Gabor Csardi <address@hidden>     MTA KFKI RMKI