Page History
- 2007-Nov-07 11:03 ono
- 2005-Dec-31 20:46 cpb
- 2005-Dec-31 16:00 cpb
- 2005-Aug-21 14:22 cpb
- 2005-Aug-21 03:22 cpb
These are more like observations from a latecomer, but better than nothing. CvstracArchitecture is a big picture overview. This talks about the nitty-gritty coding details.
Indentation
CVSTrac source uses two spaces for indentation, no tabs.
Braces and Parentheses
Braces are a modified K&R. Generally, there should be no whitespace between the trailing paren and the leading brace. i.e.
void function(args){ if( condition ){ } }
In the case of else and else if keywords, also eliminate extra whitespace:
if( condition ){ }else if( condition2 ){ }else{ }
Within parentheses, rules differ. For example, if and while statements use internal whitespace:
if( condition ){ while( v[i] ) i++; }
but for loops are a bit different:
for(i=0; i<40; i++){ }
Note that single-line if, for and occasionally while constructs are perfectly acceptable:
if( tn<=0 ) tn = 1; for(nChng=0; az[nChng]; nChng++){}
Preprocessing
CVSTrac has a magical preprocessor which extracts HTML strings prefixed inline by '@' characters and basically turns them into cgi_printf() calls. CvstracArchitecture discusses this further.
Variables
Variable naming is partially Hungarian style.
- 'z' prefixes NUL-terminated strings
- 'az' prefixes an array of 'z' strings. 'az' strings also appear to be NULL terminated.
- 'p' prefixes a pointer to something
- 'n' occasionally prefixes integers
Some commonly used variable names
- tn is a ticket number
- cn is a change/checkin number
- rn is a report number
Frequently Seen Functions
Not even close to a complete list.
- P(x) the CGI parameter x, or NULL
- PD(x,y) the CGI parameter x, or y
- cgi_printf() writes a formatted string into the CGI output buffer
- mprintf() is a custom function to format a string into a new memory buffer
- output_formatted(zText,zPage) output zText to the CGI buffer, doing any needed wiki formatting. zPage indicates the source page (i.e. wiki page) and is used for finding embeddable attachments like images.
- db_query() execute a SQLite query against the database and return the results as an az array. Deallocate results with db_query_free().
- db_short_query(), returns a single NUL-terminated string. Clean up with free().
- db_execute() executes a SQLite query, returning nothing.
Memory
CVSTrac doesn't worry about memory management! It's assumed that a CVSTrac instance will live only long enough to serve out a request and then resources will be reclaimed (AKA garbage collection by exit()). As such, you frequently see constructs like:
zPath = mprintf("%s/%s", zDir, zFile);
without a corresponding free(). The only time memory is really a concern happens when a large amount of activity happens in a loop. In such instances, free() or db_query_free() will be used.
Format Strings
CVSTrac uses a custom mprintf() which supports additional formatting. For security purposes, the following are preferred over just %s:
- %h Escapes HTML markup
- %t For URLs. Preserves "/" characters
- %T For URLs. Translates "/" into "%2F"
- %q Escapes ' characters in SQL
Security
CVSTrac cares about security. This means dynamic memory allocation where possible, really large static buffers with limits on the size of copies, heavy use of the %q format (as found in mprintf() and db_query()), and a lot of heavily used helper functions to manage all this.