]>
Commit | Line | Data |
---|---|---|
6025df65 DM |
1 | Pacman - Contributing |
2 | ===================== | |
d1165f7f | 3 | |
6025df65 DM |
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. | |
f9a40e5d | 8 | |
d1165f7f DM |
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: | |
5f289962 | 14 | + |
3d8be429 DM |
15 | [source,C] |
16 | ------------------------------------------- | |
5f289962 | 17 | /* vim: set ts=2 sw=2 noet: */ |
3d8be429 | 18 | ------------------------------------------- |
d1165f7f DM |
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 | |
5f289962 | 23 | spaces around the parentheses of the block. ALWAYS use opening and closing |
4576000c DM |
24 | braces, even if it's just a one-line block. This reduces future error when |
25 | blocks are expanded beyond one line. | |
5f289962 | 26 | + |
3d8be429 DM |
27 | [source,C] |
28 | ------------------------------------------- | |
5f289962 DM |
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 { | |
0303b26b | 38 | return 1; |
5f289962 DM |
39 | } |
40 | free(it); | |
41 | it = ptr; | |
42 | } | |
3d8be429 | 43 | ------------------------------------------- |
d1165f7f DM |
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. | |
5f289962 | 48 | + |
3d8be429 DM |
49 | [source,C] |
50 | ------------------------------------------- | |
5f289962 DM |
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 | } | |
3d8be429 | 61 | ------------------------------------------- |
5f289962 DM |
62 | |
63 | 4. Comments should be ANSI-C89 compliant. That means no `// Comment` style; | |
64 | use only `/* Comment */` style. | |
d1165f7f | 65 | |
4576000c DM |
66 | /* This is a comment */ |
67 | NOT | |
68 | // This is a comment | |
69 | ||
0303b26b | 70 | 5. Return statements should *not* be written like function calls. |
d1165f7f | 71 | |
d1165f7f | 72 | return 0; |
0303b26b DM |
73 | NOT |
74 | return(0); | |
d1165f7f DM |
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 | ||
4576000c DM |
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 | ||
6c142684 DM |
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 | ||
925d44bd | 100 | for(a = 0; a < n && n > 0; a++, n--) {} |
6c142684 DM |
101 | NOT |
102 | for(a=0;a<n&&n>0;a++,n--) {} | |
103 | ||
527ae709 BPG |
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 | ||
4576000c | 148 | |
869e81e1 DM |
149 | Other Concerns |
150 | -------------- | |
151 | ||
5f289962 DM |
152 | Header Includes |
153 | ~~~~~~~~~~~~~~~ | |
154 | ||
869e81e1 DM |
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 | ||
3d8be429 DM |
159 | [source,C] |
160 | ------------------------------------------- | |
869e81e1 DM |
161 | #include <standardheader.h> |
162 | #include <another.h> | |
163 | #include <...> | |
3d8be429 | 164 | ------------------------------------------- |
869e81e1 DM |
165 | |
166 | Follow this with some more headers, depending on whether the file is in libalpm | |
167 | or pacman proper. For libalpm: | |
168 | ||
3d8be429 DM |
169 | [source,C] |
170 | ------------------------------------------- | |
869e81e1 DM |
171 | /* libalpm */ |
172 | #include "yourfile.h" | |
173 | #include "alpm_list.h" | |
174 | #include "anythingelse.h" | |
3d8be429 | 175 | ------------------------------------------- |
869e81e1 DM |
176 | |
177 | For pacman: | |
178 | ||
3d8be429 DM |
179 | [source,C] |
180 | ------------------------------------------- | |
869e81e1 DM |
181 | #include <alpm.h> |
182 | #include <alpm_list.h> | |
183 | ||
184 | /* pacman */ | |
185 | #include "yourfile.h" | |
186 | #include "anythingelse.h" | |
3d8be429 | 187 | ------------------------------------------- |
869e81e1 | 188 | |
d6ccd443 DR |
189 | Never directly include config.h. This will always be added via Makefiles. |
190 | ||
8a8dfc9d DM |
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 | ||
5f289962 | 204 | ///// |
cd8747ba | 205 | vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: |
5f289962 | 206 | ///// |