libfossil  Hex Artifact Content

Artifact e62fa3d98ae60dc8b72036eaba567218e9a47efc:

Wiki page [HackersGuide] by stephan 2014-11-07 15:09:51.
0000: 44 20 32 30 31 34 2d 31 31 2d 30 37 54 31 35 3a  D 2014-11-07T15:
0010: 30 39 3a 35 31 2e 35 33 32 0a 4c 20 48 61 63 6b  09:51.532.L Hack
0020: 65 72 73 47 75 69 64 65 0a 50 20 62 32 34 63 36  ersGuide.P b24c6
0030: 63 37 32 33 62 65 34 36 64 64 38 63 37 61 66 30  c723be46dd8c7af0
0040: 30 64 62 61 65 34 62 62 66 61 32 39 63 37 37 31  0dbae4bbfa29c771
0050: 62 62 35 0a 55 20 73 74 65 70 68 61 6e 0a 57 20  bb5.U stephan.W 
0060: 33 37 33 35 0a 3c 68 31 3e 48 61 63 6b 65 72 27  3735.<h1>Hacker'
0070: 73 20 47 75 69 64 65 3c 2f 68 31 3e 0d 0a 0d 0a  s Guide</h1>....
0080: 53 65 65 20 61 6c 73 6f 3a 20 5b 62 75 69 6c 64  See also: [build
0090: 69 6e 67 5d 2c 20 5b 41 6d 61 6c 67 61 6d 61 74  ing], [Amalgamat
00a0: 69 6f 6e 42 75 69 6c 64 5d 0d 0a 0d 0a 54 68 69  ionBuild]....Thi
00b0: 73 20 70 61 67 65 20 70 72 69 6d 61 72 69 6c 79  s page primarily
00c0: 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 74 65 73 20   contains notes 
00d0: 66 6f 72 20 61 6e 79 6f 6e 65 20 77 68 6f 27 73  for anyone who's
00e0: 20 61 63 74 69 76 65 6c 79 20 68 61 63 6b 69 6e   actively hackin
00f0: 67 20 6f 6e 20 6c 69 62 66 6f 73 73 69 6c 20 69  g on libfossil i
0100: 6e 74 65 72 6e 61 6c 73 2c 20 65 2e 67 2e 20 63  nternals, e.g. c
0110: 68 61 6e 67 69 6e 67 20 3c 74 74 3e 66 73 6c 5f  hanging <tt>fsl_
0120: 63 78 3c 2f 74 74 3e 27 73 20 73 74 72 75 63 74  cx</tt>'s struct
0130: 75 72 65 2e 0d 0a 0d 0a 41 6e 20 3c 65 6d 3e 65  ure.....An <em>e
0140: 78 63 65 65 64 69 6e 67 6c 79 20 62 72 69 65 66  xceedingly brief
0150: 3c 2f 65 6d 3e 20 69 6e 74 72 6f 20 74 6f 20 74  </em> intro to t
0160: 68 65 20 73 6f 75 72 63 65 20 74 72 65 65 3a 0d  he source tree:.
0170: 0a 0d 0a 20 20 2a 20 20 54 68 65 20 70 72 69 6d  ...  *  The prim
0180: 61 72 79 20 22 65 78 70 6f 72 74 65 64 22 20 64  ary "exported" d
0190: 69 73 74 72 69 62 75 74 61 62 6c 65 20 69 73 20  istributable is 
01a0: 74 68 65 20 5b 41 6d 61 6c 67 61 6d 61 74 69 6f  the [Amalgamatio
01b0: 6e 42 75 69 6c 64 5d 2e 20 54 68 65 20 6f 74 68  nBuild]. The oth
01c0: 65 72 20 73 6f 75 72 63 65 73 20 61 6e 64 20 68  er sources and h
01d0: 65 61 64 65 72 73 20 61 72 65 20 65 73 73 65 6e  eaders are essen
01e0: 74 69 61 6c 6c 79 20 63 6f 6d 70 6f 6e 65 6e 74  tially component
01f0: 73 20 66 6f 72 20 63 72 65 61 74 69 6e 67 20 74  s for creating t
0200: 68 61 74 20 64 65 6c 69 76 65 72 61 62 6c 65 2e  hat deliverable.
0210: 0d 0a 20 20 2a 20 20 50 75 62 6c 69 63 20 68 65  ..  *  Public he
0220: 61 64 65 72 73 20 67 6f 20 69 6e 20 3c 74 74 3e  aders go in <tt>
0230: 69 6e 63 6c 75 64 65 2f 66 6f 73 73 69 6c 2d 73  include/fossil-s
0240: 63 6d 2f 3c 2f 74 74 3e 2e 20 54 68 65 72 65 20  cm/</tt>. There 
0250: 69 73 20 61 74 20 6c 65 61 73 74 20 6f 6e 65 20  is at least one 
0260: 70 73 65 75 64 6f 2d 70 72 69 76 61 74 65 20 68  pseudo-private h
0270: 65 61 64 65 72 20 28 3c 74 74 3e 66 6f 73 73 69  eader (<tt>fossi
0280: 6c 2d 69 6e 74 65 72 6e 61 6c 2e 68 3c 2f 74 74  l-internal.h</tt
0290: 3e 29 20 74 68 65 72 65 20 61 73 20 77 65 6c 6c  >) there as well
02a0: 2c 20 62 75 74 20 74 68 61 74 20 6f 6e 65 20 69  , but that one i
02b0: 73 20 75 6e 64 65 72 20 63 6f 6e 73 69 64 65 72  s under consider
02c0: 61 74 69 6f 6e 20 66 6f 72 20 62 65 69 6e 67 20  ation for being 
02d0: 6d 6f 76 65 64 20 74 6f 2e 2e 2e 0d 0a 20 20 2a  moved to.....  *
02e0: 20 20 50 72 69 76 61 74 65 20 69 6d 70 6c 20 66    Private impl f
02f0: 69 6c 65 73 20 61 6e 64 20 68 65 61 64 65 72 73  iles and headers
0300: 20 67 6f 20 69 6e 20 3c 74 74 3e 73 72 63 2f 3c   go in <tt>src/<
0310: 2f 74 74 3e 2e 20 0d 0a 20 20 2a 20 20 44 65 6d  /tt>. ..  *  Dem
0320: 6f 2f 74 65 73 74 20 61 70 70 73 20 63 61 6e 20  o/test apps can 
0330: 62 65 20 66 6f 75 6e 64 20 69 6e 20 3c 74 74 3e  be found in <tt>
0340: 66 2d 61 70 70 73 2f 3c 2f 74 74 3e 2e 0d 0a 20  f-apps/</tt>... 
0350: 20 2a 20 20 54 68 65 20 74 72 75 6c 79 20 61 64   *  The truly ad
0360: 76 65 6e 74 75 72 6f 75 73 20 6d 69 67 68 74 20  venturous might 
0370: 77 61 6e 64 20 74 6f 20 65 78 70 6c 6f 72 65 20  wand to explore 
0380: 74 68 65 20 6f 74 68 65 72 20 76 61 72 69 6f 75  the other variou
0390: 73 20 73 75 62 64 69 72 73 2c 20 6c 69 6b 65 20  s subdirs, like 
03a0: 3c 74 74 3e 73 71 6c 2f 3c 2f 74 74 3e 20 28 73  <tt>sql/</tt> (s
03b0: 63 68 65 6d 61 20 66 69 6c 65 73 29 2c 20 3c 74  chema files), <t
03c0: 74 3e 63 70 70 2f 3c 2f 74 74 3e 20 28 6f 6e 65  t>cpp/</tt> (one
03d0: 20 70 6f 74 65 6e 74 69 61 6c 20 43 2b 2b 20 62   potential C++ b
03e0: 69 6e 64 69 6e 67 29 20 61 6e 64 20 3c 74 74 3e  inding) and <tt>
03f0: 73 32 2f 3c 2f 74 74 3e 20 28 73 63 72 69 70 74  s2/</tt> (script
0400: 20 62 69 6e 64 69 6e 67 73 29 2e 0d 0a 20 20 2a   bindings)...  *
0410: 20 20 54 68 65 20 22 6e 61 74 69 76 65 22 20 62    The "native" b
0420: 75 69 6c 64 20 70 6c 61 74 66 6f 72 6d 20 72 65  uild platform re
0430: 71 75 69 72 65 73 20 47 4e 55 20 4d 61 6b 65 20  quires GNU Make 
0440: 33 2e 38 31 20 6f 72 20 68 69 67 68 65 72 20 61  3.81 or higher a
0450: 6e 64 20 74 68 65 20 63 6f 6e 76 65 6e 74 69 6f  nd the conventio
0460: 6e 61 6c 20 73 65 74 20 6f 66 20 55 6e 69 78 2d  nal set of Unix-
0470: 73 69 64 65 20 62 75 69 6c 64 20 74 6f 6f 6c 73  side build tools
0480: 2e 20 43 6f 6e 74 72 69 62 75 74 69 6f 6e 73 20  . Contributions 
0490: 6f 66 20 63 6f 6e 74 72 6f 6c 20 66 69 6c 65 73  of control files
04a0: 20 28 6f 72 20 52 45 41 44 4d 45 73 29 20 66 6f   (or READMEs) fo
04b0: 72 20 6f 74 68 65 72 20 62 75 69 6c 64 20 70 6c  r other build pl
04c0: 61 74 66 6f 72 6d 73 20 61 72 65 20 6f 66 20 63  atforms are of c
04d0: 6f 75 72 73 65 20 77 65 6c 63 6f 6d 65 64 2e 0d  ourse welcomed..
04e0: 0a 20 20 2a 20 20 54 68 65 20 6f 76 65 72 61 6c  .  *  The overal
04f0: 6c 20 73 74 79 6c 65 20 69 73 20 61 20 64 69 72  l style is a dir
0500: 65 63 74 20 61 72 74 69 66 61 63 74 20 28 61 73  ect artifact (as
0510: 20 69 74 20 77 65 72 65 29 20 6f 66 20 66 6f 73   it were) of fos
0520: 73 69 6c 28 31 29 2c 20 61 6e 64 20 77 65 20 61  sil(1), and we a
0530: 73 6b 20 74 68 61 74 20 61 6c 6c 20 63 6f 6e 74  sk that all cont
0540: 72 69 62 75 74 6f 72 73 20 6d 61 69 6e 74 61 69  ributors maintai
0550: 6e 20 74 68 65 20 67 65 6e 65 72 61 6c 20 6f 76  n the general ov
0560: 65 72 61 6c 6c 20 73 74 79 6c 65 2e 20 57 65 20  erall style. We 
0570: 61 72 65 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e  are <em>not</em>
0580: 20 70 69 63 6b 79 20 61 62 6f 75 74 20 70 6c 61   picky about pla
0590: 63 65 6d 65 6e 74 20 6f 66 20 73 70 61 63 65 73  cement of spaces
05a0: 20 61 72 6f 75 6e 64 20 70 61 72 65 6e 74 68 65   around parenthe
05b0: 73 69 73 20 61 6e 64 20 77 68 61 74 6e 6f 74 2c  sis and whatnot,
05c0: 20 6d 61 69 6e 6c 79 20 6a 75 73 74 20 74 68 65   mainly just the
05d0: 20 6f 76 65 72 61 6c 6c 20 69 6e 64 65 6e 74 61   overall indenta
05e0: 74 69 6f 6e 20 61 6e 64 20 3c 74 74 3e 7b 3c 2f  tion and <tt>{</
05f0: 74 74 3e 62 72 61 63 69 6e 67 3c 74 74 3e 7d 3c  tt>bracing<tt>}<
0600: 2f 74 74 3e 20 73 74 79 6c 65 73 2c 20 61 73 20  /tt> styles, as 
0610: 77 65 6c 6c 20 61 73 20 74 68 65 20 6e 61 6d 69  well as the nami
0620: 6e 67 20 73 74 79 6c 65 20 66 6f 72 20 70 75 62  ng style for pub
0630: 6c 69 63 20 73 79 6d 62 6f 6c 73 20 28 65 2e 67  lic symbols (e.g
0640: 2e 20 61 20 70 72 65 66 69 78 20 6f 66 20 22 66  . a prefix of "f
0650: 73 6c 5f 22 20 6f 6e 20 6d 6f 73 74 20 73 79 6d  sl_" on most sym
0660: 62 6f 6c 73 29 2e 20 54 68 65 20 6f 6e 65 20 6e  bols). The one n
0670: 6f 74 61 62 6c 65 20 65 78 63 65 70 74 69 6f 6e  otable exception
0680: 20 69 73 20 68 6f 77 20 41 50 49 73 20 61 72 65   is how APIs are
0690: 20 64 6f 63 75 6d 65 6e 74 65 64 3a 20 6c 69 62   documented: lib
06a0: 66 6f 73 73 69 6c 20 75 73 65 73 20 44 6f 78 79  fossil uses Doxy
06b0: 67 65 6e 20 73 74 79 6c 65 20 28 61 6e 64 20 44  gen style (and D
06c0: 6f 78 79 67 65 6e 20 63 61 6e 6e 6f 74 20 73 77  oxygen cannot sw
06d0: 61 6c 6c 6f 77 20 66 6f 73 73 69 6c 27 73 20 6e  allow fossil's n
06e0: 61 74 69 76 65 20 63 6f 6d 6d 65 6e 74 20 73 74  ative comment st
06f0: 79 6c 65 29 2e 0d 0a 0d 0a 0d 0a 0d 0a 3c 68 32  yle).........<h2
0700: 3e 41 6e 20 49 6e 74 72 6f 64 75 63 74 69 6f 6e  >An Introduction
0710: 20 74 6f 20 73 74 72 75 63 74 73 2e 2e 2e 3c 2f   to structs...</
0720: 68 32 3e 0d 0a 0d 0a 41 6c 6c 20 28 6f 72 20 61  h2>....All (or a
0730: 6c 6d 6f 73 74 20 61 6c 6c 29 20 73 74 72 75 63  lmost all) struc
0740: 74 73 20 69 6e 20 74 68 65 20 6c 69 62 72 61 72  ts in the librar
0750: 79 20 61 72 65 20 61 63 63 6f 6d 70 61 6e 69 65  y are accompanie
0760: 64 20 62 79 20 6f 74 68 65 72 20 63 6f 6e 73 74  d by other const
0770: 72 75 63 74 73 20 77 68 69 63 68 20 68 65 6c 70  ructs which help
0780: 20 65 6e 73 75 72 65 20 28 69 6e 73 75 72 65 3f   ensure (insure?
0790: 29 20 63 6f 6e 73 69 73 74 65 6e 63 79 20 72 65  ) consistency re
07a0: 67 61 72 64 69 6e 67 20 68 6f 77 20 6c 69 62 72  garding how libr
07b0: 61 72 79 2d 6c 65 76 65 6c 20 73 74 72 75 63 74  ary-level struct
07c0: 73 20 61 72 65 20 74 6f 20 62 65 20 69 6e 69 74  s are to be init
07d0: 69 61 6c 69 7a 65 64 2e 20 54 68 65 20 67 65 6e  ialized. The gen
07e0: 65 72 61 6c 20 70 61 74 74 65 72 6e 20 6c 6f 6f  eral pattern loo
07f0: 6b 73 20 6c 69 6b 65 20 74 68 69 73 3a 0d 0a 0d  ks like this:...
0800: 0a 3c 6e 6f 77 69 6b 69 3e 3c 70 72 65 3e 0d 0a  .<nowiki><pre>..
0810: 73 74 72 75 63 74 20 66 73 6c 5f 66 6f 6f 20 7b  struct fsl_foo {
0820: 20 2e 2e 2e 20 7d 3b 0d 0a 74 79 70 65 64 65 66   ... };..typedef
0830: 20 73 74 72 75 63 74 20 66 73 6c 5f 66 6f 6f 20   struct fsl_foo 
0840: 66 73 6c 5f 66 6f 6f 3b 0d 0a 65 78 74 65 72 6e  fsl_foo;..extern
0850: 20 63 6f 6e 73 74 20 66 73 6c 5f 66 6f 6f 5f 65   const fsl_foo_e
0860: 6d 70 74 79 3b 0d 0a 23 64 65 66 69 6e 65 20 66  mpty;..#define f
0870: 73 6c 5f 66 6f 6f 5f 65 6d 70 74 79 5f 6d 20 7b  sl_foo_empty_m {
0880: 20 2e 2e 2e 6d 65 6d 62 65 72 20 69 6e 69 74 69   ...member initi
0890: 61 6c 69 7a 65 72 73 2e 2e 2e 20 7d 0d 0a 3c 2f  alizers... }..</
08a0: 70 72 65 3e 3c 2f 6e 6f 77 69 6b 69 3e 0d 0a 0d  pre></nowiki>...
08b0: 0a 54 68 65 20 70 75 72 70 6f 73 65 20 6f 66 20  .The purpose of 
08c0: 74 68 65 20 22 65 6d 70 74 79 5f 6d 22 20 6d 61  the "empty_m" ma
08d0: 63 72 6f 20 69 73 20 74 6f 20 64 65 66 69 6e 65  cro is to define
08e0: 20 61 20 63 6c 65 61 6e 6c 79 2d 69 6e 69 74 69   a cleanly-initi
08f0: 61 6c 69 7a 65 64 20 63 6f 6e 73 74 20 73 74 61  alized const sta
0900: 74 65 20 66 6f 72 20 74 68 61 74 20 73 74 72 75  te for that stru
0910: 63 74 2e 20 54 68 65 20 3c 74 74 3e 66 73 6c 5f  ct. The <tt>fsl_
0920: 66 6f 6f 5f 65 6d 70 74 79 3c 2f 74 74 3e 20 69  foo_empty</tt> i
0930: 6e 73 74 61 6e 63 65 20 69 73 20 67 75 61 72 61  nstance is guara
0940: 6e 74 65 65 64 20 74 6f 20 62 65 20 69 6e 69 74  nteed to be init
0950: 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 3c 74  ialized using <t
0960: 74 3e 66 73 6c 5f 66 6f 6f 5f 65 6d 70 74 79 5f  t>fsl_foo_empty_
0970: 6d 3c 2f 74 74 3e 2c 20 62 75 74 20 62 6f 74 68  m</tt>, but both
0980: 20 74 68 65 20 22 65 6d 70 74 79 22 20 61 6e 64   the "empty" and
0990: 20 22 65 6d 70 74 79 5f 6d 22 20 76 61 72 69 61   "empty_m" varia
09a0: 6e 74 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  nts are provided
09b0: 20 62 65 63 61 75 73 65 20 63 6f 64 65 20 72 65   because code re
09c0: 71 75 69 72 65 73 20 64 69 66 66 65 72 65 6e 74  quires different
09d0: 20 69 6e 69 74 69 61 6c 69 7a 65 72 73 20 69 6e   initializers in
09e0: 20 64 69 66 66 65 72 65 6e 74 20 63 6f 6e 74 65   different conte
09f0: 78 74 73 20 28 65 78 61 6d 70 6c 65 73 20 61 72  xts (examples ar
0a00: 65 20 70 72 6f 76 69 64 65 64 20 62 65 6c 6f 77  e provided below
0a10: 29 2e 0d 0a 0d 0a 54 68 65 20 22 5f 6d 22 20 73  ).....The "_m" s
0a20: 75 66 66 69 78 20 64 65 6e 6f 74 65 73 20 22 6d  uffix denotes "m
0a30: 61 63 72 6f 22 2c 20 62 79 20 74 68 65 20 77 61  acro", by the wa
0a40: 79 2e 0d 0a 0d 0a 41 6c 6c 20 6e 6f 6e 2d 6f 70  y.....All non-op
0a50: 61 71 75 65 20 73 74 72 75 63 74 73 20 63 61 6e  aque structs can
0a60: 20 61 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 69   and should be i
0a70: 6e 69 74 69 61 6c 69 7a 65 64 20 69 6e 20 63 6f  nitialized in co
0a80: 64 65 20 6c 69 6b 65 20 74 68 69 73 3a 0d 0a 0d  de like this:...
0a90: 0a 3c 6e 6f 77 69 6b 69 3e 3c 70 72 65 3e 0d 0a  .<nowiki><pre>..
0aa0: 66 73 6c 5f 62 75 66 66 65 72 20 62 75 66 20 3d  fsl_buffer buf =
0ab0: 20 66 73 6c 5f 62 75 66 66 65 72 5f 65 6d 70 74   fsl_buffer_empt
0ac0: 79 3b 0d 0a 66 73 6c 5f 64 65 63 6b 20 64 65 63  y;..fsl_deck dec
0ad0: 6b 20 3d 20 66 73 6c 5f 64 65 63 6b 5f 65 6d 70  k = fsl_deck_emp
0ae0: 74 79 3b 0d 0a 0d 0a 2f 2f 20 54 68 65 20 22 65  ty;....// The "e
0af0: 6d 70 74 79 5f 6d 22 20 6d 61 63 72 6f 73 20 61  mpty_m" macros a
0b00: 72 65 20 72 65 71 75 69 72 65 64 20 6d 61 69 6e  re required main
0b10: 6c 79 20 66 6f 72 20 69 6e 2d 73 74 72 75 63 74  ly for in-struct
0b20: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 3a   initialization:
0b30: 0d 0a 73 74 72 75 63 74 20 7b 0d 0a 20 20 66 73  ..struct {..  fs
0b40: 6c 5f 62 75 66 66 65 72 20 62 75 66 3b 0d 0a 20  l_buffer buf;.. 
0b50: 20 66 73 6c 5f 64 65 63 6b 20 64 65 63 6b 3b 0d   fsl_deck deck;.
0b60: 0a 7d 20 66 6f 6f 20 3d 20 7b 0d 0a 20 20 66 73  .} foo = {..  fs
0b70: 6c 5f 62 75 66 66 65 72 5f 65 6d 70 74 79 5f 6d  l_buffer_empty_m
0b80: 2c 0d 0a 20 20 66 73 6c 5f 64 65 63 6b 5f 65 6d  ,..  fsl_deck_em
0b90: 70 74 79 5f 6d 0d 0a 7d 3b 0d 0a 3c 2f 70 72 65  pty_m..};..</pre
0ba0: 3e 3c 2f 6e 6f 77 69 6b 69 3e 0d 0a 0d 0a 54 68  ></nowiki>....Th
0bb0: 61 74 20 65 6e 73 75 72 65 73 20 28 69 6e 73 75  at ensures (insu
0bc0: 72 65 73 3f 29 20 74 68 61 74 20 61 6c 6c 20 73  res?) that all s
0bd0: 74 72 75 63 74 20 6d 65 6d 62 65 72 73 20 67 65  truct members ge
0be0: 74 20 73 65 74 20 74 6f 20 6b 6e 6f 77 6e 20 64  t set to known d
0bf0: 65 66 61 75 6c 74 20 76 61 6c 75 65 73 20 28 77  efault values (w
0c00: 68 69 63 68 20 6e 65 65 64 20 6e 6f 74 20 62 65  hich need not be
0c10: 20 4e 55 4c 4c 2f 30 29 2c 20 61 6e 64 20 68 65   NULL/0), and he
0c20: 6c 70 73 20 68 61 72 64 65 6e 20 74 68 65 20 63  lps harden the c
0c30: 6f 64 65 20 61 67 61 69 6e 73 74 20 75 6e 69 6e  ode against unin
0c40: 69 74 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79  itialized memory
0c50: 20 61 63 63 65 73 73 20 28 73 69 6e 63 65 20 61   access (since a
0c60: 6c 6c 20 6d 65 6d 62 65 72 73 20 67 65 74 20 69  ll members get i
0c70: 6e 69 74 69 61 6c 69 7a 65 64 20 74 6f 20 77 68  nitialized to wh
0c80: 61 74 65 76 65 72 20 74 68 65 20 73 74 72 75 63  atever the struc
0c90: 74 20 64 65 76 65 6c 6f 70 65 72 20 64 65 65 6d  t developer deem
0ca0: 65 64 20 73 65 6e 73 69 62 6c 65 2c 20 61 6e 64  ed sensible, and
0cb0: 20 4e 55 4c 4c 20 69 73 20 67 65 6e 65 72 61 6c   NULL is general
0cc0: 6c 79 20 74 68 65 20 73 65 6e 73 69 62 6c 65 20  ly the sensible 
0cd0: 64 65 66 61 75 6c 74 20 66 6f 72 20 70 6f 69 6e  default for poin
0ce0: 74 65 72 20 6d 65 6d 62 65 72 73 29 2e 0d 0a 0d  ter members)....
0cf0: 0a 0d 0a 3c 68 32 3e 57 68 65 6e 20 75 70 64 61  ...<h2>When upda
0d00: 74 69 6e 67 20 73 74 72 75 63 74 73 2e 2e 2e 3c  ting structs...<
0d10: 2f 68 32 3e 0d 0a 0d 0a 57 68 65 6e 20 63 68 61  /h2>....When cha
0d20: 6e 67 69 6e 67 20 74 68 65 20 6d 65 6d 62 65 72  nging the member
0d30: 73 20 6f 66 20 73 74 72 75 63 74 73 2c 20 69 74  s of structs, it
0d40: 20 69 73 20 3c 65 6d 3e 63 72 69 74 69 63 61 6c   is <em>critical
0d50: 3c 2f 65 6d 3e 20 74 68 61 74 20 74 68 65 20 61  </em> that the a
0d60: 63 63 6f 6d 70 61 6e 79 69 6e 67 20 22 65 6d 70  ccompanying "emp
0d70: 74 79 5f 6d 22 20 6d 61 63 72 6f 20 28 64 65 73  ty_m" macro (des
0d80: 63 72 69 62 65 64 20 61 62 6f 76 65 29 20 61 6c  cribed above) al
0d90: 73 6f 20 62 65 20 75 70 64 61 74 65 64 2e 20 46  so be updated. F
0da0: 61 69 6c 69 6e 67 20 74 6f 20 64 6f 20 73 6f 20  ailing to do so 
0db0: 63 61 6e 20 6c 65 61 64 20 74 6f 20 75 6e 64 65  can lead to unde
0dc0: 66 69 6e 65 64 20 72 65 73 75 6c 74 73 20 28 62  fined results (b
0dd0: 65 73 74 20 63 61 73 65 20 69 73 20 61 20 63 6f  est case is a co
0de0: 6d 70 69 6c 61 74 69 6f 6e 20 66 61 69 6c 75 72  mpilation failur
0df0: 65 20 77 68 65 6e 20 74 68 65 20 73 68 61 72 65  e when the share
0e00: 64 20 73 74 72 75 63 74 20 22 65 6d 70 74 79 22  d struct "empty"
0e10: 20 69 6e 73 74 61 6e 63 65 20 69 73 20 69 6e 69   instance is ini
0e20: 74 69 61 6c 69 7a 65 64 20 66 72 6f 6d 20 74 68  tialized from th
0e30: 65 20 22 65 6d 70 74 79 5f 6d 22 20 6d 61 63 72  e "empty_m" macr
0e40: 6f 29 2e 0d 0a 0d 0a 41 66 74 65 72 20 63 68 61  o).....After cha
0e50: 6e 67 69 6e 67 20 61 20 73 74 72 75 63 74 2c 20  nging a struct, 
0e60: 6d 61 6b 65 20 73 75 72 65 20 74 6f 20 64 6f 20  make sure to do 
0e70: 61 20 66 75 6c 6c 2f 63 6c 65 61 6e 20 72 65 62  a full/clean reb
0e80: 75 69 6c 64 20 6f 72 20 79 6f 75 20 6d 69 67 68  uild or you migh
0e90: 74 20 73 65 65 20 3c 65 6d 3e 72 65 61 6c 6c 79  t see <em>really
0ea0: 3c 2f 65 6d 3e 20 77 65 69 72 64 20 72 65 73 75  </em> weird resu
0eb0: 6c 74 73 20 69 6e 20 63 6f 64 65 20 63 6f 6d 70  lts in code comp
0ec0: 69 6c 65 64 20 61 67 61 69 6e 73 74 20 6f 6c 64  iled against old
0ed0: 65 72 20 73 74 72 75 63 74 2e 0d 0a 0d 0a 3c 6e  er struct.....<n
0ee0: 6f 77 69 6b 69 3e 3c 70 72 65 3e 0d 0a 3c 2f 70  owiki><pre>..</p
0ef0: 72 65 3e 3c 2f 6e 6f 77 69 6b 69 3e 0a 5a 20 64  re></nowiki>.Z d
0f00: 35 62 37 35 63 37 34 66 33 64 62 35 37 63 66 30  5b75c74f3db57cf0
0f10: 39 66 66 39 31 34 61 37 33 63 34 62 39 61 65 0a  9ff914a73c4b9ae.