4 \chapter{Bacula Developer Notes}
5 \label{_ChapterStart10}
6 \index{Bacula Developer Notes}
7 \index{Notes!Bacula Developer}
8 \addcontentsline{toc}{section}{Bacula Developer Notes}
10 This document is intended mostly for developers and describes how you can
11 contribute to the Bacula project and the the general framework of making
12 Bacula source changes.
14 \subsection{Contributions}
16 \addcontentsline{toc}{subsubsection}{Contributions}
18 Contributions to the Bacula project come in many forms: ideas,
19 participation in helping people on the bacula-users email list, packaging
20 Bacula binaries for the community, helping improve the documentation, and
23 Contributions in the form of submissions for inclusion in the project are
24 broken into two groups. The first are contributions that are aids and not
25 essential to Bacula. In general, these will be scripts or will go into the
26 {\bf bacula/examples} directory. For these kinds of non-essential
27 contributions there is no obligation to do a copyright assignment as
28 described below. However, a copyright assignment would still be
31 The second class of contributions are those which will be integrated with
32 Bacula and become an essential part (code, scripts, documentation, ...)
33 Within this class of contributions, there are two hurdles to surmount. One
34 is getting your patch accepted, and two is dealing with copyright issues.
35 The following text describes some of the requirements for such code.
39 \addcontentsline{toc}{subsubsection}{Patches}
41 Subject to the copyright assignment described below, your patches should be
42 sent in {\bf git format-patch} format relative to the current contents of the
43 master branch of the Source Forge Git repository. Please attach the
44 output file or files generated by the {\bf git format-patch} to the email
45 rather than include them directory to avoid wrapping of the lines
46 in the patch. Please be sure to use the Bacula
47 indenting standard (see below) for source code. If you have checked out
48 the source with Git, you can get a diff using.
55 If you plan on doing significant development work over a period of time,
56 after having your first patch reviewed and approved, you will be eligible
57 for having developer Git write access so that you can commit your changes
58 directly to the Git repository. To do so, you will need a userid on Source
61 \subsection{Copyrights}
63 \addcontentsline{toc}{subsubsection}{Copyrights}
65 To avoid future problems concerning changing licensing or
66 copyrights, all code contributions more than a hand full of lines
67 must be in the Public Domain or have the copyright transferred to
68 the Free Software Foundation Europe e.V. with a Fiduciary License
69 Agreement (FLA) as the case for all the current code.
71 Prior to November 2004, all the code was copyrighted by Kern Sibbald and
72 John Walker. After November 2004, the code was copyrighted by Kern
73 Sibbald, then on the 15th of November 2006, Kern transferred the copyright
74 to the Free Software Foundation Europe e.V. In signing the FLA and
75 transferring the copyright, you retain the right to use the code you have
76 submitted as you want, and you ensure that Bacula will always remain Free
79 Your name should be clearly indicated as the author of the code, and you
80 must be extremely careful not to violate any copyrights or patents or use
81 other people's code without acknowledging it. The purpose of this
82 requirement is to avoid future copyright, patent, or intellectual property
83 problems. Please read the LICENSE agreement in the main Bacula source code
84 directory. When you sign the Fiduciary License Agreement (FLA) and send it
85 in, you are agreeing to the terms of that LICENSE file.
87 If you don't understand what we mean by future problems, please
88 examine the difficulties Mozilla was having finding
89 previous contributors at \elink{
90 http://www.mozilla.org/MPL/missing.html}
91 {http://www.mozilla.org/MPL/missing.html}. The other important issue is to
92 avoid copyright, patent, or intellectual property violations as was
93 (May 2003) claimed by SCO against IBM.
95 Although the copyright will be held by the Free Software
96 Foundation Europe e.V., each developer is expected to indicate
97 that he wrote and/or modified a particular module (or file) and
98 any other sources. The copyright assignment may seem a bit
99 unusual, but in reality, it is not. Most large projects require
102 If you have any doubts about this, please don't hesitate to ask. The
103 objective is to assure the long term survival of the Bacula project.
105 Items not needing a copyright assignment are: most small changes,
106 enhancements, or bug fixes of 5-10 lines of code, which amount to
107 less than 20% of any particular file.
109 \subsection{Copyright Assignment -- Fiduciary License Agreement}
110 \index{Copyright Assignment}
111 \index{Assignment!Copyright}
112 \addcontentsline{toc}{subsubsection}{Copyright Assignment -- Fiduciary License Agreement}
114 Since this is not a commercial enterprise, and we prefer to believe in
115 everyone's good faith, previously developers could assign the copyright by
116 explicitly acknowledging that they do so in their first submission. This
117 was sufficient if the developer is independent, or an employee of a
118 not-for-profit organization or a university. However, in an effort to
119 ensure that the Bacula code is really clean, beginning in August 2006, all
120 previous and future developers with SVN write access will be asked to submit a
121 copyright assignment (or Fiduciary License Agreement -- FLA),
122 which means you agree to the LICENSE in the main source
123 directory. It also means that you receive back the right to use
124 the code that you have submitted.
126 Any developer who wants to contribute and is employed by a company should
127 either list the employer as the owner of the code, or get explicit
128 permission from him to sign the copyright assignment. This is because in
129 many countries, all work that an employee does whether on company time or
130 in the employee's free time is considered to be Intellectual Property of
131 the company. Obtaining official approval or an FLA from the company will
132 avoid misunderstandings between the employee, the company, and the Bacula
133 project. A good number of companies have already followed this procedure.
135 The Fiduciary License Agreement is posted on the Bacula web site at:
136 \elink{http://www.bacula.org/en/FLA-bacula.en.pdf}{http://www.bacula.org/en/FLA-bacula.en.pdf}
138 The instructions for filling out this agreement are also at:
139 \elink{http://www.bacula.org/?page=fsfe}{http://www.bacula.org/?page=fsfe}
141 It should be filled out, then sent to:
145 Cotes-de-Montmoiret 9
150 Please note that the above address is different from the officially
151 registered office mentioned in the document. When you send in such a
152 complete document, please notify me: kern at sibbald dot com, and
153 please add your email address to the FLA so that I can contact you
154 to confirm reception of the signed FLA.
157 \section{The Development Cycle}
158 \index{Developement Cycle}
159 \index{Cycle!Developement}
160 \addcontentsline{toc}{subsubsection}{Development Cycle}
162 As discussed on the email lists, the number of contributions are
163 increasing significantly. We expect this positive trend
164 will continue. As a consequence, we have modified how we do
165 development, and instead of making a list of all the features that we will
166 implement in the next version, each developer signs up for one (maybe
167 two) projects at a time, and when they are complete, and the code
168 is stable, we will release a new version. The release cycle will probably
169 be roughly six months.
171 The difference is that with a shorter release cycle and fewer released
172 feature, we will have more time to review the new code that is being
173 contributed, and will be able to devote more time to a smaller number of
174 projects (some prior versions had too many new features for us to handle
177 Future release schedules will be much the same, and the
178 number of new features will also be much the same providing that the
179 contributions continue to come -- and they show no signs of let up :-)
181 \index{Feature Requests}
182 {\bf Feature Requests:} \\
183 In addition, we have "formalizee" the feature requests a bit.
185 Instead of me maintaining an informal list of everything I run into
186 (kernstodo), we now maintain a "formal" list of projects. This
187 means that all new feature requests, including those recently discussed on
188 the email lists, must be formally submitted and approved.
190 Formal submission of feature requests will take two forms: \\
191 1. non-mandatory, but highly recommended is to discuss proposed new features
192 on the mailing list.\\
193 2. Formal submission of an Feature Request in a special format. We'll
194 give an example of this below, but you can also find it on the web site
195 under "Support -\gt{} Feature Requests". Since it takes a bit of time to
196 properly fill out a Feature Request form, you probably should check on the
199 Once the Feature Request is received by the keeper of the projects list, it
200 will be sent to the Bacula project manager (Kern), and he will either
201 accept it (90% of the time), send it back asking for clarification (10% of
202 the time), send it to the email list asking for opinions, or reject it
205 If it is accepted, it will go in the "projects" file (a simple ASCII file)
206 maintained in the main Bacula source directory.
208 {\bf Implementation of Feature Requests:}\\
209 Any qualified developer can sign up for a project. The project must have
210 an entry in the projects file, and the developer's name will appear in the
213 {\bf How Feature Requests are accepted:}\\
214 Acceptance of Feature Requests depends on several things: \\
215 1. feedback from users. If it is negative, the Feature Request will probably not be
217 2. the difficulty of the project. A project that is so
218 difficult that we cannot imagine finding someone to implement probably won't
219 be accepted. Obviously if you know how to implement it, don't hesitate
220 to put it in your Feature Request \\
221 3. whether or not the Feature Request fits within the current strategy of
222 Bacula (for example an Feature Request that requests changing the tape to
223 tar format probably would not be accepted, ...).
225 {\bf How Feature Requests are prioritized:}\\
226 Once an Feature Request is accepted, it needs to be implemented. If you
227 can find a developer for it, or one signs up for implementing it, then the
228 Feature Request becomes top priority (at least for that developer).
230 Between releases of Bacula, we will generally solicit Feature Request input
231 for the next version, and by way of this email, we suggest that you send
232 discuss and send in your Feature Requests for the next release. Please
233 verify that the Feature Request is not in the current list (attached to this email).
235 Once users have had several weeks to submit Feature Requests, the keeper of
236 the projects list will organize them, and request users to vote on them.
237 This will allow fixing prioritizing the Feature Requests. Having a
238 priority is one thing, but getting it implement is another thing -- we are
239 hoping that the Bacula community will take more responsibility for assuring
240 the implementation of accepted Feature Requests.
242 Feature Request format:
244 ============= Empty Feature Request form ===========
245 Item n: One line summary ...
247 Origin: Name and email of originator.
250 What: More detailed explanation ...
252 Why: Why it is important ...
254 Notes: Additional notes or features (omit if not used)
255 ============== End Feature Request form ==============
259 ============= Example Completed Feature Request form ===========
260 Item 1: Implement a Migration job type that will move the job
261 data from one device to another.
262 Origin: Sponsored by Riege Sofware International GmbH. Contact:
263 Daniel Holtkamp <holtkamp at riege dot com>
264 Date: 28 October 2005
265 Status: Partially coded in 1.37 -- much more to do. Assigned to
268 What: The ability to copy, move, or archive data that is on a
269 device to another device is very important.
271 Why: An ISP might want to backup to disk, but after 30 days
272 migrate the data to tape backup and delete it from
273 disk. Bacula should be able to handle this
274 automatically. It needs to know what was put where,
275 and when, and what to migrate -- it is a bit like
276 retention periods. Doing so would allow space to be
277 freed up for current backups while maintaining older
280 Notes: Migration could be triggered by:
284 Highwater size (keep total size)
286 =================================================
290 \section{Bacula Code Submissions and Projects}
291 \index{Submissions and Projects}
292 \addcontentsline{toc}{subsection}{Code Submissions and Projects}
294 Getting code implemented in Bacula works roughly as follows:
298 \item Kern is the project manager, but prefers not to be a "gate keeper".
299 This means that the developers are expected to be self-motivated,
300 and once they have experience submit directly to the Git
301 repositories. However,
302 it is a good idea to have your patches reviewed prior to submitting,
303 and it is a bad idea to submit monster patches because no one will
304 be able to properly review them. See below for more details on this.
306 \item There are growing numbers of contributions (very good).
308 \item Some contributions come in the form of relatively small patches,
309 which Kern reviews, integrates, documents, tests, and maintains.
311 \item All Bacula developers take full
312 responsibility for writing the code, posting as patches so that we can
313 review it as time permits, integrating it at an appropriate time,
314 responding to our requests for tweaking it (name changes, ...),
315 document it in the code, document it in the manual (even though
316 their mother tongue is not English), test it, develop and commit
317 regression scripts, and answer in a timely fashion all bug reports --
318 even occasionally accepting additional bugs :-)
320 This is a sustainable way of going forward with Bacula, and the
321 direction that the project will be taking more and more. For
322 example, in the past, we have had some very dedicated programmers
323 who did major projects. However, some of these
324 programmers due to outside obligations (job responsibilities change of
325 job, school duties, ...) could not continue to maintain the code. In
326 those cases, the code suffers from lack of maintenance, sometimes we
327 patch it, sometimes not. In the end, if the code is not maintained, the
328 code gets dropped from the project (there are two such contributions
329 that are heading in that direction). When ever possible, we would like
330 to avoid this, and ensure a continuation of the code and a sharing of
331 the development, debugging, documentation, and maintenance
335 \section{Patches for Released Versions}
336 \index{Patches for Released Versions}
337 \addcontentsline{toc}{subsection}{Patches for Released Versions}
338 If you fix a bug in a released version, you should, unless it is
339 an absolutely trivial bug, create and release a patch file for the
340 bug. The procedure is as follows:
342 Fix the bug in the released branch and in the develpment master branch.
344 Make a patch file for the branch and add the branch patch to
345 the patches directory in both the branch and the trunk.
346 The name should be 2.2.4-xxx.patch where xxx is unique, in this case it can
347 be "restore", e.g. 2.2.4-restore.patch. Add to the top of the
348 file a brief description and instructions for applying it -- see for example
349 2.2.4-poll-mount.patch. The best way to create the patch file is as
353 (edit) 2.2.4-restore.patch
358 mv 0001-xxx 2.2.4-restore.patch
361 check to make sure no extra junk got put into the patch file (i.e.
362 it should have the patch for that bug only).
364 If there is not a bug report on the problem, create one, then add the
365 patch to the bug report.
367 Then upload it to the 2.2.x release of bacula-patches.
369 So, end the end, the patch file is:
371 \item Attached to the bug report
373 \item In Branch-2.2/bacula/patches/...
377 \item Loaded on Source Forge bacula-patches 2.2.x release. When
378 you add it, click on the check box to send an Email so that all the
379 users that are monitoring SF patches get notified.
383 \section{Bacula Git repositories}
385 \addcontentsline{toc}{subsection}{Git repositories}
386 As of September 2009, the Bacula source code has been split into
387 three Git repositories. One is a repository that holds the
388 main Bacula source code with directories {\bf bacula}, {\bf gui},
389 and {\bf regress}. The second repository contains
390 the directories {\bf docs} directory, and the third repository
391 contains the {\bf rescue} directory. All three repositories are
392 hosted on Source Forge.
394 Previously everything was in a single SVN repository.
395 We have split the SVN repository into three because Git
396 offers significant advantages for ease of managing and integrating
397 developer's changes. However, one of the disadvantages of Git is that you
398 must work with the full repository, while SVN allows you to checkout
399 individual directories. If we put everything into a single Git
400 repository it would be far bigger than most developers would want
401 to checkout, so we have separted the docs and rescue into their own
402 repositories, and moved only the parts that are most actively
403 worked on by the developers (bacula, gui, and regress) to a the
404 Git Bacula repository.
406 Bacula developers must now have a certain knowledege
411 \addcontentsline{toc}{subsection}{Git Usage}
413 Please note that if you are familiar with SVN, Git is similar,
414 (and better), but there can be a few surprising differences that
415 can lead to damaging the history of the repository (repo) if
416 you attempt to force pushing data into the Git repo.
418 The Bacula Git repo contains the subdirectories {\bf bacula}, {\bf gui},
419 and {\bf regress}. With Git it is not possible to pull only a
420 single directory, because of the hash code nature of Git, you
421 must take all or nothing.
423 For developers, the most important thing to remember about Git and
424 the Source Forge repository is not to "force" a {\bf push} to the
425 repository, and not to use the {\bf rebase} command on the {\bf
426 master} branch of the repository. Doing so, will possibly rewrite
427 the Git repository history and cause a lot of problems for the
430 You may and should use {\bf rebase} on your own branches that you
431 want to synchronize with the {\bf master} branch, but please
432 do not use {\bf rebase} on the {\bf master} branch. The proper
433 way of merging changes will be discussed below.
435 You can get a full copy of the Source Forge Bacula Git repository with the
439 git clone git://bacula.git.sourceforge.net/gitroot/bacula/bacula trunk
442 This will put a read-only copy into the directory {\bf trunk}
443 in your current directory, and {\bf trunk} will contain
444 the subdirectories: {\bf bacula}, {\bf gui}, and {\bf regress}.
446 If you have write permission, you can get a copy of the Git
450 git clone ssh://<userid>@bacula.git.sourceforge.net/gitroot/bacula/bacula trunk
453 where you replace \verb+<userid>+ with your Source Forge login
454 userid, and you must have previously uploaded your public ssh key
457 The above command needs to be done only once. Thereafter, you can:
464 As of August 2009, the size of the repository ({\bf trunk} in the above
465 example) will be approximately 55 Megabytes. However, if you build
466 from source in this directory and do a lot of updates and regression
467 testing, the directory could become several hundred megabytes.
469 \subsection{Learning Git}
471 If you want to learn more about Git, we recommend that you visit:\\
472 \elink{http://book.git-scm.com/}{http://book.git-scm.com/}.
474 Some of the differences between Git and SVN are:
476 \item Your main Git directory is a full Git repository to which you can
478 \item The Git database is kept in the directory {\bf .git} at the
479 top level of the directory.
480 \item all the important Git configuration information is kept in the
481 file {\bf .git/config} in ASCII format that is easy to manually edit.
482 \item When you do a {\bf commit} the changes are put in {\bf .git}
483 rather than in the external repository.
484 \item You can upload your changes to the external repository using
485 the command {\bf git push}.
486 \item You can download all the current changes in the external repository
487 and merge them into your {\bf master} branch using the command
489 \item The command {\bf git add} is used to add a new file to the
490 repository AND to tell Git that you want a file that has changed
491 to be in the next commit. This has lots of advantages, because
492 a {\bf git commit} only commits those files that have been
494 \item You can add and commit all files modifed in one command
495 using {\bf git commit -a}.
496 \item This extra use of {\bf add} allows you to make a number
497 of changes then add only a few of the files and commit them,
498 then add more files and commit them until you have committed
499 everything. This has the advantage of allowing you to more
500 easily group small changes and commit them.
501 \item If you {\bf git pull} from the main repository and make
502 some changes, and before you do a {\bf git push}, someone
503 else pushes changes to the Git repository, you will probably
504 get an error message such as:
508 To git@github.com:bacula/bacula.git
509 ! [rejected] master -> master (non-fast forward)
510 error: failed to push some refs to 'git@github.com:bacula/bacula.git'
513 which is Git's way of telling you that the main repository has changed
514 and that if you push your changes, they will not be integrated properly.
515 As we have noted, you should never ask Git to force the push.
516 See below for an explanation of why.
517 \item To integrate (merge) your changes properly, you should always do
518 a {\bf git pull} just prior to doing a {\bf git push}.
519 \item If Git is unable to merge your changes or finds a conflict it
520 will tell you and you must do conflict resolution, which is much
521 easier in Git than in SVN.
522 \item Resolving conflicts is described below in the {\bf github} section.
525 If you want to understand why it is not a good idea to force a
526 push to the repository, look at the following picture:
528 \includegraphics[width=0.85\textwidth]{\idir git-edit-commit.eps}
530 The above graphic has three lines of circles. Each circle represents
531 a commit, and time runs from the left to the right. The top line
532 shows the repository just before you are going to do a push. Note the
533 point at which you pulled is the circle on the left, your changes are
534 represented by the circle labeled {\bf Your mods}. It is shown below
535 to indicate that the changes are only in your local repository. Finally,
536 there are pushes A and B that came after the time at which you pulled.
538 If you were to force your changes into the repository, Git would place them
539 immediately after the point at which you pulled them, so they would
540 go before the pushes A and B. However, doing so would rewrite the history
541 of the repository and make it very difficult for other users to synchronize
542 since they would have to somehow wedge their changes at some point before the
543 current HEAD of the repository. This situation is shown by the second line of
546 What you really want to do is to put your changes after Push B (the current HEAD).
547 This is shown in the third line of pushes. The best way to accomplish this is to
548 work in a branch, pull the repository so you have your master equal to HEAD (in first
549 line), then to rebase your branch on the current master and then commit it. The
550 exact commands to accomplish this are shown in the next couple of sections.
552 \subsection{Publishing your changes}
554 Since Git is more complex than SVN, it takes a bit of time to learn how
555 to use it properly, and if you are not careful, you can potentially create
556 a new history in the repository. In addition, since Git is a distributed
557 version control system, we prefer to receive a full branch submission rather
558 than simply a patch. To accomplish this, you must create your changes in
559 a branch, then {\bf push} them to some public repository -- it can be your
560 own repository that you publish or another. To simplify this phase for you, we
561 have created a publich Bacula Git repository on {\bf github} where you can
562 push your branch containing changes you would like integrated into the Bacula
565 Once you have pushed your branch to {\bf github} or told us where we can pull
566 from your public repository, one of the senior Bacula devlopers will fetch your
567 changes, examine them, possibly make comments for changes they would like to
568 see, and as the final step, the senior developer will commit it to the
569 Bacula Source Forge Git repository.
573 If you are going to submit code, you create a login on
574 the Github website:\\
575 \elink{http://github.com/}{http://github.com/}\\
576 before you clone the repository.
577 You must also upload your public ssh key. Please see the instructions for
578 doing so at the above link. Then you notify one of the senior Bacula developers,
579 who will authorize your Github user name as a committer to the Bacula repository. Finally,
580 you clone the Bacula repository with:
583 git clone git@github.com:bacula/bacula.git <xxx>
586 where you replace \verb+<xxx>+ with the name
587 of a directory that you want Git to create to hold your local Bacula Git
590 Normally, you will work by creating a branch of the master branch of your
591 repository, make your modifications, then make sure it is up to date, and finally
592 push it to Github. Assuming you call the Bacula repository {\bf bacula}, you might
593 use the following commands:
599 git branch <your-name>/newbranch
600 git checkout <your-name>/newbranch
602 git add <file-edited>
603 git commit -m "<comment about commit>"
607 Note, we request you to create the branch name ({\bf \verb+<your-name>+/newbranch} with your Github
608 login name. This guarantees that the branch name will be unique and
609 easily identified as well.
611 When you have completed working on your branch, you will do:
615 git checkout <your-name>/newbranch
620 If you have completed your edits before anyone has modified the repository,
621 the {\bf git rebase master} will report that there was nothing to do. Otherwise,
622 it will merge the changes that were made in the repository before your changes.
623 If there are any conflicts, Git will tell you. Typically resolving conflicts with
624 Git is relatively easy. You simply make a diff:
630 Then edit each file that was listed in the {\bf git diff} to remove the
631 conflict, which will be indicated by lines of:
641 where {\bf text} is what is in the Bacula repository, and {\bf other text}
642 is what you have changed.
644 Once you have eliminated the conflict, the {\bf git diff} will show nothing,
648 git add <file-with-conflicts-fixed>
651 Once you have fixed all the files with conflicts in the above manner, you enter:
654 git rebase --continue
657 and your rebase will be complete.
659 If for some reason, before doing the --continue, you want to abort the rebase and return to what you had, you enter:
665 Finally to upload your branch, you do:
668 git push origin <your-name>/newbranch
671 If you wish to delete it later, you can use:
674 git push origin :<your-name>/newbranch
678 \section{Developing Bacula}
679 \index{Developing Bacula}
680 \index{Bacula!Developing}
681 \addcontentsline{toc}{subsubsection}{Developing Bacula}
683 Typically the simplest way to develop Bacula is to open one xterm window
684 pointing to the source directory you wish to update; a second xterm window at
685 the top source directory level, and a third xterm window at the bacula
686 directory \lt{}top\gt{}/src/bacula. After making source changes in one of the
687 directories, in the top source directory xterm, build the source, and start
688 the daemons by entering:
692 ./startit then in the enter:
696 ./gnome-console to start the Console program. Enter any commands for testing.
697 For example: run kernsverify full.
699 Note, the instructions here to use {\bf ./startit} are different from using a
700 production system where the administrator starts Bacula by entering {\bf
701 ./bacula start}. This difference allows a development version of {\bf Bacula}
702 to be run on a computer at the same time that a production system is running.
703 The {\bf ./startit} strip starts {\bf Bacula} using a different set of
704 configuration files, and thus permits avoiding conflicts with any production
707 To make additional source changes, exit from the Console program, and in the
708 top source directory, stop the daemons by entering:
710 ./stopit then repeat the process.
712 \subsection{Debugging}
714 \addcontentsline{toc}{subsubsection}{Debugging}
716 Probably the first thing to do is to turn on debug output.
718 A good place to start is with a debug level of 20 as in {\bf ./startit -d20}.
719 The startit command starts all the daemons with the same debug level.
720 Alternatively, you can start the appropriate daemon with the debug level you
721 want. If you really need more info, a debug level of 60 is not bad, and for
722 just about everything a level of 200.
724 \subsection{Using a Debugger}
725 \index{Using a Debugger}
726 \index{Debugger!Using a}
727 \addcontentsline{toc}{subsubsection}{Using a Debugger}
729 If you have a serious problem such as a segmentation fault, it can usually be
730 found quickly using a good multiple thread debugger such as {\bf gdb}. For
731 example, suppose you get a segmentation violation in {\bf bacula-dir}. You
732 might use the following to find the problem:
734 \lt{}start the Storage and File daemons\gt{}
737 run -f -s -c ./dird.conf
738 \lt{}it dies with a segmentation fault\gt{}
740 The {\bf -f} option is specified on the {\bf run} command to inhibit {\bf
741 dird} from going into the background. You may also want to add the {\bf -s}
742 option to the run command to disable signals which can potentially interfere
745 As an alternative to using the debugger, each {\bf Bacula} daemon has a built
746 in back trace feature when a serious error is encountered. It calls the
747 debugger on itself, produces a back trace, and emails the report to the
748 developer. For more details on this, please see the chapter in the main Bacula
749 manual entitled ``What To Do When Bacula Crashes (Kaboom)''.
751 \subsection{Memory Leaks}
754 \addcontentsline{toc}{subsubsection}{Memory Leaks}
756 Because Bacula runs routinely and unattended on client and server machines, it
757 may run for a long time. As a consequence, from the very beginning, Bacula
758 uses SmartAlloc to ensure that there are no memory leaks. To make detection of
759 memory leaks effective, all Bacula code that dynamically allocates memory MUST
760 have a way to release it. In general when the memory is no longer needed, it
761 should be immediately released, but in some cases, the memory will be held
762 during the entire time that Bacula is executing. In that case, there MUST be a
763 routine that can be called at termination time that releases the memory. In
764 this way, we will be able to detect memory leaks. Be sure to immediately
765 correct any and all memory leaks that are printed at the termination of the
768 \subsection{Special Files}
769 \index{Files!Special}
770 \index{Special Files}
771 \addcontentsline{toc}{subsubsection}{Special Files}
773 Kern uses files named 1, 2, ... 9 with any extension as scratch files. Thus
774 any files with these names are subject to being rudely deleted at any time.
776 \subsection{When Implementing Incomplete Code}
777 \index{Code!When Implementing Incomplete}
778 \index{When Implementing Incomplete Code}
779 \addcontentsline{toc}{subsubsection}{When Implementing Incomplete Code}
781 Please identify all incomplete code with a comment that contains
787 where there are three asterisks (*) before and after the word
788 FIXME (in capitals) and no intervening spaces. This is important as it allows
789 new programmers to easily recognize where things are partially implemented.
791 \subsection{Bacula Source File Structure}
792 \index{Structure!Bacula Source File}
793 \index{Bacula Source File Structure}
794 \addcontentsline{toc}{subsubsection}{Bacula Source File Structure}
796 The distribution generally comes as a tar file of the form {\bf
797 bacula.x.y.z.tar.gz} where x, y, and z are the version, release, and update
798 numbers respectively.
800 Once you detar this file, you will have a directory structure as follows:
807 |- mtx (autochanger control program + tape drive info)
808 |- sqlite (SQLite database program)
812 |- pthreads (Native win32 pthreads library -- dll)
813 |- zlib (Native win32 zlib library)
814 |- wx (wxWidgets source code)
817 |- bacula (main source directory containing configuration
818 | and installation files)
819 |- autoconf (automatic configuration files, not normally used
821 |- intl (programs used to translate)
822 |- platforms (OS specific installation files)
823 |- redhat (Red Hat installation)
824 |- solaris (Sun installation)
825 |- freebsd (FreeBSD installation)
826 |- irix (Irix installation -- not tested)
827 |- unknown (Default if system not identified)
828 |- po (translations of source strings)
829 |- src (source directory; contains global header files)
830 |- cats (SQL catalog database interface directory)
831 |- console (bacula user agent directory)
832 |- dird (Director daemon)
833 |- filed (Unix File daemon)
834 |- win32 (Win32 files to make bacula-fd be a service)
835 |- findlib (Unix file find library for File daemon)
836 |- gnome-console (GNOME version of console program)
837 |- lib (General Bacula library)
838 |- stored (Storage daemon)
839 |- tconsole (Tcl/tk console program -- not yet working)
840 |- testprogs (test programs -- normally only in Kern's tree)
841 |- tools (Various tool programs)
842 |- win32 (Native Win32 File daemon)
843 |- baculafd (Visual Studio project file)
844 |- compat (compatibility interface library)
845 |- filed (links to src/filed)
846 |- findlib (links to src/findlib)
847 |- lib (links to src/lib)
848 |- console (beginning of native console program)
849 |- wx-console (wxWidget console Win32 specific parts)
850 |- wx-console (wxWidgets console main source program)
853 |- regress (Regression scripts)
854 |- bin (temporary directory to hold Bacula installed binaries)
855 |- build (temporary directory to hold Bacula source)
856 |- scripts (scripts and .conf files)
857 |- tests (test scripts)
858 |- tmp (temporary directory for temp files)
859 |- working (temporary working directory for Bacula daemons)
862 |- docs (documentation directory)
863 |- developers (Developer's guide)
864 |- home-page (Bacula's home page source)
865 |- manual (html document directory)
866 |- manual-fr (French translation)
867 |- manual-de (German translation)
868 |- techlogs (Technical development notes);
871 |- rescue (Bacula rescue CDROM)
872 |- linux (Linux rescue CDROM)
873 |- cdrom (Linux rescue CDROM code)
875 |- solaris (Solaris rescue -- incomplete)
876 |- freebsd (FreeBSD rescue -- incomplete)
879 |- gui (Bacula GUI projects)
880 |- bacula-web (Bacula web php management code)
881 |- bimagemgr (Web application for burning CDROMs)
887 \subsection{Header Files}
890 \addcontentsline{toc}{subsubsection}{Header Files}
892 Please carefully follow the scheme defined below as it permits in general only
893 two header file includes per C file, and thus vastly simplifies programming.
894 With a large complex project like Bacula, it isn't always easy to ensure that
895 the right headers are invoked in the right order (there are a few kludges to
896 make this happen -- i.e. in a few include files because of the chicken and egg
897 problem, certain references to typedefs had to be replaced with {\bf void} ).
899 Every file should include {\bf bacula.h}. It pulls in just about everything,
900 with very few exceptions. If you have system dependent ifdefing, please do it
901 in {\bf baconfig.h}. The version number and date are kept in {\bf version.h}.
903 Each of the subdirectories (console, cats, dird, filed, findlib, lib, stored,
904 ...) contains a single directory dependent include file generally the name of
905 the directory, which should be included just after the include of {\bf
906 bacula.h}. This file (for example, for the dird directory, it is {\bf dird.h})
907 contains either definitions of things generally needed in this directory, or
908 it includes the appropriate header files. It always includes {\bf protos.h}.
911 Each subdirectory contains a header file named {\bf protos.h}, which contains
912 the prototypes for subroutines exported by files in that directory. {\bf
913 protos.h} is always included by the main directory dependent include file.
915 \subsection{Programming Standards}
916 \index{Standards!Programming}
917 \index{Programming Standards}
918 \addcontentsline{toc}{subsubsection}{Programming Standards}
920 For the most part, all code should be written in C unless there is a burning
921 reason to use C++, and then only the simplest C++ constructs will be used.
922 Note, Bacula is slowly evolving to use more and more C++.
924 Code should have some documentation -- not a lot, but enough so that I can
925 understand it. Look at the current code, and you will see that I document more
926 than most, but am definitely not a fanatic.
928 We prefer simple linear code where possible. Gotos are strongly discouraged
929 except for handling an error to either bail out or to retry some code, and
930 such use of gotos can vastly simplify the program.
932 Remember this is a C program that is migrating to a {\bf tiny} subset of C++,
933 so be conservative in your use of C++ features.
935 \subsection{Do Not Use}
938 \addcontentsline{toc}{subsubsection}{Do Not Use}
941 \item STL -- it is totally incomprehensible.
944 \subsection{Avoid if Possible}
945 \index{Possible!Avoid if}
946 \index{Avoid if Possible}
947 \addcontentsline{toc}{subsubsection}{Avoid if Possible}
950 \item Using {\bf void *} because this generally means that one must
951 using casting, and in C++ casting is rather ugly. It is OK to use
952 void * to pass structure address where the structure is not known
953 to the routines accepting the packet (typically callback routines).
954 However, declaring "void *buf" is a bad idea. Please use the
955 correct types whenever possible.
957 \item Using undefined storage specifications such as (short, int, long,
958 long long, size\_t ...). The problem with all these is that the number of bytes
959 they allocate depends on the compiler and the system. Instead use
960 Bacula's types (int8\_t, uint8\_t, int32\_t, uint32\_t, int64\_t, and
961 uint64\_t). This guarantees that the variables are given exactly the
962 size you want. Please try at all possible to avoid using size\_t ssize\_t
963 and the such. They are very system dependent. However, some system
964 routines may need them, so their use is often unavoidable.
966 \item Returning a malloc'ed buffer from a subroutine -- someone will forget
969 \item Heap allocation (malloc) unless needed -- it is expensive. Use
972 \item Templates -- they can create portability problems.
974 \item Fancy or tricky C or C++ code, unless you give a good explanation of
977 \item Too much inheritance -- it can complicate the code, and make reading it
978 difficult (unless you are in love with colons)
982 \subsection{Do Use Whenever Possible}
983 \index{Possible!Do Use Whenever}
984 \index{Do Use Whenever Possible}
985 \addcontentsline{toc}{subsubsection}{Do Use Whenever Possible}
988 \item Locking and unlocking within a single subroutine.
990 \item A single point of exit from all subroutines. A goto is
991 perfectly OK to use to get out early, but only to a label
992 named bail\_out, and possibly an ok\_out. See current code
995 \item Malloc and free within a single subroutine.
997 \item Comments and global explanations on what your code or algorithm does.
1001 \subsection{Indenting Standards}
1002 \index{Standards!Indenting}
1003 \index{Indenting Standards}
1004 \addcontentsline{toc}{subsubsection}{Indenting Standards}
1006 We find it very hard to read code indented 8 columns at a time.
1007 Even 4 at a time uses a lot of space, so we have adopted indenting
1008 3 spaces at every level. Note, indention is the visual appearance of the
1009 source on the page, while tabbing is replacing a series of up to 8 spaces from
1012 The closest set of parameters for the Linux {\bf indent} program that will
1013 produce reasonably indented code are:
1017 -nbad -bap -bbo -nbc -br -brs -c36 -cd36 -ncdb -ce -ci3 -cli0
1018 -cp36 -d0 -di1 -ndj -nfc1 -nfca -hnl -i3 -ip0 -l85 -lp -npcs
1019 -nprs -npsl -saf -sai -saw -nsob -nss -nbc -ncs -nbfda
1023 You can put the above in your .indent.pro file, and then just invoke indent on
1024 your file. However, be warned. This does not produce perfect indenting, and it
1025 will mess up C++ class statements pretty badly.
1027 Braces are required in all if statements (missing in some very old code). To
1028 avoid generating too many lines, the first brace appears on the first line
1029 (e.g. of an if), and the closing brace is on a line by itself. E.g.
1039 Just follow the convention in the code. For example we I prefer non-indented cases.
1056 Avoid using // style comments except for temporary code or turning off debug
1057 code. Standard C comments are preferred (this also keeps the code closer to
1060 Attempt to keep all lines less than 85 characters long so that the whole line
1061 of code is readable at one time. This is not a rigid requirement.
1063 Always put a brief description at the top of any new file created describing
1064 what it does and including your name and the date it was first written. Please
1065 don't forget any Copyrights and acknowledgments if it isn't 100\% your code.
1066 Also, include the Bacula copyright notice that is in {\bf src/c}.
1068 In general you should have two includes at the top of the an include for the
1069 particular directory the code is in, for includes are needed, but this should
1072 In general (except for self-contained packages), prototypes should all be put
1073 in {\bf protos.h} in each directory.
1075 Always put space around assignment and comparison operators.
1086 but your can compress things in a {\bf for} statement:
1090 for (i=0; i < del.num_ids; i++) {
1095 Don't overuse the inline if (?:). A full {\bf if} is preferred, except in a
1096 print statement, e.g.:
1100 if (ua->verbose \&& del.num_del != 0) {
1101 bsendmsg(ua, _("Pruned %d %s on Volume %s from catalog.\n"), del.num_del,
1102 del.num_del == 1 ? "Job" : "Jobs", mr->VolumeName);
1107 Leave a certain amount of debug code (Dmsg) in code you submit, so that future
1108 problems can be identified. This is particularly true for complicated code
1109 likely to break. However, try to keep the debug code to a minimum to avoid
1110 bloating the program and above all to keep the code readable.
1112 Please keep the same style in all new code you develop. If you include code
1113 previously written, you have the option of leaving it with the old indenting
1114 or re-indenting it. If the old code is indented with 8 spaces, then please
1115 re-indent it to Bacula standards.
1117 If you are using {\bf vim}, simply set your tabstop to 8 and your shiftwidth
1120 \subsection{Tabbing}
1122 \addcontentsline{toc}{subsubsection}{Tabbing}
1124 Tabbing (inserting the tab character in place of spaces) is as normal on all
1125 Unix systems -- a tab is converted space up to the next column multiple of 8.
1126 My editor converts strings of spaces to tabs automatically -- this results in
1127 significant compression of the files. Thus, you can remove tabs by replacing
1128 them with spaces if you wish. Please don't confuse tabbing (use of tab
1129 characters) with indenting (visual alignment of the code).
1133 \addcontentsline{toc}{subsubsection}{Don'ts}
1148 They are system dependent and un-safe. These should be replaced by the Bacula
1153 char *bstrncpy(char *dest, char *source, int dest_size);
1154 char *bstrncat(char *dest, char *source, int dest_size);
1155 int bsnprintf(char *buf, int32_t buf_len, const char *fmt, ...);
1156 int bvsnprintf(char *str, int32_t size, const char *format, va_list ap);
1160 See src/lib/bsys.c for more details on these routines.
1162 Don't use the {\bf \%lld} or the {\bf \%q} printf format editing types to edit
1163 64 bit integers -- they are not portable. Instead, use {\bf \%s} with {\bf
1164 edit\_uint64()}. For example:
1169 uint64_t num = something;
1171 bsnprintf(buf, sizeof(buf), "Num=%s\n", edit_uint64(num, ed1));
1175 Note: {\bf \%lld} is now permitted in Bacula code -- we have our
1176 own printf routines which handle it correctly. The edit\_uint64() subroutine
1177 can still be used if you wish, but over time, most of that old style will
1180 The edit buffer {\bf ed1} must be at least 27 bytes long to avoid overflow.
1181 See src/lib/edit.c for more details. If you look at the code, don't start
1182 screaming that I use {\bf lld}. I actually use subtle trick taught to me by
1183 John Walker. The {\bf lld} that appears in the editing routine is actually
1184 {\bf \#define} to a what is needed on your OS (usually ``lld'' or ``q'') and
1185 is defined in autoconf/configure.in for each OS. C string concatenation causes
1186 the appropriate string to be concatenated to the ``\%''.
1188 Also please don't use the STL or Templates or any complicated C++ code.
1190 \subsection{Message Classes}
1191 \index{Classes!Message}
1192 \index{Message Classes}
1193 \addcontentsline{toc}{subsubsection}{Message Classes}
1195 Currently, there are five classes of messages: Debug, Error, Job, Memory,
1198 \subsection{Debug Messages}
1199 \index{Messages!Debug}
1200 \index{Debug Messages}
1201 \addcontentsline{toc}{subsubsection}{Debug Messages}
1203 Debug messages are designed to be turned on at a specified debug level and are
1204 always sent to STDOUT. There are designed to only be used in the development
1205 debug process. They are coded as:
1207 DmsgN(level, message, arg1, ...) where the N is a number indicating how many
1208 arguments are to be substituted into the message (i.e. it is a count of the
1209 number arguments you have in your message -- generally the number of percent
1210 signs (\%)). {\bf level} is the debug level at which you wish the message to
1211 be printed. message is the debug message to be printed, and arg1, ... are the
1212 arguments to be substituted. Since not all compilers support \#defines with
1213 varargs, you must explicitly specify how many arguments you have.
1215 When the debug message is printed, it will automatically be prefixed by the
1216 name of the daemon which is running, the filename where the Dmsg is, and the
1217 line number within the file.
1219 Some actual examples are:
1221 Dmsg2(20, ``MD5len=\%d MD5=\%s\textbackslash{}n'', strlen(buf), buf);
1223 Dmsg1(9, ``Created client \%s record\textbackslash{}n'', client->hdr.name);
1225 \subsection{Error Messages}
1226 \index{Messages!Error}
1227 \index{Error Messages}
1228 \addcontentsline{toc}{subsubsection}{Error Messages}
1230 Error messages are messages that are related to the daemon as a whole rather
1231 than a particular job. For example, an out of memory condition my generate an
1232 error message. They should be very rarely needed. In general, you should be
1233 using Job and Job Queued messages (Jmsg and Qmsg). They are coded as:
1235 EmsgN(error-code, level, message, arg1, ...) As with debug messages, you must
1236 explicitly code the of arguments to be substituted in the message. error-code
1237 indicates the severity or class of error, and it may be one of the following:
1239 \addcontentsline{lot}{table}{Message Error Code Classes}
1240 \begin{longtable}{lp{3in}}
1241 {{\bf M\_ABORT} } & {Causes the daemon to immediately abort. This should be
1242 used only in extreme cases. It attempts to produce a traceback. } \\
1243 {{\bf M\_ERROR\_TERM} } & {Causes the daemon to immediately terminate. This
1244 should be used only in extreme cases. It does not produce a traceback. } \\
1245 {{\bf M\_FATAL} } & {Causes the daemon to terminate the current job, but the
1246 daemon keeps running } \\
1247 {{\bf M\_ERROR} } & {Reports the error. The daemon and the job continue
1249 {{\bf M\_WARNING} } & {Reports an warning message. The daemon and the job
1250 continue running } \\
1251 {{\bf M\_INFO} } & {Reports an informational message.}
1255 There are other error message classes, but they are in a state of being
1256 redesigned or deprecated, so please do not use them. Some actual examples are:
1259 Emsg1(M\_ABORT, 0, ``Cannot create message thread: \%s\textbackslash{}n'',
1262 Emsg3(M\_WARNING, 0, ``Connect to File daemon \%s at \%s:\%d failed. Retrying
1263 ...\textbackslash{}n'', client-\gt{}hdr.name, client-\gt{}address,
1266 Emsg3(M\_FATAL, 0, ``bdird\lt{}filed: bad response from Filed to \%s command:
1267 \%d \%s\textbackslash{}n'', cmd, n, strerror(errno));
1269 \subsection{Job Messages}
1270 \index{Job Messages}
1271 \index{Messages!Job}
1272 \addcontentsline{toc}{subsubsection}{Job Messages}
1274 Job messages are messages that pertain to a particular job such as a file that
1275 could not be saved, or the number of files and bytes that were saved. They
1278 Jmsg(jcr, M\_FATAL, 0, "Text of message");
1280 A Jmsg with M\_FATAL will fail the job. The Jmsg() takes varargs so can
1281 have any number of arguments for substituted in a printf like format.
1282 Output from the Jmsg() will go to the Job report.
1284 If the Jmsg is followed with a number such as Jmsg1(...), the number
1285 indicates the number of arguments to be substituted (varargs is not
1286 standard for \#defines), and what is more important is that the file and
1287 line number will be prefixed to the message. This permits a sort of debug
1290 \subsection{Queued Job Messages}
1291 \index{Queued Job Messages}
1292 \index{Messages!Job}
1293 \addcontentsline{toc}{subsubsection}{Queued Job Messages}
1294 Queued Job messages are similar to Jmsg()s except that the message is
1295 Queued rather than immediately dispatched. This is necessary within the
1296 network subroutines and in the message editing routines. This is to prevent
1297 recursive loops, and to ensure that messages can be delivered even in the
1298 event of a network error.
1301 \subsection{Memory Messages}
1302 \index{Messages!Memory}
1303 \index{Memory Messages}
1304 \addcontentsline{toc}{subsubsection}{Memory Messages}
1306 Memory messages are messages that are edited into a memory buffer. Generally
1307 they are used in low level routines such as the low level device file dev.c in
1308 the Storage daemon or in the low level Catalog routines. These routines do not
1309 generally have access to the Job Control Record and so they return error
1310 essages reformatted in a memory buffer. Mmsg() is the way to do this.
1312 \subsection{Bugs Database}
1313 \index{Database!Bugs}
1314 \index{Bugs Database}
1315 \addcontentsline{toc}{subsubsection}{Bugs Database}
1316 We have a bugs database which is at:
1317 \elink{http://bugs.bacula.org}{http://bugs.bacula.org}, and as
1318 a developer you will need to respond to bugs, perhaps bugs in general
1319 if you have time, otherwise just bugs that correspond to code that
1322 If you need to answer bugs, please be sure to ask the Project Manager
1323 (currently Kern) to give you Developer access to the bugs database. This
1324 allows you to modify statuses and close bugs.
1326 The first thing is if you want to take over a bug, rather than just make a
1327 note, you should assign the bug to yourself. This helps other developers
1328 know that you are the principal person to deal with the bug. You can do so
1329 by going into the bug and clicking on the {\bf Update Issue} button. Then
1330 you simply go to the {\bf Assigned To} box and select your name from the
1331 drop down box. To actually update it you must click on the {\bf Update
1332 Information} button a bit further down on the screen, but if you have other
1333 things to do such as add a Note, you might wait before clicking on the {\bf
1334 Update Information} button.
1336 Generally, we set the {\bf Status} field to either acknowledged, confirmed,
1337 or feedback when we first start working on the bug. Feedback is set when
1338 we expect that the user should give us more information.
1340 Normally, once you are reasonably sure that the bug is fixed, and a patch
1341 is made and attached to the bug report, and/or in the SVN, you can close
1342 the bug. If you want the user to test the patch, then leave the bug open,
1343 otherwise close it and set {\bf Resolution} to {\bf Fixed}. We generally
1344 close bug reports rather quickly, even without confirmation, especially if
1345 we have run tests and can see that for us the problem is fixed. However,
1346 in doing so, it avoids misunderstandings if you leave a note while you are
1347 closing the bug that says something to the following effect:
1348 We are closing this bug because ... If for some reason, it does not fix
1349 your problem, please feel free to reopen it, or to open a new bug report
1350 describing the problem".
1352 We do not recommend that you attempt to edit any of the bug notes that have
1353 been submitted, nor to delete them or make them private. In fact, if
1354 someone accidentally makes a bug note private, you should ask the reason
1355 and if at all possible (with his agreement) make the bug note public.
1357 If the user has not properly filled in most of the important fields
1358 (platorm, OS, Product Version, ...) please do not hesitate to politely ask
1359 him. Also, if the bug report is a request for a new feature, please
1360 politely send the user to the Feature Request menu item on www.bacula.org.
1361 The same applies to a support request (we answer only bugs), you might give
1362 the user a tip, but please politely refer him to the manual and the
1363 Getting Support page of www.bacula.org.