Development.rst

Development

Structure

The sources for functions and classes are in src/. Private functions (mostly C++ source files which are to be compiled into *.mex) are implemented in private/maox_some_function.*. (maox stands for "mex file for CaosDB".

Writing Documentation

• The first string after the copyright block is used for documentation. This implies that the copyright block must be recognized as such: A copyright line should be the first line there.

• Documentation should be written as TexInfo (see below for details) in order to be available in the online documentation.

• Extract documentation from file: [txt, form] = get_help_text_from_file(make_absolute_filename('pkg/inst/some_function.m'))

• Generate HTML documentation from single file:

  pkg uninstall caosdb
  pkg install caosdb.tar.gz
  pkg load caosdb
  html_help_text('some_function', './htdocs/some.html', 'octave-forge', pkgname="caosdb")

• Generate HTML documentation for a package:

  generate_package_html('caosdb', 'htdocs', 'octave-forge')

Requirements

• We use a dedicated Octave package for documentation generation: ` generate_html <https://keepachangelog.org>`_. This package can be installed as follows:

  pkg install "https://downloads.sourceforge.net/project/octave/Octave%20Forge%20Packages/Individual%20Package%20Releases/generate_html-0.3.2.tar.gz"

TexInfo details

Here is an Example for texinfo documentation:..

https://github.com/gnu-octave/octave/blob/default/scripts/geometry/inpolygon.m

Useful TexInfo commands:

• @deftypefn ::

  Define a function that can be called. Example code:.. @deftypefn{Function File} {@var{out} =} caosdb_exec (@var{arg})

Debugging

Debugging the C++ parts

For debugging, valgrind, gdb or other debugging tools may be used. For example when segfaults occur while calling Octave (or quitting Octave), they may be investigated like this:

valgrind --trace-children=yes octave test/segfault_dummy.m

The script file test/segfault_dummy.m reproduces the segfault in this example. The output indicates code which tries to perform illegal memory access.

Useful options for valgrind include:

--exit-on-first-error=yes --error-exitcode=200

Fail-fast if there are errors.