# Used technologies

Our project uses several technologies. All of them are open, standardized and generally accepted and free. Their licence policy is compatible with

## Used Libraries

### Boost libraries

Boost is free, highly portable and de facto standard set of libraries for C++ language (see &boost_link_index;). Most of new C++ features which are very likely to became part of the standard are firstly implemented and tested here. Also the technical report (TR1) is implemented in boost.

We are using mainly &boost_link_smartptr; especially shared pointers which provide easy to use and safe automatic object life cycle maintainance of shared objects. All objects exported from kernel to higher layers are wrapped by &boost_link_sharedptr; smart pointers.

Boost Iostreams make it easy to create standard C++ streams and stream buffers and provide a framework for defining Filters and attaching them to standard streams and stream buffers. The second feature allows creating a flexible, easy to use and extend solution to support encryption/decryption and compression/decompression of objects.

### STL - standard template library

STL is C++ standard set of libraries which provides container, algorithm, iterators (and many more) template classes. Their implementation is highly portable and optimized for high performance. We are using mainly mentioned containers for data storage purposes, iterators for effective data structures traversing. For more information and documentation for STL, see &stl_link_index;.

### Qt framework

Qt is a multiplatform C++ GUI toolkit created and maintained by Trolltech, we are using version 3 of the toolkit. We are using mainly gui (widgets) classes (see &qt_link_classes;) and &qsa_link_index; framework for scripting layer. Slightly modified QSA version based on QSA 1.1.5 is included in our source tree.

## CPP Unit automatic testing

&cppunit_link_index; is a C++ unit testing framework. We are using this framework for automatic testing of kernel interface and its functionality. All test cases are placed in kernel/tests directory and they are linked to kernel/kernel_tests binary output. We have implemented test classes for all interface objects. Each class is specialized for certain class interface object. Each class has general name form

    	TestClassName

where ClassName stands for tested class. Test class implements test suite which is identified by its name. Main test program runs all test suites specified by name (). Each test suit consists of test cases which test particular behavior of tested class.

### Test class description

Each test class should inherit from CPP unit TextFixture class. At first CPPUNIT_TEST_SUITE and CPPUNIT_TEST macros should be used to prepare this class to cpp unit framework and to define test case functions. Finally class should be registered to framework, so test program can run it by specified name (this name should follow TEST_CLASSNAME convention).

Each test case should perform operations on tested class and checks which have to be kept for such operations. CPPUNIT_ASSERT macro should be used to check invariant condition or CPPUNIT_FAIL should be used to force failure of test.

See following example (it can be used as template for new test suite creation).

    	class TestClassName : public CppUnit::TestFixture
    	{
    		// defines this class as test suite
    		CPPUNIT_TEST_SUITE(TestClassName);
    			// This method has to be implemented as test case
    			CPPUNIT_TEST(TestMethod);

    			// definition of other test cases
    		CPPUNIT_TEST_SUITE_END();
    	public:
    		void setUp()
    		{
    			// this method should initialize local test class
    			// data used in tests
    		}

    		void tearDown()
    		{
    			// clean up after setUp method
    		}

    		void Test()
    		{
    			// Implementation of testcase
    			CPPUNIT_ASSERT(expected==op())

    			// ...

    			// sometimes we need to test that something throws an
    			// exception
    			try
    			{
    				// this operation should throw with this parameters
    				op(parameters);

    				// exception hasn't occured, we will force failure
    				CPPUNIT_FAIL("This operation should have failed.");
    			}catch(ExceptionType & e)
    			{
    				// ok, exception has been thrown
    			}
    		}

    	};

    	// registers this class to CPP Unit framework and assigns it
    	// with given name
    	CPPUNIT_TEST_SUITE_REGISTRATION(TestClassName);
    	CPPUNIT_TEST_SUITE_NAMED_REGISTRATION(TestClassName, "TEST_CLASSNAME");

### Test program

There are two sets of input parameters you can specify. The first set of parameters specifies input pdf files or directories. After no file with specified name is found the parameter is assumed to be a name of a test suite to run. Result of these tests is information whether the test was successful, threw an exception or a condition was not met.

## Documentation

### Code and script documentation

We are using &doxygen_link_index; documentation tool. This means that documented parts use special format for comments, where the comment starts with double star, like: /** Doxygen comment */. These comments are then used by doxygen to create html pages (or other formats).

Functions exported to scripting use different kind of documentation in addition to doxygen comments. We had to use format different from doxygen, otherwise doxygen would parse our comments and we would parse doxygen comments, which would lead into confusion. So, besides of ordinary doxygen comment which is located above the function body in .cc file, we write extra comment in corresponding .h file, that is exported to scripting API documentation. Content of the comment is often similar, but often doxygen documentation for programmer contain information not useful or misleading for script users and vice versa.

Documentation for scripts are in comment with first comment character being a dash (unlike another star for doxygen comments), like this comment: /*- Comment for function */. The comment have to be put in a header file directly above the function declaration. Comment for class is similar, but it have equal sign instead of dash, like: /*= Comment for class */. It have to be put directly above class declaration.

Another difference between doxygen and this format is that the comment is treated as docbook code - it can contain docbook tags to format the comment or insert a list or table in it, basically whetever docbook code can be put between <para> and </para> tags.

Among tools for generating documentation there is a perl script, which will parse docbook file and all strings in format of `<!--TYPE: filename.h -->` will be replaced by generated chunk of documentation from filename.h, that will document the class in it. This is used for wrapper classes, where class methods correspond to same methods in scripting environment. Similarly, all strings in format `<!--BASETYPE: filename.h -->` will be replaced with similarly generated doumentation chunk, except functions are assumed to be static functions available to script, not methods of class contained in the header file. This is used to comment the base classes (`Base`, `BaseGui` and `BaseConsole`), because slot functions in these classes are exported to scripting as static functions.

Documentation generated this way is then treated as ordinary docbook XML file. The scripting API is documented in User documentation Appendix.

### Design and user documentation

Design and user manual are written in &docbook_link_index; standardized and open free format. XML files (with osasis docbook 4.2 &docbook_link_dtd; file) which forms (this) design documentation are stored in doc/design directory. Main file is design_doc.xml file which includes all other files. Files specialized for kernel design are stored in doc/design/kernel directory. With same logic, gui design files are stored in doc/design/gui directory.