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
- Guide to Programming GridLAB-D
- Introduction
- Creating a module
- Creating a class
- Special Topics
- Source documentation
- Validation
- Debugging
- Code templates