Newer
Older
=============
Development
=============
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".
- 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:
.. code-block:: octave
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:
.. code-block:: octave
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:
.. code-block:: octave
pkg install "https://downloads.sourceforge.net/project/octave/Octave%20Forge%20Packages/Individual%20Package%20Releases/generate_html-0.3.2.tar.gz"
.. _generate_html: https://gnu-octave.github.io/packages/generate_html
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.