how_to_debug

How to Debug

Running Onigmo Interactively

You can run Onigmo interactively via Python.

On Unix-like Systems

If you build Onigmo with the normal way (./configure && make), the shared object (libonigmo.so) will be created in the .libs/ directory. You need to execute Python with setting LD_LIBRARY_PATH to .libs. E.g.:

$ LD_LIBRARY_PATH=.libs python3

On Cygwin, add .libs to $PATH instead of LD_LIBRARY_PATH:

$ PATH=.libs:$PATH python3

Python's prompt will be shown. Then you can try the following commands:

>>> from testpy import *
>>> init('UTF-8')
>>> x2('.*', 'abc', 0, 3)
OK: /.*/ 'abc'

x2() is a function to execute matching. The 1st argument is a pattern. The 2nd argument is a target string. The 3rd argument is the position where matching starts, and the 4th argument is the position where matching ends.

If you don't have onigmo.py and testpy.py in the current directory (e.g. you run configure in a shadow directory), you can try:

>>> import sys
>>> sys.path += ['..']  # Add the directory where testpy.py exists.
>>> from testpy import *
>>> init('UTF-8')
>>> x2('.*', 'abc', 0, 3)
OK: /.*/ 'abc'

On Windows

If you build Onigmo, the DLL (onigmo.dll) will be created in the build_x86 directory or in the build_x64 directory. If you build a debug version (nmake DEBUG=1), d will be appended (build_x86d or build_x64d). Add the directory into your PATH, then execute Python with the py command (pylauncher). Python 3.7 (or later) is recommended. If you build 32-bit debug version:

> PATH=build_x86d;%PATH%
> py -3-32

If you build 64-bit release version:

> PATH=build_x64;%PATH%
> py -3-64

Python's prompt will be shown. Then you can try the following commands:

>>> from testpy import *
>>> init('UTF-8')
>>> x2('.*', 'abc', 0, 3)
OK: /.*/ 'abc'

Enabling the Debugging Options at Compile Time

Open regint.h with an editor. You may find the following lines near the top of the file:

/* for debug */
/* #define ONIG_DEBUG_PARSE_TREE */
/* #define ONIG_DEBUG_COMPILE */
/* #define ONIG_DEBUG_SEARCH */
/* #define ONIG_DEBUG_MATCH */
/* #define ONIG_DEBUG_MEMLEAK */
/* #define ONIG_DONT_OPTIMIZE */

/* for byte-code statistical data. */
/* #define ONIG_DEBUG_STATISTICS */

You may want to enable some of them. E.g.:

/* for debug */
#define ONIG_DEBUG_PARSE_TREE
#define ONIG_DEBUG_COMPILE
#define ONIG_DEBUG_SEARCH
#define ONIG_DEBUG_MATCH
/* #define ONIG_DEBUG_MEMLEAK */
/* #define ONIG_DONT_OPTIMIZE */

/* for byte-code statistical data. */
/* #define ONIG_DEBUG_STATISTICS */

Do make and execute any test program. You will see a detail debug log.

Check the Coverage

This only works on Unix-like systems. (Use Cygwin on Windows.) You need to install lcov on your system.

$ ./configure CFLAGS=--coverage
$ make
$ make test
$ make lcov

The coverage data will be written in the coverage/ directory. Open coverage/index.html with a Web browser to see the results. If you want to clear the coverage results, do:

$ make lcov-clear