4 \section*{Bacula Developer Notes}
5 \label{_ChapterStart10}
6 \index{Bacula Developer Notes}
7 \index{Notes!Bacula Developer}
8 \addcontentsline{toc}{section}{Bacula Developer Notes}
12 \addcontentsline{toc}{subsection}{General}
14 This document is intended mostly for developers and describes the the general
15 framework of making Bacula source changes.
17 \subsubsection*{Contributions}
19 \addcontentsline{toc}{subsubsection}{Contributions}
21 Contributions from programmers are broken into two groups. The first are
22 contributions that are aids and not essential to Bacula. In general, these
23 will be scripts or will go into and examples or contributions directory.
24 For these kinds of non-essential contributions there is no obligation to do
25 a copyright assignment as described below. However, a copyright assignment
26 would still be appreciated.
28 The second class of contributions are those which will be integrated with
29 Bacula and become an essential part. Within this class of contributions, there
30 are two hurdles to surmount. One is getting your patch accepted, and two is
31 dealing with copyright issues. The following text describes some of the
32 requirements for such code.
34 \subsubsection*{Patches}
36 \addcontentsline{toc}{subsubsection}{Patches}
38 Subject to the copyright assignment described below, your patches should be
39 sent in {\bf diff -u} format relative to the current contents of the Source
40 Forge SVN, which is the easiest to understand and integrate.
41 Please be sure to use the Bacula indenting standard (see below).
42 If you have checked out the source with SVN, you can get a diff using:
46 svn diff > change.patch
49 If you plan on doing significant development work over a period of time,
50 after having your first patch reviewed and approved, you will be eligible
51 for having developer SVN access so that you can commit your changes
52 directly to the SVN repository. To do so, you will need a userid on Source
55 \subsubsection*{Copyrights}
57 \addcontentsline{toc}{subsubsection}{Copyrights}
59 To avoid future problems concerning changing licensing or
60 copyrights, all code contributions more than a hand full of lines
61 must be in the Public Domain or have the copyright transferred to
62 the Free Software Foundation Europe e.V. with a Fiduciary License
63 Agreement (FLA) as in the current code. Note, prior to
64 November 2004, the code was copyrighted by Kern Sibbald and John
65 Walker. After November 2004, the code was copyrighted by Kern
66 Sibbald, then on the 15th of November 2006, the copyright was
67 transferred to the Free Software Foundation Europe e.V.
69 Your name should be clearly indicated as the author of the code, and you
70 must be extremely careful not to violate any copyrights or use other
71 people's code without acknowledging it. The purpose of this requirement is
72 to avoid future copyright, patent, or intellectual property problems.
73 Please read the LICENSE agreement in the main source code
74 directory. When you sign the Fiduciary License Agreement (FLA)
75 and send it in, you are argeeing to the terms of that LICENSE
78 To understand the possible source of future problems, please
79 examine the difficulties Mozilla is (was?) having finding
80 previous contributors at \elink{
81 http://www.mozilla.org/MPL/missing.html}
82 {http://www.mozilla.org/MPL/missing.html}. The other important issue is to
83 avoid copyright, patent, or intellectual property violations as are currently
84 (May 2003) being claimed by SCO against IBM.
86 Although the copyright will be held by the Free Software
87 Foundation Europe e.V., each developer is expected to indicate
88 that he wrote and/or modified a particular module (or file) and
89 any other sources. The copyright assignment may seem a bit
90 unusual, but in reality, it is not. Most large projects require
93 If you have any doubts about this, please don't hesitate to ask. The
94 objective is to assure the long term servival of the Bacula project.
96 Items not needing a copyright assignment are: most small changes,
97 enhancements, or bug fixes of 5-10 lines of code, which amount to
98 less than 20% of any particular file.
100 \subsubsection*{Copyright Assignment -- Fiduciary License Agreement}
101 \index{Copyright Assignment}
102 \index{Assignment!Copyright}
103 \addcontentsline{toc}{subsubsection}{Copyright Assignment -- Fiduciary License Agreement}
105 Since this is not a commercial enterprise, and we prefer to believe in
106 everyone's good faith, previously developers could assign the copyright by
107 explicitly acknowledging that they do so in their first submission. This
108 was sufficient if the developer is independent, or an employee of a
109 not-for-profit organization or a university. However, in an effort to
110 ensure that the Bacula code is really clean, beginning in August 2006, all
111 previous and future developers with SVN access will be asked to submit a
112 copyright assignment (or Fiduciary License Agreement -- FLA),
113 which means you agree to the LICENSE in the main source
114 directory. It also means that you receive back the right to use
115 the code that you have submitted.
117 Any developer who wants to contribute and is employed by a company should
118 either list the employer as the owner of the code, or get
119 explicit permission from him to sign the copyright assignment.
120 This is because in many
121 countries, all work that an employee does whether on company time or in the
122 employee's free time is considered to be Intellectual Property of the
123 company. Obtaining official approval or an FLA from the company will avoid
124 misunderstandings between the employee, the company, and the Bacula
125 project. A good number of companies have already followed this procedure.
127 The Fiduciary License Agreement is posted on the Bacula web site at:
128 \elink{http://www.bacula.org/FLA-bacula.en.pdf}{http://www.bacula.org/FLA-bacula.en.pdf}
130 The instructions for filling out this agreement are also at:
131 \elink{http://www.bacula.org/?page=fsfe}{http://www.bacula.org/?page=fsfe}
133 It should be filled out, then sent to:
136 Free Software Foundation Europe
143 Please note that the above address is different from the officially
144 registered office mentioned in the document. When you send in such a
145 complete document, please notify me: kern at sibbald dot com.
149 \subsection*{The Development Cycle}
150 \index{Developement Cycle}
151 \index{Cycle!Developement}
152 \addcontentsline{toc}{subsubsection}{Development Cycle}
154 As I noted in the 1.38 ReleaseNotes, version 1.38 was different from prior
155 versions because it had a lot more contributions. I expect that this trend
156 will continue. As a consequence, I am going to modify how I normally do
157 development, and instead of making a list of all the features that I will
158 implement in the next version, I will personally sign up for one (maybe
159 two) projects at a time, and when they are complete, I will release a new
162 The difference is that I will have more time to review the new code that is
163 being contributed, and will be able to devote more time to a smaller number
164 of projects (1.38 had too many new features for me to handle correctly).
166 I expect that future release schedules will be much the same, and the
167 number of new features will also be much the same providing that the
168 contributions continue to come -- and they show no signs of let up :-)
170 \index{Feature Requests}
171 {\bf Feature Requests:} \\
172 In addition, I would like to "formalize" the feature requests a bit.
174 Instead of me maintaining an informal list of everything I run into
175 (kernstodo), I would like to maintain a "formal" list of projects. This
176 means that all new feature requests, including those recently discussed on
177 the email lists, must be formally submitted and approved.
179 Formal submission of feature requests will take two forms: \\
180 1. non-mandatory, but highly recommended is to discuss proposed new features
181 on the mailing list.\\
182 2. Formal submission of an Feature Request in a special format.
183 I'll give an example of this below, but you can also find it on the web
184 site under "Support -\gt{} Feature Requests". Since it takes a bit of time to
185 properly fill out a Feature Request form, you probably should check on the email list
188 Once the Feature Request is received by the keeper of the projects list, it
189 will be sent to me, and I will either accept it, send it back
190 asking for clarification, send it to the email list asking for opinions, or
193 If it is accepted, it will go in the "projects" file (a simple ASCII file)
194 maintained in the main Bacula source directory.
196 {\bf Implementation of Feature Requests:}\\
197 Any qualified developer can sign up for a project. The project must have
198 an entry in the projects file, and the developer's name will appear in the
201 {\bf How Feature Requests are accepted:}\\
202 Acceptance of Feature Requests depends on several things: \\
203 1. feedback from users. If it is negative, the Feature Request will probably not be
205 2. the difficulty of the project. A project that is so
206 difficult that I cannot imagine finding someone to implement probably won't
208 3. whether or not the Feature Request fits within the
209 current stategy of Bacula (for example an Feature Request that requests changing the
210 tape to tar format would not be accepted, ...)
212 {\bf How Feature Requests are prioritized:}\\
213 Once an Feature Request is accepted, it needs to be implemented. If you
214 can find a developer for it, or one signs up for implementing it, then the
215 Feature Request becomes top priority (at least for that developer).
217 Between releases of Bacula, we will generally solicit Feature Request input
218 for the next version, and by way of this email, we suggest that you send
219 discuss and send in your Feature Requests for the next release. Please
220 verify that the Feature Request is not in the current list (attached to this email).
222 Once users have had several weeks to submit Feature Requests, the keeper of the
224 organize them, and request users to vote on them. This will allow fixing
225 prioritizing the Feature Requests. Having a priority is one thing, but
226 getting it implement is another thing -- we are hoping that the Bacula
227 community will take more responsibility for assuring the implementation of
228 accepted Feature Requests.
230 Feature Request format:
232 ============= Empty Feature Request form ===========
233 Item n: One line summary ...
235 Origin: Name and email of originator.
238 What: More detailed explanation ...
240 Why: Why it is important ...
242 Notes: Additional notes or features (omit if not used)
243 ============== End Feature Request form ==============
247 ============= Example Completed Feature Request form ===========
248 Item 1: Implement a Migration job type that will move the job
249 data from one device to another.
250 Origin: Sponsored by Riege Sofware International GmbH. Contact:
251 Daniel Holtkamp <holtkamp at riege dot com>
252 Date: 28 October 2005
253 Status: Partially coded in 1.37 -- much more to do. Assigned to
256 What: The ability to copy, move, or archive data that is on a
257 device to another device is very important.
259 Why: An ISP might want to backup to disk, but after 30 days
260 migrate the data to tape backup and delete it from
261 disk. Bacula should be able to handle this
262 automatically. It needs to know what was put where,
263 and when, and what to migrate -- it is a bit like
264 retention periods. Doing so would allow space to be
265 freed up for current backups while maintaining older
268 Notes: Migration could be triggered by:
272 Highwater size (keep total size)
274 =================================================
278 \subsection*{Bacula Code Submissions and Projects}
279 \index{Submissions and Projects}
280 \addcontentsline{toc}{subsection}{Code Submissions and Projects}
282 Getting code implemented in Bacula works roughly as follows:
286 \item Kern is the project manager, but prefers not to be a "gate keeper".
288 \item There are growing numbers of contributions (very good).
290 \item Some contributions come in the form of relatively small patches,
291 which Kern reviews, integrates, documents, tests, and maintains.
293 \item All Bacula developers take full
294 responsibility for writing the code, posting as patches so that I can
295 review it as time permits, integrating it at an appropriate time,
296 responding to my requests for tweaking it (name changes, ...),
297 document it in the code, document it in the manual (even though
298 their mother tongue is not English), test it, develop and commit
299 regression scripts, and answer in a timely fashion all bug reports --
300 even occassionally accepting additional bugs :-)
302 This is a sustainable way of going forward with Bacula, and the
303 direction that the project will be taking more and more. For
304 example, in the past, we have had some very dedicated programmers
305 who did major projects. However, these
306 programmers due to outside obligations (job responsibilities change of
307 job, school duties, ...) could not continue to maintain the code. In
308 those cases, the code suffers from lack of maintenance, sometimes I
309 patch it, sometimes not. In the end, the code gets dropped from the
310 project (there are two such contributions that are heading in that
311 direction). When ever possible, we would like to avoid this, and
312 ensure a continuation of the code and a sharing of the development,
313 debugging, documentation, and maintenance responsibilities.
316 \subsection*{SVN Usage}
318 \addcontentsline{toc}{subsection}{SVN Usage}
320 Please note that if you are familar with CVS, SVN is very
321 similar (and better), but there can be a few surprising
324 The *entire* Bacula SourceForge.net Subversion repository can be
325 checked out through SVN with the following command:
328 svn checkout https://bacula.svn.sourceforge.net/svnroot/bacula bacula
331 With the above command, you will get everything, which is a very large
353 Note, you should NEVER commit code to any checkout that you have
354 done of a tag. All tags (e.g. Release-1.1, ... Release-2.0.2)
355 should be considered read-only.
357 You may commit code to the most recent item in
358 branches (in the above the most recent one is Branch-2.0). If
359 you want to commit code to an older branch, then please contact
362 You may create your own tags and/or branches, but they should
363 have a name clearly distinctive from Branch-, Release-, or Beta-,
364 which are official names used by the project. If you create a
365 tag, then you should NEVER commit code to it, for the same
366 reason noted above -- it should serve as a marker for something
367 you released. If you create a branch, then you are free to
368 commit to it as you wish.
370 You may, of course, commit to the trunk.
382 are reserved names to be created only by the project manager (or
383 with his OK), where the nnn is any sequence of numbers and
384 periods (e.g. 2.0, 2.0.1, ...).
386 In addition all tags even those that you create are read-only
387 forever. Typically tags represent release points either in the
388 trunc or in a branch.
391 Coming back to getting source code.
392 If you only want the current Bacula source code, you could use:
395 svn checkout https://bacula.svn.sourceforge.net/svnroot/bacula/trunk/bacula bacula
398 To view what is in the SVN, point your browser at the following URL:
399 http://bacula.svn.sourceforge.net/viewvc/bacula/
401 Many of the Subversion (svn) commands are almost identical to those that
402 you have used for cvs, but some (such as a checkout) can have surprising
403 results, so you should take a careful look at the documentation.
405 Robert has kindly provided the following documentation on the new
406 svn repository and how to use it:
408 Here is the list of branches:
425 Release-1.1 Release-1.19 Release-1.19a Release-1.19b
426 Release-1.20 Release-1.21 Release-1.22 Release-1.23
427 Release-1.23a Release-1.24 Release-1.25 Release-1.25a
428 Release-1.26 Release-1.27 Release-1.27a Release-1.27b
429 Release-1.27c Release-1.28 Release-1.29 Release-1.30
430 Release-1.31 Release-1.31a Release-1.32 Release-1.32a
431 Release-1.32b Release-1.32c Release-1.32d Release-1.32e
432 Release-1.32f Release-1.32f-2 Release-1.32f-3 Release-1.32f-4
433 Release-1.32f-5 Release-1.34.0 Release-1.34.1 Release-1.34.3
434 Release-1.34.4 Release-1.34.5 Release-1.34.6 Release-1.35.1
435 Release-1.35.2 Release-1.35.3 Release-1.35.6 Release-1.35.7
436 Release-1.35.8 Release-1.36.0 Release-1.36.1 Release-1.36.2
437 Release-1.36.3 Release-1.38.0 Release-1.38.1 Release-1.38.10
438 Release-1.38.11 Release-1.38.2 Release-1.38.3 Release-1.38.4
439 Release-1.38.5 Release-1.38.6 Release-1.38.7 Release-1.38.8
440 Release-1.38.9 Release-1.8.1 Release-1.8.2 Release-1.8.3
441 Release-1.8.4 Release-1.8.5 Release-1.8.6 Release-2.0.0
442 Release-2.0.1 Release-2.0.2
445 Here is a list of commands to get you started. The recommended book is
446 "Version Control with Subversion", by Ben Collins-Sussmann,
447 Brian W. Fitzpatrick, and Michael Pilato, O'Reilly. The book is
448 Open Source, so it is also available on line at:
451 http://svnbook.red-bean.com
454 Get a list of commands
460 Get a help with a command
466 Checkout the HEAD revision of all modules from the project into the
470 svn co https://bacula.svn.sourceforge.net/svnroot/bacula/trunk bacula.new
473 Checkout the HEAD revision of the bacula module into the bacula subdirectory
476 svn checkout https://bacula.svn.sourceforge.net/svnroot/bacula/trunk/bacula
479 See which files have changed in the working copy
485 See which files are out of date
491 Add a new file file.c
497 Create a new directory
503 Delete an obsolete file
512 svn move file.c newfile.c
515 Move a file to a new location
518 svn move file.c ../newdir/file.c
521 Copy a file retaining the original history in the new file
524 svn copy file.c newfile.c
527 Update the working copy with the outstanding changes
533 Compare working copy with the repository
539 Commit the changes in the local working copy
545 Specify which files are ignored in the current directory
548 svn propedit svn:ignore .
551 Mark a file to be executable
554 svn propset svn:executable '*' prog.sh
557 Unmark a file as executable
560 svn propdel svn:executable prog.sh
563 List a file's properties
569 Create a branch for a new version
572 svn copy https://bacula.svn.sourceforge.net/svnroot/bacula/trunk \
573 https://bacula.svn.sourceforge.net/svnroot/bacula/branches/Branch-2.1
576 Tag a version for a new release
579 svn copy https://bacula.svn.sourceforge.net/svnroot/bacula/branches/Branch-2.1 \
580 https://bacula.svn.sourceforge.net/svnroot/bacula/branches/Release-2.1
584 Let's say you are working in the directory scripts. You would then do:
591 when you are happy with your changes, you can do the following:
594 cd bacula (to your top level directory)
595 svn diff my-changes.patch
598 When the command is done, you can look in the file my-changes.patch
599 and you will see all the changes you have made to your copy of the
600 repository. Make sure that you understand all the changes that
601 it reports before proceeding. If you modified files that you do
602 do not want to commit to the main repository, you can simply delete
603 them from your local directory, and they will be restored from the
604 repository with the "svn update" that is shown below. Normally, you
605 should not find changes to files that you do not want to commit, and
606 if you find yourself in that position a lot, you are probably doing
609 Let's assume that now you want to commit your changes to the main
619 When you do this, it will pull any changes made by other developers into
620 your local copy of the repository, and it will check for conflicts. If there
621 are any, it will tell you, and you will need to resolve them. The problems
622 of resolving conflicts are a bit more than this document can cover, but
623 you can examine the files it claims have conflicts and look for \lt{}\lt{}\lt{}\lt{}
624 or look in the .rej files that it creates. If you have problems, just ask
625 on the developer's list.
627 Note, doing the above "svn update" is not absolutely necessary. There are
628 times when you may be working on code and you want to commit it, but you
629 explicitly do not want to move up to the latest version of the code in
630 the SVN. If that is the case, you can simply skip the "svn update" and
631 do the commit shown below. If the commit fails because of a conflict, it
632 will tell you, and you must resolve the conflict before it will permit
633 you to do the commit.
635 Once your local copy of the repository has been updated, you can now
639 svn commit -m "Some comment about what you changed"
642 or if you really only want to commit a single file, you can
646 svn commit -m "comment" scripts/file-I-edited
649 Note, if you have done a build in your directory, or you have added
650 other new files, the commit will update only the files that are
651 actually in the repository. For example, none of the object files
652 are stored in the repository, so when you do a commit, those object
653 files will simply be ignored.
655 If you want to add new files or remove files from the main SVN
656 repository, and you are not experienced with SVN, please ask Kern
657 to do it. If you follow the simple steps above, it is unlikely that
658 you will do any damage to the repository, and if you do, it is always
659 possible for us to recover, but it can be painful.
661 If you are only working in one subdirectory of say the bacula project,
662 for example, the scripts directory, you can do your commit from
663 that subdirectory, and only the changes in that directory and all its
664 subdirectories will be committed. This can be helpful for translators.
665 If you are doing a French translation, you will be working in
666 docs/manual-fr, and if you are always cd'ed into that directory when
667 doing your commits, your commit will effect only that directory. As
668 long as you are careful only to change files that you want changed,
669 you have little to worry about.
671 \subsection*{Subversion Resources}
672 \link{Subversion (svn) Resources}
673 \addcontentsline{toc}{subsection}{Subversion Resources}
678 Total CVS Files: 3286
679 Total CVS Revisions: 28924
680 Total Unique Tags: 63
681 Total Unique Branches: 11
682 CVS Repos Size in KB: 232421
683 Total SVN Commits: 4116
684 First Revision Date: Tue Apr 23 12:42:57 2002
685 Last Revision Date: Tue Feb 6 06:37:57 2007
688 The new Subversion repository size on Robert's machine:
695 190M bacula-tst/db/revs
696 17M bacula-tst/db/revprops
697 4.0K bacula-tst/db/transactions
703 Main Subversion Web Page
704 \elink{http://subversion.tigris.org}{http://subversion.tigris.org}
707 \elink{http://svnbook.red-bean.com}{http://svnbook.red-bean.com}
710 \elink{http://subversion.tigris.org/project_packages.html}{http://subversion.tigris.org/project_packages.html}
712 (For Windows users the TortoiseSVN package is awesome)
715 \elink{http://rapidsvn.tigris.org/}{http://rapidsvn.tigris.org/}
717 A nice KDE GUI client:
722 \subsection*{Developing Bacula}
723 \index{Developing Bacula}
724 \index{Bacula!Developing}
725 \addcontentsline{toc}{subsubsection}{Developing Bacula}
727 Typically the simplest way to develop Bacula is to open one xterm window
728 pointing to the source directory you wish to update; a second xterm window at
729 the top source directory level, and a third xterm window at the bacula
730 directory \lt{}top\gt{}/src/bacula. After making source changes in one of the
731 directories, in the top source directory xterm, build the source, and start
732 the daemons by entering:
736 ./startit then in the enter:
740 ./gnome-console to start the Console program. Enter any commands for testing.
741 For example: run kernsverify full.
743 Note, the instructions here to use {\bf ./startit} are different from using a
744 production system where the administrator starts Bacula by entering {\bf
745 ./bacula start}. This difference allows a development version of {\bf Bacula}
746 to be run on a computer at the same time that a production system is running.
747 The {\bf ./startit} strip starts {\bf Bacula} using a different set of
748 configuration files, and thus permits avoiding conflicts with any production
751 To make additional source changes, exit from the Console program, and in the
752 top source directory, stop the daemons by entering:
754 ./stopit then repeat the process.
756 \subsubsection*{Debugging}
758 \addcontentsline{toc}{subsubsection}{Debugging}
760 Probably the first thing to do is to turn on debug output.
762 A good place to start is with a debug level of 20 as in {\bf ./startit -d20}.
763 The startit command starts all the daemons with the same debug level.
764 Alternatively, you can start the appropriate daemon with the debug level you
765 want. If you really need more info, a debug level of 60 is not bad, and for
766 just about everything a level of 200.
768 \subsubsection*{Using a Debugger}
769 \index{Using a Debugger}
770 \index{Debugger!Using a}
771 \addcontentsline{toc}{subsubsection}{Using a Debugger}
773 If you have a serious problem such as a segmentation fault, it can usually be
774 found quickly using a good multiple thread debugger such as {\bf gdb}. For
775 example, suppose you get a segmentation violation in {\bf bacula-dir}. You
776 might use the following to find the problem:
778 \lt{}start the Storage and File daemons\gt{}
781 run -f -s -c ./dird.conf
782 \lt{}it dies with a segmentation fault\gt{}
784 The {\bf -f} option is specified on the {\bf run} command to inhibit {\bf
785 dird} from going into the background. You may also want to add the {\bf -s}
786 option to the run command to disable signals which can potentially interfere
789 As an alternative to using the debugger, each {\bf Bacula} daemon has a built
790 in back trace feature when a serious error is encountered. It calls the
791 debugger on itself, produces a back trace, and emails the report to the
792 developer. For more details on this, please see the chapter in the main Bacula
793 manual entitled ``What To Do When Bacula Crashes (Kaboom)''.
795 \subsubsection*{Memory Leaks}
798 \addcontentsline{toc}{subsubsection}{Memory Leaks}
800 Because Bacula runs routinely and unattended on client and server machines, it
801 may run for a long time. As a consequence, from the very beginning, Bacula
802 uses SmartAlloc to ensure that there are no memory leaks. To make detection of
803 memory leaks effective, all Bacula code that dynamically allocates memory MUST
804 have a way to release it. In general when the memory is no longer needed, it
805 should be immediately released, but in some cases, the memory will be held
806 during the entire time that Bacula is executing. In that case, there MUST be a
807 routine that can be called at termination time that releases the memory. In
808 this way, we will be able to detect memory leaks. Be sure to immediately
809 correct any and all memory leaks that are printed at the termination of the
812 \subsubsection*{Special Files}
813 \index{Files!Special}
814 \index{Special Files}
815 \addcontentsline{toc}{subsubsection}{Special Files}
817 Kern uses files named 1, 2, ... 9 with any extension as scratch files. Thus
818 any files with these names are subject to being rudely deleted at any time.
820 \subsubsection*{When Implementing Incomplete Code}
821 \index{Code!When Implementing Incomplete}
822 \index{When Implementing Incomplete Code}
823 \addcontentsline{toc}{subsubsection}{When Implementing Incomplete Code}
825 Please identify all incomplete code with a comment that contains
831 where there are three asterisks (*) before and after the word
832 FIXME (in capitals) and no intervening spaces. This is important as it allows
833 new programmers to easily recognize where things are partially implemented.
835 \subsubsection*{Bacula Source File Structure}
836 \index{Structure!Bacula Source File}
837 \index{Bacula Source File Structure}
838 \addcontentsline{toc}{subsubsection}{Bacula Source File Structure}
840 The distribution generally comes as a tar file of the form {\bf
841 bacula.x.y.z.tar.gz} where x, y, and z are the version, release, and update
842 numbers respectively.
844 Once you detar this file, you will have a directory structure as follows:
851 |- mtx (autochanger control program + tape drive info)
852 |- sqlite (SQLite database program)
856 |- pthreads (Native win32 pthreads library -- dll)
857 |- zlib (Native win32 zlib library)
858 |- wx (wxWidgets source code)
861 |- bacula (main source directory containing configuration
862 | and installation files)
863 |- autoconf (automatic configuration files, not normally used
865 |- intl (programs used to translate)
866 |- platforms (OS specific installation files)
867 |- redhat (Red Hat installation)
868 |- solaris (Sun installation)
869 |- freebsd (FreeBSD installation)
870 |- irix (Irix installation -- not tested)
871 |- unknown (Default if system not identified)
872 |- po (translations of source strings)
873 |- src (source directory; contains global header files)
874 |- cats (SQL catalog database interface directory)
875 |- console (bacula user agent directory)
876 |- dird (Director daemon)
877 |- filed (Unix File daemon)
878 |- win32 (Win32 files to make bacula-fd be a service)
879 |- findlib (Unix file find library for File daemon)
880 |- gnome-console (GNOME version of console program)
881 |- lib (General Bacula library)
882 |- stored (Storage daemon)
883 |- tconsole (Tcl/tk console program -- not yet working)
884 |- testprogs (test programs -- normally only in Kern's tree)
885 |- tools (Various tool programs)
886 |- win32 (Native Win32 File daemon)
887 |- baculafd (Visual Studio project file)
888 |- compat (compatibility interface library)
889 |- filed (links to src/filed)
890 |- findlib (links to src/findlib)
891 |- lib (links to src/lib)
892 |- console (beginning of native console program)
893 |- wx-console (wxWidget console Win32 specific parts)
894 |- wx-console (wxWidgets console main source program)
897 |- regress (Regression scripts)
898 |- bin (temporary directory to hold Bacula installed binaries)
899 |- build (temporary directory to hold Bacula source)
900 |- scripts (scripts and .conf files)
901 |- tests (test scripts)
902 |- tmp (temporary directory for temp files)
903 |- working (temporary working directory for Bacula daemons)
906 |- docs (documentation directory)
907 |- developers (Developer's guide)
908 |- home-page (Bacula's home page source)
909 |- manual (html document directory)
910 |- manual-fr (French translation)
911 |- manual-de (German translation)
912 |- techlogs (Technical development notes);
915 |- rescue (Bacula rescue CDROM)
916 |- linux (Linux rescue CDROM)
917 |- cdrom (Linux rescue CDROM code)
919 |- solaris (Solaris rescue -- incomplete)
920 |- freebsd (FreeBSD rescue -- incomplete)
923 |- gui (Bacula GUI projects)
924 |- bacula-web (Bacula web php management code)
925 |- bimagemgr (Web application for burning CDROMs)
931 \subsubsection*{Header Files}
934 \addcontentsline{toc}{subsubsection}{Header Files}
936 Please carefully follow the scheme defined below as it permits in general only
937 two header file includes per C file, and thus vastly simplifies programming.
938 With a large complex project like Bacula, it isn't always easy to ensure that
939 the right headers are invoked in the right order (there are a few kludges to
940 make this happen -- i.e. in a few include files because of the chicken and egg
941 problem, certain references to typedefs had to be replaced with {\bf void} ).
943 Every file should include {\bf bacula.h}. It pulls in just about everything,
944 with very few exceptions. If you have system dependent ifdefing, please do it
945 in {\bf baconfig.h}. The version number and date are kept in {\bf version.h}.
947 Each of the subdirectories (console, cats, dird, filed, findlib, lib, stored,
948 ...) contains a single directory dependent include file generally the name of
949 the directory, which should be included just after the include of {\bf
950 bacula.h}. This file (for example, for the dird directory, it is {\bf dird.h})
951 contains either definitions of things generally needed in this directory, or
952 it includes the appropriate header files. It always includes {\bf protos.h}.
955 Each subdirectory contains a header file named {\bf protos.h}, which contains
956 the prototypes for subroutines exported by files in that directory. {\bf
957 protos.h} is always included by the main directory dependent include file.
959 \subsubsection*{Programming Standards}
960 \index{Standards!Programming}
961 \index{Programming Standards}
962 \addcontentsline{toc}{subsubsection}{Programming Standards}
964 For the most part, all code should be written in C unless there is a burning
965 reason to use C++, and then only the simplest C++ constructs will be used.
966 Note, Bacula is slowly evolving to use more and more C++.
968 Code should have some documentation -- not a lot, but enough so that I can
969 understand it. Look at the current code, and you will see that I document more
970 than most, but am definitely not a fanatic.
972 I prefer simple linear code where possible. Gotos are strongly discouraged
973 except for handling an error to either bail out or to retry some code, and
974 such use of gotos can vastly simplify the program.
976 Remember this is a C program that is migrating to a {\bf tiny} subset of C++,
977 so be conservative in your use of C++ features.
979 \subsubsection*{Do Not Use}
982 \addcontentsline{toc}{subsubsection}{Do Not Use}
985 \item STL -- it is totally incomprehensible.
988 \subsubsection*{Avoid if Possible}
989 \index{Possible!Avoid if}
990 \index{Avoid if Possible}
991 \addcontentsline{toc}{subsubsection}{Avoid if Possible}
994 \item Using {\bf void *} because this generally means that one must
995 using casting, and in C++ casting is rather ugly. It is OK to use
996 void * to pass structure address where the structure is not known
997 to the routines accepting the packet (typically callback routines).
998 However, declaring "void *buf" is a bad idea. Please use the
999 correct types whenever possible.
1001 \item Using undefined storage specifications such as (short, int, long,
1002 long long, size_t ...). The problem with all these is that the number of bytes
1003 they allocate depends on the compiler and the system. Instead use
1004 Bacula's types (int8_t, uint8_t, int32_t, uint32_t, int64_t, and
1005 uint64_t). This guarantees that the variables are given exactly the
1006 size you want. Please try at all possible to avoid using size_t ssize_t
1007 and the such. They are very system dependent. However, some system
1008 routines may need them, so their use is often unavoidable.
1010 \item Returning a malloc'ed buffer from a subroutine -- someone will forget
1013 \item Heap allocation (malloc) unless needed -- it is expensive. Use
1016 \item Templates -- they can create portability problems.
1018 \item Fancy or tricky C or C++ code, unless you give a good explanation of
1021 \item Too much inheritance -- it can complicate the code, and make reading it
1022 difficult (unless you are in love with colons)
1026 \subsubsection*{Do Use Whenever Possible}
1027 \index{Possible!Do Use Whenever}
1028 \index{Do Use Whenever Possible}
1029 \addcontentsline{toc}{subsubsection}{Do Use Whenever Possible}
1032 \item Locking and unlocking within a single subroutine.
1034 \item A single point of exit from all subroutines. A goto is
1035 perfectly OK to use to get out early, but only to a label
1036 named bail_out, and possibly an ok_out. See current code
1039 \item Malloc and free within a single subroutine.
1041 \item Comments and global explanations on what your code or algorithm does.
1045 \subsubsection*{Indenting Standards}
1046 \index{Standards!Indenting}
1047 \index{Indenting Standards}
1048 \addcontentsline{toc}{subsubsection}{Indenting Standards}
1050 I cannot stand code indented 8 columns at a time. This makes the code
1051 unreadable. Even 4 at a time uses a lot of space, so I have adopted indenting
1052 3 spaces at every level. Note, indention is the visual appearance of the
1053 source on the page, while tabbing is replacing a series of up to 8 spaces from
1056 The closest set of parameters for the Linux {\bf indent} program that will
1057 produce reasonably indented code are:
1061 -nbad -bap -bbo -nbc -br -brs -c36 -cd36 -ncdb -ce -ci3 -cli0
1062 -cp36 -d0 -di1 -ndj -nfc1 -nfca -hnl -i3 -ip0 -l85 -lp -npcs
1063 -nprs -npsl -saf -sai -saw -nsob -nss -nbc -ncs -nbfda
1067 You can put the above in your .indent.pro file, and then just invoke indent on
1068 your file. However, be warned. This does not produce perfect indenting, and it
1069 will mess up C++ class statements pretty badly.
1071 Braces are required in all if statements (missing in some very old code). To
1072 avoid generating too many lines, the first brace appears on the first line
1073 (e.g. of an if), and the closing brace is on a line by itself. E.g.
1083 Just follow the convention in the code. Originally I indented case clauses
1084 under a switch(), but now I prefer non-indented cases.
1101 Avoid using // style comments except for temporary code or turning off debug
1102 code. Standard C comments are preferred (this also keeps the code closer to
1105 Attempt to keep all lines less than 85 characters long so that the whole line
1106 of code is readable at one time. This is not a rigid requirement.
1108 Always put a brief description at the top of any new file created describing
1109 what it does and including your name and the date it was first written. Please
1110 don't forget any Copyrights and acknowledgments if it isn't 100\% your code.
1111 Also, include the Bacula copyright notice that is in {\bf src/c}.
1113 In general you should have two includes at the top of the an include for the
1114 particular directory the code is in, for includes are needed, but this should
1117 In general (except for self-contained packages), prototypes should all be put
1118 in {\bf protos.h} in each directory.
1120 Always put space around assignment and comparison operators.
1131 but your can compress things in a {\bf for} statement:
1135 for (i=0; i < del.num_ids; i++) {
1140 Don't overuse the inline if (?:). A full {\bf if} is preferred, except in a
1141 print statement, e.g.:
1145 if (ua->verbose \&& del.num_del != 0) {
1146 bsendmsg(ua, _("Pruned %d %s on Volume %s from catalog.\n"), del.num_del,
1147 del.num_del == 1 ? "Job" : "Jobs", mr->VolumeName);
1152 Leave a certain amount of debug code (Dmsg) in code you submit, so that future
1153 problems can be identified. This is particularly true for complicated code
1154 likely to break. However, try to keep the debug code to a minimum to avoid
1155 bloating the program and above all to keep the code readable.
1157 Please keep the same style in all new code you develop. If you include code
1158 previously written, you have the option of leaving it with the old indenting
1159 or re-indenting it. If the old code is indented with 8 spaces, then please
1160 re-indent it to Bacula standards.
1162 If you are using {\bf vim}, simply set your tabstop to 8 and your shiftwidth
1165 \subsubsection*{Tabbing}
1167 \addcontentsline{toc}{subsubsection}{Tabbing}
1169 Tabbing (inserting the tab character in place of spaces) is as normal on all
1170 Unix systems -- a tab is converted space up to the next column multiple of 8.
1171 My editor converts strings of spaces to tabs automatically -- this results in
1172 significant compression of the files. Thus, you can remove tabs by replacing
1173 them with spaces if you wish. Please don't confuse tabbing (use of tab
1174 characters) with indenting (visual alignment of the code).
1176 \subsubsection*{Don'ts}
1178 \addcontentsline{toc}{subsubsection}{Don'ts}
1193 They are system dependent and un-safe. These should be replaced by the Bacula
1198 char *bstrncpy(char *dest, char *source, int dest_size);
1199 char *bstrncat(char *dest, char *source, int dest_size);
1200 int bsnprintf(char *buf, int32_t buf_len, const char *fmt, ...);
1201 int bvsnprintf(char *str, int32_t size, const char *format, va_list ap);
1205 See src/lib/bsys.c for more details on these routines.
1207 Don't use the {\bf \%lld} or the {\bf \%q} printf format editing types to edit
1208 64 bit integers -- they are not portable. Instead, use {\bf \%s} with {\bf
1209 edit\_uint64()}. For example:
1214 uint64_t num = something;
1216 bsnprintf(buf, sizeof(buf), "Num=%s\n", edit_uint64(num, ed1));
1220 The edit buffer {\bf ed1} must be at least 27 bytes long to avoid overflow.
1221 See src/lib/edit.c for more details. If you look at the code, don't start
1222 screaming that I use {\bf lld}. I actually use subtle trick taught to me by
1223 John Walker. The {\bf lld} that appears in the editing routine is actually
1224 {\bf \#define} to a what is needed on your OS (usually ``lld'' or ``q'') and
1225 is defined in autoconf/configure.in for each OS. C string concatenation causes
1226 the appropriate string to be concatenated to the ``\%''.
1228 Also please don't use the STL or Templates or any complicated C++ code.
1230 \subsubsection*{Message Classes}
1231 \index{Classes!Message}
1232 \index{Message Classes}
1233 \addcontentsline{toc}{subsubsection}{Message Classes}
1235 Currently, there are five classes of messages: Debug, Error, Job, Memory,
1238 \subsubsection*{Debug Messages}
1239 \index{Messages!Debug}
1240 \index{Debug Messages}
1241 \addcontentsline{toc}{subsubsection}{Debug Messages}
1243 Debug messages are designed to be turned on at a specified debug level and are
1244 always sent to STDOUT. There are designed to only be used in the development
1245 debug process. They are coded as:
1247 DmsgN(level, message, arg1, ...) where the N is a number indicating how many
1248 arguments are to be substituted into the message (i.e. it is a count of the
1249 number arguments you have in your message -- generally the number of percent
1250 signs (\%)). {\bf level} is the debug level at which you wish the message to
1251 be printed. message is the debug message to be printed, and arg1, ... are the
1252 arguments to be substituted. Since not all compilers support \#defines with
1253 varargs, you must explicitly specify how many arguments you have.
1255 When the debug message is printed, it will automatically be prefixed by the
1256 name of the daemon which is running, the filename where the Dmsg is, and the
1257 line number within the file.
1259 Some actual examples are:
1261 Dmsg2(20, ``MD5len=\%d MD5=\%s\textbackslash{}n'', strlen(buf), buf);
1263 Dmsg1(9, ``Created client \%s record\textbackslash{}n'', client->hdr.name);
1265 \subsubsection*{Error Messages}
1266 \index{Messages!Error}
1267 \index{Error Messages}
1268 \addcontentsline{toc}{subsubsection}{Error Messages}
1270 Error messages are messages that are related to the daemon as a whole rather
1271 than a particular job. For example, an out of memory condition my generate an
1272 error message. They should be very rarely needed. In general, you should be
1273 using Job and Job Queued messages (Jmsg and Qmsg). They are coded as:
1275 EmsgN(error-code, level, message, arg1, ...) As with debug messages, you must
1276 explicitly code the of arguments to be substituted in the message. error-code
1277 indicates the severity or class of error, and it may be one of the following:
1279 \addcontentsline{lot}{table}{Message Error Code Classes}
1280 \begin{longtable}{lp{3in}}
1281 {{\bf M\_ABORT} } & {Causes the daemon to immediately abort. This should be
1282 used only in extreme cases. It attempts to produce a traceback. } \\
1283 {{\bf M\_ERROR\_TERM} } & {Causes the daemon to immediately terminate. This
1284 should be used only in extreme cases. It does not produce a traceback. } \\
1285 {{\bf M\_FATAL} } & {Causes the daemon to terminate the current job, but the
1286 daemon keeps running } \\
1287 {{\bf M\_ERROR} } & {Reports the error. The daemon and the job continue
1289 {{\bf M\_WARNING} } & {Reports an warning message. The daemon and the job
1290 continue running } \\
1291 {{\bf M\_INFO} } & {Reports an informational message.}
1295 There are other error message classes, but they are in a state of being
1296 redesigned or deprecated, so please do not use them. Some actual examples are:
1299 Emsg1(M\_ABORT, 0, ``Cannot create message thread: \%s\textbackslash{}n'',
1302 Emsg3(M\_WARNING, 0, ``Connect to File daemon \%s at \%s:\%d failed. Retrying
1303 ...\textbackslash{}n'', client-\gt{}hdr.name, client-\gt{}address,
1306 Emsg3(M\_FATAL, 0, ``bdird\lt{}filed: bad response from Filed to \%s command:
1307 \%d \%s\textbackslash{}n'', cmd, n, strerror(errno));
1309 \subsubsection*{Job Messages}
1310 \index{Job Messages}
1311 \index{Messages!Job}
1312 \addcontentsline{toc}{subsubsection}{Job Messages}
1314 Job messages are messages that pertain to a particular job such as a file that
1315 could not be saved, or the number of files and bytes that were saved. They
1318 Jmsg(jcr, M\_FATAL, 0, "Text of message");
1320 A Jmsg with M\_FATAL will fail the job. The Jmsg() takes varargs so can
1321 have any number of arguments for substituted in a printf like format.
1322 Output from the Jmsg() will go to the Job report.
1324 If the Jmsg is followed with a number such as Jmsg1(...), the number
1325 indicates the number of arguments to be substituted (varargs is not
1326 standard for \#defines), and what is more important is that the file and
1327 line number will be prefixed to the message. This permits a sort of debug
1330 \subsubsection*{Queued Job Messages}
1331 \index{Queued Job Messages}
1332 \index{Messages!Job}
1333 \addcontentsline{toc}{subsubsection}{Queued Job Messages}
1334 Queued Job messages are similar to Jmsg()s except that the message is
1335 Queued rather than immediately dispatched. This is necessary within the
1336 network subroutines and in the message editing routines. This is to prevent
1337 recursive loops, and to ensure that messages can be delivered even in the
1338 event of a network error.
1341 \subsubsection*{Memory Messages}
1342 \index{Messages!Memory}
1343 \index{Memory Messages}
1344 \addcontentsline{toc}{subsubsection}{Memory Messages}
1346 Memory messages are messages that are edited into a memory buffer. Generally
1347 they are used in low level routines such as the low level device file dev.c in
1348 the Storage daemon or in the low level Catalog routines. These routines do not
1349 generally have access to the Job Control Record and so they return error
1350 messages reformatted in a memory buffer. Mmsg() is the way to do this.