librsync  2.3.4
CONTRIBUTING

Instructions and conventions for people wanting to work on librsync. Please consider these guidelines even if you're doing your own fork.

Requirements

There are a bunch of tools and libraries that are useful for development or that librsync depends on. In addition to the standard cmake/gcc/make/etc C development tools, the following packages are recommended;

These can all be installed on Debian/Ubuntu systems by running;

```Shell $ apt-get update $ apt-get install libpopt-dev libb2-dev doxygen graphviz indent clang-tidy iwyu $ git clone https://github.com/dbaarda/tidyc.git $ cp tidyc/tidyc ~/bin ```

Windows

Not all the recommended packages are easily available on windows. Cygwin and MSYS2 provide a development environment similar to Linux. Some packages can also be found on Chocolatey. For native development using standard MSVC tools, libpopt can be found on vcpkg and installed by running;

```Shell $ vcpkg update $ vcpkg –triplet x64-windows install libpopt ```

For cmake to find the installed libpopt you need to add -D CMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake to the cmake cmdline. This configures cmake to correctly search the vcpkg install locations to find libraries.

MacOS

MacOS is generally more similar to Linux than Windows, and several packages are available on homebrew. The libpopt library can be installed by running;

```Shell $ brew update $ brew install popt ```

Building

The minimal instructions to fetch, configure, compile, and test everything using a in-place default Debug build with trace enabled using the internal blake2 implementation is;

```Shell $ git clone https://github.com/librsync/librsync.git $ cd librsync $ cmake . $ make check ```

For cmake, -B can be used to select a separate build directory, and -G can select a different make system. Also the following settings can be changed with -D <setting>=<value> arguments when generating the project with cmake;

So for a Release build in a separate directory using Ninja, clang, static linking, and libb2 with trace enabled, do this instead;

```Shell $ cmake -B build -G Ninja -D CMAKE_C_COMPILER=clang \ -D CMAKE_BUILD_TYPE=Release \ -D BUILD_SHARED_LIBS=OFF \ -D USE_LIBB2=ON \ -D ENABLE_TRACE=ON $ cmake –build build –config Release –target check ```

You can also use ccmake or cmake-gui to interactively configure and generate into a separate build directory with;

```Shell $ ccmake -B build ```

Coding

The prefered style for code is equivalent to using GNU indent with the following arguments;

```Shell $ indent -linux -nut -i4 -ppi2 -l80 -lc80 -fc1 -sob -T FILE -T Rollsum -T rs_result ```

The preferred style for non-docbook comments are as follows;

```C

                     /*=
                      | A short poem that
                      | shall never ever be
                      | reformated or reindented
                      */

/* Single line comment indented to match code indenting. */

/* Blank line delimited paragraph multi-line comments.

   Without leading stars, or blank line comment delimiters. */

int a;                      /* code line comments */

```

The preferred style for docbook comments is javadoc with autobrief as follows;

```C /** /file file.c

There is a make tidy target that will use GNU indent to reformat all code and non-docbook comments, doing some pre/post processing with sed to handle some corner cases indent doesn't handle well.

There is a make tidyc target that will reformat all code and comments with tidyc. This will also correctly reformat all docbook comments, equivalent to running tidyc with the following arguments;

```Shell $ tidyc -R -C -l80 -T FILE -T Rollsum -T rs_result ```

There is make clang-tidy and make iwyu targets for checking for coding errors and incorrect #include statements. Note that the iwyu check gets confused by and will emit warnings about fileutil.c which has extra conditional includes necessary to find working functions on various platforms. Other than fileutil.c both checks should be clean.

If iwyu finds problems, make ifwu-fix can be run to automatically fix them, followed by make tidyc to reformat the result to our preferred style. Note that this doesn't always produce an ideal result and may require manual intervention.

Please try to update docs and tests in parallel with code changes.

Testing

Using make check will compile and run all tests. Additional code correctness checks can be run with make clang-tidy and make iwyu.

Note that assert() is used extensively within the code for verifying the correctness of internal operations using a roughly design-by-contract approach. These are only enabled for Debug builds, so testing with a Debug build will give a better chance of identifying problems during development. Once you are confident the code is correct, a Release build will turn these off giving faster execution.

There are also GitHub Actions configured for the librsync project to configure, build, test, and lint everything on a variety of different platforms with a variety of different settings. These are run against any pull request or commit, and are a good way to check things are not broken for other platforms.

Test results for builds of public github branches are at https://github.com/librsync/librsync/actions.

Documenting

NEWS.md contains a list of user-visible changes in the library between release versions. This includes changes to the way it's packaged, bug fixes, portability notes, changes to the API, and so on. Add and update items under a "Changes in X.Y.Z" heading at the top of the file. Do this as you go along, so that we don't need to work out what happened when it's time for a release.

TODO.md contains a list of ideas and proposals for the future. Ideally entries should be formated in a way that can be just moved into NEWS.md when they are done. Regularly check to see if there is anything that needs removing or updating.

Submitting

Fixes or improvements in pull requests are welcome. Please:

Releasing

If you are making a new tarball release of librsync, follow this checklist: