4 \section*{Bacula Developer Notes}
5 \label{_ChapterStart10}
6 \index{Bacula Developer Notes}
7 \index{Notes!Bacula Developer}
8 \addcontentsline{toc}{section}{Bacula Developer Notes}
12 \addcontentsline{toc}{subsection}{General}
14 This document is intended mostly for developers and describes the the general
15 framework of making Bacula source changes.
17 \subsubsection*{Contributions}
19 \addcontentsline{toc}{subsubsection}{Contributions}
21 Contributions from programmers are broken into two groups. The first are
22 contributions that are aids and not essential to Bacula. In general, these
23 will be scripts or will go into and examples or contributions directory.
25 The second class of contributions are those which will be integrated with
26 Bacula and become an essential part. Within this class of contributions, there
27 are two hurdles to surmount. One is getting your patch accepted, and two is
28 dealing with copyright issues. The following text describes some of the
29 requirements for such code.
31 \subsubsection*{Patches}
33 \addcontentsline{toc}{subsubsection}{Patches}
35 Subject to the copyright assignment described below, your patches should be
36 sent in {\bf diff -u} format relative to the current contents of the Source
37 Forge CVS, which is the easiest for me to understand. If you have checked
38 out the source with CVS, you can get a diff using:
41 cvs diff -u \lt{}change.patch
45 significant development work over a period of time, after having your first
46 patch reviewed and approved, you will be eligible for having developer CVS access so
47 that you can commit your changes directly to the CVS repository. To do so, you
48 will need a userid on Source Forge.
50 \subsubsection*{Copyrights}
52 \addcontentsline{toc}{subsubsection}{Copyrights}
54 To avoid future problems concerning changing licensing or copyrights, all code
55 contributions more than a hand full of lines must be in the Public Domain or
56 have the copyright assigned to Kern Sibbald as in the current code. Note,
57 prior to November 2004, the code was copyrighted by Kern Sibbald and John
60 Your name should be clearly indicated as the author of the code, and you must
61 be extremely careful not to violate any copyrights or use other people's code
62 without acknowledging it. The purpose of this requirement is to avoid future
63 copyright, patent, or intellectual property problems. To understand on
64 possible source of future problems, please examine the difficulties Mozilla is
65 (was?) having finding previous contributors at
67 http://www.mozilla.org/MPL/missing.html}
68 {http://www.mozilla.org/MPL/missing.html}. The other important issue is to
69 avoid copyright, patent, or intellectual property violations as are currently
70 (May 2003) being claimed by SCO against IBM.
72 Although the copyright will be held by Kern, each developer is expected to
73 indicate that he wrote and/or modified a particular module (or file) and any
74 other sources. The copyright assignment may seem a bit unusual, but in
75 reality, it is not. Most large projects require this. In fact, the paperwork
76 associated with making contributions to the Free Software Foundation, was for
79 If you have any doubts about this, please don't hesitate to ask. Our (John and
80 my) track records with Autodesk are easily available; early
81 programmers/founders/contributors and later employees had substantial shares
82 of the company, and no one founder had a controlling part of the company. Even
83 though Microsoft created many millionaires among early employees, the politics
84 of Autodesk (during our time at the helm) is in stark contrast to Microsoft
85 where the majority of the company is still tightly held among a few.
87 Items not needing a copyright assignment are: most small changes,
88 enhancements, or bug fixes of 5-10 lines of code, and documentation.
90 \subsubsection*{Copyright Assignment}
91 \index{Copyright Assignment}
92 \index{Assignment!Copyright}
93 \addcontentsline{toc}{subsubsection}{Copyright Assignment}
95 Since this is not a commercial enterprise, and I prefer to believe in
96 everyone's good faith, developers can assign the copyright by explicitly
97 acknowledging that they do so in their first submission. This is sufficient if
98 the developer is independent, or an employee of a not-for-profit organization
99 or a university. Any developer that wants to contribute and is employed by a
100 company must get a copyright assignment from his employer. This is to avoid
101 misunderstandings between the employee, the company, and the Bacula project.
103 \subsubsection*{Corporate Assignment Statement}
104 \index{Statement!Corporate Assignment}
105 \index{Corporate Assignment Statement}
106 \addcontentsline{toc}{subsubsection}{Corporate Assignment Statement}
108 The following statement must be filled out by the employer, signed, and mailed
109 to my address (please ask me for my address and I will email it -- I'd prefer
110 not to include it here).
114 Copyright release and transfer statement.
115 <On company letter head>
118 Concerning: Copyright release and transfer
120 <Company, Inc> is hereby agrees that <names-of-developers> and
121 other employees of <Company, Inc> are authorized to develop
122 code for and contribute code to the Bacula project for an
123 undetermined period of time. The copyright as well as all
124 other rights to and interests in such contributed code are
125 hereby transferred to Kern Sibbald.
127 Signed in <City, Country> on <Date>:
129 <Name of Person>, <Position in Company, Inc>
134 This release/transfer statement must be sent to:
138 \subsection*{Basic CVS Usage}
139 \index{Basic CVS Usage}
141 \addcontentsline{toc}{subsection}{Basic CVS Usage}
143 The Bacula CVS is kept at Source Forge. If you are not a developer,
144 you only be able to access the public CVS, which runs about 6 hours behind
145 the developer's CVS. If you are a developer, then you will have immediate
146 access to "the" CVS and any changes ("commit") that you make will be
147 immediately seen by other developers.
149 For developer access to the CVS, go to the Bacula page on Source Forge
150 and click on the CVS menu item. Then follow the instructions for
151 installing your SSH public key. It may take a few hours until the
152 key is actually installed, and then you will have access to the CVS.
154 The Bacula CVS is divided into the following CVS "projects" or "modules".
158 bacula (Bacula source code)
159 docs (Bacula documentation)
160 gui (Some of the GUI programs that do not use
161 the Bacula core code)
162 rescue (Bacula CDROM rescue code)
163 regress (Bacula regression scripts)
164 ryol (Roll your own Linux -- incomplete project)
168 Most of you will want either the Bacula source (bacula) and/or the
171 To get the source for a project, you must check it out ("checkout"), which
174 The first time you checkout the code for each project, you will need to
175 tell the cvs program where the CVS repository is. You do so by doing:
179 export CVSROOT=:ext:<nnnn>@cvs.bacula.sourceforge.net:/cvsroot/bacula
182 where you replace \lt{}nnnn\gt{} by your Source Forge user name.
187 cvs -z3 checkout -d <directory> bacula
190 where you replace \lt{}directory\gt{} by the name of the directory you want
191 to contain the Bacula source code. If you want the docs, replace the
192 word "bacula" on the above line by "docs" and be sure to put it in
193 a different directory. The -z3 just tells CVS to use compression during
194 the transmission, which makes things go faster.
196 The above command should generate output that looks a bit like the
200 cvs checkout: Updating bacula
209 Let's assume you used the name "bacula" for the directory, so your
213 cvs -z3 checkout -d bacula bacula
216 When the command is done, simply do:
223 and then build Bacula. You will notice a lot of extra CVS directories
224 in the source code. Don't ever change or delete them, or you will mess up
225 your copy of the project. Also, do not rename or delete any of the files
226 in your copy of the repository or you may have problems. Any files that
227 you change will remain only on your system until you do a "commit", which
230 Let's say you are working in the directory scripts. You would then do:
237 when you are happy with your changes, you can do the following:
240 cd bacula (to your top level directory)
241 cvs diff -u >my-changes.patch
244 When the command is done, you can look in the file my-changes.patch
245 and you will see all the changes you have made to your copy of the
246 repository. Make sure that you understand all the changes that
247 it reports before proceeding. If you modified files that you do
248 do not want to commit to the main repository, you can simply delete
249 them from your local directory, and they will be restored from the
250 repository with the "cvs update" that is shown below. Normally, you
251 should not find changes to files that you do not want to commit, and
252 if you find yourself in that position a lot, you are probably doing
255 Let's assume that now you want to commit your changes to the main CVS
265 When you do this, it will pull any changes made by other developers into
266 your local copy of the repository, and it will check for conflicts. If there
267 are any, it will tell you, and you will need to resolve them. The problems
268 of resolving conflicts are a bit more than this document can cover, but
269 you can examine the files it claims have conflicts and look for \lt{}\lt{}\lt{}\lt{}
270 or look in the .rej files that it creates. If you have problems, just ask
271 on the developer's list.
273 Note, doing the above "cvs update" is not absolutely necessary. There are
274 times when you may be working on code and you want to commit it, but you
275 explicitly do not want to move up to the latest version of the code in
276 the CVS. If that is the case, you can simply skip the "cvs update" and
277 do the commit shown below. If the commit fails because of a conflict, it
278 will tell you, and you must resolve the conflict before it will permit
279 you to do the commit.
281 Once your local copy of the repository has been updated, you can now
285 cvs commit -m "Some comment about what you changed"
288 or if you really only want to commit a single file, you can
292 cvs commit -m "comment" scripts/file-I-edited
295 Note, if you have done a build in your directory, or you have added
296 other new files, the commit will update only the files that are
297 actually in the repository. For example, none of the object files
298 are stored in the repository, so when you do a commit, those object
299 files will simply be ignored.
301 If you want to add new files or remove files from the main CVS
302 repository, and you are not experienced with CVS, please ask Kern
303 to do it. If you follow the simple steps above, it is unlikely that
304 you will do any damage to the repository, and if you do, it is always
305 possible for us to recover, but it can be painful.
307 If you are only working in one subdirectory of say the bacula project,
308 for example, the scripts directory, you can do your commit from
309 that subdirectory, and only the changes in that directory and all its
310 subdirectories will be committed. This can be helpful for translators.
311 If you are doing a French translation, you will be working in
312 docs/manual-fr, and if you are always cd'ed into that directory when
313 doing your commits, your commit will effect only that directory. As
314 long as you are careful only to change files that you want changed,
315 you have little to worry about.
317 \subsection*{The Development Cycle}
318 \index{Developement Cycle}
319 \index{Cycle!Developement}
320 \addcontentsline{toc}{subsubsection}{Development Cycle}
322 As I noted in the 1.38 ReleaseNotes, version 1.38 was different from prior
323 versions because it had a lot more contributions. I expect that this trend
324 will continue. As a consequence, I am going to modify how I normally do
325 development, and instead of making a list of all the features that I will
326 implement in the next version, I will personally sign up for one (maybe
327 two) projects at a time, and when they are complete, I will release a new
330 The difference is that I will have more time to review the new code that is
331 being contributed, and will be able to devote more time to a smaller number
332 of projects (1.38 had too many new features for me to handle correctly).
334 I expect that future release schedules will be much the same, and the
335 number of new features will also be much the same providing that the
336 contributions continue to come -- and they show no signs of let up :-)
338 {\bf Feature Requests:} \\
339 In addition, I would like to "formalize" the feature requests a bit.
341 Instead of me maintaining an informal list of everything I run into
342 (kernstodo), I would like to maintain a "formal" list of projects. This
343 means that all new feature requests, including those recently discussed on
344 the email lists, must be formally submitted and approved.
346 Formal submission of feature requests will take two forms: \\
347 1. non-mandatory, but highly recommended is to discuss proposed new features
348 on the mailing list.\\
349 2. Formal submission of an Feature Request in a special format.
350 I'll give an example of this below, but you can also find it on the web
351 site under "Support -\gt{} Feature Requests". Since it takes a bit of time to
352 properly fill out a Feature Request form, you probably should check on the email list
355 Once I receive the Feature Request, I will either accept it, send it back
356 asking for clarification, send it to the email list asking for opinions, or
359 If it is accepted, it will go in the "projects" file (a simple ASCII file)
360 maintained in the main Bacula source directory.
362 {\bf Implementation of Feature Requests:}\\
363 Any qualified developer can sign up for a project. The project must have
364 an entry in the projects file, and the developer's name will appear in the
367 {\bf How Feature Requests are accepted:}\\
368 Acceptance of Feature Requests depends on several things: \\
369 1. feedback from users. If it is negative, the Feature Request will probably not be
371 2. the difficulty of the project. A project that is so
372 difficult that I cannot imagine finding someone to implement probably won't
374 3. whether or not the Feature Request fits within the
375 current stategy of Bacula (for example an Feature Request that requests changing the
376 tape to tar format would not be accepted, ...)
378 {\bf How Feature Requests are prioritized:}\\
379 Once an Feature Request is accepted, it needs to be implemented. If you
380 can find a developer for it, or one signs up for implementing it, then the
381 Feature Request becomes top priority (at least for that developer).
383 Between releases of Bacula, I will generally solicit Feature Request input
384 for the next version, and by way of this email, I suggest that you send
385 discuss and send in your Feature Requests for the next release. Please
386 verify that the Feature Request is not in the current list (attached to this email).
388 Once users have had several weeks to submit Feature Requests, I will
389 organize them, and request users to vote on them. This will allow fixing
390 prioritizing the Feature Requests. Having a priority is one thing, but
391 getting it implement is another thing -- I am hoping that the Bacula
392 community will take more responsibility for assuring the implementation of
393 accepted Feature Requests.
395 Feature Request format:
397 ============= Empty Feature Request form ===========
398 Item n: One line summary ...
400 Origin: Name and email of originator.
403 What: More detailed explanation ...
405 Why: Why it is important ...
407 Notes: Additional notes or features (omit if not used)
408 ============== End Feature Request form ==============
412 ============= Example Completed Feature Request form ===========
413 Item 1: Implement a Migration job type that will move the job
414 data from one device to another.
415 Origin: Sponsored by Riege Sofware International GmbH. Contact:
416 Daniel Holtkamp <holtkamp at riege dot com>
417 Date: 28 October 2005
418 Status: Partially coded in 1.37 -- much more to do. Assigned to
421 What: The ability to copy, move, or archive data that is on a
422 device to another device is very important.
424 Why: An ISP might want to backup to disk, but after 30 days
425 migrate the data to tape backup and delete it from
426 disk. Bacula should be able to handle this
427 automatically. It needs to know what was put where,
428 and when, and what to migrate -- it is a bit like
429 retention periods. Doing so would allow space to be
430 freed up for current backups while maintaining older
433 Notes: Migration could be triggered by:
437 Highwater size (keep total size)
439 =================================================
443 \subsection*{Developing Bacula}
444 \index{Developing Bacula}
445 \index{Bacula!Developing}
446 \addcontentsline{toc}{subsubsection}{Developing Bacula}
448 Typically the simplest way to develop Bacula is to open one xterm window
449 pointing to the source directory you wish to update; a second xterm window at
450 the top source directory level, and a third xterm window at the bacula
451 directory \lt{}top\gt{}/src/bacula. After making source changes in one of the
452 directories, in the top source directory xterm, build the source, and start
453 the daemons by entering:
457 ./startit then in the enter:
461 ./gnome-console to start the Console program. Enter any commands for testing.
462 For example: run kernsverify full.
464 Note, the instructions here to use {\bf ./startit} are different from using a
465 production system where the administrator starts Bacula by entering {\bf
466 ./bacula start}. This difference allows a development version of {\bf Bacula}
467 to be run on a computer at the same time that a production system is running.
468 The {\bf ./startit} strip starts {\bf Bacula} using a different set of
469 configuration files, and thus permits avoiding conflicts with any production
472 To make additional source changes, exit from the Console program, and in the
473 top source directory, stop the daemons by entering:
475 ./stopit then repeat the process.
477 \subsubsection*{Debugging}
479 \addcontentsline{toc}{subsubsection}{Debugging}
481 Probably the first thing to do is to turn on debug output.
483 A good place to start is with a debug level of 20 as in {\bf ./startit -d20}.
484 The startit command starts all the daemons with the same debug level.
485 Alternatively, you can start the appropriate daemon with the debug level you
486 want. If you really need more info, a debug level of 60 is not bad, and for
487 just about everything a level of 200.
489 \subsubsection*{Using a Debugger}
490 \index{Using a Debugger}
491 \index{Debugger!Using a}
492 \addcontentsline{toc}{subsubsection}{Using a Debugger}
494 If you have a serious problem such as a segmentation fault, it can usually be
495 found quickly using a good multiple thread debugger such as {\bf gdb}. For
496 example, suppose you get a segmentation violation in {\bf bacula-dir}. You
497 might use the following to find the problem:
499 \lt{}start the Storage and File daemons\gt{}
502 run -f -s -c ./dird.conf
503 \lt{}it dies with a segmentation fault\gt{}
505 The {\bf -f} option is specified on the {\bf run} command to inhibit {\bf
506 dird} from going into the background. You may also want to add the {\bf -s}
507 option to the run command to disable signals which can potentially interfere
510 As an alternative to using the debugger, each {\bf Bacula} daemon has a built
511 in back trace feature when a serious error is encountered. It calls the
512 debugger on itself, produces a back trace, and emails the report to the
513 developer. For more details on this, please see the chapter in the main Bacula
514 manual entitled ``What To Do When Bacula Crashes (Kaboom)''.
516 \subsubsection*{Memory Leaks}
519 \addcontentsline{toc}{subsubsection}{Memory Leaks}
521 Because Bacula runs routinely and unattended on client and server machines, it
522 may run for a long time. As a consequence, from the very beginning, Bacula
523 uses SmartAlloc to ensure that there are no memory leaks. To make detection of
524 memory leaks effective, all Bacula code that dynamically allocates memory MUST
525 have a way to release it. In general when the memory is no longer needed, it
526 should be immediately released, but in some cases, the memory will be held
527 during the entire time that Bacula is executing. In that case, there MUST be a
528 routine that can be called at termination time that releases the memory. In
529 this way, we will be able to detect memory leaks. Be sure to immediately
530 correct any and all memory leaks that are printed at the termination of the
533 \subsubsection*{Special Files}
534 \index{Files!Special}
535 \index{Special Files}
536 \addcontentsline{toc}{subsubsection}{Special Files}
538 Kern uses files named 1, 2, ... 9 with any extension as scratch files. Thus
539 any files with these names are subject to being rudely deleted at any time.
541 \subsubsection*{When Implementing Incomplete Code}
542 \index{Code!When Implementing Incomplete}
543 \index{When Implementing Incomplete Code}
544 \addcontentsline{toc}{subsubsection}{When Implementing Incomplete Code}
546 Please identify all incomplete code with a comment that contains {\bf
547 ***FIXME***}, where there are three asterisks (*) before and after the word
548 FIXME (in capitals) and no intervening spaces. This is important as it allows
549 new programmers to easily recognize where things are partially implemented.
551 \subsubsection*{Bacula Source File Structure}
552 \index{Structure!Bacula Source File}
553 \index{Bacula Source File Structure}
554 \addcontentsline{toc}{subsubsection}{Bacula Source File Structure}
556 The distribution generally comes as a tar file of the form {\bf
557 bacula.x.y.z.tar.gz} where x, y, and z are the version, release, and update
558 numbers respectively.
560 Once you detar this file, you will have a directory structure as follows:
567 |- mtx (autochanger control program + tape drive info)
568 |- sqlite (SQLite database program)
572 |- pthreads (Native win32 pthreads library -- dll)
573 |- zlib (Native win32 zlib library)
574 |- wx (wxWidgets source code)
577 |- bacula (main source directory containing configuration
578 | and installation files)
579 |- autoconf (automatic configuration files, not normally used
581 |- intl (programs used to translate)
582 |- platforms (OS specific installation files)
583 |- redhat (Red Hat installation)
584 |- solaris (Sun installation)
585 |- freebsd (FreeBSD installation)
586 |- irix (Irix installation -- not tested)
587 |- unknown (Default if system not identified)
588 |- po (translations of source strings)
589 |- src (source directory; contains global header files)
590 |- cats (SQL catalog database interface directory)
591 |- console (bacula user agent directory)
592 |- dird (Director daemon)
593 |- filed (Unix File daemon)
594 |- win32 (Win32 files to make bacula-fd be a service)
595 |- findlib (Unix file find library for File daemon)
596 |- gnome-console (GNOME version of console program)
597 |- lib (General Bacula library)
598 |- stored (Storage daemon)
599 |- tconsole (Tcl/tk console program -- not yet working)
600 |- testprogs (test programs -- normally only in Kern's tree)
601 |- tools (Various tool programs)
602 |- win32 (Native Win32 File daemon)
603 |- baculafd (Visual Studio project file)
604 |- compat (compatibility interface library)
605 |- filed (links to src/filed)
606 |- findlib (links to src/findlib)
607 |- lib (links to src/lib)
608 |- console (beginning of native console program)
609 |- wx-console (wxWidget console Win32 specific parts)
610 |- wx-console (wxWidgets console main source program)
613 |- regress (Regression scripts)
614 |- bin (temporary directory to hold Bacula installed binaries)
615 |- build (temporary directory to hold Bacula source)
616 |- scripts (scripts and .conf files)
617 |- tests (test scripts)
618 |- tmp (temporary directory for temp files)
621 |- docs (documentation directory)
622 |- developers (Developer's guide)
623 |- home-page (Bacula's home page source)
624 |- manual (html document directory)
625 |- manual-fr (French translation)
626 |- manual-de (German translation)
627 |- techlogs (Technical development notes);
630 |- rescue (Bacula rescue CDROM)
631 |- linux (Linux rescue CDROM)
632 |- cdrom (Linux rescue CDROM code)
634 |- solaris (Solaris rescue -- incomplete)
635 |- freebsd (FreeBSD rescue -- incomplete)
638 |- gui (Bacula GUI projects)
639 |- bacula-web (Bacula web php management code)
640 |- bimagemgr (Web application for burning CDROMs)
646 \subsubsection*{Header Files}
649 \addcontentsline{toc}{subsubsection}{Header Files}
651 Please carefully follow the scheme defined below as it permits in general only
652 two header file includes per C file, and thus vastly simplifies programming.
653 With a large complex project like Bacula, it isn't always easy to ensure that
654 the right headers are invoked in the right order (there are a few kludges to
655 make this happen -- i.e. in a few include files because of the chicken and egg
656 problem, certain references to typedefs had to be replaced with {\bf void} ).
658 Every file should include {\bf bacula.h}. It pulls in just about everything,
659 with very few exceptions. If you have system dependent ifdefing, please do it
660 in {\bf baconfig.h}. The version number and date are kept in {\bf version.h}.
662 Each of the subdirectories (console, cats, dird, filed, findlib, lib, stored,
663 ...) contains a single directory dependent include file generally the name of
664 the directory, which should be included just after the include of {\bf
665 bacula.h}. This file (for example, for the dird directory, it is {\bf dird.h})
666 contains either definitions of things generally needed in this directory, or
667 it includes the appropriate header files. It always includes {\bf protos.h}.
670 Each subdirectory contains a header file named {\bf protos.h}, which contains
671 the prototypes for subroutines exported by files in that directory. {\bf
672 protos.h} is always included by the main directory dependent include file.
674 \subsubsection*{Programming Standards}
675 \index{Standards!Programming}
676 \index{Programming Standards}
677 \addcontentsline{toc}{subsubsection}{Programming Standards}
679 For the most part, all code should be written in C unless there is a burning
680 reason to use C++, and then only the simplest C++ constructs will be used.
681 Note, Bacula is slowly evolving to use more and more C++.
683 Code should have some documentation -- not a lot, but enough so that I can
684 understand it. Look at the current code, and you will see that I document more
685 than most, but am definitely not a fanatic.
687 I prefer simple linear code where possible. Gotos are strongly discouraged
688 except for handling an error to either bail out or to retry some code, and
689 such use of gotos can vastly simplify the program.
691 Remember this is a C program that is migrating to a {\bf tiny} subset of C++,
692 so be conservative in your use of C++ features.
694 \subsubsection*{Do Not Use}
697 \addcontentsline{toc}{subsubsection}{Do Not Use}
700 \item STL -- it is totally incomprehensible.
703 \subsubsection*{Avoid if Possible}
704 \index{Possible!Avoid if}
705 \index{Avoid if Possible}
706 \addcontentsline{toc}{subsubsection}{Avoid if Possible}
709 \item Returning a malloc'ed buffer from a subroutine -- someone will forget
711 \item Using reference variables -- it allows subroutines to create side
713 \item Heap allocation (malloc) unless needed -- it is expensive.
714 \item Templates -- they can create portability problems.
715 \item Fancy or tricky C or C++ code, unless you give a good explanation of
717 \item Too much inheritance -- it can complicate the code, and make reading it
718 difficult (unless you are in love with colons)
721 \subsubsection*{Do Use Whenever Possible}
722 \index{Possible!Do Use Whenever}
723 \index{Do Use Whenever Possible}
724 \addcontentsline{toc}{subsubsection}{Do Use Whenever Possible}
727 \item Locking and unlocking within a single subroutine.
728 \item Malloc and free within a single subroutine.
729 \item Comments and global explanations on what your code or algorithm does.
732 \subsubsection*{Indenting Standards}
733 \index{Standards!Indenting}
734 \index{Indenting Standards}
735 \addcontentsline{toc}{subsubsection}{Indenting Standards}
737 I cannot stand code indented 8 columns at a time. This makes the code
738 unreadable. Even 4 at a time uses a lot of space, so I have adopted indenting
739 3 spaces at every level. Note, indention is the visual appearance of the
740 source on the page, while tabbing is replacing a series of up to 8 spaces from
743 The closest set of parameters for the Linux {\bf indent} program that will
744 produce reasonably indented code are:
748 -nbad -bap -bbo -nbc -br -brs -c36 -cd36 -ncdb -ce -ci3 -cli0
749 -cp36 -d0 -di1 -ndj -nfc1 -nfca -hnl -i3 -ip0 -l85 -lp -npcs
750 -nprs -npsl -saf -sai -saw -nsob -nss -nbc -ncs -nbfda
754 You can put the above in your .indent.pro file, and then just invoke indent on
755 your file. However, be warned. This does not produce perfect indenting, and it
756 will mess up C++ class statements pretty badly.
758 Braces are required in all if statements (missing in some very old code). To
759 avoid generating too many lines, the first brace appears on the first line
760 (e.g. of an if), and the closing brace is on a line by itself. E.g.
770 Just follow the convention in the code. Originally I indented case clauses
771 under a switch(), but now I prefer non-indented cases.
788 Avoid using // style comments except for temporary code or turning off debug
789 code. Standard C comments are preferred (this also keeps the code closer to
792 Attempt to keep all lines less than 85 characters long so that the whole line
793 of code is readable at one time. This is not a rigid requirement.
795 Always put a brief description at the top of any new file created describing
796 what it does and including your name and the date it was first written. Please
797 don't forget any Copyrights and acknowledgments if it isn't 100\% your code.
798 Also, include the Bacula copyright notice that is in {\bf src/c}.
800 In general you should have two includes at the top of the an include for the
801 particular directory the code is in, for includes are needed, but this should
804 In general (except for self-contained packages), prototypes should all be put
805 in {\bf protos.h} in each directory.
807 Always put space around assignment and comparison operators.
818 but your can compress things in a {\bf for} statement:
822 for (i=0; i < del.num_ids; i++) {
827 Don't overuse the inline if (?:). A full {\bf if} is preferred, except in a
828 print statement, e.g.:
832 if (ua->verbose \&& del.num_del != 0) {
833 bsendmsg(ua, _("Pruned %d %s on Volume %s from catalog.\n"), del.num_del,
834 del.num_del == 1 ? "Job" : "Jobs", mr->VolumeName);
839 Leave a certain amount of debug code (Dmsg) in code you submit, so that future
840 problems can be identified. This is particularly true for complicated code
841 likely to break. However, try to keep the debug code to a minimum to avoid
842 bloating the program and above all to keep the code readable.
844 Please keep the same style in all new code you develop. If you include code
845 previously written, you have the option of leaving it with the old indenting
846 or re-indenting it. If the old code is indented with 8 spaces, then please
847 re-indent it to Bacula standards.
849 If you are using {\bf vim}, simply set your tabstop to 8 and your shiftwidth
852 \subsubsection*{Tabbing}
854 \addcontentsline{toc}{subsubsection}{Tabbing}
856 Tabbing (inserting the tab character in place of spaces) is as normal on all
857 Unix systems -- a tab is converted space up to the next column multiple of 8.
858 My editor converts strings of spaces to tabs automatically -- this results in
859 significant compression of the files. Thus, you can remove tabs by replacing
860 them with spaces if you wish. Please don't confuse tabbing (use of tab
861 characters) with indenting (visual alignment of the code).
863 \subsubsection*{Don'ts}
865 \addcontentsline{toc}{subsubsection}{Don'ts}
880 They are system dependent and un-safe. These should be replaced by the Bacula
885 char *bstrncpy(char *dest, char *source, int dest_size);
886 char *bstrncat(char *dest, char *source, int dest_size);
887 int bsnprintf(char *buf, int32_t buf_len, const char *fmt, ...);
888 int bvsnprintf(char *str, int32_t size, const char *format, va_list ap);
892 See src/lib/bsys.c for more details on these routines.
894 Don't use the {\bf \%lld} or the {\bf \%q} printf format editing types to edit
895 64 bit integers -- they are not portable. Instead, use {\bf \%s} with {\bf
896 edit\_uint64()}. For example:
901 uint64_t num = something;
903 bsnprintf(buf, sizeof(buf), "Num=%s\n", edit_uint64(num, ed1));
907 The edit buffer {\bf ed1} must be at least 27 bytes long to avoid overflow.
908 See src/lib/edit.c for more details. If you look at the code, don't start
909 screaming that I use {\bf lld}. I actually use subtle trick taught to me by
910 John Walker. The {\bf lld} that appears in the editing routine is actually
911 {\bf \#define} to a what is needed on your OS (usually ``lld'' or ``q'') and
912 is defined in autoconf/configure.in for each OS. C string concatenation causes
913 the appropriate string to be concatenated to the ``\%''.
915 Also please don't use the STL or Templates or any complicated C++ code.
917 \subsubsection*{Message Classes}
918 \index{Classes!Message}
919 \index{Message Classes}
920 \addcontentsline{toc}{subsubsection}{Message Classes}
922 Currently, there are five classes of messages: Debug, Error, Job, Memory,
925 \subsubsection*{Debug Messages}
926 \index{Messages!Debug}
927 \index{Debug Messages}
928 \addcontentsline{toc}{subsubsection}{Debug Messages}
930 Debug messages are designed to be turned on at a specified debug level and are
931 always sent to STDOUT. There are designed to only be used in the development
932 debug process. They are coded as:
934 DmsgN(level, message, arg1, ...) where the N is a number indicating how many
935 arguments are to be substituted into the message (i.e. it is a count of the
936 number arguments you have in your message -- generally the number of percent
937 signs (\%)). {\bf level} is the debug level at which you wish the message to
938 be printed. message is the debug message to be printed, and arg1, ... are the
939 arguments to be substituted. Since not all compilers support \#defines with
940 varargs, you must explicitly specify how many arguments you have.
942 When the debug message is printed, it will automatically be prefixed by the
943 name of the daemon which is running, the filename where the Dmsg is, and the
944 line number within the file.
946 Some actual examples are:
948 Dmsg2(20, ``MD5len=\%d MD5=\%s\textbackslash{}n'', strlen(buf), buf);
950 Dmsg1(9, ``Created client \%s record\textbackslash{}n'', client->hdr.name);
952 \subsubsection*{Error Messages}
953 \index{Messages!Error}
954 \index{Error Messages}
955 \addcontentsline{toc}{subsubsection}{Error Messages}
957 Error messages are messages that are related to the daemon as a whole rather
958 than a particular job. For example, an out of memory condition my generate an
959 error message. They should be very rarely needed. In general, you should be
960 using Job and Job Queued messages (Jmsg and Qmsg). They are coded as:
962 EmsgN(error-code, level, message, arg1, ...) As with debug messages, you must
963 explicitly code the of arguments to be substituted in the message. error-code
964 indicates the severity or class of error, and it may be one of the following:
966 \addcontentsline{lot}{table}{Message Error Code Classes}
967 \begin{longtable}{lp{3in}}
968 {{\bf M\_ABORT} } & {Causes the daemon to immediately abort. This should be
969 used only in extreme cases. It attempts to produce a traceback. } \\
970 {{\bf M\_ERROR\_TERM} } & {Causes the daemon to immediately terminate. This
971 should be used only in extreme cases. It does not produce a traceback. } \\
972 {{\bf M\_FATAL} } & {Causes the daemon to terminate the current job, but the
973 daemon keeps running } \\
974 {{\bf M\_ERROR} } & {Reports the error. The daemon and the job continue
976 {{\bf M\_WARNING} } & {Reports an warning message. The daemon and the job
977 continue running } \\
978 {{\bf M\_INFO} } & {Reports an informational message.}
982 There are other error message classes, but they are in a state of being
983 redesigned or deprecated, so please do not use them. Some actual examples are:
986 Emsg1(M\_ABORT, 0, ``Cannot create message thread: \%s\textbackslash{}n'',
989 Emsg3(M\_WARNING, 0, ``Connect to File daemon \%s at \%s:\%d failed. Retrying
990 ...\textbackslash{}n'', client-\gt{}hdr.name, client-\gt{}address,
993 Emsg3(M\_FATAL, 0, ``bdird\lt{}filed: bad response from Filed to \%s command:
994 \%d \%s\textbackslash{}n'', cmd, n, strerror(errno));
996 \subsubsection*{Job Messages}
999 \addcontentsline{toc}{subsubsection}{Job Messages}
1001 Job messages are messages that pertain to a particular job such as a file that
1002 could not be saved, or the number of files and bytes that were saved. They
1005 Jmsg(jcr, M\_FATAL, 0, "Text of message");
1007 A Jmsg with M\_FATAL will fail the job. The Jmsg() takes varargs so can
1008 have any number of arguments for substituted in a printf like format.
1009 Output from the Jmsg() will go to the Job report.
1011 If the Jmsg is followed with a number such as Jmsg1(...), the number
1012 indicates the number of arguments to be substituted (varargs is not
1013 standard for \#defines), and what is more important is that the file and
1014 line number will be prefixed to the message. This permits a sort of debug
1017 \subsubsection*{Queued Job Messages}
1018 \index{Queued Job Messages}
1019 \index{Messages!Job}
1020 \addcontentsline{toc}{subsubsection}{Queued Job Messages}
1021 Queued Job messages are similar to Jmsg()s except that the message is
1022 Queued rather than immediately dispatched. This is necessary within the
1023 network subroutines and in the message editing routines. This is to prevent
1024 recursive loops, and to ensure that messages can be delivered even in the
1025 event of a network error.
1028 \subsubsection*{Memory Messages}
1029 \index{Messages!Memory}
1030 \index{Memory Messages}
1031 \addcontentsline{toc}{subsubsection}{Memory Messages}
1033 Memory messages are messages that are edited into a memory buffer. Generally
1034 they are used in low level routines such as the low level device file dev.c in
1035 the Storage daemon or in the low level Catalog routines. These routines do not
1036 generally have access to the Job Control Record and so they return error
1037 messages reformatted in a memory buffer. Mmsg() is the way to do this.