| 1 | TITLE Programmers Notes for Box Backup |
|---|
| 2 | |
|---|
| 3 | This directory contains the programmers notes for the Box Backup system. They will be of interest only if you want to review or modify the code. |
|---|
| 4 | |
|---|
| 5 | These notes are intended to be run through a script to produce HTML at some later stage, hence the marks such as 'TITLE'. |
|---|
| 6 | |
|---|
| 7 | |
|---|
| 8 | SUBTITLE Organisation |
|---|
| 9 | |
|---|
| 10 | The project is split up into several modules. The modules within 'lib' are building blocks for creation of the actual executable programs within 'bin'. 'test' contains unit tests for lib and bin modules. |
|---|
| 11 | |
|---|
| 12 | The file modules.txt lists the modules which are to be built, and their dependencies. It also allows for platform differences. |
|---|
| 13 | |
|---|
| 14 | |
|---|
| 15 | SUBTITLE Documentation Organisation |
|---|
| 16 | |
|---|
| 17 | In this directory, the files correspond to modules or areas of interest. Sub directories of the same name contain files documenting specific classes within that module. |
|---|
| 18 | |
|---|
| 19 | |
|---|
| 20 | SUBTITLE Suggested reading order |
|---|
| 21 | |
|---|
| 22 | * common/lib_common.txt |
|---|
| 23 | * common/lib_server.txt |
|---|
| 24 | * bin_bbackupd.txt |
|---|
| 25 | * backup_encryption.txt |
|---|
| 26 | * bin_bbstored.txt |
|---|
| 27 | * raidfile/lib_raidfile.txt |
|---|
| 28 | |
|---|
| 29 | and refer to other sections as required. |
|---|
| 30 | |
|---|
| 31 | |
|---|
| 32 | SUBTITLE Building |
|---|
| 33 | |
|---|
| 34 | The makefiles are generated by makebuildenv.pl. (The top level makefile is generated by makeparcels.pl, but this is for the end user to use, not a programmer.) |
|---|
| 35 | |
|---|
| 36 | To build a module, cd to it and type make. If the -DRELEASE option is specified (RELEASE=1 with GNU make) the release version will be built. The object files and exes are placed in a directory structure under 'release' or 'debug'. |
|---|
| 37 | |
|---|
| 38 | It is intended that a test will be written for everything, so in general make commands will be issued only within the test/* modules. Once it has been built, cd to debug/test/<testname> and run the test with ./t . |
|---|
| 39 | |
|---|
| 40 | |
|---|
| 41 | SUBTITLE Programming style |
|---|
| 42 | |
|---|
| 43 | The code is written to be easy to write. Ease of programming is the primary concern, as this should lead to fewer bugs. Efficiency improvements can be made later when the system as a whole works. |
|---|
| 44 | |
|---|
| 45 | Much use is made of the STL. |
|---|
| 46 | |
|---|
| 47 | There is no common base class. |
|---|
| 48 | |
|---|
| 49 | All errors are reported using exceptions. |
|---|
| 50 | |
|---|
| 51 | Some of the boring code is generated by perl scripts from description files. |
|---|
| 52 | |
|---|
| 53 | There are a lot of modules and classes which can easily be used to build other projects in the future -- there is a lot of "framework" code. |
|---|
| 54 | |
|---|
| 55 | |
|---|
| 56 | SUBTITLE Lots more documentation |
|---|
| 57 | |
|---|
| 58 | The files are extensively commented. Consider this notes as an overview, and then read the source files for detailed and definitive information. |
|---|
| 59 | |
|---|
| 60 | Each function and class has a very brief decsription of it's purpose in a standard header, and extensive efforts have been maed to comment the code itself. |
|---|
| 61 | |
|---|
