Here You Go!

Software Source Code Browsing Using Doxygen

Lucky — Wed, 29 Sep 2010 04:54:59 +0000

(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/.

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.

OlivePad: India’s Answer to iPAD

Lucky — Sat, 24 Jul 2010 06:15:19 +0000

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

Olive Telecom, an Indian-based multinational company, launched India’s first 3.5G Pad, named OlivePad-VT100. The main features of OlivePad are:

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

How to Enable Creation of Core Dump Files Due to Crashed Applications in Fedora Linux Distribution

Lucky — Sat, 24 Jul 2010 00:49:49 +0000

It is needed frequently to analyze the cause of a crashed application. One way to do it is through the creating of core dump files that can be later analyzed to debug the issue. Core dump files are a snapshot of the memory area being used by the application at the time the crash occurred. Creation of core dump files may not be enabled by default, and may require some configuration. The instructions to enable the core dump files, I am going to describe here, are tested on Fedora Linux Distribution.

Enter following line at the command prompt:

$ulimit -c unlimited

Now check the output of the command “ulimit -c”, and it should show “unlimited” as follows.

$ulimit -c
unlimited

The above change, done in the way, will not be permanent. To make them permanent, edit file “/etc/security/limits.conf” (You must either be root user or must have “sudo” permission to edit this file.) and type the following line.

* soft core unlimited

“*” means that this change is applicable for all users. However, to make this change for only a specific user, you should enter as follows:

soft core unlimited

The core dump files, generated after an application crashes, are stored in the directory from where the application was run. To place the core dump files in another location, the “sysctl” variable, named “kernel.core_pattern”, is used. The value of this variable can be checked as follows:

$sysctl -a|grep core_pattern #(if you are root user.)
kernel.core_pattern = core #(assuming “abrtd” is not running. The explanation about “abrtd” is discussed below.)

$sudo sysctl -a|grep core_pattern #(if you are non-root user with sudo permissions.)
kernel.core_pattern = core

The value of kernel.core_pattern is “core” currently. Two ways to change the value of this variable are as follows:

sysctl -w kernel.core_pattern=/tmp/core.%p

Now if you check the value of “kernel.core_pattern”, it will be “/tmp/core.%p”.

$sysctl -a|grep core_pattern
kernel.core_pattern = /tmp/core.%p

This means that the core dump files will be generated in the “/tmp” directory. “%p” extension to core dump files is used to append the process id of the application that crashed. This way, the variable kernel.core_pattern is also used to format the name of core dump files.

ABRT (Automated Bug Reporting Tool) Daemon:

ABRT is an application, included in Fedora Linux Distribution, that is used to report bugs in the software packages whenever crash occurs. Due to this, ABRT also helps in creation of core dump files. Multiple packages may be needed to run various features of ABRT daemon, and their listing is as follows.

abrt
abrt-plugin-bugzilla
abrt-plugin-runapp
abrt-desktop
abrt-addon-ccpp
abrt-addon-kerneloops
abrt-plugin-logger
abrt-libs
abrt-addon-python
abrt-gui

To install these packages in Fedora, one can do:

$yum install #(if root user.)

$sudo yum install #(if non-root user with sudo permissions.)

To check whether ABRT daemon is running on your system, execute:

$service abrtd status or #sudo service abrtd status
abrt is stopped

If it is stopped as shown above, “abrtd” can be started as follows:

$service abrtd start or #sudo service abrtd start
Starting abrt daemon: [ OK ]

And, now the status should show as follows:
$service abrtd status or #sudo service abrtd status
abrt (pid 5678) is running…

When “abrtd” is running, the value of sysctl variable “kernel.core_pattern” is different from the above as shown below:

$sysctl -a|grep core_pattern
kernel.core_pattern = |/usr/libexec/abrt-hook-ccpp /var/cache/abrt %p %s %u %c

“abrtd” creates a sub-directory (named something like “ccpp-1279914365-14618″) in the directory “/var/cache/abrt” as shown in the value of the variable. This also means that the core files will also be stored in that sub-directory in the “/var/cache/abrt” directory (in addition to the current directory where application was run). ABRT daemon also creates other files in addition to the core dump files in the sub-directory to further help users in debugging the crash issue.

By default, “abrtd” created core dump files only for those executable (or packages) that are managed by “rpm” (red hat package manager) utility. To enable “abrtd” for non-rpm application (something you compiled locally and are not managed through rpm), you need to edit the file cat “/etc/abrt/abrt.conf” , and change the value of the field “ProcessUnpackaged” to “yes” as follows:

ProcessUnpackaged = no #(before editing the file)

ProcessUnpackaged = yes #(after editing the file)

India Makes World’s Cheapest Laptop, Sakshat, based on Open Souce Linux Operating System

Lucky — Fri, 23 Jul 2010 14:53:12 +0000

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

10 Amazing iPhone 4 Features

Lucky — Fri, 23 Jul 2010 02:39:19 +0000

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

Mozilla Firefox Does Not Connect To Internet When Network Connection Is Up

Lucky — Tue, 20 Jul 2010 16:07:42 +0000

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

Steve Jobs’ 2 Steps Solution to IPhone 4 Call Drop (Reception and Antenna) Issues

Lucky — Sat, 17 Jul 2010 08:07:33 +0000

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

Steve Jobs Says IPhone 4 Call Drop (Reception and Antenna) Issue Affects Only 0.55% Users

Lucky — Sat, 17 Jul 2010 08:04:39 +0000

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

Steve Jobs Admits Call Drop (Reception and Antenna) Issues with iPhone 4

Lucky — Sat, 17 Jul 2010 08:01:23 +0000

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

Apple Provides IOS 4.0.1 and a Free Case to Address iPhone 4 Call Drop (Reception and Antenna) Issues

Lucky — Sat, 17 Jul 2010 07:57:26 +0000

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