Bareos Developer Notes¶

This document is intended mostly for developers and describes how you can contribute to the Bareos project and the general framework of making Bareos source changes.

History¶

Bareos is a fork of the open source project Bacula version 5.2. In 2010 the Bacula community developer Marco van Wieringen started to collect rejected or neglected community contributions in his own branch. This branch was later on the base of Bareos and since then was enriched by a lot of new features.

This documentation also bases on the original Bacula documentation, it is technically also a fork of the documenation created following the rules of the GNU Free Documentation License.

Original author of Bacula and it’s documentation is Kern Sibbald. We thank Kern and all contributors to Bacula and its documentation. We maintain a list of contributors to Bacula (until the time we’ve started the fork) and Bareos in our AUTHORS file.

Contributions¶

Contributions to the Bareos project come in many forms: ideas, participation in helping people on the bareos-users email list, packaging Bareos binaries for the community, helping improve the documentation, and submitting code.

Patches¶

Patches should be sent as a pull-request to the master branch of the GitHub repository. To do so, you will need an account on GitHub. If you don’t want to sign up to GitHub, you can also send us your patches via E-Mail in git format-patch format to the bareos-devel mailing list.

Please make sure to use the Bareos formatting standards. Don’t forget any Copyrights and acknowledgments if it isn’t 100% your code. Also, include the Bareos copyright notice that can be found in every source file.

Commit message guideline¶

Start with a subject on a single line. If your commit changes a specific component of bareos try to mention it at the start of the subject.

Next comes an empty line.

If your commit fixes an existing bug, add a line in the format Fixes #12345: The exact title of the bug you fix.. After this you can just write your detailed commit information.

We strongly encourage you to keep the subject down to 50 characters and to wrap your text at the 50 character boundary. However, this is by no means enforced.

lib: do a sample commit

Fixes #12345: Really nasty library needs a sample commit.

This patch fixes a bug in one of the libraries.
Before we applied this specific change, the
library was completely okay, but in desperate
need of a sample commit.

Bug Database¶

We have a bug database which is at https://bugs.bareos.org.

The first thing is if you want to take over a bug, rather than just make a note, you should assign the bug to yourself. This helps other developers know that you are the principal person to deal with the bug. You can do so by going into the bug and clicking on the Update Issue button. Then you simply go to the Assigned To box and select your name from the drop down box. To actually update it you must click on the Update Information button a bit further down on the screen, but if you have other things to do such as add a Note, you might wait before clicking on the Update Information button.

Generally, we set the Status field to either acknowledged, confirmed, or feedback when we first start working on the bug. Feedback is set when we expect that the user should give us more information.

Normally, once you are reasonably sure that the bug is fixed, and a patch is made and attached to the bug report, and/or in the Git, you can close the bug. If you want the user to test the patch, then leave the bug open, otherwise close it and set Resolution to Fixed. We generally close bug reports rather quickly, even without confirmation, especially if we have run tests and can see that for us the problem is fixed. However, in doing so, it avoids misunderstandings if you leave a note while you are closing the bug that says something to the following effect: We are closing this bug because… If for some reason, it does not fix your problem, please feel free to reopen it, or to open a new bug report describing the problem“.

We do not recommend that you attempt to edit any of the bug notes that have been submitted, nor to delete them or make them private. In fact, if someone accidentally makes a bug note private, you should ask the reason and if at all possible (with his agreement) make the bug note public.

If the user has not properly filled in most of the important fields (platform, OS, Product Version, …) please do not hesitate to politely ask him to do so. The same applies to a support request (we answer only bugs), you might give the user a tip, but please politely refer him to the manual, the bareos-users mailing list and maybe the commercial support.

Reporting security issues¶

If you want to report a security-related problem, please take a look at our security policy.

Developing Bareos¶

Building the testenvironment¶

This following shell script will show how to build the Bareos test-environment from source.

Example shell script¶

#!/bin/sh

mkdir bareos-local-tests
cd bareos-local-tests
git clone https://github.com/bareos/bareos.git

mkdir build
cd build

cmake -Dsqlite3=yes -Dtraymonitor=yes ../bareos
make -j
make test

Building the documentation¶

This following shell script will show how to build the Bareos documentation from source.

Example shell script¶

#!/bin/sh

mkdir bareos-local-tests
cd bareos-local-tests
git clone https://github.com/bareos/bareos.git

mkdir build-docs
cd build-docs

cmake -Ddocs-only=yes ../bareos
make

Memory Leaks¶

Most of Bareos still uses SmartAlloc. This tracks memory allocation and allows you to detect memory leaks. However, newer code should not use SmartAlloc, but use standard C++11 resource management (RAII and smart pointers). If you need to detect memory leaks, you can just use valgrind to do so.

Guiding Principles¶

All new code should be written in modern C++11 following the Google C++ Style Guide and the C++ Core Guidelines.

We like simple rather than complex code, but complex code is still better than complicated code.

Currently there is still a lot of old C++ and C code in the code base and a lot of existing code violates our do’s and don’ts. Our long-term goal is to modernize the code-base to make it easier to understand, easier to maintain and better approachable for new developers.

Formatting Standards¶

We find it very hard to adapt to different styles of code formatting, so we agreed on a set of rules. Instead of describing these in a lenghty set of rules, we provide a configuration file for clang-format in our repository that we use to format the code. All code should be reformatted using clang-format before committing.

For some parts of code it works best to hand-optimize the formatting. We sometimes do this for larger tables and deeply nested brace initialization. If you need to hand-optimize make sure you add clang-format off and clang-format on comments so applying clang-format on your source will not undo your manual optimization. Please apply common sense and use this exception sparingly.

Use /* */ for multi-line comments. Use // for single-line comments.

Do’s¶

write modern C++11
prefer simple code
write unit tests for your code
use RAII whenever possible
honor Rule of three/Rule of five/Rule of zero
use std::string instead of char* for strings where possible
use fixed width integer types if the size of your integer matters
when in doubt always prefer the standard library over a custom implementation
follow the Google C++ Style Guide
follow the C++ Core Guidelines
get in touch with us on the bareos-devel mailing list

Don’ts¶

avoid new: Starting with C++11 there are smart pointers like shared_ptr and unique_ptr. To create a shared_ptr you should use make_shared() from the standard library. We provide a backport of C++14’s make_unique() in include/make_unique.h to create a unique_ptr. If possible use unique_ptr instead of shared_ptr.
avoid delete: You should use the RAII paradigm, so cleanup is handled automatically.
don’t transfer ownership of heap memory without move semantics: No returning of raw pointers where the caller is supposed to free the resource.
don’t use C++14 or later: Currently we support platforms where the newest available compiler supports only C++11.
don’t use C string functions: If you can, use std::string and don’t rely on C string functions.
don’t use the bareos replacements for C string functions.: These are deprecated.
avoid the edit_*() functions from edit.cc: Just use the appropriate format string. This will also avoid the temporary buffer that is required otherwise.
don’t subclass SmartAlloc: It forces the use of ancient memory management methods and severely limits the capabilities of your class
avoid smart allocation: The whole smart allocation library with get_pool_memory(), sm_free() and friends do not mix with RAII, so we will try to remove them step by step in the future. Avoid in new code if possible.