\section*{Bacula Developer Notes}
\label{_ChapterStart10}
-\index{Bacula Developer Notes }
-\index{Notes!Bacula Developer }
+\index{Bacula Developer Notes}
+\index{Notes!Bacula Developer}
\addcontentsline{toc}{section}{Bacula Developer Notes}
\subsection*{General}
-\index{General }
+\index{General}
\addcontentsline{toc}{subsection}{General}
This document is intended mostly for developers and describes the the general
framework of making Bacula source changes.
\subsubsection*{Contributions}
-\index{Contributions }
+\index{Contributions}
\addcontentsline{toc}{subsubsection}{Contributions}
Contributions from programmers are broken into two groups. The first are
contributions that are aids and not essential to Bacula. In general, these
will be scripts or will go into and examples or contributions directory.
+For these kinds of non-essential contributions there is no obligation to do
+a copyright assignment as described below. However, a copyright assignment
+would still be appreciated.
The second class of contributions are those which will be integrated with
Bacula and become an essential part. Within this class of contributions, there
requirements for such code.
\subsubsection*{Patches}
-\index{Patches }
+\index{Patches}
\addcontentsline{toc}{subsubsection}{Patches}
Subject to the copyright assignment described below, your patches should be
sent in {\bf diff -u} format relative to the current contents of the Source
-Forge CVS, which is the easiest for me to understand. If you have checked
-out the source with CVS, you can get a diff using:
+Forge SVN, which is the easiest to understand and integrate.
+Please be sure to use the Bacula indenting standard (see below).
+If you have checked out the source with SVN, you can get a diff using:
\begin{verbatim}
-cvs diff -u
+svn update
+svn diff > change.patch
\end{verbatim}
-If you plan on doing
-significant development work over a period of time, after having your first
-patch reviewed and approved, you will be eligible for having developer CVS access so
-that you can commit your changes directly to the CVS repository. To do so, you
-will need a userid on Source Forge.
+If you plan on doing significant development work over a period of time,
+after having your first patch reviewed and approved, you will be eligible
+for having developer SVN access so that you can commit your changes
+directly to the SVN repository. To do so, you will need a userid on Source
+Forge.
\subsubsection*{Copyrights}
-\index{Copyrights }
+\index{Copyrights}
\addcontentsline{toc}{subsubsection}{Copyrights}
-To avoid future problems concerning changing licensing or copyrights, all code
-contributions more than a hand full of lines must be in the Public Domain or
-have the copyright assigned to Kern Sibbald as in the current code. Note,
-prior to November 2004, the code was copyrighted by Kern Sibbald and John
-Walker.
-
-Your name should be clearly indicated as the author of the code, and you must
-be extremely careful not to violate any copyrights or use other people's code
-without acknowledging it. The purpose of this requirement is to avoid future
-copyright, patent, or intellectual property problems. To understand on
-possible source of future problems, please examine the difficulties Mozilla is
-(was?) having finding previous contributors at
-\elink{
+To avoid future problems concerning changing licensing or
+copyrights, all code contributions more than a hand full of lines
+must be in the Public Domain or have the copyright transferred to
+the Free Software Foundation Europe e.V. with a Fiduciary License
+Agreement (FLA) as in the current code. Note, prior to
+November 2004, the code was copyrighted by Kern Sibbald and John
+Walker. After November 2004, the code was copyrighted by Kern
+Sibbald, then on the 15th of November 2006, the copyright was
+transferred to the Free Software Foundation Europe e.V.
+
+Your name should be clearly indicated as the author of the code, and you
+must be extremely careful not to violate any copyrights or use other
+people's code without acknowledging it. The purpose of this requirement is
+to avoid future copyright, patent, or intellectual property problems.
+Please read the LICENSE agreement in the main source code
+directory. When you sign the Fiduciary License Agreement (FLA)
+and send it in, you are argeeing to the terms of that LICENSE
+file.
+
+To understand the possible source of future problems, please
+examine the difficulties Mozilla is (was?) having finding
+previous contributors at \elink{
http://www.mozilla.org/MPL/missing.html}
{http://www.mozilla.org/MPL/missing.html}. The other important issue is to
avoid copyright, patent, or intellectual property violations as are currently
(May 2003) being claimed by SCO against IBM.
-Although the copyright will be held by Kern, each developer is expected to
-indicate that he wrote and/or modified a particular module (or file) and any
-other sources. The copyright assignment may seem a bit unusual, but in
-reality, it is not. Most large projects require this. In fact, the paperwork
-associated with making contributions to the Free Software Foundation, was for
-me unsurmountable.
-
-If you have any doubts about this, please don't hesitate to ask. Our (John and
-my) track records with Autodesk are easily available; early
-programmers/founders/contributors and later employees had substantial shares
-of the company, and no one founder had a controlling part of the company. Even
-though Microsoft created many millionaires among early employees, the politics
-of Autodesk (during our time at the helm) is in stark contrast to Microsoft
-where the majority of the company is still tightly held among a few.
+Although the copyright will be held by the Free Software
+Foundation Europe e.V., each developer is expected to indicate
+that he wrote and/or modified a particular module (or file) and
+any other sources. The copyright assignment may seem a bit
+unusual, but in reality, it is not. Most large projects require
+this.
+
+If you have any doubts about this, please don't hesitate to ask. The
+objective is to assure the long term servival of the Bacula project.
Items not needing a copyright assignment are: most small changes,
-enhancements, or bug fixes of 5-10 lines of code, and documentation.
-
-\subsubsection*{Copyright Assignment}
-\index{Copyright Assignment }
-\index{Assignment!Copyright }
-\addcontentsline{toc}{subsubsection}{Copyright Assignment}
-
-Since this is not a commercial enterprise, and I prefer to believe in
-everyone's good faith, developers can assign the copyright by explicitly
-acknowledging that they do so in their first submission. This is sufficient if
-the developer is independent, or an employee of a not-for-profit organization
-or a university. Any developer that wants to contribute and is employed by a
-company must get a copyright assignment from his employer. This is to avoid
-misunderstandings between the employee, the company, and the Bacula project.
-
-\subsubsection*{Corporate Assignment Statement}
-\index{Statement!Corporate Assignment }
-\index{Corporate Assignment Statement }
-\addcontentsline{toc}{subsubsection}{Corporate Assignment Statement}
-
-The following statement must be filled out by the employer, signed, and mailed
-to my address (please ask me for my address and I will email it -- I'd prefer
-not to include it here).
+enhancements, or bug fixes of 5-10 lines of code, which amount to
+less than 20% of any particular file.
+
+\subsubsection*{Copyright Assignment -- Fiduciary License Agreement}
+\index{Copyright Assignment}
+\index{Assignment!Copyright}
+\addcontentsline{toc}{subsubsection}{Copyright Assignment -- Fiduciary License Agreement}
+
+Since this is not a commercial enterprise, and we prefer to believe in
+everyone's good faith, previously developers could assign the copyright by
+explicitly acknowledging that they do so in their first submission. This
+was sufficient if the developer is independent, or an employee of a
+not-for-profit organization or a university. However, in an effort to
+ensure that the Bacula code is really clean, beginning in August 2006, all
+previous and future developers with SVN access will be asked to submit a
+copyright assignment (or Fiduciary License Agreement -- FLA),
+which means you agree to the LICENSE in the main source
+directory. It also means that you receive back the right to use
+the code that you have submitted.
+
+Any developer who wants to contribute and is employed by a company should
+either list the employer as the owner of the code, or get
+explicit permission from him to sign the copyright assignment.
+This is because in many
+countries, all work that an employee does whether on company time or in the
+employee's free time is considered to be Intellectual Property of the
+company. Obtaining official approval or an FLA from the company will avoid
+misunderstandings between the employee, the company, and the Bacula
+project. A good number of companies have already followed this procedure.
+
+The Fiduciary License Agreement is posted on the Bacula web site at:
+\elink{http://www.bacula.org/FLA-bacula.en.pdf}{http://www.bacula.org/FLA-bacula.en.pdf}
+
+The instructions for filling out this agreement are also at:
+\elink{http://www.bacula.org/?page=fsfe}{http://www.bacula.org/?page=fsfe}
+
+It should be filled out, then sent to:
-\footnotesize
\begin{verbatim}
-Copyright release and transfer statement.
- <On company letter head>
+ Free Software Foundation Europe
+ Freedom Task Force
+ Sumatrastrasse 25
+ 8006 Zürich
+ Switzerland
+\end{verbatim}
- To: Kern Sibbald
- Concerning: Copyright release and transfer
+Please note that the above address is different from the officially
+registered office mentioned in the document. When you send in such a
+complete document, please notify me: kern at sibbald dot com.
+
+
+
+\subsection*{The Development Cycle}
+\index{Developement Cycle}
+\index{Cycle!Developement}
+\addcontentsline{toc}{subsubsection}{Development Cycle}
+
+As I noted in the 1.38 ReleaseNotes, version 1.38 was different from prior
+versions because it had a lot more contributions. I expect that this trend
+will continue. As a consequence, I am going to modify how I normally do
+development, and instead of making a list of all the features that I will
+implement in the next version, I will personally sign up for one (maybe
+two) projects at a time, and when they are complete, I will release a new
+version.
+
+The difference is that I will have more time to review the new code that is
+being contributed, and will be able to devote more time to a smaller number
+of projects (1.38 had too many new features for me to handle correctly).
+
+I expect that future release schedules will be much the same, and the
+number of new features will also be much the same providing that the
+contributions continue to come -- and they show no signs of let up :-)
+
+\index{Feature Requests}
+{\bf Feature Requests:} \\
+In addition, I would like to "formalize" the feature requests a bit.
+
+Instead of me maintaining an informal list of everything I run into
+(kernstodo), I would like to maintain a "formal" list of projects. This
+means that all new feature requests, including those recently discussed on
+the email lists, must be formally submitted and approved.
+
+Formal submission of feature requests will take two forms: \\
+1. non-mandatory, but highly recommended is to discuss proposed new features
+on the mailing list.\\
+2. Formal submission of an Feature Request in a special format.
+I'll give an example of this below, but you can also find it on the web
+site under "Support -\gt{} Feature Requests". Since it takes a bit of time to
+properly fill out a Feature Request form, you probably should check on the email list
+first.
+
+Once the Feature Request is received by the keeper of the projects list, it
+will be sent to me, and I will either accept it, send it back
+asking for clarification, send it to the email list asking for opinions, or
+reject it.
+
+If it is accepted, it will go in the "projects" file (a simple ASCII file)
+maintained in the main Bacula source directory.
+
+{\bf Implementation of Feature Requests:}\\
+Any qualified developer can sign up for a project. The project must have
+an entry in the projects file, and the developer's name will appear in the
+Status field.
+
+{\bf How Feature Requests are accepted:}\\
+Acceptance of Feature Requests depends on several things: \\
+1. feedback from users. If it is negative, the Feature Request will probably not be
+accepted. \\
+2. the difficulty of the project. A project that is so
+difficult that I cannot imagine finding someone to implement probably won't
+be accepted. \\
+ 3. whether or not the Feature Request fits within the
+current stategy of Bacula (for example an Feature Request that requests changing the
+tape to tar format would not be accepted, ...)
+
+{\bf How Feature Requests are prioritized:}\\
+Once an Feature Request is accepted, it needs to be implemented. If you
+can find a developer for it, or one signs up for implementing it, then the
+Feature Request becomes top priority (at least for that developer).
+
+Between releases of Bacula, we will generally solicit Feature Request input
+for the next version, and by way of this email, we suggest that you send
+discuss and send in your Feature Requests for the next release. Please
+verify that the Feature Request is not in the current list (attached to this email).
+
+Once users have had several weeks to submit Feature Requests, the keeper of the
+projects list will
+organize them, and request users to vote on them. This will allow fixing
+prioritizing the Feature Requests. Having a priority is one thing, but
+getting it implement is another thing -- we are hoping that the Bacula
+community will take more responsibility for assuring the implementation of
+accepted Feature Requests.
+
+Feature Request format:
+\begin{verbatim}
+============= Empty Feature Request form ===========
+Item n: One line summary ...
+ Date: Date submitted
+ Origin: Name and email of originator.
+ Status:
- <Company, Inc> is hereby agrees that <names-of-developers> and
- other employees of <Company, Inc> are authorized to develop
- code for and contribute code to the Bacula project for an
- undetermined period of time. The copyright as well as all
- other rights to and interests in such contributed code are
- hereby transferred to Kern Sibbald.
+ What: More detailed explanation ...
- Signed in <City, Country> on <Date>:
+ Why: Why it is important ...
- <Name of Person>, <Position in Company, Inc>
+ Notes: Additional notes or features (omit if not used)
+============== End Feature Request form ==============
+\end{verbatim}
+\begin{verbatim}
+============= Example Completed Feature Request form ===========
+Item 1: Implement a Migration job type that will move the job
+ data from one device to another.
+ Origin: Sponsored by Riege Sofware International GmbH. Contact:
+ Daniel Holtkamp <holtkamp at riege dot com>
+ Date: 28 October 2005
+ Status: Partially coded in 1.37 -- much more to do. Assigned to
+ Kern.
+
+ What: The ability to copy, move, or archive data that is on a
+ device to another device is very important.
+
+ Why: An ISP might want to backup to disk, but after 30 days
+ migrate the data to tape backup and delete it from
+ disk. Bacula should be able to handle this
+ automatically. It needs to know what was put where,
+ and when, and what to migrate -- it is a bit like
+ retention periods. Doing so would allow space to be
+ freed up for current backups while maintaining older
+ data on tape drives.
+
+ Notes: Migration could be triggered by:
+ Number of Jobs
+ Number of Volumes
+ Age of Jobs
+ Highwater size (keep total size)
+ Lowwater mark
+=================================================
\end{verbatim}
-\normalsize
-This release/transfer statement must be sent to:
-Kern Sibbald
-Address-to-be-given
-\subsection*{Basic CVS Usage}
-\index{Basic CVS Usage}
-\index{CVS}
-\addcontentsline{toc}{subsection}{Basic CVS Usage}
+\subsection*{Bacula Code Submissions and Projects}
+\index{Submissions and Projects}
+\addcontentsline{toc}{subsection}{Code Submissions and Projects}
+
+Getting code implemented in Bacula works roughly as follows:
+
+\begin{itemize}
+
+\item Kern is the project manager, but prefers not to be a "gate keeper".
+
+\item There are growing numbers of contributions (very good).
+
+\item Some contributions come in the form of relatively small patches,
+ which Kern reviews, integrates, documents, tests, and maintains.
+
+\item All Bacula developers take full
+ responsibility for writing the code, posting as patches so that I can
+ review it as time permits, integrating it at an appropriate time,
+ responding to my requests for tweaking it (name changes, ...),
+ document it in the code, document it in the manual (even though
+ their mother tongue is not English), test it, develop and commit
+ regression scripts, and answer in a timely fashion all bug reports --
+ even occassionally accepting additional bugs :-)
+
+ This is a sustainable way of going forward with Bacula, and the
+ direction that the project will be taking more and more. For
+ example, in the past, we have had some very dedicated programmers
+ who did major projects. However, these
+ programmers due to outside obligations (job responsibilities change of
+ job, school duties, ...) could not continue to maintain the code. In
+ those cases, the code suffers from lack of maintenance, sometimes I
+ patch it, sometimes not. In the end, the code gets dropped from the
+ project (there are two such contributions that are heading in that
+ direction). When ever possible, we would like to avoid this, and
+ ensure a continuation of the code and a sharing of the development,
+ debugging, documentation, and maintenance responsibilities.
+\end{itemize}
+
+
+\subsection*{SVN Usage}
+\index{SVN Usage}
+\addcontentsline{toc}{subsection}{SVN Usage}
+Please note that if you are familar with CVS, SVN is very
+similar (and better), but there can be a few surprising
+differences.
-The Bacula CVS is kept at Source Forge. If you are not a developer,
-you only be able to access the public CVS, which runs about 6 hours behind
-the developer's CVS. If you are a developer, then you will have immediate
-access to "the" CVS and any changes ("commit") that you make will be
-immediately seen by other developers.
+The *entire* Bacula SourceForge.net Subversion repository can be
+checked out through SVN with the following command:
-For developer access to the CVS, go to the Bacula page on Source Forge
-and click on the CVS menu item. Then follow the instructions for
-installing your SSH public key. It may take a few hours until the
-key is actually installed, and then you will have access to the CVS.
+\begin{verbatim}
+svn checkout https://bacula.svn.sourceforge.net/svnroot/bacula bacula
+\end{verbatim}
-The Bacula CVS is divided into the following CVS "projects" or "modules".
+With the above command, you will get everything, which is a very large
+amount of data:
\begin{verbatim}
+branches/
+ Branch-1.32a/
+ ...
+ Branch-2.0/
+ import/
+ vendor/
+tags/
+ Release-1.1/
+ ...
+ Release-2.0.2/
+trunk/
+ bacula/
+ docs/
+ gui/
+ regress/
+ rescue/
+\end{verbatim}
+
+Note, you should NEVER commit code to any checkout that you have
+done of a tag. All tags (e.g. Release-1.1, ... Release-2.0.2)
+should be considered read-only.
+
+You may commit code to the most recent item in
+branches (in the above the most recent one is Branch-2.0). If
+you want to commit code to an older branch, then please contact
+Kern first.
- bacula (Bacula source code)
- docs (Bacula documentation)
- rescue (Bacula CDROM rescue code)
- regress (Bacula regression scripts)
- ryol (Roll your own Linux -- incomplete project)
+You may create your own tags and/or branches, but they should
+have a name clearly distinctive from Branch-, Release-, or Beta-,
+which are official names used by the project. If you create a
+tag, then you should NEVER commit code to it, for the same
+reason noted above -- it should serve as a marker for something
+you released. If you create a branch, then you are free to
+commit to it as you wish.
+You may, of course, commit to the trunk.
+
+In summary:
+
+\begin{verbatim}
+branches
+ Branch-nnn
+tags
+ Release-nnn
+ Beta-nnn
\end{verbatim}
-Most of you will want either the Bacula source (bacula) and/or the
-documents (docs).
+are reserved names to be created only by the project manager (or
+with his OK), where the nnn is any sequence of numbers and
+periods (e.g. 2.0, 2.0.1, ...).
+
+In addition all tags even those that you create are read-only
+forever. Typically tags represent release points either in the
+trunc or in a branch.
-To get the source for a project, you must check it out ("checkout"), which
-you do usually once.
-The first time you checkout the code for each project, you will need to
-tell the cvs program where the CVS repository is. You do so by doing:
+Coming back to getting source code.
+If you only want the current Bacula source code, you could use:
\begin{verbatim}
-export CVS_RSH=ssh
-export CVSROOT=:ext:<nnnn>@cvs.bacula.sourceforge.net:/cvsroot/bacula
+svn checkout https://bacula.svn.sourceforge.net/svnroot/bacula/trunk/bacula bacula
\end{verbatim}
-where you replace \lt{}nnnn\gt{} by your Source Forge user name.
+To view what is in the SVN, point your browser at the following URL:
+http://bacula.svn.sourceforge.net/viewvc/bacula/
-Then do
+Many of the Subversion (svn) commands are almost identical to those that
+you have used for cvs, but some (such as a checkout) can have surprising
+results, so you should take a careful look at the documentation.
+Robert has kindly provided the following documentation on the new
+svn repository and how to use it:
+
+Here is the list of branches:
\begin{verbatim}
-cvs -z3 checkout -d <directory> bacula
+ Branch-1.32a
+ Branch-1.32e
+ Branch-1.34.2
+ Branch-1.34.5
+ Branch-1.36
+ Branch-1.36.1
+ Branch-1.36.2
+ Branch-1.38
+ Branch-2.0
+ import
+ vendor
\end{verbatim}
-where you replace \lt{}directory\gt{} by the name of the directory you want
-to contain the Bacula source code. If you want the docs, replace the
-word "bacula" on the above line by "docs" and be sure to put it in
-a different directory. The -z3 just tells CVS to use compression during
-the transmission, which makes things go faster.
+The list of tags is:
+\begin{verbatim}
+ Release-1.1 Release-1.19 Release-1.19a Release-1.19b
+ Release-1.20 Release-1.21 Release-1.22 Release-1.23
+ Release-1.23a Release-1.24 Release-1.25 Release-1.25a
+ Release-1.26 Release-1.27 Release-1.27a Release-1.27b
+ Release-1.27c Release-1.28 Release-1.29 Release-1.30
+ Release-1.31 Release-1.31a Release-1.32 Release-1.32a
+ Release-1.32b Release-1.32c Release-1.32d Release-1.32e
+ Release-1.32f Release-1.32f-2 Release-1.32f-3 Release-1.32f-4
+ Release-1.32f-5 Release-1.34.0 Release-1.34.1 Release-1.34.3
+ Release-1.34.4 Release-1.34.5 Release-1.34.6 Release-1.35.1
+ Release-1.35.2 Release-1.35.3 Release-1.35.6 Release-1.35.7
+ Release-1.35.8 Release-1.36.0 Release-1.36.1 Release-1.36.2
+ Release-1.36.3 Release-1.38.0 Release-1.38.1 Release-1.38.10
+ Release-1.38.11 Release-1.38.2 Release-1.38.3 Release-1.38.4
+ Release-1.38.5 Release-1.38.6 Release-1.38.7 Release-1.38.8
+ Release-1.38.9 Release-1.8.1 Release-1.8.2 Release-1.8.3
+ Release-1.8.4 Release-1.8.5 Release-1.8.6 Release-2.0.0
+ Release-2.0.1 Release-2.0.2
+\end{verbatim}
-The above command should generate output that looks a bit like the
-following:
+Here is a list of commands to get you started. The recommended book is
+"Version Control with Subversion", by Ben Collins-Sussmann,
+Brian W. Fitzpatrick, and Michael Pilato, O'Reilly. The book is
+Open Source, so it is also available on line at:
\begin{verbatim}
-cvs checkout: Updating bacula
-U bacula/Makefile
-U bacula/bar.c
-U bacula/foo.c
-U bacula/main.c
-...
+ http://svnbook.red-bean.com
\end{verbatim}
+Get a list of commands
+
+\begin{verbatim}
+ svn help
+\end{verbatim}
-Let's assume you used the name "bacula" for the directory, so your
-command was:
+Get a help with a command
\begin{verbatim}
-cvs -z3 checkout -d bacula bacula
+ svn help command
\end{verbatim}
-When the command is done, simply do:
+Checkout the HEAD revision of all modules from the project into the
+directory bacula-new
\begin{verbatim}
-cd bacula
+ svn co https://bacula.svn.sourceforge.net/svnroot/bacula/trunk bacula.new
+\end{verbatim}
+
+Checkout the HEAD revision of the bacula module into the bacula subdirectory
+
+\begin{verbatim}
+ svn checkout https://bacula.svn.sourceforge.net/svnroot/bacula/trunk/bacula
+\end{verbatim}
+
+See which files have changed in the working copy
+
+\begin{verbatim}
+ svn status
+\end{verbatim}
+
+See which files are out of date
+
+\begin{verbatim}
+ svn status -u
+\end{verbatim}
+
+Add a new file file.c
+
+\begin{verbatim}
+ svn add file.c
+\end{verbatim}
+
+Create a new directory
+
+\begin{verbatim}
+ svn mkdir newdir
+\end{verbatim}
+
+Delete an obsolete file
+
+\begin{verbatim}
+ svn delete file.c
+\end{verbatim}
+
+Rename a file
+
+\begin{verbatim}
+ svn move file.c newfile.c
+\end{verbatim}
+
+Move a file to a new location
+
+\begin{verbatim}
+ svn move file.c ../newdir/file.c
+\end{verbatim}
+
+Copy a file retaining the original history in the new file
+
+\begin{verbatim}
+ svn copy file.c newfile.c
+\end{verbatim}
+
+Update the working copy with the outstanding changes
+
+\begin{verbatim}
+ svn update
+\end{verbatim}
+
+Compare working copy with the repository
+
+\begin{verbatim}
+ svn diff file.c
+\end{verbatim}
+
+Commit the changes in the local working copy
+
+\begin{verbatim}
+ svn commit
+\end{verbatim}
+
+Specify which files are ignored in the current directory
+
+\begin{verbatim}
+ svn propedit svn:ignore .
\end{verbatim}
+Mark a file to be executable
+
+\begin{verbatim}
+ svn propset svn:executable '*' prog.sh
+\end{verbatim}
+
+Unmark a file as executable
+
+\begin{verbatim}
+ svn propdel svn:executable prog.sh
+\end{verbatim}
+
+List a file's properties
+
+\begin{verbatim}
+ svn proplist file.c
+\end{verbatim}
+
+Create a branch for a new version
+
+\begin{verbatim}
+ svn copy https://bacula.svn.sourceforge.net/svnroot/bacula/trunk \
+ https://bacula.svn.sourceforge.net/svnroot/bacula/branches/Branch-2.1
+\end{verbatim}
+
+Tag a version for a new release
+
+\begin{verbatim}
+ svn copy https://bacula.svn.sourceforge.net/svnroot/bacula/branches/Branch-2.1 \
+ https://bacula.svn.sourceforge.net/svnroot/bacula/branches/Release-2.1
+\end{verbatim}
-and then build Bacula. You will notice a lot of extra CVS directories
-in the source code. Don't ever change or delete them, or you will mess up
-your copy of the project. Also, do not rename or delete any of the files
-in your copy of the repository or you may have problems. Any files that
-you change will remain only on your system until you do a "commit", which
-is explained later.
Let's say you are working in the directory scripts. You would then do:
\begin{verbatim}
cd bacula (to your top level directory)
-cvs diff -u >my-changes.patch
+svn diff my-changes.patch
\end{verbatim}
When the command is done, you can look in the file my-changes.patch
it reports before proceeding. If you modified files that you do
do not want to commit to the main repository, you can simply delete
them from your local directory, and they will be restored from the
-repository with the "cvs update" that is shown below. Normally, you
+repository with the "svn update" that is shown below. Normally, you
should not find changes to files that you do not want to commit, and
if you find yourself in that position a lot, you are probably doing
something wrong.
-Let's assume that now you want to commit your changes to the main CVS
-repository.
+Let's assume that now you want to commit your changes to the main
+SVN repository.
First do:
\begin{verbatim}
-cvs bacula
-cvs update
+cd bacula
+svn update
\end{verbatim}
When you do this, it will pull any changes made by other developers into
or look in the .rej files that it creates. If you have problems, just ask
on the developer's list.
-Note, doing the above "cvs update" is not absolutely necessary. There are
+Note, doing the above "svn update" is not absolutely necessary. There are
times when you may be working on code and you want to commit it, but you
explicitly do not want to move up to the latest version of the code in
-the CVS. If that is the case, you can simply skip the "cvs update" and
+the SVN. If that is the case, you can simply skip the "svn update" and
do the commit shown below. If the commit fails because of a conflict, it
will tell you, and you must resolve the conflict before it will permit
you to do the commit.
commit your changes:
\begin{verbatim}
-cvs commit -m "Some comment about what you changed"
+svn commit -m "Some comment about what you changed"
\end{verbatim}
or if you really only want to commit a single file, you can
do:
\begin{verbatim}
-cvs commit -m "comment" scripts/file-I-edited
+svn commit -m "comment" scripts/file-I-edited
\end{verbatim}
Note, if you have done a build in your directory, or you have added
are stored in the repository, so when you do a commit, those object
files will simply be ignored.
-If you want to add new files or remove files from the main CVS
-repository, and you are not experienced with CVS, please ask Kern
+If you want to add new files or remove files from the main SVN
+repository, and you are not experienced with SVN, please ask Kern
to do it. If you follow the simple steps above, it is unlikely that
you will do any damage to the repository, and if you do, it is always
possible for us to recover, but it can be painful.
long as you are careful only to change files that you want changed,
you have little to worry about.
+\subsection*{Subversion Resources}
+\index{Subversion (svn) Resources}
+\addcontentsline{toc}{subsection}{Subversion Resources}
+
+\begin{verbatim}
+cvs2svn Statistics:
+------------------
+Total CVS Files: 3286
+Total CVS Revisions: 28924
+Total Unique Tags: 63
+Total Unique Branches: 11
+CVS Repos Size in KB: 232421
+Total SVN Commits: 4116
+First Revision Date: Tue Apr 23 12:42:57 2002
+Last Revision Date: Tue Feb 6 06:37:57 2007
+\end{verbatim}
+
+The new Subversion repository size on Robert's machine:
+
+\begin{verbatim}
+4.0K bacula-tst/dav
+12K bacula-tst/locks
+40K bacula-tst/hooks
+16K bacula-tst/conf
+190M bacula-tst/db/revs
+17M bacula-tst/db/revprops
+4.0K bacula-tst/db/transactions
+206M bacula-tst/db
+206M bacula-tst
+\end{verbatim}
+
+
+Main Subversion Web Page
+\elink{http://subversion.tigris.org}{http://subversion.tigris.org}
+
+Subversion Book
+\elink{http://svnbook.red-bean.com}{http://svnbook.red-bean.com}
+
+Subversion Clients
+\elink{http://subversion.tigris.org/project\_packages.html}{http://subversion.tigris.org/project\_packages.html}
+
+ (For Windows users the TortoiseSVN package is awesome)
+
+GUI UNIX client link
+\elink{http://rapidsvn.tigris.org/}{http://rapidsvn.tigris.org/}
+
+A nice KDE GUI client:
+kdesvn
+
+
\subsection*{Developing Bacula}
-\index{Developing Bacula }
-\index{Bacula!Developing }
+\index{Developing Bacula}
+\index{Bacula!Developing}
\addcontentsline{toc}{subsubsection}{Developing Bacula}
Typically the simplest way to develop Bacula is to open one xterm window
./stopit then repeat the process.
\subsubsection*{Debugging}
-\index{Debugging }
+\index{Debugging}
\addcontentsline{toc}{subsubsection}{Debugging}
Probably the first thing to do is to turn on debug output.
just about everything a level of 200.
\subsubsection*{Using a Debugger}
-\index{Using a Debugger }
-\index{Debugger!Using a }
+\index{Using a Debugger}
+\index{Debugger!Using a}
\addcontentsline{toc}{subsubsection}{Using a Debugger}
If you have a serious problem such as a segmentation fault, it can usually be
manual entitled ``What To Do When Bacula Crashes (Kaboom)''.
\subsubsection*{Memory Leaks}
-\index{Leaks!Memory }
-\index{Memory Leaks }
+\index{Leaks!Memory}
+\index{Memory Leaks}
\addcontentsline{toc}{subsubsection}{Memory Leaks}
Because Bacula runs routinely and unattended on client and server machines, it
daemons.
\subsubsection*{Special Files}
-\index{Files!Special }
-\index{Special Files }
+\index{Files!Special}
+\index{Special Files}
\addcontentsline{toc}{subsubsection}{Special Files}
Kern uses files named 1, 2, ... 9 with any extension as scratch files. Thus
any files with these names are subject to being rudely deleted at any time.
\subsubsection*{When Implementing Incomplete Code}
-\index{Code!When Implementing Incomplete }
-\index{When Implementing Incomplete Code }
+\index{Code!When Implementing Incomplete}
+\index{When Implementing Incomplete Code}
\addcontentsline{toc}{subsubsection}{When Implementing Incomplete Code}
-Please identify all incomplete code with a comment that contains {\bf
-***FIXME***}, where there are three asterisks (*) before and after the word
+Please identify all incomplete code with a comment that contains
+
+\begin{verbatim}
+***FIXME***
+\end{verbatim}
+
+where there are three asterisks (*) before and after the word
FIXME (in capitals) and no intervening spaces. This is important as it allows
new programmers to easily recognize where things are partially implemented.
\subsubsection*{Bacula Source File Structure}
-\index{Structure!Bacula Source File }
-\index{Bacula Source File Structure }
+\index{Structure!Bacula Source File}
+\index{Bacula Source File Structure}
\addcontentsline{toc}{subsubsection}{Bacula Source File Structure}
The distribution generally comes as a tar file of the form {\bf
|- scripts (scripts and .conf files)
|- tests (test scripts)
|- tmp (temporary directory for temp files)
+ |- working (temporary working directory for Bacula daemons)
Project docs:
|- docs (documentation directory)
\normalsize
\subsubsection*{Header Files}
-\index{Header Files }
-\index{Files!Header }
+\index{Header Files}
+\index{Files!Header}
\addcontentsline{toc}{subsubsection}{Header Files}
Please carefully follow the scheme defined below as it permits in general only
protos.h} is always included by the main directory dependent include file.
\subsubsection*{Programming Standards}
-\index{Standards!Programming }
-\index{Programming Standards }
+\index{Standards!Programming}
+\index{Programming Standards}
\addcontentsline{toc}{subsubsection}{Programming Standards}
For the most part, all code should be written in C unless there is a burning
so be conservative in your use of C++ features.
\subsubsection*{Do Not Use}
-\index{Use!Do Not }
-\index{Do Not Use }
+\index{Use!Do Not}
+\index{Do Not Use}
\addcontentsline{toc}{subsubsection}{Do Not Use}
\begin{itemize}
-\item STL -- it is totally incomprehensible.
- \end{itemize}
+ \item STL -- it is totally incomprehensible.
+\end{itemize}
\subsubsection*{Avoid if Possible}
-\index{Possible!Avoid if }
-\index{Avoid if Possible }
+\index{Possible!Avoid if}
+\index{Avoid if Possible}
\addcontentsline{toc}{subsubsection}{Avoid if Possible}
\begin{itemize}
+\item Using {\bf void *} because this generally means that one must
+ using casting, and in C++ casting is rather ugly. It is OK to use
+ void * to pass structure address where the structure is not known
+ to the routines accepting the packet (typically callback routines).
+ However, declaring "void *buf" is a bad idea. Please use the
+ correct types whenever possible.
+
+\item Using undefined storage specifications such as (short, int, long,
+ long long, size\_t ...). The problem with all these is that the number of bytes
+ they allocate depends on the compiler and the system. Instead use
+ Bacula's types (int8\_t, uint8\_t, int32\_t, uint32\_t, int64\_t, and
+ uint64\_t). This guarantees that the variables are given exactly the
+ size you want. Please try at all possible to avoid using size\_t ssize\_t
+ and the such. They are very system dependent. However, some system
+ routines may need them, so their use is often unavoidable.
+
\item Returning a malloc'ed buffer from a subroutine -- someone will forget
to release it.
-\item Using reference variables -- it allows subroutines to create side
- effects.
-\item Heap allocation (malloc) unless needed -- it is expensive.
+
+\item Heap allocation (malloc) unless needed -- it is expensive. Use
+ POOL\_MEM instead.
+
\item Templates -- they can create portability problems.
+
\item Fancy or tricky C or C++ code, unless you give a good explanation of
why you used it.
+
\item Too much inheritance -- it can complicate the code, and make reading it
difficult (unless you are in love with colons)
- \end{itemize}
+
+\end{itemize}
\subsubsection*{Do Use Whenever Possible}
-\index{Possible!Do Use Whenever }
-\index{Do Use Whenever Possible }
+\index{Possible!Do Use Whenever}
+\index{Do Use Whenever Possible}
\addcontentsline{toc}{subsubsection}{Do Use Whenever Possible}
\begin{itemize}
\item Locking and unlocking within a single subroutine.
+
+\item A single point of exit from all subroutines. A goto is
+ perfectly OK to use to get out early, but only to a label
+ named bail\_out, and possibly an ok\_out. See current code
+ examples.
+
\item Malloc and free within a single subroutine.
+
\item Comments and global explanations on what your code or algorithm does.
- \end{itemize}
+
+\end{itemize}
\subsubsection*{Indenting Standards}
-\index{Standards!Indenting }
-\index{Indenting Standards }
+\index{Standards!Indenting}
+\index{Indenting Standards}
\addcontentsline{toc}{subsubsection}{Indenting Standards}
I cannot stand code indented 8 columns at a time. This makes the code
\begin{verbatim}
if (abc) {
some_code;
- }
+ }
\end{verbatim}
\normalsize
break;
default:
break;
- }
+ }
\end{verbatim}
\normalsize
a = 1;
if (b >= 2) {
cleanup();
- }
+ }
\end{verbatim}
\normalsize
if (ua->verbose \&& del.num_del != 0) {
bsendmsg(ua, _("Pruned %d %s on Volume %s from catalog.\n"), del.num_del,
del.num_del == 1 ? "Job" : "Jobs", mr->VolumeName);
- }
+ }
\end{verbatim}
\normalsize
to 3.
\subsubsection*{Tabbing}
-\index{Tabbing }
+\index{Tabbing}
\addcontentsline{toc}{subsubsection}{Tabbing}
Tabbing (inserting the tab character in place of spaces) is as normal on all
characters) with indenting (visual alignment of the code).
\subsubsection*{Don'ts}
-\index{Don'ts }
+\index{Don'ts}
\addcontentsline{toc}{subsubsection}{Don'ts}
Please don't use:
Also please don't use the STL or Templates or any complicated C++ code.
\subsubsection*{Message Classes}
-\index{Classes!Message }
-\index{Message Classes }
+\index{Classes!Message}
+\index{Message Classes}
\addcontentsline{toc}{subsubsection}{Message Classes}
Currently, there are five classes of messages: Debug, Error, Job, Memory,
and Queued.
\subsubsection*{Debug Messages}
-\index{Messages!Debug }
-\index{Debug Messages }
+\index{Messages!Debug}
+\index{Debug Messages}
\addcontentsline{toc}{subsubsection}{Debug Messages}
Debug messages are designed to be turned on at a specified debug level and are
Dmsg1(9, ``Created client \%s record\textbackslash{}n'', client->hdr.name);
\subsubsection*{Error Messages}
-\index{Messages!Error }
-\index{Error Messages }
+\index{Messages!Error}
+\index{Error Messages}
\addcontentsline{toc}{subsubsection}{Error Messages}
Error messages are messages that are related to the daemon as a whole rather
\addcontentsline{lot}{table}{Message Error Code Classes}
\begin{longtable}{lp{3in}}
-{{\bf M\_ABORT} } & {Causes the daemon to immediately abort. This should be
-used only in extreme cases. It attempts to produce a traceback. } \\
-{{\bf M\_ERROR\_TERM} } & {Causes the daemon to immediately terminate. This
-should be used only in extreme cases. It does not produce a traceback. } \\
-{{\bf M\_FATAL} } & {Causes the daemon to terminate the current job, but the
-daemon keeps running } \\
-{{\bf M\_ERROR} } & {Reports the error. The daemon and the job continue
-running } \\
-{{\bf M\_WARNING} } & {Reports an warning message. The daemon and the job
-continue running } \\
-{{\bf M\_INFO} } & {Reports an informational message. }
+{{\bf M\_ABORT} } & {Causes the daemon to immediately abort. This should be
+used only in extreme cases. It attempts to produce a traceback. } \\
+{{\bf M\_ERROR\_TERM} } & {Causes the daemon to immediately terminate. This
+should be used only in extreme cases. It does not produce a traceback. } \\
+{{\bf M\_FATAL} } & {Causes the daemon to terminate the current job, but the
+daemon keeps running } \\
+{{\bf M\_ERROR} } & {Reports the error. The daemon and the job continue
+running } \\
+{{\bf M\_WARNING} } & {Reports an warning message. The daemon and the job
+continue running } \\
+{{\bf M\_INFO} } & {Reports an informational message.}
\end{longtable}
\%d \%s\textbackslash{}n'', cmd, n, strerror(errno));
\subsubsection*{Job Messages}
-\index{Job Messages }
-\index{Messages!Job }
+\index{Job Messages}
+\index{Messages!Job}
\addcontentsline{toc}{subsubsection}{Job Messages}
Job messages are messages that pertain to a particular job such as a file that
from user's output.
\subsubsection*{Queued Job Messages}
-\index{Queued Job Messages }
-\index{Messages!Job }
+\index{Queued Job Messages}
+\index{Messages!Job}
\addcontentsline{toc}{subsubsection}{Queued Job Messages}
Queued Job messages are similar to Jmsg()s except that the message is
Queued rather than immediately dispatched. This is necessary within the
\subsubsection*{Memory Messages}
-\index{Messages!Memory }
-\index{Memory Messages }
+\index{Messages!Memory}
+\index{Memory Messages}
\addcontentsline{toc}{subsubsection}{Memory Messages}
Memory messages are messages that are edited into a memory buffer. Generally
projects / bacula / docs / blobdiff