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 diff -u} format relative to the current contents of the Source
43 Forge GIT repository or SVN repository. The diff -u format is the easiest
44 for us to understand and integrate. Please be sure to use the Bacula
45 indenting standard (see below) for source code. If you have checked out
46 the source with GIT or SVN, you can get a diff using.
48 For the bacula, gui, and regress directories:
51 git diff >change.patch
54 For the docs or rescue directories:
57 svn diff > change.patch
60 If you plan on doing significant development work over a period of time,
61 after having your first patch reviewed and approved, you will be eligible
62 for having developer GIT or SVN write access so that you can commit your changes
63 directly to the GIT or SVN repository. To do so, you will need a userid on Source
66 \subsection{Copyrights}
68 \addcontentsline{toc}{subsubsection}{Copyrights}
70 To avoid future problems concerning changing licensing or
71 copyrights, all code contributions more than a hand full of lines
72 must be in the Public Domain or have the copyright transferred to
73 the Free Software Foundation Europe e.V. with a Fiduciary License
74 Agreement (FLA) as the case for all the current code.
76 Prior to November 2004, all the code was copyrighted by Kern Sibbald and
77 John Walker. After November 2004, the code was copyrighted by Kern
78 Sibbald, then on the 15th of November 2006, Kern transferred the copyright
79 to the Free Software Foundation Europe e.V. In signing the FLA and
80 transferring the copyright, you retain the right to use the code you have
81 submitted as you want, and you ensure that Bacula will always remain Free
84 Your name should be clearly indicated as the author of the code, and you
85 must be extremely careful not to violate any copyrights or patents or use
86 other people's code without acknowledging it. The purpose of this
87 requirement is to avoid future copyright, patent, or intellectual property
88 problems. Please read the LICENSE agreement in the main Bacula source code
89 directory. When you sign the Fiduciary License Agreement (FLA) and send it
90 in, you are agreeing to the terms of that LICENSE file.
92 If you don't understand what we mean by future problems, please
93 examine the difficulties Mozilla was having finding
94 previous contributors at \elink{
95 http://www.mozilla.org/MPL/missing.html}
96 {http://www.mozilla.org/MPL/missing.html}. The other important issue is to
97 avoid copyright, patent, or intellectual property violations as was
98 (May 2003) claimed by SCO against IBM.
100 Although the copyright will be held by the Free Software
101 Foundation Europe e.V., each developer is expected to indicate
102 that he wrote and/or modified a particular module (or file) and
103 any other sources. The copyright assignment may seem a bit
104 unusual, but in reality, it is not. Most large projects require
107 If you have any doubts about this, please don't hesitate to ask. The
108 objective is to assure the long term survival of the Bacula project.
110 Items not needing a copyright assignment are: most small changes,
111 enhancements, or bug fixes of 5-10 lines of code, which amount to
112 less than 20% of any particular file.
114 \subsection{Copyright Assignment -- Fiduciary License Agreement}
115 \index{Copyright Assignment}
116 \index{Assignment!Copyright}
117 \addcontentsline{toc}{subsubsection}{Copyright Assignment -- Fiduciary License Agreement}
119 Since this is not a commercial enterprise, and we prefer to believe in
120 everyone's good faith, previously developers could assign the copyright by
121 explicitly acknowledging that they do so in their first submission. This
122 was sufficient if the developer is independent, or an employee of a
123 not-for-profit organization or a university. However, in an effort to
124 ensure that the Bacula code is really clean, beginning in August 2006, all
125 previous and future developers with SVN write access will be asked to submit a
126 copyright assignment (or Fiduciary License Agreement -- FLA),
127 which means you agree to the LICENSE in the main source
128 directory. It also means that you receive back the right to use
129 the code that you have submitted.
131 Any developer who wants to contribute and is employed by a company should
132 either list the employer as the owner of the code, or get explicit
133 permission from him to sign the copyright assignment. This is because in
134 many countries, all work that an employee does whether on company time or
135 in the employee's free time is considered to be Intellectual Property of
136 the company. Obtaining official approval or an FLA from the company will
137 avoid misunderstandings between the employee, the company, and the Bacula
138 project. A good number of companies have already followed this procedure.
140 The Fiduciary License Agreement is posted on the Bacula web site at:
141 \elink{http://www.bacula.org/en/FLA-bacula.en.pdf}{http://www.bacula.org/en/FLA-bacula.en.pdf}
143 The instructions for filling out this agreement are also at:
144 \elink{http://www.bacula.org/?page=fsfe}{http://www.bacula.org/?page=fsfe}
146 It should be filled out, then sent to:
150 Cotes-de-Montmoiret 9
155 Please note that the above address is different from the officially
156 registered office mentioned in the document. When you send in such a
157 complete document, please notify me: kern at sibbald dot com, and
158 please add your email address to the FLA so that I can contact you
159 to confirm reception of the signed FLA.
162 \section{The Development Cycle}
163 \index{Developement Cycle}
164 \index{Cycle!Developement}
165 \addcontentsline{toc}{subsubsection}{Development Cycle}
167 As I noted in previous emails the number of contributions are
168 increasing significantly. We expect this positive trend
169 will continue. As a consequence, we have modified how we do
170 development, and instead of making a list of all the features that we will
171 implement in the next version, each developer signs up for one (maybe
172 two) projects at a time, and when they are complete, and the code
173 is stable, we will release a new version. The release cycle will probably
174 be roughly six months.
176 The difference is that with a shorter release cycle and fewer released
177 feature, we will have more time to review the new code that is being
178 contributed, and will be able to devote more time to a smaller number of
179 projects (some prior versions had too many new features for us to handle
182 Future release schedules will be much the same, and the
183 number of new features will also be much the same providing that the
184 contributions continue to come -- and they show no signs of let up :-)
186 \index{Feature Requests}
187 {\bf Feature Requests:} \\
188 In addition, we have "formalizee" the feature requests a bit.
190 Instead of me maintaining an informal list of everything I run into
191 (kernstodo), we now maintain a "formal" list of projects. This
192 means that all new feature requests, including those recently discussed on
193 the email lists, must be formally submitted and approved.
195 Formal submission of feature requests will take two forms: \\
196 1. non-mandatory, but highly recommended is to discuss proposed new features
197 on the mailing list.\\
198 2. Formal submission of an Feature Request in a special format. We'll
199 give an example of this below, but you can also find it on the web site
200 under "Support -\gt{} Feature Requests". Since it takes a bit of time to
201 properly fill out a Feature Request form, you probably should check on the
204 Once the Feature Request is received by the keeper of the projects list, it
205 will be sent to the Bacula project manager (Kern), and he will either
206 accept it (90% of the time), send it back asking for clarification (10% of
207 the time), send it to the email list asking for opinions, or reject it
210 If it is accepted, it will go in the "projects" file (a simple ASCII file)
211 maintained in the main Bacula source directory.
213 {\bf Implementation of Feature Requests:}\\
214 Any qualified developer can sign up for a project. The project must have
215 an entry in the projects file, and the developer's name will appear in the
218 {\bf How Feature Requests are accepted:}\\
219 Acceptance of Feature Requests depends on several things: \\
220 1. feedback from users. If it is negative, the Feature Request will probably not be
222 2. the difficulty of the project. A project that is so
223 difficult that we cannot imagine finding someone to implement probably won't
224 be accepted. Obviously if you know how to implement it, don't hesitate
225 to put it in your Feature Request \\
226 3. whether or not the Feature Request fits within the current strategy of
227 Bacula (for example an Feature Request that requests changing the tape to
228 tar format probably would not be accepted, ...).
230 {\bf How Feature Requests are prioritized:}\\
231 Once an Feature Request is accepted, it needs to be implemented. If you
232 can find a developer for it, or one signs up for implementing it, then the
233 Feature Request becomes top priority (at least for that developer).
235 Between releases of Bacula, we will generally solicit Feature Request input
236 for the next version, and by way of this email, we suggest that you send
237 discuss and send in your Feature Requests for the next release. Please
238 verify that the Feature Request is not in the current list (attached to this email).
240 Once users have had several weeks to submit Feature Requests, the keeper of
241 the projects list will organize them, and request users to vote on them.
242 This will allow fixing prioritizing the Feature Requests. Having a
243 priority is one thing, but getting it implement is another thing -- we are
244 hoping that the Bacula community will take more responsibility for assuring
245 the implementation of accepted Feature Requests.
247 Feature Request format:
249 ============= Empty Feature Request form ===========
250 Item n: One line summary ...
252 Origin: Name and email of originator.
255 What: More detailed explanation ...
257 Why: Why it is important ...
259 Notes: Additional notes or features (omit if not used)
260 ============== End Feature Request form ==============
264 ============= Example Completed Feature Request form ===========
265 Item 1: Implement a Migration job type that will move the job
266 data from one device to another.
267 Origin: Sponsored by Riege Sofware International GmbH. Contact:
268 Daniel Holtkamp <holtkamp at riege dot com>
269 Date: 28 October 2005
270 Status: Partially coded in 1.37 -- much more to do. Assigned to
273 What: The ability to copy, move, or archive data that is on a
274 device to another device is very important.
276 Why: An ISP might want to backup to disk, but after 30 days
277 migrate the data to tape backup and delete it from
278 disk. Bacula should be able to handle this
279 automatically. It needs to know what was put where,
280 and when, and what to migrate -- it is a bit like
281 retention periods. Doing so would allow space to be
282 freed up for current backups while maintaining older
285 Notes: Migration could be triggered by:
289 Highwater size (keep total size)
291 =================================================
295 \section{Bacula Code Submissions and Projects}
296 \index{Submissions and Projects}
297 \addcontentsline{toc}{subsection}{Code Submissions and Projects}
299 Getting code implemented in Bacula works roughly as follows:
303 \item Kern is the project manager, but prefers not to be a "gate keeper".
304 This means that the developers are expected to be self-motivated,
305 and once they have experience submit directly to the GIT or SVN
306 repositories. However,
307 it is a good idea to have your patches reviewed prior to submitting,
308 and it is a bad idea to submit monster patches because no one will
309 be able to properly review them. See below for more details on this.
311 \item There are growing numbers of contributions (very good).
313 \item Some contributions come in the form of relatively small patches,
314 which Kern reviews, integrates, documents, tests, and maintains.
316 \item All Bacula developers take full
317 responsibility for writing the code, posting as patches so that we can
318 review it as time permits, integrating it at an appropriate time,
319 responding to our requests for tweaking it (name changes, ...),
320 document it in the code, document it in the manual (even though
321 their mother tongue is not English), test it, develop and commit
322 regression scripts, and answer in a timely fashion all bug reports --
323 even occasionally accepting additional bugs :-)
325 This is a sustainable way of going forward with Bacula, and the
326 direction that the project will be taking more and more. For
327 example, in the past, we have had some very dedicated programmers
328 who did major projects. However, some of these
329 programmers due to outside obligations (job responsibilities change of
330 job, school duties, ...) could not continue to maintain the code. In
331 those cases, the code suffers from lack of maintenance, sometimes we
332 patch it, sometimes not. In the end, if the code is not maintained, the
333 code gets dropped from the project (there are two such contributions
334 that are heading in that direction). When ever possible, we would like
335 to avoid this, and ensure a continuation of the code and a sharing of
336 the development, debugging, documentation, and maintenance
340 \section{Patches for Released Versions}
341 \index{Patches for Released Versions}
342 \addcontentsline{toc}{subsection}{Patches for Released Versions}
343 If you fix a bug in a released version, you should, unless it is
344 an absolutely trivial bug, create and release a patch file for the
345 bug. The procedure is as follows:
347 Fix the bug in the branch and in the trunk.
349 Make a patch file for the branch and add the branch patch to
350 the patches directory in both the branch and the trunk.
351 The name should be 2.2.4-xxx.patch where xxx is unique, in this case it can
352 be "restore", e.g. 2.2.4-restore.patch. Add to the top of the
353 file a brief description and instructions for applying it -- see for example
354 2.2.4-poll-mount.patch. The best way to create the patch file is as
358 (edit) 2.2.4-restore.patch
362 git diff >>2.2.4-restore.patch
365 check to make sure no extra junk got put into the patch file (i.e.
366 it should have the patch for that bug only).
368 If there is not a bug report on the problem, create one, then add the
369 patch to the bug report.
371 Then upload it to the 2.2.x release of bacula-patches.
373 So, end the end, the patch file is:
375 \item Attached to the bug report
377 \item In Branch-2.2/bacula/patches/...
381 \item Loaded on Source Forge bacula-patches 2.2.x release. When
382 you add it, click on the check box to send an Email so that all the
383 users that are monitoring SF patches get notified.
387 \section{Bacula GIT and SVN repositories}
389 \addcontentsline{toc}{subsection}{GIT and SVN repositories}
390 As of August 2009, the Bacula source code has been split into
391 two repositories. One is a GIT repository that holds the
392 main Bacula source code with directories {\bf bacula}, {\bf gui},
393 and {\bf regress}. The second repository (SVN) contains
394 the directories {\bf rescue} and {\bf docs}. Both repositories are
395 hosted on Source Forge.
397 Previously everything was in a single SVN repository.
398 We have split the SVN repository into two because GIT
399 offers significant advantages for ease of managing and integrating
400 developer's changes. However, one of the disadvantages of GIT is that you
401 must work with the full repository, while SVN allows you to checkout
402 individual directories. If we put everything into a single GIT
403 repository it would be far bigger than most developers would want
404 to checkout, so we have left the docs and rescue in the old SVN
405 repository, and moved only the parts that are most actively
406 worked on by the developers (bacula, gui, and regress) to a GIT
409 Unfortunately, Bacula developers must now have a certain knowledege
410 of both GIT and SVN, and if you are a core Bacula developer knowledge of
411 GIT is particularly important.
415 \addcontentsline{toc}{subsection}{GIT Usage}
417 Please note that if you are familiar with SVN, GIT is similar,
418 (and better), but there can be a few surprising differences that
419 can lead to damaging the history of the repository (repo) if
420 you attempt to force pushing data into the GIT repo.
422 The Bacula GIT repo contains the subdirectories {\bf bacula}, {\bf gui},
423 and {\bf regress}. With GIT it is not possible to pull only a
424 single directory, because of the hash code nature of git, you
425 must take all or nothing.
427 For developers, the most important thing to remember about GIT and
428 the Source Forge repository is not to "force" a {\bf push} to the
429 repository, and not to use the {\bf rebase} command on the {\bf
430 master} branch of the repository. Doing so, will possibly rewrite
431 the GIT repository history and cause a lot of problems for the
434 You may and should use {\bf rebase} on your own branches that you
435 want to synchronize with the {\bf master} branch, but please
436 do not use {\bf rebase} on the {\bf master} branch. The proper
437 way of merging changes will be discussed below.
439 You can get a full copy of the Source Forge Bacula GIT repository with the
443 git clone git://bacula.git.sourceforge.net/gitroot/bacula/bacula trunk
446 This will put a read-only copy into the directory {\bf trunk}
447 in your current directory, and {\bf trunk} will contain
448 the subdirectories: {\bf bacula}, {\bf gui}, and {\bf regress}.
450 If you have write permission, you can get a copy of the GIT
454 git clone ssh://<userid>@bacula.git.sourceforge.net/gitroot/bacula/bacula trunk
457 where you replace \verb+<userid>+ with your Source Forge login
458 userid, and you must have previously uploaded your public ssh key
461 The above command needs to be done only once. Thereafter, you can:
468 As of August 2009, the size of the repository ({\bf trunk} in the above
469 example) will be approximately 55 Megabytes. However, if you build
470 from source in this directory and do a lot of updates and regression
471 testing, the directory could become several hundred megabytes.
473 \subsection{Learning GIT}
475 If you want to learn more about GIT, we recommend that you visit:\\
476 \elink{http://book.git-scm.com/}{http://book.git-scm.com/}.
478 Some of the differences between GIT and SVN are:
480 \item Your main git directory is a full git repository to which you can
482 \item The git database is kept in the directory {\bf .git} at the
483 top level of the directory.
484 \item all the important git configuration information is kept in the
485 file {\bf .git/config} in ASCII format that is easy to manually edit.
486 \item When you do a {\bf commit} the changes are put in {\bf .git}
487 rather than in the external repository.
488 \item You can upload your changes to the external repository using
489 the command {\bf git push}.
490 \item You can download all the current changes in the external repository
491 and merge them into your {\bf master} branch using the command
493 \item The command {\bf git add} is used to add a new file to the
494 repository AND to tell git that you want a file that has changed
495 to be in the next commit. This has lots of advantages, because
496 a {\bf git commit} only commits those files that have been
498 \item You can add and commit all files modifed in one command
499 using {\bf git commit -a}.
500 \item This extra use of {\bf add} allows you to make a number
501 of changes then add only a few of the files and commit them,
502 then add more files and commit them until you have committed
503 everything. This has the advantage of allowing you to more
504 easily group small changes and commit them.
505 \item If you {\bf git pull} from the main repository and make
506 some changes, and before you do a {\bf git push}, someone
507 else pushes changes to the git repository, you will probably
508 get an error message such as:
512 To git@github.com:bacula/bacula.git
513 ! [rejected] master -> master (non-fast forward)
514 error: failed to push some refs to 'git@github.com:bacula/bacula.git'
517 which is git's way of telling you that the main repository has changed
518 and that if you push your changes, they will not be integrated properly.
519 As we have noted, you should never ask git to force the push.
520 See below for an explanation of why.
521 \item To integrate (merge) your changes properly, you should always do
522 a {\bf git pull} just prior to doing a {\bf git push}.
523 \item If git is unable to merge your changes or finds a conflict it
524 will tell you and you must do conflict resolution, which is much
525 easier in git than in SVN.
526 \item Resolving conflicts is described below in the {\bf github} section.
529 If you want to understand why it is not a good idea to force a
530 push to the repository, look at the following picture:
532 \includegraphics[width=0.85\textwidth]{\idir git-edit-commit.eps}
534 The above graphic has three lines of circles. Each circle represents
535 a commit, and time runs from the left to the right. The top line
536 shows the repository just before you are going to do a push. Note the
537 point at which you pulled is the circle on the left, your changes are
538 represented by the circle labeled {\bf Your mods}. It is shown below
539 to indicate that the changes are only in your local repository. Finally,
540 there are pushes A and B that came after the time at which you pulled.
542 If you were to force your changes into the repository, Git would place them
543 immediately after the point at which you pulled them, so they would
544 go before the pushes A and B. However, doing so would rewrite the history
545 of the repository and make it very difficult for other users to synchronize
546 since they would have to somehow wedge their changes at some point before the
547 current HEAD of the repository. This situation is shown by the second line of
550 What you really want to do is to put your changes after Push B (the current HEAD).
551 This is shown in the third line of pushes. The best way to accomplish this is to
552 work in a branch, pull the repository so you have your master equal to HEAD (in first
553 line), then to rebase your branch on the current master and then commit it. The
554 exact commands to accomplish this are shown in the next couple of sections.
556 \subsection{Publishing your changes}
558 Since GIT is more complex than SVN, it takes a bit of time to learn how
559 to use it properly, and if you are not careful, you can potentially create
560 a new history in the repository. In addition, since GIT is a distributed
561 version control system, we prefer to receive a full branch submission rather
562 than simply a patch. To accomplish this, you must create your changes in
563 a branch, then {\bf push} them to some public repository -- it can be your
564 own repository that you publish or another. To simplify this phase for you, we
565 have created a publich Bacula GIT repository on {\bf github} where you can
566 push your branch containing changes you would like integrated into the Bacula
569 Once you have pushed your branch to {\bf github} or told us where we can pull
570 from your public repository, one of the senior Bacula devlopers will fetch your
571 changes, examine them, possibly make comments for changes they would like to
572 see, and as the final step, the senior developer will commit it to the
573 Bacula Source Forge GIT repository.
577 If you are going to submit code, you create a login on
578 the Github website:\\
579 \elink{http://github.com/}{http://github.com/}\\
580 before you clone the repository.
581 You must also upload your public ssh key. Please see the instructions for
582 doing so at the above link. Then you notify one of the senior Bacula developers,
583 who will authorize your Github user name as a committer to the Bacula repository. Finally,
584 you clone the Bacula repository with:
587 git clone git@github.com:bacula/bacula.git <xxx>
590 where you replace \verb+<xxx>+ with the name
591 of a directory that you want git to create to hold your local Bacula git
594 Normally, you will work by creating a branch of the master branch of your
595 repository, make your modifications, then make sure it is up to date, and finally
596 push it to Github. Assuming you call the Bacula repository {\bf bacula}, you might
597 use the following commands:
603 git branch <your-name>/newbranch
604 git checkout <your-name>/newbranch
606 git add <file-edited>
607 git commit -m "<comment about commit>"
611 Note, we request you to create the branch name ({\bf \verb+<your-name>+/newbranch} with your github
612 login name. This guarantees that the branch name will be unique and
613 easily identified as well.
615 When you have completed working on your branch, you will do:
619 git checkout <your-name>/newbranch
624 If you have completed your edits before anyone has modified the repository,
625 the {\bf git rebase master} will report that there was nothing to do. Otherwise,
626 it will merge the changes that were made in the repository before your changes.
627 If there are any conflicts, git will tell you. Typically resolving conflicts with
628 git is relatively easy. You simply make a diff:
634 Then edit each file that was listed in the {\bf git diff} to remove the
635 conflict, which will be indicated by lines of:
645 where {\bf text} is what is in the Bacula repository, and {\bf other text}
646 is what you have changed.
648 Once you have eliminated the conflict, the {\bf git diff} will show nothing,
652 git add <file-with-conflicts-fixed>
655 Once you have fixed all the files with conflicts in the above manner, you enter:
658 git rebase --continue
661 and your rebase will be complete.
663 If for some reason, before doing the --continue, you want to abort the rebase and return to what you had, you enter:
669 Finally to upload your branch, you do:
672 git push origin <your-name>/newbranch
675 If you wish to delete it later, you can use:
678 git push origin :<your-name>/newbranch
685 \addcontentsline{toc}{subsection}{SVN Usage}
687 Note: this section is somewhat out of date, since the SVN now
688 contains only the docs and rescue subdirectories. The bacula,
689 gui, and regress directories are now maintained in a GIT
692 Please note that if you are familiar with CVS, SVN is very
693 similar (and better), but there can be a few surprising
696 The Bacula SourceForge.net Subversion repository that contains
697 the documentation and the rescue scripts checked out through SVN with the
701 svn checkout https://bacula.svn.sourceforge.net/svnroot/bacula bacula
704 With the above command, you will get everything, which is a very large
726 Note, you should NEVER commit code to any checkout that you have
727 done of a tag. All tags (e.g. Release-1.1, ... Release-2.0.2)
728 should be considered read-only.
730 You may commit code to the most recent item in
731 branches (in the above the most recent one is Branch-2.0). If
732 you want to commit code to an older branch, then please contact
735 You may create your own tags and/or branches, but they should
736 have a name clearly distinctive from Branch-, Release-, or Beta-,
737 which are official names used by the project. If you create a
738 tag, then you should NEVER commit code to it, for the same
739 reason noted above -- it should serve as a marker for something
740 you released. If you create a branch, then you are free to
741 commit to it as you wish.
743 You may, of course, commit to the trunk.
755 are reserved names to be created only by the project manager (or
756 with his OK), where the nnn is any sequence of numbers and
757 periods (e.g. 2.0, 2.0.1, ...).
759 In addition all tags even those that you create are read-only
760 forever. Typically tags represent release points either in the
761 trunk or in a branch.
764 Coming back to getting source code.
765 If you only want the current Bacula source code, you should see
766 the above section that describes the GIT repository.
768 To view what is in the SVN, point your browser at the following URL:
769 http://bacula.svn.sourceforge.net/viewvc/bacula/
771 Many of the Subversion (svn) commands are almost identical to those that
772 you have used for cvs, but some (such as a checkout) can have surprising
773 results, so you should take a careful look at the documentation.
775 The following documentation on the new
776 svn repository will help you know how to use it:
778 Here is the list of branches:
795 Release-1.1 Release-1.19 Release-1.19a Release-1.19b
796 Release-1.20 Release-1.21 Release-1.22 Release-1.23
797 Release-1.23a Release-1.24 Release-1.25 Release-1.25a
798 Release-1.26 Release-1.27 Release-1.27a Release-1.27b
799 Release-1.27c Release-1.28 Release-1.29 Release-1.30
800 Release-1.31 Release-1.31a Release-1.32 Release-1.32a
801 Release-1.32b Release-1.32c Release-1.32d Release-1.32e
802 Release-1.32f Release-1.32f-2 Release-1.32f-3 Release-1.32f-4
803 Release-1.32f-5 Release-1.34.0 Release-1.34.1 Release-1.34.3
804 Release-1.34.4 Release-1.34.5 Release-1.34.6 Release-1.35.1
805 Release-1.35.2 Release-1.35.3 Release-1.35.6 Release-1.35.7
806 Release-1.35.8 Release-1.36.0 Release-1.36.1 Release-1.36.2
807 Release-1.36.3 Release-1.38.0 Release-1.38.1 Release-1.38.10
808 Release-1.38.11 Release-1.38.2 Release-1.38.3 Release-1.38.4
809 Release-1.38.5 Release-1.38.6 Release-1.38.7 Release-1.38.8
810 Release-1.38.9 Release-1.8.1 Release-1.8.2 Release-1.8.3
811 Release-1.8.4 Release-1.8.5 Release-1.8.6 Release-2.0.0
812 Release-2.0.1 Release-2.0.2
815 Here is a list of commands to get you started. The recommended book is
816 "Version Control with Subversion", by Ben Collins-Sussmann,
817 Brian W. Fitzpatrick, and Michael Pilato, O'Reilly. The book is
818 Open Source, so it is also available on line at:
821 http://svnbook.red-bean.com
824 Get a list of commands
830 Get a help with a command
836 Checkout the HEAD revision of all modules from the project into the
840 svn co https://bacula.svn.sourceforge.net/svnroot/bacula/trunk bacula.new
843 Checkout the HEAD revision of the bacula module into the bacula subdirectory
846 svn checkout https://bacula.svn.sourceforge.net/svnroot/bacula/trunk/bacula
849 See which files have changed in the working copy
855 See which files are out of date
861 Add a new file file.c
867 Create a new directory
873 Delete an obsolete file
882 svn move file.c newfile.c
885 Move a file to a new location
888 svn move file.c ../newdir/file.c
891 Copy a file retaining the original history in the new file
894 svn copy file.c newfile.c
897 Update the working copy with the outstanding changes
903 Compare working copy with the repository
909 Commit the changes in the local working copy
915 Specify which files are ignored in the current directory
918 svn propedit svn:ignore .
921 Mark a file to be executable
924 svn propset svn:executable '*' prog.sh
927 Unmark a file as executable
930 svn propdel svn:executable prog.sh
933 List a file's properties
939 Create a branch for a new version
942 svn copy https://bacula.svn.sourceforge.net/svnroot/bacula/trunk \
943 https://bacula.svn.sourceforge.net/svnroot/bacula/branches/Branch-2.1
946 Tag a version for a new release
949 svn copy https://bacula.svn.sourceforge.net/svnroot/bacula/branches/Branch-2.1 \
950 https://bacula.svn.sourceforge.net/svnroot/bacula/branches/Release-2.1
954 Let's say you are working in the directory scripts. You would then do:
961 when you are happy with your changes, you can do the following:
964 cd bacula (to your top level directory)
965 svn diff my-changes.patch
968 When the command is done, you can look in the file my-changes.patch
969 and you will see all the changes you have made to your copy of the
970 repository. Make sure that you understand all the changes that
971 it reports before proceeding. If you modified files that you do
972 do not want to commit to the main repository, you can simply delete
973 them from your local directory, and they will be restored from the
974 repository with the "svn update" that is shown below. Normally, you
975 should not find changes to files that you do not want to commit, and
976 if you find yourself in that position a lot, you are probably doing
979 Let's assume that now you want to commit your changes to the main
989 When you do this, it will pull any changes made by other developers into
990 your local copy of the repository, and it will check for conflicts. If there
991 are any, it will tell you, and you will need to resolve them. The problems
992 of resolving conflicts are a bit more than this document can cover, but
993 you can examine the files it claims have conflicts and look for \lt{}\lt{}\lt{}\lt{}
994 or look in the .rej files that it creates. If you have problems, just ask
995 on the developer's list.
997 Note, doing the above "svn update" is not absolutely necessary. There are
998 times when you may be working on code and you want to commit it, but you
999 explicitly do not want to move up to the latest version of the code in
1000 the SVN. If that is the case, you can simply skip the "svn update" and
1001 do the commit shown below. If the commit fails because of a conflict, it
1002 will tell you, and you must resolve the conflict before it will permit
1003 you to do the commit.
1005 Once your local copy of the repository has been updated, you can now
1006 commit your changes:
1009 svn commit -m "Some comment about what you changed"
1012 or if you really only want to commit a single file, you can
1016 svn commit -m "comment" scripts/file-I-edited
1019 Note, if you have done a build in your directory, or you have added
1020 other new files, the commit will update only the files that are
1021 actually in the repository. For example, none of the object files
1022 are stored in the repository, so when you do a commit, those object
1023 files will simply be ignored.
1025 If you want to add new files or remove files from the main SVN
1026 repository, and you are not experienced with SVN, please ask Kern
1027 to do it. If you follow the simple steps above, it is unlikely that
1028 you will do any damage to the repository, and if you do, it is always
1029 possible for us to recover, but it can be painful.
1031 If you are only working in one subdirectory of say the bacula project,
1032 for example, the scripts directory, you can do your commit from
1033 that subdirectory, and only the changes in that directory and all its
1034 subdirectories will be committed. This can be helpful for translators.
1035 If you are doing a French translation, you will be working in
1036 docs/manual-fr, and if you are always cd'ed into that directory when
1037 doing your commits, your commit will effect only that directory. As
1038 long as you are careful only to change files that you want changed,
1039 you have little to worry about.
1041 \section{Subversion Resources}
1042 \index{Subversion (svn) Resources}
1043 \addcontentsline{toc}{subsection}{Subversion Resources}
1045 Main Subversion Web Page
1046 \elink{http://subversion.tigris.org}{http://subversion.tigris.org}
1049 \elink{http://svnbook.red-bean.com}{http://svnbook.red-bean.com}
1052 \elink{http://subversion.tigris.org/project\_packages.html}{http://subversion.tigris.org/project\_packages.html}
1054 (For Windows users the TortoiseSVN package is awesome)
1056 GUI UNIX client link
1057 \elink{http://rapidsvn.tigris.org/}{http://rapidsvn.tigris.org/}
1059 A nice KDE GUI client:
1064 \section{Developing Bacula}
1065 \index{Developing Bacula}
1066 \index{Bacula!Developing}
1067 \addcontentsline{toc}{subsubsection}{Developing Bacula}
1069 Typically the simplest way to develop Bacula is to open one xterm window
1070 pointing to the source directory you wish to update; a second xterm window at
1071 the top source directory level, and a third xterm window at the bacula
1072 directory \lt{}top\gt{}/src/bacula. After making source changes in one of the
1073 directories, in the top source directory xterm, build the source, and start
1074 the daemons by entering:
1078 ./startit then in the enter:
1082 ./gnome-console to start the Console program. Enter any commands for testing.
1083 For example: run kernsverify full.
1085 Note, the instructions here to use {\bf ./startit} are different from using a
1086 production system where the administrator starts Bacula by entering {\bf
1087 ./bacula start}. This difference allows a development version of {\bf Bacula}
1088 to be run on a computer at the same time that a production system is running.
1089 The {\bf ./startit} strip starts {\bf Bacula} using a different set of
1090 configuration files, and thus permits avoiding conflicts with any production
1093 To make additional source changes, exit from the Console program, and in the
1094 top source directory, stop the daemons by entering:
1096 ./stopit then repeat the process.
1098 \subsection{Debugging}
1100 \addcontentsline{toc}{subsubsection}{Debugging}
1102 Probably the first thing to do is to turn on debug output.
1104 A good place to start is with a debug level of 20 as in {\bf ./startit -d20}.
1105 The startit command starts all the daemons with the same debug level.
1106 Alternatively, you can start the appropriate daemon with the debug level you
1107 want. If you really need more info, a debug level of 60 is not bad, and for
1108 just about everything a level of 200.
1110 \subsection{Using a Debugger}
1111 \index{Using a Debugger}
1112 \index{Debugger!Using a}
1113 \addcontentsline{toc}{subsubsection}{Using a Debugger}
1115 If you have a serious problem such as a segmentation fault, it can usually be
1116 found quickly using a good multiple thread debugger such as {\bf gdb}. For
1117 example, suppose you get a segmentation violation in {\bf bacula-dir}. You
1118 might use the following to find the problem:
1120 \lt{}start the Storage and File daemons\gt{}
1123 run -f -s -c ./dird.conf
1124 \lt{}it dies with a segmentation fault\gt{}
1126 The {\bf -f} option is specified on the {\bf run} command to inhibit {\bf
1127 dird} from going into the background. You may also want to add the {\bf -s}
1128 option to the run command to disable signals which can potentially interfere
1131 As an alternative to using the debugger, each {\bf Bacula} daemon has a built
1132 in back trace feature when a serious error is encountered. It calls the
1133 debugger on itself, produces a back trace, and emails the report to the
1134 developer. For more details on this, please see the chapter in the main Bacula
1135 manual entitled ``What To Do When Bacula Crashes (Kaboom)''.
1137 \subsection{Memory Leaks}
1138 \index{Leaks!Memory}
1139 \index{Memory Leaks}
1140 \addcontentsline{toc}{subsubsection}{Memory Leaks}
1142 Because Bacula runs routinely and unattended on client and server machines, it
1143 may run for a long time. As a consequence, from the very beginning, Bacula
1144 uses SmartAlloc to ensure that there are no memory leaks. To make detection of
1145 memory leaks effective, all Bacula code that dynamically allocates memory MUST
1146 have a way to release it. In general when the memory is no longer needed, it
1147 should be immediately released, but in some cases, the memory will be held
1148 during the entire time that Bacula is executing. In that case, there MUST be a
1149 routine that can be called at termination time that releases the memory. In
1150 this way, we will be able to detect memory leaks. Be sure to immediately
1151 correct any and all memory leaks that are printed at the termination of the
1154 \subsection{Special Files}
1155 \index{Files!Special}
1156 \index{Special Files}
1157 \addcontentsline{toc}{subsubsection}{Special Files}
1159 Kern uses files named 1, 2, ... 9 with any extension as scratch files. Thus
1160 any files with these names are subject to being rudely deleted at any time.
1162 \subsection{When Implementing Incomplete Code}
1163 \index{Code!When Implementing Incomplete}
1164 \index{When Implementing Incomplete Code}
1165 \addcontentsline{toc}{subsubsection}{When Implementing Incomplete Code}
1167 Please identify all incomplete code with a comment that contains
1173 where there are three asterisks (*) before and after the word
1174 FIXME (in capitals) and no intervening spaces. This is important as it allows
1175 new programmers to easily recognize where things are partially implemented.
1177 \subsection{Bacula Source File Structure}
1178 \index{Structure!Bacula Source File}
1179 \index{Bacula Source File Structure}
1180 \addcontentsline{toc}{subsubsection}{Bacula Source File Structure}
1182 The distribution generally comes as a tar file of the form {\bf
1183 bacula.x.y.z.tar.gz} where x, y, and z are the version, release, and update
1184 numbers respectively.
1186 Once you detar this file, you will have a directory structure as follows:
1193 |- mtx (autochanger control program + tape drive info)
1194 |- sqlite (SQLite database program)
1198 |- pthreads (Native win32 pthreads library -- dll)
1199 |- zlib (Native win32 zlib library)
1200 |- wx (wxWidgets source code)
1203 |- bacula (main source directory containing configuration
1204 | and installation files)
1205 |- autoconf (automatic configuration files, not normally used
1207 |- intl (programs used to translate)
1208 |- platforms (OS specific installation files)
1209 |- redhat (Red Hat installation)
1210 |- solaris (Sun installation)
1211 |- freebsd (FreeBSD installation)
1212 |- irix (Irix installation -- not tested)
1213 |- unknown (Default if system not identified)
1214 |- po (translations of source strings)
1215 |- src (source directory; contains global header files)
1216 |- cats (SQL catalog database interface directory)
1217 |- console (bacula user agent directory)
1218 |- dird (Director daemon)
1219 |- filed (Unix File daemon)
1220 |- win32 (Win32 files to make bacula-fd be a service)
1221 |- findlib (Unix file find library for File daemon)
1222 |- gnome-console (GNOME version of console program)
1223 |- lib (General Bacula library)
1224 |- stored (Storage daemon)
1225 |- tconsole (Tcl/tk console program -- not yet working)
1226 |- testprogs (test programs -- normally only in Kern's tree)
1227 |- tools (Various tool programs)
1228 |- win32 (Native Win32 File daemon)
1229 |- baculafd (Visual Studio project file)
1230 |- compat (compatibility interface library)
1231 |- filed (links to src/filed)
1232 |- findlib (links to src/findlib)
1233 |- lib (links to src/lib)
1234 |- console (beginning of native console program)
1235 |- wx-console (wxWidget console Win32 specific parts)
1236 |- wx-console (wxWidgets console main source program)
1239 |- regress (Regression scripts)
1240 |- bin (temporary directory to hold Bacula installed binaries)
1241 |- build (temporary directory to hold Bacula source)
1242 |- scripts (scripts and .conf files)
1243 |- tests (test scripts)
1244 |- tmp (temporary directory for temp files)
1245 |- working (temporary working directory for Bacula daemons)
1248 |- docs (documentation directory)
1249 |- developers (Developer's guide)
1250 |- home-page (Bacula's home page source)
1251 |- manual (html document directory)
1252 |- manual-fr (French translation)
1253 |- manual-de (German translation)
1254 |- techlogs (Technical development notes);
1257 |- rescue (Bacula rescue CDROM)
1258 |- linux (Linux rescue CDROM)
1259 |- cdrom (Linux rescue CDROM code)
1261 |- solaris (Solaris rescue -- incomplete)
1262 |- freebsd (FreeBSD rescue -- incomplete)
1265 |- gui (Bacula GUI projects)
1266 |- bacula-web (Bacula web php management code)
1267 |- bimagemgr (Web application for burning CDROMs)
1273 \subsection{Header Files}
1274 \index{Header Files}
1275 \index{Files!Header}
1276 \addcontentsline{toc}{subsubsection}{Header Files}
1278 Please carefully follow the scheme defined below as it permits in general only
1279 two header file includes per C file, and thus vastly simplifies programming.
1280 With a large complex project like Bacula, it isn't always easy to ensure that
1281 the right headers are invoked in the right order (there are a few kludges to
1282 make this happen -- i.e. in a few include files because of the chicken and egg
1283 problem, certain references to typedefs had to be replaced with {\bf void} ).
1285 Every file should include {\bf bacula.h}. It pulls in just about everything,
1286 with very few exceptions. If you have system dependent ifdefing, please do it
1287 in {\bf baconfig.h}. The version number and date are kept in {\bf version.h}.
1289 Each of the subdirectories (console, cats, dird, filed, findlib, lib, stored,
1290 ...) contains a single directory dependent include file generally the name of
1291 the directory, which should be included just after the include of {\bf
1292 bacula.h}. This file (for example, for the dird directory, it is {\bf dird.h})
1293 contains either definitions of things generally needed in this directory, or
1294 it includes the appropriate header files. It always includes {\bf protos.h}.
1297 Each subdirectory contains a header file named {\bf protos.h}, which contains
1298 the prototypes for subroutines exported by files in that directory. {\bf
1299 protos.h} is always included by the main directory dependent include file.
1301 \subsection{Programming Standards}
1302 \index{Standards!Programming}
1303 \index{Programming Standards}
1304 \addcontentsline{toc}{subsubsection}{Programming Standards}
1306 For the most part, all code should be written in C unless there is a burning
1307 reason to use C++, and then only the simplest C++ constructs will be used.
1308 Note, Bacula is slowly evolving to use more and more C++.
1310 Code should have some documentation -- not a lot, but enough so that I can
1311 understand it. Look at the current code, and you will see that I document more
1312 than most, but am definitely not a fanatic.
1314 We prefer simple linear code where possible. Gotos are strongly discouraged
1315 except for handling an error to either bail out or to retry some code, and
1316 such use of gotos can vastly simplify the program.
1318 Remember this is a C program that is migrating to a {\bf tiny} subset of C++,
1319 so be conservative in your use of C++ features.
1321 \subsection{Do Not Use}
1324 \addcontentsline{toc}{subsubsection}{Do Not Use}
1327 \item STL -- it is totally incomprehensible.
1330 \subsection{Avoid if Possible}
1331 \index{Possible!Avoid if}
1332 \index{Avoid if Possible}
1333 \addcontentsline{toc}{subsubsection}{Avoid if Possible}
1336 \item Using {\bf void *} because this generally means that one must
1337 using casting, and in C++ casting is rather ugly. It is OK to use
1338 void * to pass structure address where the structure is not known
1339 to the routines accepting the packet (typically callback routines).
1340 However, declaring "void *buf" is a bad idea. Please use the
1341 correct types whenever possible.
1343 \item Using undefined storage specifications such as (short, int, long,
1344 long long, size\_t ...). The problem with all these is that the number of bytes
1345 they allocate depends on the compiler and the system. Instead use
1346 Bacula's types (int8\_t, uint8\_t, int32\_t, uint32\_t, int64\_t, and
1347 uint64\_t). This guarantees that the variables are given exactly the
1348 size you want. Please try at all possible to avoid using size\_t ssize\_t
1349 and the such. They are very system dependent. However, some system
1350 routines may need them, so their use is often unavoidable.
1352 \item Returning a malloc'ed buffer from a subroutine -- someone will forget
1355 \item Heap allocation (malloc) unless needed -- it is expensive. Use
1358 \item Templates -- they can create portability problems.
1360 \item Fancy or tricky C or C++ code, unless you give a good explanation of
1363 \item Too much inheritance -- it can complicate the code, and make reading it
1364 difficult (unless you are in love with colons)
1368 \subsection{Do Use Whenever Possible}
1369 \index{Possible!Do Use Whenever}
1370 \index{Do Use Whenever Possible}
1371 \addcontentsline{toc}{subsubsection}{Do Use Whenever Possible}
1374 \item Locking and unlocking within a single subroutine.
1376 \item A single point of exit from all subroutines. A goto is
1377 perfectly OK to use to get out early, but only to a label
1378 named bail\_out, and possibly an ok\_out. See current code
1381 \item Malloc and free within a single subroutine.
1383 \item Comments and global explanations on what your code or algorithm does.
1387 \subsection{Indenting Standards}
1388 \index{Standards!Indenting}
1389 \index{Indenting Standards}
1390 \addcontentsline{toc}{subsubsection}{Indenting Standards}
1392 We find it very hard to read code indented 8 columns at a time.
1393 Even 4 at a time uses a lot of space, so we have adopted indenting
1394 3 spaces at every level. Note, indention is the visual appearance of the
1395 source on the page, while tabbing is replacing a series of up to 8 spaces from
1398 The closest set of parameters for the Linux {\bf indent} program that will
1399 produce reasonably indented code are:
1403 -nbad -bap -bbo -nbc -br -brs -c36 -cd36 -ncdb -ce -ci3 -cli0
1404 -cp36 -d0 -di1 -ndj -nfc1 -nfca -hnl -i3 -ip0 -l85 -lp -npcs
1405 -nprs -npsl -saf -sai -saw -nsob -nss -nbc -ncs -nbfda
1409 You can put the above in your .indent.pro file, and then just invoke indent on
1410 your file. However, be warned. This does not produce perfect indenting, and it
1411 will mess up C++ class statements pretty badly.
1413 Braces are required in all if statements (missing in some very old code). To
1414 avoid generating too many lines, the first brace appears on the first line
1415 (e.g. of an if), and the closing brace is on a line by itself. E.g.
1425 Just follow the convention in the code. For example we I prefer non-indented cases.
1442 Avoid using // style comments except for temporary code or turning off debug
1443 code. Standard C comments are preferred (this also keeps the code closer to
1446 Attempt to keep all lines less than 85 characters long so that the whole line
1447 of code is readable at one time. This is not a rigid requirement.
1449 Always put a brief description at the top of any new file created describing
1450 what it does and including your name and the date it was first written. Please
1451 don't forget any Copyrights and acknowledgments if it isn't 100\% your code.
1452 Also, include the Bacula copyright notice that is in {\bf src/c}.
1454 In general you should have two includes at the top of the an include for the
1455 particular directory the code is in, for includes are needed, but this should
1458 In general (except for self-contained packages), prototypes should all be put
1459 in {\bf protos.h} in each directory.
1461 Always put space around assignment and comparison operators.
1472 but your can compress things in a {\bf for} statement:
1476 for (i=0; i < del.num_ids; i++) {
1481 Don't overuse the inline if (?:). A full {\bf if} is preferred, except in a
1482 print statement, e.g.:
1486 if (ua->verbose \&& del.num_del != 0) {
1487 bsendmsg(ua, _("Pruned %d %s on Volume %s from catalog.\n"), del.num_del,
1488 del.num_del == 1 ? "Job" : "Jobs", mr->VolumeName);
1493 Leave a certain amount of debug code (Dmsg) in code you submit, so that future
1494 problems can be identified. This is particularly true for complicated code
1495 likely to break. However, try to keep the debug code to a minimum to avoid
1496 bloating the program and above all to keep the code readable.
1498 Please keep the same style in all new code you develop. If you include code
1499 previously written, you have the option of leaving it with the old indenting
1500 or re-indenting it. If the old code is indented with 8 spaces, then please
1501 re-indent it to Bacula standards.
1503 If you are using {\bf vim}, simply set your tabstop to 8 and your shiftwidth
1506 \subsection{Tabbing}
1508 \addcontentsline{toc}{subsubsection}{Tabbing}
1510 Tabbing (inserting the tab character in place of spaces) is as normal on all
1511 Unix systems -- a tab is converted space up to the next column multiple of 8.
1512 My editor converts strings of spaces to tabs automatically -- this results in
1513 significant compression of the files. Thus, you can remove tabs by replacing
1514 them with spaces if you wish. Please don't confuse tabbing (use of tab
1515 characters) with indenting (visual alignment of the code).
1519 \addcontentsline{toc}{subsubsection}{Don'ts}
1534 They are system dependent and un-safe. These should be replaced by the Bacula
1539 char *bstrncpy(char *dest, char *source, int dest_size);
1540 char *bstrncat(char *dest, char *source, int dest_size);
1541 int bsnprintf(char *buf, int32_t buf_len, const char *fmt, ...);
1542 int bvsnprintf(char *str, int32_t size, const char *format, va_list ap);
1546 See src/lib/bsys.c for more details on these routines.
1548 Don't use the {\bf \%lld} or the {\bf \%q} printf format editing types to edit
1549 64 bit integers -- they are not portable. Instead, use {\bf \%s} with {\bf
1550 edit\_uint64()}. For example:
1555 uint64_t num = something;
1557 bsnprintf(buf, sizeof(buf), "Num=%s\n", edit_uint64(num, ed1));
1561 Note: {\bf \%lld} is now permitted in Bacula code -- we have our
1562 own printf routines which handle it correctly. The edit\_uint64() subroutine
1563 can still be used if you wish, but over time, most of that old style will
1566 The edit buffer {\bf ed1} must be at least 27 bytes long to avoid overflow.
1567 See src/lib/edit.c for more details. If you look at the code, don't start
1568 screaming that I use {\bf lld}. I actually use subtle trick taught to me by
1569 John Walker. The {\bf lld} that appears in the editing routine is actually
1570 {\bf \#define} to a what is needed on your OS (usually ``lld'' or ``q'') and
1571 is defined in autoconf/configure.in for each OS. C string concatenation causes
1572 the appropriate string to be concatenated to the ``\%''.
1574 Also please don't use the STL or Templates or any complicated C++ code.
1576 \subsection{Message Classes}
1577 \index{Classes!Message}
1578 \index{Message Classes}
1579 \addcontentsline{toc}{subsubsection}{Message Classes}
1581 Currently, there are five classes of messages: Debug, Error, Job, Memory,
1584 \subsection{Debug Messages}
1585 \index{Messages!Debug}
1586 \index{Debug Messages}
1587 \addcontentsline{toc}{subsubsection}{Debug Messages}
1589 Debug messages are designed to be turned on at a specified debug level and are
1590 always sent to STDOUT. There are designed to only be used in the development
1591 debug process. They are coded as:
1593 DmsgN(level, message, arg1, ...) where the N is a number indicating how many
1594 arguments are to be substituted into the message (i.e. it is a count of the
1595 number arguments you have in your message -- generally the number of percent
1596 signs (\%)). {\bf level} is the debug level at which you wish the message to
1597 be printed. message is the debug message to be printed, and arg1, ... are the
1598 arguments to be substituted. Since not all compilers support \#defines with
1599 varargs, you must explicitly specify how many arguments you have.
1601 When the debug message is printed, it will automatically be prefixed by the
1602 name of the daemon which is running, the filename where the Dmsg is, and the
1603 line number within the file.
1605 Some actual examples are:
1607 Dmsg2(20, ``MD5len=\%d MD5=\%s\textbackslash{}n'', strlen(buf), buf);
1609 Dmsg1(9, ``Created client \%s record\textbackslash{}n'', client->hdr.name);
1611 \subsection{Error Messages}
1612 \index{Messages!Error}
1613 \index{Error Messages}
1614 \addcontentsline{toc}{subsubsection}{Error Messages}
1616 Error messages are messages that are related to the daemon as a whole rather
1617 than a particular job. For example, an out of memory condition my generate an
1618 error message. They should be very rarely needed. In general, you should be
1619 using Job and Job Queued messages (Jmsg and Qmsg). They are coded as:
1621 EmsgN(error-code, level, message, arg1, ...) As with debug messages, you must
1622 explicitly code the of arguments to be substituted in the message. error-code
1623 indicates the severity or class of error, and it may be one of the following:
1625 \addcontentsline{lot}{table}{Message Error Code Classes}
1626 \begin{longtable}{lp{3in}}
1627 {{\bf M\_ABORT} } & {Causes the daemon to immediately abort. This should be
1628 used only in extreme cases. It attempts to produce a traceback. } \\
1629 {{\bf M\_ERROR\_TERM} } & {Causes the daemon to immediately terminate. This
1630 should be used only in extreme cases. It does not produce a traceback. } \\
1631 {{\bf M\_FATAL} } & {Causes the daemon to terminate the current job, but the
1632 daemon keeps running } \\
1633 {{\bf M\_ERROR} } & {Reports the error. The daemon and the job continue
1635 {{\bf M\_WARNING} } & {Reports an warning message. The daemon and the job
1636 continue running } \\
1637 {{\bf M\_INFO} } & {Reports an informational message.}
1641 There are other error message classes, but they are in a state of being
1642 redesigned or deprecated, so please do not use them. Some actual examples are:
1645 Emsg1(M\_ABORT, 0, ``Cannot create message thread: \%s\textbackslash{}n'',
1648 Emsg3(M\_WARNING, 0, ``Connect to File daemon \%s at \%s:\%d failed. Retrying
1649 ...\textbackslash{}n'', client-\gt{}hdr.name, client-\gt{}address,
1652 Emsg3(M\_FATAL, 0, ``bdird\lt{}filed: bad response from Filed to \%s command:
1653 \%d \%s\textbackslash{}n'', cmd, n, strerror(errno));
1655 \subsection{Job Messages}
1656 \index{Job Messages}
1657 \index{Messages!Job}
1658 \addcontentsline{toc}{subsubsection}{Job Messages}
1660 Job messages are messages that pertain to a particular job such as a file that
1661 could not be saved, or the number of files and bytes that were saved. They
1664 Jmsg(jcr, M\_FATAL, 0, "Text of message");
1666 A Jmsg with M\_FATAL will fail the job. The Jmsg() takes varargs so can
1667 have any number of arguments for substituted in a printf like format.
1668 Output from the Jmsg() will go to the Job report.
1670 If the Jmsg is followed with a number such as Jmsg1(...), the number
1671 indicates the number of arguments to be substituted (varargs is not
1672 standard for \#defines), and what is more important is that the file and
1673 line number will be prefixed to the message. This permits a sort of debug
1676 \subsection{Queued Job Messages}
1677 \index{Queued Job Messages}
1678 \index{Messages!Job}
1679 \addcontentsline{toc}{subsubsection}{Queued Job Messages}
1680 Queued Job messages are similar to Jmsg()s except that the message is
1681 Queued rather than immediately dispatched. This is necessary within the
1682 network subroutines and in the message editing routines. This is to prevent
1683 recursive loops, and to ensure that messages can be delivered even in the
1684 event of a network error.
1687 \subsection{Memory Messages}
1688 \index{Messages!Memory}
1689 \index{Memory Messages}
1690 \addcontentsline{toc}{subsubsection}{Memory Messages}
1692 Memory messages are messages that are edited into a memory buffer. Generally
1693 they are used in low level routines such as the low level device file dev.c in
1694 the Storage daemon or in the low level Catalog routines. These routines do not
1695 generally have access to the Job Control Record and so they return error
1696 essages reformatted in a memory buffer. Mmsg() is the way to do this.
1698 \subsection{Bugs Database}
1699 \index{Database!Bugs}
1700 \index{Bugs Database}
1701 \addcontentsline{toc}{subsubsection}{Bugs Database}
1702 We have a bugs database which is at:
1703 \elink{http://bugs.bacula.org}{http://bugs.bacula.org}, and as
1704 a developer you will need to respond to bugs, perhaps bugs in general
1705 if you have time, otherwise just bugs that correspond to code that
1708 If you need to answer bugs, please be sure to ask the Project Manager
1709 (currently Kern) to give you Developer access to the bugs database. This
1710 allows you to modify statuses and close bugs.
1712 The first thing is if you want to take over a bug, rather than just make a
1713 note, you should assign the bug to yourself. This helps other developers
1714 know that you are the principal person to deal with the bug. You can do so
1715 by going into the bug and clicking on the {\bf Update Issue} button. Then
1716 you simply go to the {\bf Assigned To} box and select your name from the
1717 drop down box. To actually update it you must click on the {\bf Update
1718 Information} button a bit further down on the screen, but if you have other
1719 things to do such as add a Note, you might wait before clicking on the {\bf
1720 Update Information} button.
1722 Generally, we set the {\bf Status} field to either acknowledged, confirmed,
1723 or feedback when we first start working on the bug. Feedback is set when
1724 we expect that the user should give us more information.
1726 Normally, once you are reasonably sure that the bug is fixed, and a patch
1727 is made and attached to the bug report, and/or in the SVN, you can close
1728 the bug. If you want the user to test the patch, then leave the bug open,
1729 otherwise close it and set {\bf Resolution} to {\bf Fixed}. We generally
1730 close bug reports rather quickly, even without confirmation, especially if
1731 we have run tests and can see that for us the problem is fixed. However,
1732 in doing so, it avoids misunderstandings if you leave a note while you are
1733 closing the bug that says something to the following effect:
1734 We are closing this bug because ... If for some reason, it does not fix
1735 your problem, please feel free to reopen it, or to open a new bug report
1736 describing the problem".
1738 We do not recommend that you attempt to edit any of the bug notes that have
1739 been submitted, nor to delete them or make them private. In fact, if
1740 someone accidentally makes a bug note private, you should ask the reason
1741 and if at all possible (with his agreement) make the bug note public.
1743 If the user has not properly filled in most of the important fields
1744 (platorm, OS, Product Version, ...) please do not hesitate to politely ask
1745 him. Also, if the bug report is a request for a new feature, please
1746 politely send the user to the Feature Request menu item on www.bacula.org.
1747 The same applies to a support request (we answer only bugs), you might give
1748 the user a tip, but please politely refer him to the manual and the
1749 Getting Support page of www.bacula.org.