Developers Documentation

We encourage contributions, especially completed ones (pull requests and patches). However please be aware of some restrictions:

• This is backup software, it needs to be simple and reliable.
• Almost all of the code is in C++ for performance.
• The code is portable (cross-platform) and must remain so.
• We have limited capacity to review contributions or respond to emails, so it may take a while.
• We prefer not to add complexity where possible, especially if it can be done in a separate process via an interface.
• All contributions must be dual-licensed BSD and GPL (can be used under either license).
• Please follow our CodingStyle.
• Please use Github pull requests where possible.

If you are looking for something interesting to do, or a sense of what's left to be done, please have a look at the Redesign and Feature Requests pages.

Simplicity and Reliability

As this is backup software, our top priority is not to break it, especially silently. If you are developing a new feature, please think about how you can minimise the impact on the rest of the codebase. For example:

• Bugs should have tests that demonstrate the problem, which the patch fixes.
• Significant new features should have extensive tests. For example, the S3 storage feature includes a near-complete S3 simulator, and most tests are specialised to run on it as well as the old storage backend.
• Please add new configuration options sparingly, and especially do not make them required (as that would break existing installations).
• Ports to and support for new platforms are especially welcome, as they exercise odd corner cases, but automated testing is essential. This is why we do not officially support ARM or Solaris platforms at this time.
• Instead of adding a new file filtering mechanism (for example), a way to do this in an external process would be far more general and useful.

Language

Box Backup is designed to be cross-platform, and to run on less powerful systems (for example, NAS devices with embedded Linux), by not hogging resources and having minimal dependencies.

• Box Backup is written in C++, so your libraries must be too (or C if the API is simple and doesn't benefit massively from C++, e.g. PCRE, OpenSSL, QDBM).
• External libraries are often very well-tested, but should be optional. If necessary, your new feature should automatically be compiled out if the necessary libraries are not present.
• This is a cross-platform application. Support for Linux, Mac OS X and Windows is mandatory. Therefore your libraries need to be available on all three.
• Libraries may need to be bundled, but it must be possible to unbundle them (some distros require this).
• The libraries must have compatible licenses, which basically means BSD 2-clause or MIT licensed, not GPL.
• Instead of adding hooks for a new GUI or web UI (for example), if you added language bindings (for example SIP or SWIG) that would have a much bigger and longer-lasting impact.

Portability

Box Backup was originally developed for UNIX. Windows compatibility was added later, mainly through an emulation layer (lib/win32/emu.cpp/h) which provides POSIX and UNIX-like functions, such as an open() replacement which supports non-ASCII characters in filenames, fstat() and lstat(), opendir(), syslog(), strtoui64().

In most cases you can code for UNIX, but be aware when using functions that are not available on Windows, or are replaced by the emulation layer. Where possible use existing C++ classes such as FileStream to access files (which supports locking) and use O_BINARY when opening binary files.

We have adopted QDBM databases as they compile easily on Windows, while BDB and TDB do not.

Code reviews

Code reviews are mandatory before merging. Sometimes we will take your contribution and merge it ourselves, if no changes are required, or only trivial ones.

Tests are also mandatory.

We have one active developer who works full-time and has a family, so please don't be surprised if it takes days or weeks to review your contribution. After that, please send a reminder!

Please use Github Pull Requests where possible. They reduce the time required by us to review and process submissions. The test suite is automatically run on all pull requests, so you'll get quick feedback if something is broken. If it is, please fix it without waiting for us to ask you. Your pull request cannot and will not be merged until the tests pass, at the very least. Don't be surprised if you have to download VirtualBox and install FreeBSD in a virtual machine to debug and fix a failing test.

License

Box Backup has an unusual licensing situation, where part of the code is dual-licensed (BSD and GPL) and part is only GPL. This stems from a time when we were worried about someone taking our code and turning it into a commercial product without giving anything back to the community. This fear has largely passed, so the project may be relicensed in future under the BSD 2-clause license. To support this, all contributions must be licensed under BOTH the BSD 2-clause AND the GPL license, so that they may be used under either.

All contributors are required to confirm that they agree to this license for all submissions, in their first pull request or patch submission.

Specific Areas

Not much here yet:

• StoreObjectInfoFile format
• TestResults
• BoxBackupStoreProtocol