You are currently browsing the monthly archive for September 2010.

(Please visit new location of this post here at http://binaryjunction.com/.)

Frequently, software developers need to walk through software source codes, they are working on, for various reasons, such as for understanding the code flow or for debugging a particular problem. There are several tools available for this purpose though. However, I will describe here how to use a similar tool, called Doxygen, which can be used to create documentation from the source codes. The source code documentation can be created in the form of html files, and these html files can then be later used for source code browsing. One of the main advantages of Doxygen documentation is that the functional call references can be viewed in the form of graphs, which make code walk through very easy to understand. According to the Doxygen manual, it can be used to create documentation for several languages, such as C, C++, JAVA and many other languages. However, I have only used with C language code as this is the language I mostly use for my work. However, it does not make any difference as the instructions are same for creating documentation for all supported language. The first thing for creating Doxygen documentation is to create a configuration file with the extension “.cfg”. I have provided a sample configuration file below, and I have always used this configuration file for all of my projects. The instruction (provided below) of using Doxygen is also based on this configuration file. I have verified these instruction on Fedora 13 Linux distribution using Doxygen-1.7.1.

For full post, please click here at http://binaryjunction.com/.

Frequently, software developers need to walk through software source codes, they are working on, for various reasons, such as for understanding the code flow or for debugging a particular problem. There are several tools available for this purpose though. However, I will describe here how to use a similar tool, called Doxygen, which can be used to create documentation from the source codes. The source code documentation can be created in the form of html files, and these html files can then be later used for source code browsing. One of the main advantages of Doxygen documentation is that the functional call references can be viewed in the form of graphs, which make code walk through very easy to understand. According to the Doxygen manual, it can be used to create documentation for several languages, such as C, C++, JAVA and many other languages. However, I have only used with C language code as this is the language I mostly use for my work. However, it does not make any difference as the instructions are same for creating documentation for all supported language. The first thing for creating Doxygen documentation is to create a configuration file with the extension “.cfg”. I have provided a sample configuration file below, and I have always used this configuration file for all of my projects. The instruction (provided below) of using Doxygen is also based on this configuration file. I have verified these instruction on Fedora 13 Linux distribution using Doxygen-1.7.1.1.Before using the provided configuration file, first verify that your system has “doxygen”, “dot” and “perl” commands installed. Depending upon your configuration, you may not need “dot” program, but the sample configuration file below creates graphs, and “dot” command is required for creating graphs. 

2.Now assume that the source code, you are working on, is available in the “myproject” directory, “cd” to this directory.

$cd /path/to/myproject

3.Copy the sample file provided below as “doxygen-configuration.cfg” in the “myproject” directory. You can give any name for this configuration file as far as the extension is “.cfg”.

4.Run Doxygen with the configuration file as follows:

$doxygen doxygen-configuration.cfg

After this, it may take a few minutes to complete the documentation creation depending upon your system speed. Once this process is complete, the documentation will be created in the directory “myproject-doxygen/html/” directory inside your “myproject”. You can always change this as you want to in your configuration file by changing “OUTPUT_DIRECTORY” parameter. Generally the naming format of created html files is as follows:

4a) If the name of a source code file is “xy.c”, then its created documentation will be “xy_8c.html”, and its source code will be “xy_8c_source.html”. Same is true for the header files (*.h).
4b) If the name of a source code file is “xy_wz.c”, then its created documentation will be “xy__wz_8c.html” (note double underscores “__”), and its source code will be “xy__wz_8c_source.html”. Same is true for the header files (*.h).

In addition to these files, Doxygen creates several other files too. The size of the complete documentation may be very large, sometimes in 100s of megabytes (Mbs), and even in gigabytes (Gbs) depending upon your configuration parameters.

5. You can start browsing the html documentation files in your favorite web browser. For a starting point for browsing the source code, assume that the “main()” function is in file “xy.c”, then you can open “/path/to/myproject/myproject-doxygen/html/xy_8c.html” in your web browser.

—–doxygen-configuration.cfg—————
ABBREVIATE_BRIEF       =
ALIASES                =
ALLEXTERNALS           = NO
ALPHABETICAL_INDEX     = YES
ALWAYS_DETAILED_SEC    = YES
BINARY_TOC             = NO
BRIEF_MEMBER_DESC      = YES
BUILTIN_STL_SUPPORT    = NO
CALLER_GRAPH           = YES
CALL_GRAPH             = YES
CASE_SENSE_NAMES       = YES
CHM_FILE               =
CHM_INDEX_ENCODING     =
CLASS_DIAGRAMS         = YES
CLASS_GRAPH            = YES
COLLABORATION_GRAPH    = YES
COLS_IN_ALPHA_INDEX    = 5
COMPACT_LATEX          = NO
COMPACT_RTF            = NO
CPP_CLI_SUPPORT        = NO
CREATE_SUBDIRS         = NO
DIRECTORY_GRAPH        = YES
DISABLE_INDEX          = NO
DISTRIBUTE_GROUP_DOC   = NO
DOCSET_BUNDLE_ID       = org.doxygen.Project
DOCSET_FEEDNAME        = “Doxygen generated docs”
DOT_CLEANUP            = YES
DOTFILE_DIRS           =
DOT_FONTNAME           = FreeSans
DOT_FONTPATH           =
DOT_FONTSIZE           = 10
DOT_GRAPH_MAX_NODES    = 50
DOT_IMAGE_FORMAT       = png
DOT_MULTI_TARGETS      = YES
DOT_PATH               =
DOT_TRANSPARENT        = NO
DOXYFILE_ENCODING      = UTF-8
ENABLED_SECTIONS       =
ENABLE_PREPROCESSING   = YES
ENUM_VALUES_PER_LINE   = 4
EXAMPLE_PATH           =
EXAMPLE_PATTERNS       =
EXAMPLE_RECURSIVE      = NO
EXCLUDE                =
EXCLUDE_PATTERNS       =
EXCLUDE_SYMBOLS        =
EXCLUDE_SYMLINKS       = NO
EXPAND_AS_DEFINED      =
EXPAND_ONLY_PREDEF     = NO
EXTERNAL_GROUPS        = YES
EXTRACT_ALL            = YES
EXTRACT_ANON_NSPACES   = NO
EXTRACT_LOCAL_CLASSES  = YES
EXTRACT_LOCAL_METHODS  = NO
EXTRACT_PRIVATE        = YES
EXTRACT_STATIC         = YES
EXTRA_PACKAGES         =
FILE_PATTERNS          =
FILE_VERSION_FILTER    =
FILTER_PATTERNS        =
FILTER_SOURCE_FILES    = NO
FORMULA_FONTSIZE       = 10
FULL_PATH_NAMES        = YES
GENERATE_AUTOGEN_DEF   = NO
GENERATE_BUGLIST       = YES
GENERATE_CHI           = NO
GENERATE_DOCSET        = NO
GENERATE_HTMLHELP      = NO
GENERATE_HTML          = YES
GENERATE_LATEX         = NO
GENERATE_LEGEND        = YES
GENERATE_MAN           = NO
GENERATE_PERLMOD       = NO
GENERATE_QHP           = NO
GENERATE_RTF           = NO
GENERATE_TAGFILE       =
GENERATE_TESTLIST      = YES
GENERATE_TODOLIST      = YES
GENERATE_TREEVIEW      = ALL
GENERATE_XML           = NO
GRAPHICAL_HIERARCHY    = YES
GROUP_GRAPHS           = YES
HAVE_DOT               = YES
HHC_LOCATION           =
HIDE_FRIEND_COMPOUNDS  = NO
HIDE_IN_BODY_DOCS      = NO
HIDE_SCOPE_NAMES       = NO
HIDE_UNDOC_CLASSES     = NO
HIDE_UNDOC_MEMBERS     = NO
HIDE_UNDOC_RELATIONS   = NO
HTML_ALIGN_MEMBERS     = YES
HTML_DYNAMIC_SECTIONS  = YES
HTML_FILE_EXTENSION    = .html
HTML_FOOTER            =
HTML_HEADER            =
HTML_OUTPUT            = html
HTML_STYLESHEET        =
IDL_PROPERTY_SUPPORT   = YES
IGNORE_PREFIX          =
IMAGE_PATH             =
INCLUDED_BY_GRAPH      = YES
INCLUDE_FILE_PATTERNS  =
INCLUDE_GRAPH          = YES
INCLUDE_PATH           =
INHERIT_DOCS           = YES
INLINE_INFO            = YES
INLINE_INHERITED_MEMB  = NO
INLINE_SOURCES         = YES
INPUT                  =
INPUT_ENCODING         = UTF-8
INPUT_FILTER           =
INTERNAL_DOCS          = NO
JAVADOC_AUTOBRIEF      = NO
LATEX_BATCHMODE        = NO
LATEX_CMD_NAME         = latex
LATEX_HEADER           =
LATEX_HIDE_INDICES     = NO
LATEX_OUTPUT           = latex
LAYOUT_FILE            =
MACRO_EXPANSION        = YES
MAKEINDEX_CMD_NAME     = makeindex
MAN_EXTENSION          = .3 .5 .8
MAN_LINKS              = YES
MAN_OUTPUT             = man
MAX_DOT_GRAPH_DEPTH    = 0
MAX_INITIALIZER_LINES  = 30
MSCGEN_PATH            =
MULTILINE_CPP_IS_BRIEF = NO
OPTIMIZE_FOR_FORTRAN   = NO
OPTIMIZE_OUTPUT_FOR_C  = YES
OPTIMIZE_OUTPUT_JAVA   = NO
OPTIMIZE_OUTPUT_VHDL   = NO
OUTPUT_DIRECTORY       = myproject-doxygen
OUTPUT_LANGUAGE        = English
PAPER_TYPE             = a4wide
PDF_HYPERLINKS         = YES
PERLMOD_LATEX          = NO
PERLMOD_MAKEVAR_PREFIX =
PERLMOD_PRETTY         = YES
PERL_PATH              = /usr/bin/perl
PREDEFINED             =
PROJECT_NAME           = myproject
PROJECT_NUMBER         =
QCH_FILE               =
QHG_LOCATION           =
QHP_NAMESPACE          = org.doxygen.Project
QHP_VIRTUAL_FOLDER     = doc
QT_AUTOBRIEF           = NO
QUIET                  = NO
RECURSIVE              = YES
REFERENCED_BY_RELATION = YES
REFERENCES_LINK_SOURCE = YES
REFERENCES_RELATION    = YES
REPEAT_BRIEF           = YES
RTF_EXTENSIONS_FILE    =
RTF_HYPERLINKS         = NO
RTF_OUTPUT             = rtf
RTF_STYLESHEET_FILE    =
SEARCHENGINE           = YES
SEARCH_INCLUDES        = YES
SEPARATE_MEMBER_PAGES  = NO
SHORT_NAMES            = NO
SHOW_DIRECTORIES       = YES
SHOW_FILES             = YES
SHOW_INCLUDE_FILES     = YES
SHOW_NAMESPACES        = YES
SHOW_USED_FILES        = YES
SIP_SUPPORT            = NO
SKIP_FUNCTION_MACROS   = YES
SORT_BRIEF_DOCS        = NO
SORT_BY_SCOPE_NAME     = NO
SORT_GROUP_NAMES       = NO
SORT_MEMBER_DOCS       = NO
SOURCE_BROWSER         = YES
STRIP_CODE_COMMENTS    = YES
STRIP_FROM_INC_PATH    =
STRIP_FROM_PATH        =
SUBGROUPING            = YES
SYMBOL_CACHE_SIZE      = 0
TAB_SIZE               = 8
TAGFILES               =
TEMPLATE_RELATIONS     = YES
TOC_EXPAND             = NO
TREEVIEW_WIDTH         = 250
TYPEDEF_HIDES_STRUCT   = NO
UML_LOOK               = NO
USE_HTAGS              = NO
USE_PDFLATEX           = NO
VERBATIM_HEADERS       = YES
WARN_FORMAT            = “$file:$line: $text”
WARN_IF_DOC_ERROR      = YES
WARN_IF_UNDOCUMENTED   = YES
WARNINGS               = YES
WARN_LOGFILE           =
WARN_NO_PARAMDOC       = NO
XML_DTD                =
XML_OUTPUT             = xml
XML_PROGRAMLISTING     = YES
XML_SCHEMA             =
—–doxygen-configuration.cfg—————

Customization of the Doxygen configuration file:

It is possible that you may not like the name of the Doxygen documentation directory “myproject-doxygen” as in the sample file above, and you want to give some other name to it, and also you want to store in some other location. Similarly, depending upon your project requirement, you may also want to change some or all of the configuration parameters according to your needs. I am only going to describe some of the configuration parameters here, you can follow the link http://www.stack.nl/~dimitri/doxygen/configuration.html to go through the complete description of each parameters. It is also possible that some of these parameters may get obsoleted in future. While running doxygen (as in step 4 above), it will output warnings about the obsoleted parameters and then you can modify the configuration file accordingly. Some of the Doxygen’s configuration parameters work in group, and if you modify one parameter, it may affect all other parameters in the group, so be careful about it.

1)GENERATE_HTML:  If you want to generate html files or not and I set it to YES.
2)GENERATE_LATEX: If you want to generate the documentation output in the latex file format. Latex files can be converted to pdf files. I did not want this so I set it to NO.
3)HTML_FILE_EXTENSION: I assume that this parameter is self-explanatory and allows to set the extension of html files. I set it to “.html”.
4)INCLUDE_GRAPH: If you want to generate the call graphs, I set it to YES.
5)The following parameters are language specific. As I am only using C, so I just set it for C, you can set it according to your language.
OPTIMIZE_FOR_FORTRAN   = NO
OPTIMIZE_OUTPUT_FOR_C  = YES
OPTIMIZE_OUTPUT_JAVA   = NO
OPTIMIZE_OUTPUT_VHDL   = NO

6)OUTPUT_DIRECTORY: where you want to store the Doxygen documentation.
7)OUTPUT_LANGUAGE: By default, it is English, but you can set it to the other supported language as per your requirements.
8)PROJECT_NAME: Name of the project, you are working on.
9)PROJECT_NUMBER: Version of the project, you are are working on.
10)SOURCE_BROWSER: If you want the Doxygen to create source code files in html format or not (*.source.html, as explained above in step 4).

Important Links:
http://www.stack.nl/~dimitri/doxygen/ : Main Doxygen website
http://www.stack.nl/~dimitri/doxygen/configuration.html : Here, you can find explanation to each of the configurations parameters, and can customize accordingly.