How to view my Source

This is experimental source code. It is open and not designed for code review in the same way that a house is not designed to be a factory.

The directory structure is flat. There is a root directory called proj/ and each project or module within the workspace has its own directory under the root directory. This simplified the tools as they make assumptions on where files are, and it was easier handling all a project/modules files in the one directory.

The names of the module/project's directory hint at what the projects are about. For example visit explores a variant of the visitor pattern, vrml is a primitive VRML parser. The projects web page contains a more detailed description.

Project names ending in lib are libraries. For example graphicslib mathlib misclib

Doxygen is used for the source code document generation. There is still a lot of my code which needs to be cleaned up and documented with Doxygen.

I am doing major redesign and writing of classes. It is not unusual for a major class to be broken for a period of over a year, because I am doing a major redesign somewhere else so patience is needed. Plans to write the geometry engine (created from scratch) are slow but very rewarding.

Disclaimer: A lot of the code is incorrect or I have changed my opinion but not rewritten the project. Sometimes I work in non-linear ways so a silly idea can later be replaced my something much stronger, or removed.

I am combining open interfaces with disciplined programming techniques in at times non standard ways.

Anytime I code something in C++ it goes here. I have maths interests, interests in patterns, computation and graphics.

Documentation of the ideas is as important as the program. The theory and practise both aid each other. So I link the C++ project to the theory and vice versa. For example C++ bucket and Bucket Sort both have links to each other.

Since much of my interest is in computational geometry the Computational Geometry page contains the algorithms, many of which are documented here before they get implemented.

IDE

The workspace has a command line IDE (Integrated Development Environment). The tool chain consists of editing the files with vi or gvim, building the makefiles from the source with a script written in bash - see Makefile Build Tool, compiling the makefiles with gcc, test for compilation and running the unit tests - see testscripts.sh.

Any other tools can also be optionally part of the tool chain. For example gdb can be used for debugging, gprof for profiling, gnuplot for displaying the results.

Since this is a Unix environment other command line functions were written. For example mkerrors gdb calls make with -g option and displays the first 10 error message lines.

For windows people who are familiar with the IDE as a GUI the command line does all the tasks and potentially more because you are in control. Neither is the command line not a gui because it may call programs in the tool chain which are gui driven.

Documentation is part of the development process. Doxygen and other tools for documentation of the program and the theory pages in html. While not directly part of the tool chain and hence IDE it is not acceptable to not have the source documented.

Testing

Current Situation and Goal

The goal is to get the workspace to the point where Continuous integration is taking place. ie a "current" build for testing, demo, or release purposes.

This is not yet realized. So the current situation is critical, however the framework for managing the workspace has been implemented to meet the goal of continuous integration.

Previously I was managing the dependencies by hand but encountered many problems in maintaining dependencies.

I investigated and implemented automated build and testing tools, and Extreme Programming principles which were suited to my development.

Therefore I have implemented the framework for automated build and testing in this code base. testscripts.sh provide tools at the command line for compiling and testing the workspace as a whole, or as modules with their units.

The main point of continuous integration is when a change is made in one part of the code that effects another the dependency can be addressed.

The workspace has automatic makefile generation for managing dependencies between source files and linking. See Makefile Build Tool. This is also a point where testing of included files occurs. This step was not automated because it would require the client to additional specify header files not in the source tree. Further consideration of system header files. What I wanted was a hands off IDE that minimized configuration files and largely works from the source.

The workspace has a unit testing framework. Over time the workspace will develop using this technology.

There is clearly a need to move away from manual to automatic testing where possible. This will give confidence in the workspace to drive more aggressive software goals. More time on software development and less time on tracking and re-fixing bugs. So even if I do not know what is going on, the software will.

The key to getting better software is through transparency. report provides a measure as to what is working. It still requires knowledge to know if the module is important or how relevant the message or module is.

The only major missing component in the tool chain is source control. I will probably use subversion. The requirements that I have are that the source control is unobtrusive (appears not to be there except when I need it), and lets the directories be renamed and moved. I do not want the source control to include comments on every edit - there should be a separation between the source and the source control. I do not believe tying your source control to your code is good, for example what if you wish to change the source control program at a later date. What I want are tools such as three diff comparisons.

Command Line

At the command line run testworkspaceupdate to update the workspace where each project/module is tested and the status is embedded within my html documentation.

So I have a wrapper which does the testing and then inserts the results into the html documentation.

function testworkspaceupdate
{
  proj;
  testworkspace $@
  bash update.sh html
  popd;
}

For example $testworkspaceupdate took a bit over 4 minutes where the workspace was already compiled. With heavier unit testing the time will increase.

So I type a one line command, wait, then know the status of my workspace.

testscripts.sh is where the unit testing and workspace functions are implemented. For a finer grain of control these can be used these within the source tree.

testmodule <update,release,silent,summary,clean> - compiles and tests a module. Default (no release) is debug code. update rewrites the makefile.
testreport <brief> - With no arguments generate proj/report.html from previous tests. With brief all modules status is output to the command line.
testunit <filename> <silent/summary> - run a test script in a module directory.
testunits <silent/summary> - run testunit on scripts testcripts*.txt in a module/directory.
testworkspace <update,release,silent,summary,clean> - compiles and tests modules.

The compilation is done generally in debug or release mode. This was reflected by testing in these modes as command line options. This restriction will be addressed at a later point in time as the client may want to supply other command line options to the compiler.

By my convention the test scripts are named testscript*.txt . Here is an example.
The text file testscript01.txt :
./main prog=3 in=treeindexed01.txt ./main prog=2

To run this test script.
bsptrees]$ testunit testscript01.txt

This outputs to the screen and writes a report to testreport.txt in the local directory. Other options can be supplied such as silent or summary to control output to the screen.
bsptrees]$ testunit testscript01.txt silent

bsptrees]$ testunit testscript01.txt summary

Report  testscript01.txt  Success
./main prog=3 in=treeindexed01.txt
  Success
./main prog=2
  Success

The plural testunits does the same for each testscript in the current directory.

testmodule does both compilation and unit testing. The results are written to testreport.txt.
testmodule release compiles release code.
testmodule release silent compiles it without printing to the screen.
I generally delete the object files when changing the compiler flags.
testmodule clean
The update option rebuilds the makefile.
testmodule update summary

testmodule is used by testworkspace to update the workspace. It passes its arguments to each module being processed. So the whole workspace is made uptodate.

Finally to extract the workspace state a report needs to be written.
testreport brief outputs at the command line a one line summary for each module. For example.
zpr : module=Failure compiled=Success
There are three states as a module can not be successful if compilation failed.
testreport writes the report as a html file. All the individual reports are collected and displayed on the one page. The visual icons make interpreting the state easy.

assert

This concerns testing at the micro level, the primary testing strategy in the *.cpp or *.h file.

Using assert and NOT using exception handling. This results in different ways of doing business. The errors are caught in debug code and largely error handling code is thrown away in the release code.

Exception handling incurs a cost as another return path in the code is needed. The goal of this code base is to optimize speed and where possible use direct bindings (no virtual functions).

I have never met an bug that can not be caught in debug code. And I have used assert in multi-threaded programming situations while catching bugs.

<TODO>

Finer grain control over testing and compiling, and realizing that the two are really linked. For example a test script may want to run and generate gprof information. This could be in addition to normal testing, so two different compilations of the source are needed.

Additional bash testscipts could do the logic. For example recompile source and run other tests.
The project build links is broken for this project page.
main.cpp is not linked.
Either in the source table or in the makefile.
Implement source control.
Investigate Subversion.
Downloading the source file cppcode.tar.gz needs to be changed to include other files in the build such as configuration and demonstration files.

C++ Projects