AFSLore/CodeArchitecture.mdwn

   1 -- [[StevenJenkins]] - 08 Jun 2007
   2
   3 This is an entry point into the code architecture. As always, the source for your release is the authoritative reference, but this wiki is designed to help navigate the source and point out relevant documentation.
   4
   5 -- Starting Point --
   6
   7 - <http://www.openafs.org/cgi-bin/cvsweb.cgi/openafs/doc/pdf/> Early architectural documents. Out of date, but still important. You should especially read the Architectural Overview document (archov-doc.pdf)
   8 - To understand the source layout, consult src/SOURCE-MAP -- this is a good place to go after reading the Architectural Overview
   9 - Need to document the build environment issues -- README, README.DEVEL, README.CVS
  10 - src/BUILDNOTES (at least in the 1.4 tree) is not very helpful.
  11
  12 [Hard Drive Restoration](http://www.securedatarecovery.com)
  13
  14 -- Source Browsing --
  15
  16 - The source tree has been converted to git - see [[GitDevelopers]] for how to access it.
  17
  18 - If you must use CVS, see [[OpenAFSCVS]]
  19
  20 But in that tree, README.CVS has the following line:
  21
  22 Do not use the CVS tree unless you know what you're doing.
  23
  24 This document helps you learn what you're doing.
  25
  26 - cvs co, regen.sh (&amp; when to run regen.sh)
  27
  28 ----
  29
  30 In the source itself ---
  31
  32 - **find | grep** is very helpful. For example, to find all the RX packages (ie, so that you can start to identify the various namespaces of components), you can do:
  33
  34     find . -name \*.xg -exec grep -H "^package" {} \; | grep -v 'example' | grep -v 'bulktest' | \
  35       sed -e 's|^./src/||' | sed -e 's/package/ /' | awk '{printf "%10s   %s\n", $2, $1}'
  36
  37 which results in:
  38
  39         VOTE_   ubik/ubik_int.xg:
  40          DISK_   ubik/ubik_int.xg:
  41        SAMPLE_   ubik/utst_int.xg:
  42            VL_   vlserver/vldbint.xg:
  43        UPDATE_   update/update.xg:
  44          TEST_   rxgk/test.xg:
  45          RXGK_   rxgk/rxgk_proto.xg:
  46       RXAFSCB_   fsint/afscbint.xg:
  47         RXAFS_   fsint/afsint.xg:
  48       RXSTATS_   rxstat/rxstat.xg:
  49            PR_   ptserver/ptint.xg:
  50          BOZO_   bozo/bosint.xg:
  51         BUMON_   bubasics/backmon.xg:
  52            TC_   bubasics/butc.xg:
  53            BC_   bubasics/bumon.xg:
  54           ADK_   dauth/adkint.xg:
  55        RMTSYS_   sys/rmtsys.xg:
  56         AFSVol   volser/volint.xg:
  57
  58 In other words, if something starts with BOZO\_, you know that it is generated by rxgen, and the interface is defined in `bozo/bosint.xg`.
  59
  60 In addition to the package name, also note that only rxstat uses an M prefix; all others use S.
  61
  62 - Assuming you have a fairly modern grep, you can use its recursive facility:
  63
  64   $ **grep -r regex .**
  65
  66 and find every time <pattern> appears in a file
  67
  68 - If you're looking for one specific word, the <tt>-w</tt> switch is your friend as well.
  69
  70   $ **egrep -w -r VFORMAT .**
  71
  72 will find all instances of **VFORMAT** but will not find **ABVFORMAT**
  73
  74 - cscope: a source code browser, linked to your editor. Setup is simple: cd to your source tree and run:
  75
  76     $ **cscope -R -b**
  77
  78 Then run
  79
  80     $ **cscope -d**
  81
  82 to start. The interface is simple. I tend to use it for finding things, but not necessarily for editing. When I'm studying the source, trying to understand how components link together, or bug-hunting, I tend to live inside `cscope`.
  83
  84 - doxygen: what it is, how to set up, how to use, how to make even more useful (ie, src code changes)
  85
  86 - gdb: examples of using (primarily b, bt)