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 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 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 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/}.
479 \subsection{Publishing your changes}
481 Since GIT is more complex than SVN, it takes a bit of time to learn how
482 to use it properly, and if you are not careful, you can potentially create
483 a new history in the repository. In addition, since GIT is a distributed
484 version control system, we prefer to receive a full branch submission rather
485 than simply a patch. To accomplish this, you must create your changes in
486 a branch, then {\bf push} them to some public repository -- it can be your
487 own repository that you publish or another. To simplify this phase for you, we
488 have created a publich Bacula GIT repository on {\bf github} where you can
489 push your branch containing changes you would like integrated into the Bacula
492 Once you have pushed your branch to {\bf github} or told us where we can pull
493 from your public repository, one of the senior Bacula devlopers will fetch your
494 changes, examine them, possibly make comments for changes they would like to
495 see, and as the final step, the senior developer will commit it to the
496 Bacula Source Forge GIT repository.
500 If you are going to submit before cloning the Bacula Github database, you must create a login on
501 the Github website:\\
502 \elink{http://github.com/}{http://github.com/}\\
503 You must also upload your public ssh key. Please see the instructions
504 at the above link. Then you notify one of the senior Bacula developers,
505 who will add your Github user name to the Bacula repository. Finally,
506 you clone the Bacula repository with:
509 git clone git@github.com:<username>/bacula.git <xxx>
512 where you replace \verb+<username>+ with the User Name that you created
513 when you created your Github login, and you replace \verb+<xxx>+ with the name
514 of a directory that you want git to create to hold your local Bacula git
517 Normally, you will work by creating a branch of the master branch of your
518 repository, make your modifications, then make sure it is up to date, and finally
519 push it to Github. Assuming you call the Bacula repository {\bf bacula}, you might
520 use the following commands:
526 git branch <your-name>/newbranch
527 git checkout <your-name>/newbranch
529 git add <file-edited>
530 git commit -m "<comment about commit>"
534 Note, we request you to create the branch name with your github
535 login name. This guarantees that the branch name will be unique and
536 easily identified as well.
538 When you have completed working on your branch, you will do:
542 git checkout <your-name>/newbranch
547 If you have completed your edits before anyone has modified the repository,
548 the {\bf git rebase master} will report that there was nothing to do. Otherwise,
549 it will merge the changes that were made in the repository before your changes.
550 If there are any conflicts, git will tell you. Typically resolving conflicts with
551 git is relatively easy. You simply make a diff:
557 Then edit each file that was listed in the {\bf git diff} to remove the
558 conflict, which will be indicated by lines of:
568 where {\bf text} is what is in the Bacula repository, and {\bf other text}
569 is what you have changed.
571 Once you have eliminated the conflict, the {\bf git diff} will show nothing,
575 git add <file-with-conflicts-fixed>
578 Once you have fixed all the files with conflicts in the above manner, you enter:
581 git rebase --continue
584 and your rebase will be complete.
586 If for some reason, before doing the --continue, you want to abort the rebase and return to what you had, you enter:
592 Finally to upload your branch, you do:
595 git push origin <your-name>/newbranch
598 If you wish to delete it later, you can use:
601 git push origin :<your-name>/newbranch
608 \addcontentsline{toc}{subsection}{SVN Usage}
610 Note: this section is somewhat out of date, since the SVN now
611 contains only the docs and rescue subdirectories. The bacula,
612 gui, and regress directories are now maintained in a GIT
615 Please note that if you are familiar with CVS, SVN is very
616 similar (and better), but there can be a few surprising
619 The Bacula SourceForge.net Subversion repository that contains
620 the documentation and the rescue scripts checked out through SVN with the
624 svn checkout https://bacula.svn.sourceforge.net/svnroot/bacula bacula
627 With the above command, you will get everything, which is a very large
649 Note, you should NEVER commit code to any checkout that you have
650 done of a tag. All tags (e.g. Release-1.1, ... Release-2.0.2)
651 should be considered read-only.
653 You may commit code to the most recent item in
654 branches (in the above the most recent one is Branch-2.0). If
655 you want to commit code to an older branch, then please contact
658 You may create your own tags and/or branches, but they should
659 have a name clearly distinctive from Branch-, Release-, or Beta-,
660 which are official names used by the project. If you create a
661 tag, then you should NEVER commit code to it, for the same
662 reason noted above -- it should serve as a marker for something
663 you released. If you create a branch, then you are free to
664 commit to it as you wish.
666 You may, of course, commit to the trunk.
678 are reserved names to be created only by the project manager (or
679 with his OK), where the nnn is any sequence of numbers and
680 periods (e.g. 2.0, 2.0.1, ...).
682 In addition all tags even those that you create are read-only
683 forever. Typically tags represent release points either in the
684 trunk or in a branch.
687 Coming back to getting source code.
688 If you only want the current Bacula source code, you should see
689 the above section that describes the GIT repository.
691 To view what is in the SVN, point your browser at the following URL:
692 http://bacula.svn.sourceforge.net/viewvc/bacula/
694 Many of the Subversion (svn) commands are almost identical to those that
695 you have used for cvs, but some (such as a checkout) can have surprising
696 results, so you should take a careful look at the documentation.
698 The following documentation on the new
699 svn repository will help you know how to use it:
701 Here is the list of branches:
718 Release-1.1 Release-1.19 Release-1.19a Release-1.19b
719 Release-1.20 Release-1.21 Release-1.22 Release-1.23
720 Release-1.23a Release-1.24 Release-1.25 Release-1.25a
721 Release-1.26 Release-1.27 Release-1.27a Release-1.27b
722 Release-1.27c Release-1.28 Release-1.29 Release-1.30
723 Release-1.31 Release-1.31a Release-1.32 Release-1.32a
724 Release-1.32b Release-1.32c Release-1.32d Release-1.32e
725 Release-1.32f Release-1.32f-2 Release-1.32f-3 Release-1.32f-4
726 Release-1.32f-5 Release-1.34.0 Release-1.34.1 Release-1.34.3
727 Release-1.34.4 Release-1.34.5 Release-1.34.6 Release-1.35.1
728 Release-1.35.2 Release-1.35.3 Release-1.35.6 Release-1.35.7
729 Release-1.35.8 Release-1.36.0 Release-1.36.1 Release-1.36.2
730 Release-1.36.3 Release-1.38.0 Release-1.38.1 Release-1.38.10
731 Release-1.38.11 Release-1.38.2 Release-1.38.3 Release-1.38.4
732 Release-1.38.5 Release-1.38.6 Release-1.38.7 Release-1.38.8
733 Release-1.38.9 Release-1.8.1 Release-1.8.2 Release-1.8.3
734 Release-1.8.4 Release-1.8.5 Release-1.8.6 Release-2.0.0
735 Release-2.0.1 Release-2.0.2
738 Here is a list of commands to get you started. The recommended book is
739 "Version Control with Subversion", by Ben Collins-Sussmann,
740 Brian W. Fitzpatrick, and Michael Pilato, O'Reilly. The book is
741 Open Source, so it is also available on line at:
744 http://svnbook.red-bean.com
747 Get a list of commands
753 Get a help with a command
759 Checkout the HEAD revision of all modules from the project into the
763 svn co https://bacula.svn.sourceforge.net/svnroot/bacula/trunk bacula.new
766 Checkout the HEAD revision of the bacula module into the bacula subdirectory
769 svn checkout https://bacula.svn.sourceforge.net/svnroot/bacula/trunk/bacula
772 See which files have changed in the working copy
778 See which files are out of date
784 Add a new file file.c
790 Create a new directory
796 Delete an obsolete file
805 svn move file.c newfile.c
808 Move a file to a new location
811 svn move file.c ../newdir/file.c
814 Copy a file retaining the original history in the new file
817 svn copy file.c newfile.c
820 Update the working copy with the outstanding changes
826 Compare working copy with the repository
832 Commit the changes in the local working copy
838 Specify which files are ignored in the current directory
841 svn propedit svn:ignore .
844 Mark a file to be executable
847 svn propset svn:executable '*' prog.sh
850 Unmark a file as executable
853 svn propdel svn:executable prog.sh
856 List a file's properties
862 Create a branch for a new version
865 svn copy https://bacula.svn.sourceforge.net/svnroot/bacula/trunk \
866 https://bacula.svn.sourceforge.net/svnroot/bacula/branches/Branch-2.1
869 Tag a version for a new release
872 svn copy https://bacula.svn.sourceforge.net/svnroot/bacula/branches/Branch-2.1 \
873 https://bacula.svn.sourceforge.net/svnroot/bacula/branches/Release-2.1
877 Let's say you are working in the directory scripts. You would then do:
884 when you are happy with your changes, you can do the following:
887 cd bacula (to your top level directory)
888 svn diff my-changes.patch
891 When the command is done, you can look in the file my-changes.patch
892 and you will see all the changes you have made to your copy of the
893 repository. Make sure that you understand all the changes that
894 it reports before proceeding. If you modified files that you do
895 do not want to commit to the main repository, you can simply delete
896 them from your local directory, and they will be restored from the
897 repository with the "svn update" that is shown below. Normally, you
898 should not find changes to files that you do not want to commit, and
899 if you find yourself in that position a lot, you are probably doing
902 Let's assume that now you want to commit your changes to the main
912 When you do this, it will pull any changes made by other developers into
913 your local copy of the repository, and it will check for conflicts. If there
914 are any, it will tell you, and you will need to resolve them. The problems
915 of resolving conflicts are a bit more than this document can cover, but
916 you can examine the files it claims have conflicts and look for \lt{}\lt{}\lt{}\lt{}
917 or look in the .rej files that it creates. If you have problems, just ask
918 on the developer's list.
920 Note, doing the above "svn update" is not absolutely necessary. There are
921 times when you may be working on code and you want to commit it, but you
922 explicitly do not want to move up to the latest version of the code in
923 the SVN. If that is the case, you can simply skip the "svn update" and
924 do the commit shown below. If the commit fails because of a conflict, it
925 will tell you, and you must resolve the conflict before it will permit
926 you to do the commit.
928 Once your local copy of the repository has been updated, you can now
932 svn commit -m "Some comment about what you changed"
935 or if you really only want to commit a single file, you can
939 svn commit -m "comment" scripts/file-I-edited
942 Note, if you have done a build in your directory, or you have added
943 other new files, the commit will update only the files that are
944 actually in the repository. For example, none of the object files
945 are stored in the repository, so when you do a commit, those object
946 files will simply be ignored.
948 If you want to add new files or remove files from the main SVN
949 repository, and you are not experienced with SVN, please ask Kern
950 to do it. If you follow the simple steps above, it is unlikely that
951 you will do any damage to the repository, and if you do, it is always
952 possible for us to recover, but it can be painful.
954 If you are only working in one subdirectory of say the bacula project,
955 for example, the scripts directory, you can do your commit from
956 that subdirectory, and only the changes in that directory and all its
957 subdirectories will be committed. This can be helpful for translators.
958 If you are doing a French translation, you will be working in
959 docs/manual-fr, and if you are always cd'ed into that directory when
960 doing your commits, your commit will effect only that directory. As
961 long as you are careful only to change files that you want changed,
962 you have little to worry about.
964 \section{Subversion Resources}
965 \index{Subversion (svn) Resources}
966 \addcontentsline{toc}{subsection}{Subversion Resources}
968 Main Subversion Web Page
969 \elink{http://subversion.tigris.org}{http://subversion.tigris.org}
972 \elink{http://svnbook.red-bean.com}{http://svnbook.red-bean.com}
975 \elink{http://subversion.tigris.org/project\_packages.html}{http://subversion.tigris.org/project\_packages.html}
977 (For Windows users the TortoiseSVN package is awesome)
980 \elink{http://rapidsvn.tigris.org/}{http://rapidsvn.tigris.org/}
982 A nice KDE GUI client:
987 \section{Developing Bacula}
988 \index{Developing Bacula}
989 \index{Bacula!Developing}
990 \addcontentsline{toc}{subsubsection}{Developing Bacula}
992 Typically the simplest way to develop Bacula is to open one xterm window
993 pointing to the source directory you wish to update; a second xterm window at
994 the top source directory level, and a third xterm window at the bacula
995 directory \lt{}top\gt{}/src/bacula. After making source changes in one of the
996 directories, in the top source directory xterm, build the source, and start
997 the daemons by entering:
1001 ./startit then in the enter:
1005 ./gnome-console to start the Console program. Enter any commands for testing.
1006 For example: run kernsverify full.
1008 Note, the instructions here to use {\bf ./startit} are different from using a
1009 production system where the administrator starts Bacula by entering {\bf
1010 ./bacula start}. This difference allows a development version of {\bf Bacula}
1011 to be run on a computer at the same time that a production system is running.
1012 The {\bf ./startit} strip starts {\bf Bacula} using a different set of
1013 configuration files, and thus permits avoiding conflicts with any production
1016 To make additional source changes, exit from the Console program, and in the
1017 top source directory, stop the daemons by entering:
1019 ./stopit then repeat the process.
1021 \subsection{Debugging}
1023 \addcontentsline{toc}{subsubsection}{Debugging}
1025 Probably the first thing to do is to turn on debug output.
1027 A good place to start is with a debug level of 20 as in {\bf ./startit -d20}.
1028 The startit command starts all the daemons with the same debug level.
1029 Alternatively, you can start the appropriate daemon with the debug level you
1030 want. If you really need more info, a debug level of 60 is not bad, and for
1031 just about everything a level of 200.
1033 \subsection{Using a Debugger}
1034 \index{Using a Debugger}
1035 \index{Debugger!Using a}
1036 \addcontentsline{toc}{subsubsection}{Using a Debugger}
1038 If you have a serious problem such as a segmentation fault, it can usually be
1039 found quickly using a good multiple thread debugger such as {\bf gdb}. For
1040 example, suppose you get a segmentation violation in {\bf bacula-dir}. You
1041 might use the following to find the problem:
1043 \lt{}start the Storage and File daemons\gt{}
1046 run -f -s -c ./dird.conf
1047 \lt{}it dies with a segmentation fault\gt{}
1049 The {\bf -f} option is specified on the {\bf run} command to inhibit {\bf
1050 dird} from going into the background. You may also want to add the {\bf -s}
1051 option to the run command to disable signals which can potentially interfere
1054 As an alternative to using the debugger, each {\bf Bacula} daemon has a built
1055 in back trace feature when a serious error is encountered. It calls the
1056 debugger on itself, produces a back trace, and emails the report to the
1057 developer. For more details on this, please see the chapter in the main Bacula
1058 manual entitled ``What To Do When Bacula Crashes (Kaboom)''.
1060 \subsection{Memory Leaks}
1061 \index{Leaks!Memory}
1062 \index{Memory Leaks}
1063 \addcontentsline{toc}{subsubsection}{Memory Leaks}
1065 Because Bacula runs routinely and unattended on client and server machines, it
1066 may run for a long time. As a consequence, from the very beginning, Bacula
1067 uses SmartAlloc to ensure that there are no memory leaks. To make detection of
1068 memory leaks effective, all Bacula code that dynamically allocates memory MUST
1069 have a way to release it. In general when the memory is no longer needed, it
1070 should be immediately released, but in some cases, the memory will be held
1071 during the entire time that Bacula is executing. In that case, there MUST be a
1072 routine that can be called at termination time that releases the memory. In
1073 this way, we will be able to detect memory leaks. Be sure to immediately
1074 correct any and all memory leaks that are printed at the termination of the
1077 \subsection{Special Files}
1078 \index{Files!Special}
1079 \index{Special Files}
1080 \addcontentsline{toc}{subsubsection}{Special Files}
1082 Kern uses files named 1, 2, ... 9 with any extension as scratch files. Thus
1083 any files with these names are subject to being rudely deleted at any time.
1085 \subsection{When Implementing Incomplete Code}
1086 \index{Code!When Implementing Incomplete}
1087 \index{When Implementing Incomplete Code}
1088 \addcontentsline{toc}{subsubsection}{When Implementing Incomplete Code}
1090 Please identify all incomplete code with a comment that contains
1096 where there are three asterisks (*) before and after the word
1097 FIXME (in capitals) and no intervening spaces. This is important as it allows
1098 new programmers to easily recognize where things are partially implemented.
1100 \subsection{Bacula Source File Structure}
1101 \index{Structure!Bacula Source File}
1102 \index{Bacula Source File Structure}
1103 \addcontentsline{toc}{subsubsection}{Bacula Source File Structure}
1105 The distribution generally comes as a tar file of the form {\bf
1106 bacula.x.y.z.tar.gz} where x, y, and z are the version, release, and update
1107 numbers respectively.
1109 Once you detar this file, you will have a directory structure as follows:
1116 |- mtx (autochanger control program + tape drive info)
1117 |- sqlite (SQLite database program)
1121 |- pthreads (Native win32 pthreads library -- dll)
1122 |- zlib (Native win32 zlib library)
1123 |- wx (wxWidgets source code)
1126 |- bacula (main source directory containing configuration
1127 | and installation files)
1128 |- autoconf (automatic configuration files, not normally used
1130 |- intl (programs used to translate)
1131 |- platforms (OS specific installation files)
1132 |- redhat (Red Hat installation)
1133 |- solaris (Sun installation)
1134 |- freebsd (FreeBSD installation)
1135 |- irix (Irix installation -- not tested)
1136 |- unknown (Default if system not identified)
1137 |- po (translations of source strings)
1138 |- src (source directory; contains global header files)
1139 |- cats (SQL catalog database interface directory)
1140 |- console (bacula user agent directory)
1141 |- dird (Director daemon)
1142 |- filed (Unix File daemon)
1143 |- win32 (Win32 files to make bacula-fd be a service)
1144 |- findlib (Unix file find library for File daemon)
1145 |- gnome-console (GNOME version of console program)
1146 |- lib (General Bacula library)
1147 |- stored (Storage daemon)
1148 |- tconsole (Tcl/tk console program -- not yet working)
1149 |- testprogs (test programs -- normally only in Kern's tree)
1150 |- tools (Various tool programs)
1151 |- win32 (Native Win32 File daemon)
1152 |- baculafd (Visual Studio project file)
1153 |- compat (compatibility interface library)
1154 |- filed (links to src/filed)
1155 |- findlib (links to src/findlib)
1156 |- lib (links to src/lib)
1157 |- console (beginning of native console program)
1158 |- wx-console (wxWidget console Win32 specific parts)
1159 |- wx-console (wxWidgets console main source program)
1162 |- regress (Regression scripts)
1163 |- bin (temporary directory to hold Bacula installed binaries)
1164 |- build (temporary directory to hold Bacula source)
1165 |- scripts (scripts and .conf files)
1166 |- tests (test scripts)
1167 |- tmp (temporary directory for temp files)
1168 |- working (temporary working directory for Bacula daemons)
1171 |- docs (documentation directory)
1172 |- developers (Developer's guide)
1173 |- home-page (Bacula's home page source)
1174 |- manual (html document directory)
1175 |- manual-fr (French translation)
1176 |- manual-de (German translation)
1177 |- techlogs (Technical development notes);
1180 |- rescue (Bacula rescue CDROM)
1181 |- linux (Linux rescue CDROM)
1182 |- cdrom (Linux rescue CDROM code)
1184 |- solaris (Solaris rescue -- incomplete)
1185 |- freebsd (FreeBSD rescue -- incomplete)
1188 |- gui (Bacula GUI projects)
1189 |- bacula-web (Bacula web php management code)
1190 |- bimagemgr (Web application for burning CDROMs)
1196 \subsection{Header Files}
1197 \index{Header Files}
1198 \index{Files!Header}
1199 \addcontentsline{toc}{subsubsection}{Header Files}
1201 Please carefully follow the scheme defined below as it permits in general only
1202 two header file includes per C file, and thus vastly simplifies programming.
1203 With a large complex project like Bacula, it isn't always easy to ensure that
1204 the right headers are invoked in the right order (there are a few kludges to
1205 make this happen -- i.e. in a few include files because of the chicken and egg
1206 problem, certain references to typedefs had to be replaced with {\bf void} ).
1208 Every file should include {\bf bacula.h}. It pulls in just about everything,
1209 with very few exceptions. If you have system dependent ifdefing, please do it
1210 in {\bf baconfig.h}. The version number and date are kept in {\bf version.h}.
1212 Each of the subdirectories (console, cats, dird, filed, findlib, lib, stored,
1213 ...) contains a single directory dependent include file generally the name of
1214 the directory, which should be included just after the include of {\bf
1215 bacula.h}. This file (for example, for the dird directory, it is {\bf dird.h})
1216 contains either definitions of things generally needed in this directory, or
1217 it includes the appropriate header files. It always includes {\bf protos.h}.
1220 Each subdirectory contains a header file named {\bf protos.h}, which contains
1221 the prototypes for subroutines exported by files in that directory. {\bf
1222 protos.h} is always included by the main directory dependent include file.
1224 \subsection{Programming Standards}
1225 \index{Standards!Programming}
1226 \index{Programming Standards}
1227 \addcontentsline{toc}{subsubsection}{Programming Standards}
1229 For the most part, all code should be written in C unless there is a burning
1230 reason to use C++, and then only the simplest C++ constructs will be used.
1231 Note, Bacula is slowly evolving to use more and more C++.
1233 Code should have some documentation -- not a lot, but enough so that I can
1234 understand it. Look at the current code, and you will see that I document more
1235 than most, but am definitely not a fanatic.
1237 We prefer simple linear code where possible. Gotos are strongly discouraged
1238 except for handling an error to either bail out or to retry some code, and
1239 such use of gotos can vastly simplify the program.
1241 Remember this is a C program that is migrating to a {\bf tiny} subset of C++,
1242 so be conservative in your use of C++ features.
1244 \subsection{Do Not Use}
1247 \addcontentsline{toc}{subsubsection}{Do Not Use}
1250 \item STL -- it is totally incomprehensible.
1253 \subsection{Avoid if Possible}
1254 \index{Possible!Avoid if}
1255 \index{Avoid if Possible}
1256 \addcontentsline{toc}{subsubsection}{Avoid if Possible}
1259 \item Using {\bf void *} because this generally means that one must
1260 using casting, and in C++ casting is rather ugly. It is OK to use
1261 void * to pass structure address where the structure is not known
1262 to the routines accepting the packet (typically callback routines).
1263 However, declaring "void *buf" is a bad idea. Please use the
1264 correct types whenever possible.
1266 \item Using undefined storage specifications such as (short, int, long,
1267 long long, size\_t ...). The problem with all these is that the number of bytes
1268 they allocate depends on the compiler and the system. Instead use
1269 Bacula's types (int8\_t, uint8\_t, int32\_t, uint32\_t, int64\_t, and
1270 uint64\_t). This guarantees that the variables are given exactly the
1271 size you want. Please try at all possible to avoid using size\_t ssize\_t
1272 and the such. They are very system dependent. However, some system
1273 routines may need them, so their use is often unavoidable.
1275 \item Returning a malloc'ed buffer from a subroutine -- someone will forget
1278 \item Heap allocation (malloc) unless needed -- it is expensive. Use
1281 \item Templates -- they can create portability problems.
1283 \item Fancy or tricky C or C++ code, unless you give a good explanation of
1286 \item Too much inheritance -- it can complicate the code, and make reading it
1287 difficult (unless you are in love with colons)
1291 \subsection{Do Use Whenever Possible}
1292 \index{Possible!Do Use Whenever}
1293 \index{Do Use Whenever Possible}
1294 \addcontentsline{toc}{subsubsection}{Do Use Whenever Possible}
1297 \item Locking and unlocking within a single subroutine.
1299 \item A single point of exit from all subroutines. A goto is
1300 perfectly OK to use to get out early, but only to a label
1301 named bail\_out, and possibly an ok\_out. See current code
1304 \item Malloc and free within a single subroutine.
1306 \item Comments and global explanations on what your code or algorithm does.
1310 \subsection{Indenting Standards}
1311 \index{Standards!Indenting}
1312 \index{Indenting Standards}
1313 \addcontentsline{toc}{subsubsection}{Indenting Standards}
1315 We find it very hard to read code indented 8 columns at a time.
1316 Even 4 at a time uses a lot of space, so we have adopted indenting
1317 3 spaces at every level. Note, indention is the visual appearance of the
1318 source on the page, while tabbing is replacing a series of up to 8 spaces from
1321 The closest set of parameters for the Linux {\bf indent} program that will
1322 produce reasonably indented code are:
1326 -nbad -bap -bbo -nbc -br -brs -c36 -cd36 -ncdb -ce -ci3 -cli0
1327 -cp36 -d0 -di1 -ndj -nfc1 -nfca -hnl -i3 -ip0 -l85 -lp -npcs
1328 -nprs -npsl -saf -sai -saw -nsob -nss -nbc -ncs -nbfda
1332 You can put the above in your .indent.pro file, and then just invoke indent on
1333 your file. However, be warned. This does not produce perfect indenting, and it
1334 will mess up C++ class statements pretty badly.
1336 Braces are required in all if statements (missing in some very old code). To
1337 avoid generating too many lines, the first brace appears on the first line
1338 (e.g. of an if), and the closing brace is on a line by itself. E.g.
1348 Just follow the convention in the code. For example we I prefer non-indented cases.
1365 Avoid using // style comments except for temporary code or turning off debug
1366 code. Standard C comments are preferred (this also keeps the code closer to
1369 Attempt to keep all lines less than 85 characters long so that the whole line
1370 of code is readable at one time. This is not a rigid requirement.
1372 Always put a brief description at the top of any new file created describing
1373 what it does and including your name and the date it was first written. Please
1374 don't forget any Copyrights and acknowledgments if it isn't 100\% your code.
1375 Also, include the Bacula copyright notice that is in {\bf src/c}.
1377 In general you should have two includes at the top of the an include for the
1378 particular directory the code is in, for includes are needed, but this should
1381 In general (except for self-contained packages), prototypes should all be put
1382 in {\bf protos.h} in each directory.
1384 Always put space around assignment and comparison operators.
1395 but your can compress things in a {\bf for} statement:
1399 for (i=0; i < del.num_ids; i++) {
1404 Don't overuse the inline if (?:). A full {\bf if} is preferred, except in a
1405 print statement, e.g.:
1409 if (ua->verbose \&& del.num_del != 0) {
1410 bsendmsg(ua, _("Pruned %d %s on Volume %s from catalog.\n"), del.num_del,
1411 del.num_del == 1 ? "Job" : "Jobs", mr->VolumeName);
1416 Leave a certain amount of debug code (Dmsg) in code you submit, so that future
1417 problems can be identified. This is particularly true for complicated code
1418 likely to break. However, try to keep the debug code to a minimum to avoid
1419 bloating the program and above all to keep the code readable.
1421 Please keep the same style in all new code you develop. If you include code
1422 previously written, you have the option of leaving it with the old indenting
1423 or re-indenting it. If the old code is indented with 8 spaces, then please
1424 re-indent it to Bacula standards.
1426 If you are using {\bf vim}, simply set your tabstop to 8 and your shiftwidth
1429 \subsection{Tabbing}
1431 \addcontentsline{toc}{subsubsection}{Tabbing}
1433 Tabbing (inserting the tab character in place of spaces) is as normal on all
1434 Unix systems -- a tab is converted space up to the next column multiple of 8.
1435 My editor converts strings of spaces to tabs automatically -- this results in
1436 significant compression of the files. Thus, you can remove tabs by replacing
1437 them with spaces if you wish. Please don't confuse tabbing (use of tab
1438 characters) with indenting (visual alignment of the code).
1442 \addcontentsline{toc}{subsubsection}{Don'ts}
1457 They are system dependent and un-safe. These should be replaced by the Bacula
1462 char *bstrncpy(char *dest, char *source, int dest_size);
1463 char *bstrncat(char *dest, char *source, int dest_size);
1464 int bsnprintf(char *buf, int32_t buf_len, const char *fmt, ...);
1465 int bvsnprintf(char *str, int32_t size, const char *format, va_list ap);
1469 See src/lib/bsys.c for more details on these routines.
1471 Don't use the {\bf \%lld} or the {\bf \%q} printf format editing types to edit
1472 64 bit integers -- they are not portable. Instead, use {\bf \%s} with {\bf
1473 edit\_uint64()}. For example:
1478 uint64_t num = something;
1480 bsnprintf(buf, sizeof(buf), "Num=%s\n", edit_uint64(num, ed1));
1484 Note: {\bf \%lld} is now permitted in Bacula code -- we have our
1485 own printf routines which handle it correctly. The edit\_uint64() subroutine
1486 can still be used if you wish, but over time, most of that old style will
1489 The edit buffer {\bf ed1} must be at least 27 bytes long to avoid overflow.
1490 See src/lib/edit.c for more details. If you look at the code, don't start
1491 screaming that I use {\bf lld}. I actually use subtle trick taught to me by
1492 John Walker. The {\bf lld} that appears in the editing routine is actually
1493 {\bf \#define} to a what is needed on your OS (usually ``lld'' or ``q'') and
1494 is defined in autoconf/configure.in for each OS. C string concatenation causes
1495 the appropriate string to be concatenated to the ``\%''.
1497 Also please don't use the STL or Templates or any complicated C++ code.
1499 \subsection{Message Classes}
1500 \index{Classes!Message}
1501 \index{Message Classes}
1502 \addcontentsline{toc}{subsubsection}{Message Classes}
1504 Currently, there are five classes of messages: Debug, Error, Job, Memory,
1507 \subsection{Debug Messages}
1508 \index{Messages!Debug}
1509 \index{Debug Messages}
1510 \addcontentsline{toc}{subsubsection}{Debug Messages}
1512 Debug messages are designed to be turned on at a specified debug level and are
1513 always sent to STDOUT. There are designed to only be used in the development
1514 debug process. They are coded as:
1516 DmsgN(level, message, arg1, ...) where the N is a number indicating how many
1517 arguments are to be substituted into the message (i.e. it is a count of the
1518 number arguments you have in your message -- generally the number of percent
1519 signs (\%)). {\bf level} is the debug level at which you wish the message to
1520 be printed. message is the debug message to be printed, and arg1, ... are the
1521 arguments to be substituted. Since not all compilers support \#defines with
1522 varargs, you must explicitly specify how many arguments you have.
1524 When the debug message is printed, it will automatically be prefixed by the
1525 name of the daemon which is running, the filename where the Dmsg is, and the
1526 line number within the file.
1528 Some actual examples are:
1530 Dmsg2(20, ``MD5len=\%d MD5=\%s\textbackslash{}n'', strlen(buf), buf);
1532 Dmsg1(9, ``Created client \%s record\textbackslash{}n'', client->hdr.name);
1534 \subsection{Error Messages}
1535 \index{Messages!Error}
1536 \index{Error Messages}
1537 \addcontentsline{toc}{subsubsection}{Error Messages}
1539 Error messages are messages that are related to the daemon as a whole rather
1540 than a particular job. For example, an out of memory condition my generate an
1541 error message. They should be very rarely needed. In general, you should be
1542 using Job and Job Queued messages (Jmsg and Qmsg). They are coded as:
1544 EmsgN(error-code, level, message, arg1, ...) As with debug messages, you must
1545 explicitly code the of arguments to be substituted in the message. error-code
1546 indicates the severity or class of error, and it may be one of the following:
1548 \addcontentsline{lot}{table}{Message Error Code Classes}
1549 \begin{longtable}{lp{3in}}
1550 {{\bf M\_ABORT} } & {Causes the daemon to immediately abort. This should be
1551 used only in extreme cases. It attempts to produce a traceback. } \\
1552 {{\bf M\_ERROR\_TERM} } & {Causes the daemon to immediately terminate. This
1553 should be used only in extreme cases. It does not produce a traceback. } \\
1554 {{\bf M\_FATAL} } & {Causes the daemon to terminate the current job, but the
1555 daemon keeps running } \\
1556 {{\bf M\_ERROR} } & {Reports the error. The daemon and the job continue
1558 {{\bf M\_WARNING} } & {Reports an warning message. The daemon and the job
1559 continue running } \\
1560 {{\bf M\_INFO} } & {Reports an informational message.}
1564 There are other error message classes, but they are in a state of being
1565 redesigned or deprecated, so please do not use them. Some actual examples are:
1568 Emsg1(M\_ABORT, 0, ``Cannot create message thread: \%s\textbackslash{}n'',
1571 Emsg3(M\_WARNING, 0, ``Connect to File daemon \%s at \%s:\%d failed. Retrying
1572 ...\textbackslash{}n'', client-\gt{}hdr.name, client-\gt{}address,
1575 Emsg3(M\_FATAL, 0, ``bdird\lt{}filed: bad response from Filed to \%s command:
1576 \%d \%s\textbackslash{}n'', cmd, n, strerror(errno));
1578 \subsection{Job Messages}
1579 \index{Job Messages}
1580 \index{Messages!Job}
1581 \addcontentsline{toc}{subsubsection}{Job Messages}
1583 Job messages are messages that pertain to a particular job such as a file that
1584 could not be saved, or the number of files and bytes that were saved. They
1587 Jmsg(jcr, M\_FATAL, 0, "Text of message");
1589 A Jmsg with M\_FATAL will fail the job. The Jmsg() takes varargs so can
1590 have any number of arguments for substituted in a printf like format.
1591 Output from the Jmsg() will go to the Job report.
1593 If the Jmsg is followed with a number such as Jmsg1(...), the number
1594 indicates the number of arguments to be substituted (varargs is not
1595 standard for \#defines), and what is more important is that the file and
1596 line number will be prefixed to the message. This permits a sort of debug
1599 \subsection{Queued Job Messages}
1600 \index{Queued Job Messages}
1601 \index{Messages!Job}
1602 \addcontentsline{toc}{subsubsection}{Queued Job Messages}
1603 Queued Job messages are similar to Jmsg()s except that the message is
1604 Queued rather than immediately dispatched. This is necessary within the
1605 network subroutines and in the message editing routines. This is to prevent
1606 recursive loops, and to ensure that messages can be delivered even in the
1607 event of a network error.
1610 \subsection{Memory Messages}
1611 \index{Messages!Memory}
1612 \index{Memory Messages}
1613 \addcontentsline{toc}{subsubsection}{Memory Messages}
1615 Memory messages are messages that are edited into a memory buffer. Generally
1616 they are used in low level routines such as the low level device file dev.c in
1617 the Storage daemon or in the low level Catalog routines. These routines do not
1618 generally have access to the Job Control Record and so they return error
1619 essages reformatted in a memory buffer. Mmsg() is the way to do this.
1621 \subsection{Bugs Database}
1622 \index{Database!Bugs}
1623 \index{Bugs Database}
1624 \addcontentsline{toc}{subsubsection}{Bugs Database}
1625 We have a bugs database which is at:
1626 \elink{http://bugs.bacula.org}{http://bugs.bacula.org}, and as
1627 a developer you will need to respond to bugs, perhaps bugs in general
1628 if you have time, otherwise just bugs that correspond to code that
1631 If you need to answer bugs, please be sure to ask the Project Manager
1632 (currently Kern) to give you Developer access to the bugs database. This
1633 allows you to modify statuses and close bugs.
1635 The first thing is if you want to take over a bug, rather than just make a
1636 note, you should assign the bug to yourself. This helps other developers
1637 know that you are the principal person to deal with the bug. You can do so
1638 by going into the bug and clicking on the {\bf Update Issue} button. Then
1639 you simply go to the {\bf Assigned To} box and select your name from the
1640 drop down box. To actually update it you must click on the {\bf Update
1641 Information} button a bit further down on the screen, but if you have other
1642 things to do such as add a Note, you might wait before clicking on the {\bf
1643 Update Information} button.
1645 Generally, we set the {\bf Status} field to either acknowledged, confirmed,
1646 or feedback when we first start working on the bug. Feedback is set when
1647 we expect that the user should give us more information.
1649 Normally, once you are reasonably sure that the bug is fixed, and a patch
1650 is made and attached to the bug report, and/or in the SVN, you can close
1651 the bug. If you want the user to test the patch, then leave the bug open,
1652 otherwise close it and set {\bf Resolution} to {\bf Fixed}. We generally
1653 close bug reports rather quickly, even without confirmation, especially if
1654 we have run tests and can see that for us the problem is fixed. However,
1655 in doing so, it avoids misunderstandings if you leave a note while you are
1656 closing the bug that says something to the following effect:
1657 We are closing this bug because ... If for some reason, it does not fix
1658 your problem, please feel free to reopen it, or to open a new bug report
1659 describing the problem".
1661 We do not recommend that you attempt to edit any of the bug notes that have
1662 been submitted, nor to delete them or make them private. In fact, if
1663 someone accidentally makes a bug note private, you should ask the reason
1664 and if at all possible (with his agreement) make the bug note public.
1666 If the user has not properly filled in most of the important fields
1667 (platorm, OS, Product Version, ...) please do not hesitate to politely ask
1668 him. Also, if the bug report is a request for a new feature, please
1669 politely send the user to the Feature Request menu item on www.bacula.org.
1670 The same applies to a support request (we answer only bugs), you might give
1671 the user a tip, but please politely refer him to the manual and the
1672 Getting Support page of www.bacula.org.