HACKING

   1 Pacman - Contributing
   2 =====================
   3
   4 This file is meant to give you a brief overview of coding style and other
   5 concerns when hacking on pacman. If you are interested in contributing, please
   6 read link:submitting-patches.html[submitting-patches] and
   7 link:translation-help.html[translation-help] as well.
   8
   9 Coding style
  10 ------------
  11
  12 1.  All code should be indented with tabs. (Ignore the use of only spaces in
  13     this file) By default, source files contain the following VIM modeline:
  14 +
  15 [source,C]
  16 -------------------------------------------
  17 /* vim: set ts=2 sw=2 noet: */
  18 -------------------------------------------
  19
  20 2.  When opening new blocks such as 'while', 'if', or 'for', leave the opening
  21     brace on the same line as the beginning of the codeblock. The closing brace
  22     gets its own line (the only exception being 'else'). Do not use extra
  23     spaces around the parentheses of the block. ALWAYS use opening and closing
  24     braces, even if it's just a one-line block. This reduces future error when
  25     blocks are expanded beyond one line.
  26 +
  27 [source,C]
  28 -------------------------------------------
  29 for(lp = list; lp; lp = lp->next) {
  30   newlist = _alpm_list_add(newlist, strdup(lp->data));
  31 }
  32
  33 while(it) {
  34   ptr = it->next;
  35   if(fn) {
  36     fn(it->data);
  37   } else {
  38     return 1;
  39   }
  40   free(it);
  41   it = ptr;
  42 }
  43 -------------------------------------------
  44
  45 3.  When declaring a new function, put the opening and closing braces on their
  46     own line. Also, when declaring a pointer, do not put a space between the
  47     asterisk and the variable name.
  48 +
  49 [source,C]
  50 -------------------------------------------
  51 alpm_list_t *alpm_list_add(alpm_list_t *list, void *data)
  52 {
  53   alpm_list_t *ptr, *lp;
  54
  55   ptr = list;
  56   if(ptr == NULL) {
  57   ...
  58   }
  59   ...
  60 }
  61 -------------------------------------------
  62
  63 4.  Comments should be ANSI-C89 compliant. That means no `// Comment` style;
  64     use only `/* Comment */` style.
  65
  66     /* This is a comment */
  67        NOT
  68     // This is a comment
  69
  70 5.  Return statements should *not* be written like function calls.
  71
  72     return 0;
  73        NOT
  74     return(0);
  75
  76 6.  The sizeof() operator should accept a type, not a value. (TODO: in certain
  77     cases, it may be better- should this be a set guideline? Read "The Practice
  78     of Programming")
  79
  80     sizeof(alpm_list_t);
  81        NOT
  82     sizeof(*mylist);
  83
  84 7.  When using strcmp() (or any function that returns 0 on success) in a
  85     conditional statement, use != 0 or == 0 and not the negation (!) operator.
  86     It reads much cleaner for humans (using a negative to check for success is
  87     confusing) and the compiler will treat it correctly anyway.
  88
  89     if(strcmp(a, b) == 0)
  90        NOT
  91     if(!strcmp(a, b))
  92
  93 8.  Use spaces around almost all arithmetic, comparison and assignment
  94     operators and after all ',;:' separators.
  95
  96         foobar[2 * size + 1] = function(a, 6);
  97            NOT
  98         foobar[2*size+1]=function(a,6);
  99
 100         for(a = 0; a < n && n > 0; a++,n--) {}
 101            NOT
 102         for(a=0;a<n&&n>0;a++,n--) {}
 103
 104 9.  Declare all variables at the start of the block.
 105 [source,C]
 106 -------------------------------------------
 107 int SYMEXPORT alpm_db_remove_server(alpm_db_t *db, const char *url)
 108 {
 109   char *newurl, *vdata = NULL;
 110
 111   newurl = url;
 112   if(!newurl) {
 113     return -1;
 114   }
 115
 116   ...
 117
 118   if(vdata) {
 119     ...
 120   }
 121
 122   return 1;
 123 }
 124 -------------------------------------------
 125
 126     NOT
 127
 128 [source,C]
 129 -------------------------------------------
 130 int SYMEXPORT alpm_db_remove_server(alpm_db_t *db, const char *url)
 131 {
 132   char *newurl = url;
 133
 134   if(!newurl) {
 135     return -1;
 136   }
 137
 138   char *vdata = NULL;
 139
 140   if(vdata) {
 141     ...
 142   }
 143
 144   return 1;
 145 }
 146 -------------------------------------------
 147
 148
 149 Other Concerns
 150 --------------
 151
 152 Header Includes
 153 ~~~~~~~~~~~~~~~
 154
 155 Currently our #include usage is in messy shape, but this is no reason to
 156 continue down this messy path. When adding an include to a file, follow this
 157 general pattern, including blank lines:
 158
 159 [source,C]
 160 -------------------------------------------
 161 #include <standardheader.h>
 162 #include <another.h>
 163 #include <...>
 164 -------------------------------------------
 165
 166 Follow this with some more headers, depending on whether the file is in libalpm
 167 or pacman proper. For libalpm:
 168
 169 [source,C]
 170 -------------------------------------------
 171 /* libalpm */
 172 #include "yourfile.h"
 173 #include "alpm_list.h"
 174 #include "anythingelse.h"
 175 -------------------------------------------
 176
 177 For pacman:
 178
 179 [source,C]
 180 -------------------------------------------
 181 #include <alpm.h>
 182 #include <alpm_list.h>
 183
 184 /* pacman */
 185 #include "yourfile.h"
 186 #include "anythingelse.h"
 187 -------------------------------------------
 188
 189 Never directly include config.h. This will always be added via Makefiles.
 190
 191 GDB and Valgrind Usage
 192 ~~~~~~~~~~~~~~~~~~~~~~
 193
 194 When using GDB or valgrind on pacman, you will want to run it on the actual
 195 binary rather than the shell script wrapper produced by libtool. The actual
 196 binary lives at `src/pacman/.libs/lt-pacman`, and will exist after running
 197 `./src/pacman/pacman` at least once.
 198
 199 For example, to run valgrind:
 200
 201     ./src/pacman/pacman
 202     valgrind --leak-check=full -- src/pacman/.libs/lt-pacman -Syu
 203
 204 /////
 205 vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us:
 206 /////