HACKING

   1 This file is meant to summarize the Viking development policies.
   2
   3 ####
   4 #### Also check information in the Wiki:
   5 #### http://sourceforge.net/apps/mediawiki/viking/index.php?title=Main_Page
   6 ####
   7
   8 Clean commits
   9 =============
  10
  11 Commits/patches should be as fine-grained as possible (and no finer). Every
  12 distinct change should be in its own commit and every commit should be a
  13 meaningful change on its own.
  14
  15 Preferred Code Contribution Methods
  16 ===================================
  17
  18 Since the project uses git for source control, patches that utilize git (especially for patch sets) are preferred in this order:
  19 * Commits pushed to a publically accessible git host (e.g. GitHub, Gitorious, etc...)
  20    - This enables commits to be easily managed such as pulling, merging or cherry-picking
  21 * Email git diffs to the dev mailing list - use 'git format-patch' method
  22 * Plain diffs can be emailed to the dev mailing list and/or stored in the SourceForge Patch Tracker for Viking.
  23
  24 Coding style
  25 ============
  26
  27 Naming:
  28 A "module" is a .c file.
  29
  30 Functions starting with "vik_" operate on an object/structure with the
  31 module name (see layer.c for an example).  Functions starting with
  32 "a_" do not, these modules may have static variables.  Both are
  33 followed by the module name. Unless of course the function is static,
  34 in which case it may be called anything.
  35
  36 All (well, practically all) global constants and macros start with
  37 "VIK_" and then the module name.
  38
  39 Coding Checks
  40 =============
  41
  42 Code should compile with the minimum number of warnings (ideally none).
  43
  44 Code should pass static analysis with defaults for 'cppcheck' (http://sourceforge.net/projects/cppcheck/) with no errors.
  45
  46 ATM there is one deliberate error in vikgpslayer.c designed to prevent building if the code encounters a GPSD version we don't handle. Something like:
  47 [vikgpslayer.c:1479]: (error) Invalid number of character ({) when these macros are defined: 'GPSD_API_MAJOR_VERSION;VIK_CONFIG_REALTIME_GPS_TRACKING'.
  48 This can be 'hidden' via cppcheck --suppress syntax.
  49
  50 Technical notices
  51 =================
  52
  53 In order to activate reference documentation, you have to specify the
  54 following configure command line:
  55 $ ./configure --enable-gtk-doc --enable-gtk-doc-html
  56
  57 Then, cd to doc/reference and launch make command.
  58
  59 ---
  60
  61 The layers panel holds all the layers. Layers connect to the layers
  62 panel via what I call "interfaces" which are really just a structure
  63 of function pointers and pointers to other bits such as
  64 icons. viklayer.c switches between the layers like
  65 polymorhpism. Anything specific to the layer should (in theory) be
  66 found solely in that layer's source file.
  67
  68 There are some ugly hacks in here, like the layers panel holding the
  69 viewport and each layer holding the viewport and a
  70 GtkTreeIter. Unfortunately it was the only way I could figure out to
  71 do some things. It would be _much_ easier with a object-oriented
  72 language.
  73
  74 ---
  75
  76 "xmpp" and "ympp" are really misnomers, as they only represent the
  77 Meters Per Pixel in UTM mode. Otherwise they are an artificial zooming
  78 system. In expedia mode it represents the "Alti", in Google mode it
  79 represents 2^(scale), e.g. 2^0 = 1, 2^8 = 256.
  80
  81 ---
  82 Implementing a MapSource
  83
  84 VikMapSource is the "interface", the really base class of the
  85 MapSource tree.  In order to implement a MapSource, you have to prefer
  86 to derive from VikMapSourceDefault, a less abstract class, adding a
  87 property based implementation for some aspects of the VikMapSource
  88 interface.  Then, you have to provide implementation for
  89 coord_to_mapcoord, mapcoord_to_center_coord and download methods.