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       &copy; 2001-2021 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.34.
  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#CUSTOM-ENTITIES"
 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#PRIVOXY-REGRESSION-TEST"
 454 >Testing with <SPAN
 455 CLASS="APPLICATION"
 456 >Privoxy-Regression-Test</SPAN
 457 ></A
 458 ></DT
 459 ><DT
 460 >5.3. <A
 461 HREF="testing.html#FUZZING"
 462 >Fuzzing Privoxy</A
 463 ></DT
 464 ></DL
 465 ></DD
 466 ><DT
 467 >6. <A
 468 HREF="newrelease.html"
 469 >Releasing a New Version</A
 470 ></DT
 471 ><DD
 472 ><DL
 473 ><DT
 474 >6.1. <A
 475 HREF="newrelease.html#VERSIONNUMBERS"
 476 >Version numbers</A
 477 ></DT
 478 ><DT
 479 >6.2. <A
 480 HREF="newrelease.html#BEFORERELEASE"
 481 >Before the Release</A
 482 ></DT
 483 ><DT
 484 >6.3. <A
 485 HREF="newrelease.html#THERELEASE"
 486 >Building and Releasing the Packages</A
 487 ></DT
 488 ><DD
 489 ><DL
 490 ><DT
 491 >6.3.1. <A
 492 HREF="newrelease.html#PACK-GUIDELINES"
 493 >Note on Privoxy Packaging</A
 494 ></DT
 495 ><DT
 496 >6.3.2. <A
 497 HREF="newrelease.html#NEWRELEASE-TARBALL"
 498 >Source Tarball</A
 499 ></DT
 500 ><DT
 501 >6.3.3. <A
 502 HREF="newrelease.html#NEWRELEASE-WINDOWS"
 503 >Windows</A
 504 ></DT
 505 ><DT
 506 >6.3.4. <A
 507 HREF="newrelease.html#NEWRELEASE-DEBIAN"
 508 >Debian</A
 509 ></DT
 510 ><DT
 511 >6.3.5. <A
 512 HREF="newrelease.html#NEWRELEASE-MACOSX"
 513 >macOS / OS X</A
 514 ></DT
 515 ><DT
 516 >6.3.6. <A
 517 HREF="newrelease.html#NEWRELEASE-FREEBSD"
 518 >FreeBSD</A
 519 ></DT
 520 ></DL
 521 ></DD
 522 ><DT
 523 >6.4. <A
 524 HREF="newrelease.html#RELEASING"
 525 >Uploading and Releasing Your Package</A
 526 ></DT
 527 ><DT
 528 >6.5. <A
 529 HREF="newrelease.html#AFTERRELEASE"
 530 >After the Release</A
 531 ></DT
 532 ></DL
 533 ></DD
 534 ><DT
 535 >7. <A
 536 HREF="webserver-update.html"
 537 >Update the Webserver</A
 538 ></DT
 539 ></DL
 540 ></DIV
 541 ></DIV
 542 ><DIV
 543 CLASS="NAVFOOTER"
 544 ><HR
 545 ALIGN="LEFT"
 546 WIDTH="100%"><TABLE
 547 SUMMARY="Footer navigation table"
 548 WIDTH="100%"
 549 BORDER="0"
 550 CELLPADDING="0"
 551 CELLSPACING="0"
 552 ><TR
 553 ><TD
 554 WIDTH="33%"
 555 ALIGN="left"
 556 VALIGN="top"
 557 >&nbsp;</TD
 558 ><TD
 559 WIDTH="34%"
 560 ALIGN="center"
 561 VALIGN="top"
 562 >&nbsp;</TD
 563 ><TD
 564 WIDTH="33%"
 565 ALIGN="right"
 566 VALIGN="top"
 567 ><A
 568 HREF="introduction.html"
 569 ACCESSKEY="N"
 570 >Next</A
 571 ></TD
 572 ></TR
 573 ><TR
 574 ><TD
 575 WIDTH="33%"
 576 ALIGN="left"
 577 VALIGN="top"
 578 >&nbsp;</TD
 579 ><TD
 580 WIDTH="34%"
 581 ALIGN="center"
 582 VALIGN="top"
 583 >&nbsp;</TD
 584 ><TD
 585 WIDTH="33%"
 586 ALIGN="right"
 587 VALIGN="top"
 588 >Introduction</TD
 589 ></TR
 590 ></TABLE
 591 ></DIV
 592 ></BODY
 593 ></HTML
 594 >