rebuild the docs
[privoxy.git] / doc / webserver / developer-manual / index.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
2 <HTML
3 ><HEAD
4 ><TITLE
5 >Privoxy Developer Manual</TITLE
6 ><META
7 NAME="GENERATOR"
8 CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
9 REL="NEXT"
10 TITLE="Introduction"
11 HREF="introduction.html"><LINK
12 REL="STYLESHEET"
13 TYPE="text/css"
14 HREF="../p_doc.css"><META
15 HTTP-EQUIV="Content-Type"
16 CONTENT="text/html;
17 charset=ISO-8859-1"></HEAD
18 ><BODY
19 CLASS="ARTICLE"
20 BGCOLOR="#EEEEEE"
21 TEXT="#000000"
22 LINK="#0000FF"
23 VLINK="#840084"
24 ALINK="#0000FF"
25 ><DIV
26 CLASS="ARTICLE"
27 ><DIV
28 CLASS="TITLEPAGE"
29 ><H1
30 CLASS="TITLE"
31 ><A
32 NAME="AEN2"
33 >Privoxy Developer Manual</A
34 ></H1
35 ><P
36 CLASS="PUBDATE"
37 >     <SUB
38 >    
39     
40       <A
41 HREF="https://www.privoxy.org/user-manual/copyright.html"
42 TARGET="_top"
43 >Copyright</A
44 >
45       © 2001-2018 by
46       <A
47 HREF="https://www.privoxy.org/"
48 TARGET="_top"
49 >Privoxy Developers</A
50 >
51      </SUB
52 >
53     <BR></P
54 ><DIV
55 ><DIV
56 CLASS="ABSTRACT"
57 ><P
58 ></P
59 ><A
60 NAME="AEN8"
61 ></A
62 ><P
63 > The developer manual provides guidance on coding, testing, packaging, documentation
64  and other issues of importance to those involved with
65  <SPAN
66 CLASS="APPLICATION"
67 >Privoxy</SPAN
68 > development. It is mandatory (and helpful!) reading
69  for anyone who wants to join the team. Note that it's currently out of date
70  and may not be entirely correct. As always, patches are welcome.</P
71 ><P
72 > Please note that this document is constantly evolving. This copy represents
73  the state at the release of version 3.0.27.
74  You can find the latest version of the this manual at <A
75 HREF="https://www.privoxy.org/developer-manual/"
76 TARGET="_top"
77 >https://www.privoxy.org/developer-manual/</A
78 >.
79  Please have a look at the
80  <A
81 HREF="https://www.privoxy.org/user-manual/contact.html"
82 TARGET="_top"
83 >contact section in the user manual</A
84 >
85  if you are interested in contacting the developers.</P
86 ><P
87 ></P
88 ></DIV
89 ></DIV
90 ><HR></DIV
91 ><DIV
92 CLASS="TOC"
93 ><DL
94 ><DT
95 ><B
96 >Table of Contents</B
97 ></DT
98 ><DT
99 >1. <A
100 HREF="introduction.html"
101 >Introduction</A
102 ></DT
103 ><DD
104 ><DL
105 ><DT
106 >1.1. <A
107 HREF="introduction.html#QUICKSTART"
108 >Quickstart to Privoxy Development</A
109 ></DT
110 ></DL
111 ></DD
112 ><DT
113 >2. <A
114 HREF="git.html"
115 >The Git Repository</A
116 ></DT
117 ><DD
118 ><DL
119 ><DT
120 >2.1. <A
121 HREF="git.html#GITACCESS"
122 >Access to Git</A
123 ></DT
124 ><DT
125 >2.2. <A
126 HREF="git.html#GITBRANCHES"
127 >Branches</A
128 ></DT
129 ><DT
130 >2.3. <A
131 HREF="git.html#GITCOMMIT"
132 >Git Commit Guidelines</A
133 ></DT
134 ></DL
135 ></DD
136 ><DT
137 >3. <A
138 HREF="documentation.html"
139 >Documentation Guidelines</A
140 ></DT
141 ><DD
142 ><DL
143 ><DT
144 >3.1. <A
145 HREF="documentation.html#SGML"
146 >Quickstart to Docbook and SGML</A
147 ></DT
148 ><DT
149 >3.2. <A
150 HREF="documentation.html#DOCSTYLE"
151 ><SPAN
152 CLASS="APPLICATION"
153 >Privoxy</SPAN
154 > Documentation Style</A
155 ></DT
156 ><DT
157 >3.3. <A
158 HREF="documentation.html#AEN203"
159 >Privoxy Custom Entities</A
160 ></DT
161 ></DL
162 ></DD
163 ><DT
164 >4. <A
165 HREF="coding.html"
166 >Coding Guidelines</A
167 ></DT
168 ><DD
169 ><DL
170 ><DT
171 >4.1. <A
172 HREF="coding.html#S1"
173 >Introduction</A
174 ></DT
175 ><DT
176 >4.2. <A
177 HREF="coding.html#S2"
178 >Using Comments</A
179 ></DT
180 ><DD
181 ><DL
182 ><DT
183 >4.2.1. <A
184 HREF="coding.html#S3"
185 >Comment, Comment, Comment</A
186 ></DT
187 ><DT
188 >4.2.2. <A
189 HREF="coding.html#S4"
190 >Use blocks for comments</A
191 ></DT
192 ><DT
193 >4.2.3. <A
194 HREF="coding.html#S5"
195 >Keep Comments on their own line</A
196 ></DT
197 ><DT
198 >4.2.4. <A
199 HREF="coding.html#S6"
200 >Comment each logical step</A
201 ></DT
202 ><DT
203 >4.2.5. <A
204 HREF="coding.html#S7"
205 >Comment All Functions Thoroughly</A
206 ></DT
207 ><DT
208 >4.2.6. <A
209 HREF="coding.html#S8"
210 >Comment at the end of braces if the
211     content is more than one screen length</A
212 ></DT
213 ></DL
214 ></DD
215 ><DT
216 >4.3. <A
217 HREF="coding.html#S9"
218 >Naming Conventions</A
219 ></DT
220 ><DD
221 ><DL
222 ><DT
223 >4.3.1. <A
224 HREF="coding.html#S10"
225 >Variable Names</A
226 ></DT
227 ><DT
228 >4.3.2. <A
229 HREF="coding.html#S11"
230 >Function Names</A
231 ></DT
232 ><DT
233 >4.3.3. <A
234 HREF="coding.html#S12"
235 >Header file prototypes</A
236 ></DT
237 ><DT
238 >4.3.4. <A
239 HREF="coding.html#S13"
240 >Enumerations, and #defines</A
241 ></DT
242 ><DT
243 >4.3.5. <A
244 HREF="coding.html#S14"
245 >Constants</A
246 ></DT
247 ></DL
248 ></DD
249 ><DT
250 >4.4. <A
251 HREF="coding.html#S15"
252 >Using Space</A
253 ></DT
254 ><DD
255 ><DL
256 ><DT
257 >4.4.1. <A
258 HREF="coding.html#S16"
259 >Put braces on a line by themselves.</A
260 ></DT
261 ><DT
262 >4.4.2. <A
263 HREF="coding.html#S17"
264 >ALL control statements should have a
265     block</A
266 ></DT
267 ><DT
268 >4.4.3. <A
269 HREF="coding.html#S18"
270 >Do not belabor/blow-up boolean
271     expressions</A
272 ></DT
273 ><DT
274 >4.4.4. <A
275 HREF="coding.html#S19"
276 >Use white space freely because it is
277     free</A
278 ></DT
279 ><DT
280 >4.4.5. <A
281 HREF="coding.html#S20"
282 >Don't use white space around structure
283     operators</A
284 ></DT
285 ><DT
286 >4.4.6. <A
287 HREF="coding.html#S21"
288 >Make the last brace of a function stand
289     out</A
290 ></DT
291 ><DT
292 >4.4.7. <A
293 HREF="coding.html#S22"
294 >Use 3 character indentions</A
295 ></DT
296 ></DL
297 ></DD
298 ><DT
299 >4.5. <A
300 HREF="coding.html#S23"
301 >Initializing</A
302 ></DT
303 ><DD
304 ><DL
305 ><DT
306 >4.5.1. <A
307 HREF="coding.html#S24"
308 >Initialize all variables</A
309 ></DT
310 ></DL
311 ></DD
312 ><DT
313 >4.6. <A
314 HREF="coding.html#S25"
315 >Functions</A
316 ></DT
317 ><DD
318 ><DL
319 ><DT
320 >4.6.1. <A
321 HREF="coding.html#S26"
322 >Name functions that return a boolean as a
323     question.</A
324 ></DT
325 ><DT
326 >4.6.2. <A
327 HREF="coding.html#S27"
328 >Always specify a return type for a
329     function.</A
330 ></DT
331 ><DT
332 >4.6.3. <A
333 HREF="coding.html#S28"
334 >Minimize function calls when iterating by
335     using variables</A
336 ></DT
337 ><DT
338 >4.6.4. <A
339 HREF="coding.html#S29"
340 >Pass and Return by Const Reference</A
341 ></DT
342 ><DT
343 >4.6.5. <A
344 HREF="coding.html#S30"
345 >Pass and Return by Value</A
346 ></DT
347 ><DT
348 >4.6.6. <A
349 HREF="coding.html#S31"
350 >Names of include files</A
351 ></DT
352 ><DT
353 >4.6.7. <A
354 HREF="coding.html#S32"
355 >Provide multiple inclusion
356     protection</A
357 ></DT
358 ><DT
359 >4.6.8. <A
360 HREF="coding.html#S33"
361 >Use `extern "C"` when appropriate</A
362 ></DT
363 ><DT
364 >4.6.9. <A
365 HREF="coding.html#S34"
366 >Where Possible, Use Forward Struct
367     Declaration Instead of Includes</A
368 ></DT
369 ></DL
370 ></DD
371 ><DT
372 >4.7. <A
373 HREF="coding.html#S35"
374 >General Coding Practices</A
375 ></DT
376 ><DD
377 ><DL
378 ><DT
379 >4.7.1. <A
380 HREF="coding.html#S36"
381 >Turn on warnings</A
382 ></DT
383 ><DT
384 >4.7.2. <A
385 HREF="coding.html#S37"
386 >Provide a default case for all switch
387     statements</A
388 ></DT
389 ><DT
390 >4.7.3. <A
391 HREF="coding.html#S38"
392 >Try to avoid falling through cases in a
393     switch statement.</A
394 ></DT
395 ><DT
396 >4.7.4. <A
397 HREF="coding.html#S40"
398 >Don't mix size_t and other types</A
399 ></DT
400 ><DT
401 >4.7.5. <A
402 HREF="coding.html#S41"
403 >Declare each variable and struct on its
404     own line.</A
405 ></DT
406 ><DT
407 >4.7.6. <A
408 HREF="coding.html#S42"
409 >Use malloc/zalloc sparingly</A
410 ></DT
411 ><DT
412 >4.7.7. <A
413 HREF="coding.html#S43"
414 >The Programmer Who Uses 'malloc' is
415     Responsible for Ensuring 'free'</A
416 ></DT
417 ><DT
418 >4.7.8. <A
419 HREF="coding.html#S44"
420 >Add loaders to the `file_list' structure
421     and in order</A
422 ></DT
423 ><DT
424 >4.7.9. <A
425 HREF="coding.html#S45"
426 >"Uncertain" new code and/or changes to
427     existing code, use XXX</A
428 ></DT
429 ></DL
430 ></DD
431 ><DT
432 >4.8. <A
433 HREF="coding.html#S46"
434 >Addendum: Template for files and function
435     comment blocks:</A
436 ></DT
437 ></DL
438 ></DD
439 ><DT
440 >5. <A
441 HREF="testing.html"
442 >Testing Guidelines</A
443 ></DT
444 ><DD
445 ><DL
446 ><DT
447 >5.1. <A
448 HREF="testing.html#TESTING-PLAN"
449 >Testplan for releases</A
450 ></DT
451 ><DT
452 >5.2. <A
453 HREF="testing.html#FUZZING"
454 >Fuzzing Privoxy</A
455 ></DT
456 ></DL
457 ></DD
458 ><DT
459 >6. <A
460 HREF="newrelease.html"
461 >Releasing a New Version</A
462 ></DT
463 ><DD
464 ><DL
465 ><DT
466 >6.1. <A
467 HREF="newrelease.html#VERSIONNUMBERS"
468 >Version numbers</A
469 ></DT
470 ><DT
471 >6.2. <A
472 HREF="newrelease.html#BEFORERELEASE"
473 >Before the Release: Freeze</A
474 ></DT
475 ><DT
476 >6.3. <A
477 HREF="newrelease.html#THERELEASE"
478 >Building and Releasing the Packages</A
479 ></DT
480 ><DD
481 ><DL
482 ><DT
483 >6.3.1. <A
484 HREF="newrelease.html#PACK-GUIDELINES"
485 >Note on Privoxy Packaging</A
486 ></DT
487 ><DT
488 >6.3.2. <A
489 HREF="newrelease.html#NEWRELEASE-TARBALL"
490 >Source Tarball</A
491 ></DT
492 ><DT
493 >6.3.3. <A
494 HREF="newrelease.html#NEWRELEASE-RPM"
495 >SuSE, Conectiva or Red Hat RPM</A
496 ></DT
497 ><DT
498 >6.3.4. <A
499 HREF="newrelease.html#NEWRELEASE-OS2"
500 >OS/2</A
501 ></DT
502 ><DT
503 >6.3.5. <A
504 HREF="newrelease.html#NEWRELEASE-SOLARIS"
505 >Solaris</A
506 ></DT
507 ><DT
508 >6.3.6. <A
509 HREF="newrelease.html#NEWRELEASE-WINDOWS"
510 >Windows</A
511 ></DT
512 ><DT
513 >6.3.7. <A
514 HREF="newrelease.html#NEWRELEASE-DEBIAN"
515 >Debian</A
516 ></DT
517 ><DT
518 >6.3.8. <A
519 HREF="newrelease.html#NEWRELEASE-MACOSX"
520 >Mac OS X</A
521 ></DT
522 ><DT
523 >6.3.9. <A
524 HREF="newrelease.html#NEWRELEASE-FREEBSD"
525 >FreeBSD</A
526 ></DT
527 ></DL
528 ></DD
529 ><DT
530 >6.4. <A
531 HREF="newrelease.html#RELEASING"
532 >Uploading and Releasing Your Package</A
533 ></DT
534 ><DT
535 >6.5. <A
536 HREF="newrelease.html#AFTERRELEASE"
537 >After the Release</A
538 ></DT
539 ></DL
540 ></DD
541 ><DT
542 >7. <A
543 HREF="webserver-update.html"
544 >Update the Webserver</A
545 ></DT
546 ></DL
547 ></DIV
548 ></DIV
549 ><DIV
550 CLASS="NAVFOOTER"
551 ><HR
552 ALIGN="LEFT"
553 WIDTH="100%"><TABLE
554 SUMMARY="Footer navigation table"
555 WIDTH="100%"
556 BORDER="0"
557 CELLPADDING="0"
558 CELLSPACING="0"
559 ><TR
560 ><TD
561 WIDTH="33%"
562 ALIGN="left"
563 VALIGN="top"
564 >&nbsp;</TD
565 ><TD
566 WIDTH="34%"
567 ALIGN="center"
568 VALIGN="top"
569 >&nbsp;</TD
570 ><TD
571 WIDTH="33%"
572 ALIGN="right"
573 VALIGN="top"
574 ><A
575 HREF="introduction.html"
576 ACCESSKEY="N"
577 >Next</A
578 ></TD
579 ></TR
580 ><TR
581 ><TD
582 WIDTH="33%"
583 ALIGN="left"
584 VALIGN="top"
585 >&nbsp;</TD
586 ><TD
587 WIDTH="34%"
588 ALIGN="center"
589 VALIGN="top"
590 >&nbsp;</TD
591 ><TD
592 WIDTH="33%"
593 ALIGN="right"
594 VALIGN="top"
595 >Introduction</TD
596 ></TR
597 ></TABLE
598 ></DIV
599 ></BODY
600 ></HTML
601 >