logtalk_doclet(1)

NAME
logtalk_doclet - Logtalk script for automating running doclets

SYNOPSIS
logtalk_doclet -v
logtalk_doclet -p prolog [-d results] [-t timeout] [-s prefix] [-z] [-- arguments]
logtalk_doclet -h

DESCRIPTION
logtalk_doclet is a script for automating running Logtalk doclets. This script runs doclets found in a directory and recursively in its sub-directories by scanning for doclet.lgt and doclet.logtalk source files. The script assumes that the doclets use an initialization/1 directive to automatically run the documentation generation goal at loading time. A non-zero exit status is returned in case of failed doclets, timed out doclets, or crashed doclets.

OPTIONS

-v  Print script version.

-p  Backend Prolog compiler. Required. The following identifiers are used: B-Prolog - b, CxProlog - cx, ECLiPSe - eclipse, GNU Prolog - gnu, GNU Prolog (native code) - gnunc, JIProlog - ji, XVM - xvm, SICStus Prolog - sicstus, SWI-Prolog - swi, SWI-Prolog with Logtalk pack - swipack, Tau Prolog - tau, XSB - xsb, YAP - yap.

-d  Directory to store the doclet run logs. Default is the local ./logtalk_doclet_logs directory.

-t  Timeout in seconds for running each doclet. Default is 0 (i.e., disabled).

-s  Path prefix to suppress when printing doclet paths. Default is the user home directory.

-z  Enable audible completion notification: two chimes on exit status 0, five chimes otherwise. Default is off.

--  Arguments to be passed to the integration script used to run the doclets (no default).

-h  Provide help on script usage.

EXIT STATUS

0   All doclets succeeded. There are no timed out or crashed doclets.

1   Some doclets failed. But there are no timed out or crashed doclets.

3   One or more doclets timed out while executing. But there are no crashed doclets.

7   One or more doclets crashed the process running them.

IMPLEMENTATION NOTES
When the script detects either a timeout, gtimeout, or gnutimeout command (provided by the GNU coreutils package), it will use it to run each test set if the timeout option is set to a value greater than zero. This package can be easily installed in POSIX operating-systems (including Linux and macOS) if not provided by default. On Windows operating-systems, the native timeout command is not usable for this purpose. But the Git for Windows installer includes the GNU coreutils package, which can be used from the bundled Bash shell.

The script kills all created child processes on exit using the pkill command.

The gnunc backend requires creating a GNU Prolog executable that includes Logtalk named gplgtnc and making it available in the system PATH. This executable can be created using the embedding script provided in the Logtalk distribution. For example:
    gprolog_embed_logtalk.sh -c -d ~/collect -s none -- --new-top-level && mv ~/collect/logtalk ~/collect/gplgtnc

ENVIRONMENT

LOGTALKHOME
    Specifies the location of the Logtalk installation.

LOGTALKUSER
    Specifies the location of the Logtalk user directory.

FILES

$LOGTALKUSER/library/tester_versions.lgt
    Logtalk source file used for printing the Logtalk and backend Prolog compiler versions.

./logtalk_doclet_logs
    Default directory created with logs resulting from running the doclets. In the case of a broken doclet or a crash while running a doclet, the files in this directory may provided useful information for debugging the problem.

SEE ALSO
The Logtalk website at https://logtalk.org/

The Logtalk Handbook at $LOGTALKHOME/docs/handbook/index.html

AUTHOR
Paulo Moura <pmoura@logtalk.org>

COPYRIGHT
Copyright (c) 1998-2026 Paulo Moura.