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 >