From GridLAB-D Wiki
Jump to: navigation, search

Troubleshooting - Developer guide to adding troubleshooting messages

Online troubleshooting documentation is generated automatically from source code comments entered immediately after the code that generates the message in question. For example, the user receives the message

FATAL: the GLPATH environment variable is not set

and must find out how to fix the problem. The message was generated from a line of code

output_fatal("the GLPATH environment variable is not set");

which must be documented. To document the troubleshooting information, you must add a C-style comment on the next line

output_fatal("the GLPATH environment variable is not set");
/* TROUBLESHOOT
   GridLAB-D requires that GLPATH be set before the system
   starts.  Make sure the environment variable is set
   and try again.
 */

No exception is made for line continuations, therefore the code

output_fatal("the GLPATH environment variable '%s' contains a folder that does not exist",
   getenv("GLPATH"));

can only be documented either as

output_fatal("the GLPATH environment variable '%s' contains a folder that does not exist", getenv("GLPATH"));
/* TROUBLESHOOT
   GridLAB-D requires that GLPATH environment variable refer to
   folders that exist.  Make sure the environment variable is set
   correctly and/or all the folders are accessible and try again.
 */

(which is preferred) or as

output_fatal("the GLPATH environment variable '%s' contains a folder that does not exist", 
/* TROUBLESHOOT
   GridLAB-D requires that GLPATH environment variable refer to
   folders that exist.  Make sure the environment variable is set
   correctly and/or all the folders are accessible and try again.
 */
   getenv("GLPATH"));

if the argument list is particularly long

Processing script

The troubleshooting guide is generated automatically by the nightly build process. The processing script source code is in utilities/troubleshooting.awk and generates an HTML file that should be placed in the root document of the www.gridlabd.org web site. There is a CSS stylesheet that also needs to be copied to the root document that is placed in the same source folder.

The command generate the HTML troubleshooting guide is

host% (cd trunk; ./utilities/troubleshooting.awk */*.{c,cpp} ) > $HTML/troubleshooting.html
host% (cd trunk; cp utilities/troubleshooting.css $HTML)

See also