Instructions and conventions for people wanting to work on librsync. Please consider these guidelines even if you\textquotesingle{}re doing your own fork.\hypertarget{md_CONTRIBUTING_autotoc_md1}{}\doxysubsection{Requirements}\label{md_CONTRIBUTING_autotoc_md1}
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;


\begin{DoxyItemize}
\item libpopt-\/dev -\/ the cmdline argument parsing library used by rdiff. If this is not available rdiff cannot be compiled, and only the librsync library will be compiled.
\item libb2-\/dev -\/ blake2 hash library librsync can use if {\ttfamily USE\+\_\+\+LIBB2} is set to {\ttfamily ON} in cmake. If this is not avalable librsync will use its included copy of blake2 (which may be older... or newer).
\item doxygen -\/ documentation generator used to generate html documentation. If installed {\ttfamily make doc} can be run to generate all the docs.
\item graphviz -\/ graph generator used by doxygen for generating diagrams. If not installed doxygen will not generate any diagrams.
\item indent -\/ code reformatter for tidying code. If installed all the code can be tidied with {\ttfamily make tidy}.
\item \href{https://github.com/dbaarda/tidyc}{\texttt{ tidyc}} -\/ extension wrapper for indent that includes better formatting of doxygen comments. If installed code and comments can be tidied with {\ttfamily make tidyc}.
\item clang-\/tidy -\/ code lint checker for potential problems. If installed the code can be checked with {\ttfamily make clang-\/tidy}.
\item iwyu -\/ {\ttfamily \#include} checker and fixer. If installed includes can be checked with {\ttfamily make iwyu}, and automatically fixed with {\ttfamily make iwyu-\/fix}. Note on some platforms this package is \href{https://bugs.launchpad.net/ubuntu/+source/iwyu/+bug/1769334}{\texttt{ missing a dependency}} and also needs {\ttfamily libclang-\/common-\/9-\/dev} to be installed.
\end{DoxyItemize}

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


\begin{DoxyCode}{0}
\DoxyCodeLine{\$ apt-\/get update}
\DoxyCodeLine{\$ apt-\/get install libpopt-\/dev libb2-\/dev doxygen graphviz indent clang-\/tidy iwyu}
\DoxyCodeLine{\$ git clone https://github.com/dbaarda/tidyc.git}
\DoxyCodeLine{\$ cp tidyc/tidyc \string~/bin}

\end{DoxyCode}
\hypertarget{md_CONTRIBUTING_autotoc_md2}{}\doxysubsubsection{Windows}\label{md_CONTRIBUTING_autotoc_md2}
Not all the recommended packages are easily available on windows. \href{https://cygwin.com/}{\texttt{ Cygwin}} and \href{http://msys2.org/}{\texttt{ MSYS2}} provide a development environment similar to Linux. Some packages can also be found on \href{https://chocolatey.org/}{\texttt{ Chocolatey}}. For native development using standard MSVC tools, libpopt can be found on \href{https://vcpkg.io/}{\texttt{ vcpkg}} and installed by running;


\begin{DoxyCode}{0}
\DoxyCodeLine{\$ vcpkg update}
\DoxyCodeLine{\$ vcpkg -\/-\/triplet x64-\/windows install libpopt}

\end{DoxyCode}


For cmake to find the installed libpopt you need to add {\ttfamily -\/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.\hypertarget{md_CONTRIBUTING_autotoc_md3}{}\doxysubsubsection{Mac\+OS}\label{md_CONTRIBUTING_autotoc_md3}
Mac\+OS is generally more similar to Linux than Windows, and several packages are available on homebrew. The libpopt library can be installed by running;


\begin{DoxyCode}{0}
\DoxyCodeLine{\$ brew update}
\DoxyCodeLine{\$ brew install popt}

\end{DoxyCode}
\hypertarget{md_CONTRIBUTING_autotoc_md4}{}\doxysubsection{Building}\label{md_CONTRIBUTING_autotoc_md4}
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;


\begin{DoxyCode}{0}
\DoxyCodeLine{\$ git clone https://github.com/librsync/librsync.git}
\DoxyCodeLine{\$ cd librsync}
\DoxyCodeLine{\$ cmake .}
\DoxyCodeLine{\$ make check}

\end{DoxyCode}


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


\begin{DoxyItemize}
\item CMAKE\+\_\+\+BUILD\+\_\+\+TYPE=(Debug$\vert$\+Release$\vert$\+Min\+Size\+Rel$\vert$\+Rel\+With\+Deb\+Info) -\/ the build type to use, which selects compiler options. The default is {\ttfamily Debug}.
\item CMAKE\+\_\+\+C\+\_\+\+COMPILER=(cc$\vert$gcc$\vert$clang$\vert$...) -\/ The compiler to use. The default is to auto-\/detect the available compiler on the platform.
\item BUILD\+\_\+\+RDIFF=(ON$\vert$\+OFF) -\/ Whether to build and test the rdiff executable. Defaults to ON if libpopt is available.
\item BUILD\+\_\+\+SHARED\+\_\+\+LIBS=(ON$\vert$\+OFF) -\/ Whether to build dynamic libraries or use static linking. Defaults to ON.
\item ENABLE\+\_\+\+TRACE=(ON$\vert$\+OFF) -\/ Whether to enable trace output in the library and for rdiff using {\ttfamily -\/v}. Trace output can help with debugging but its a little faster with ENABLE\+\_\+\+TRACE=OFF. Defaults to ON for Debug builds, and OFF for others.
\item USE\+\_\+\+LIBB2=(ON$\vert$\+OFF) -\/ Whether to use libb2 instead of the included blake2 implementation. Defaults to OFF.
\end{DoxyItemize}

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


\begin{DoxyCode}{0}
\DoxyCodeLine{\$ cmake -\/B build -\/G Ninja}
\DoxyCodeLine{  -\/D CMAKE\_C\_COMPILER=clang \(\backslash\)}
\DoxyCodeLine{  -\/D CMAKE\_BUILD\_TYPE=Release \(\backslash\)}
\DoxyCodeLine{  -\/D BUILD\_SHARED\_LIBS=OFF \(\backslash\)}
\DoxyCodeLine{  -\/D USE\_LIBB2=ON \(\backslash\)}
\DoxyCodeLine{  -\/D ENABLE\_TRACE=ON}
\DoxyCodeLine{\$ cmake -\/-\/build build -\/-\/config Release -\/-\/target check}

\end{DoxyCode}


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


\begin{DoxyCode}{0}
\DoxyCodeLine{\$ ccmake -\/B build}

\end{DoxyCode}
\hypertarget{md_CONTRIBUTING_autotoc_md5}{}\doxysubsection{Coding}\label{md_CONTRIBUTING_autotoc_md5}
The prefered style for code is equivalent to using GNU indent with the following arguments;


\begin{DoxyCode}{0}
\DoxyCodeLine{\$ indent -\/linux -\/nut -\/i4 -\/ppi2 -\/l80 -\/lc80 -\/fc1 -\/sob -\/T FILE -\/T Rollsum -\/T rs\_result}

\end{DoxyCode}


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


\begin{DoxyCode}{0}
\DoxyCodeLine{                     \textcolor{comment}{/*=}}
\DoxyCodeLine{\textcolor{comment}{                      | A short poem that}}
\DoxyCodeLine{\textcolor{comment}{                      | shall never ever be}}
\DoxyCodeLine{\textcolor{comment}{                      | reformated or reindented}}
\DoxyCodeLine{\textcolor{comment}{                      */}}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{comment}{/* Single line comment indented to match code indenting. */}}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{comment}{/* Blank line delimited paragraph multi-\/line comments.}}
\DoxyCodeLine{\textcolor{comment}{}}
\DoxyCodeLine{\textcolor{comment}{   Without leading stars, or blank line comment delimiters. */}}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{keywordtype}{int} a;                      \textcolor{comment}{/* code line comments */}}

\end{DoxyCode}


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


\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{comment}{/** /file file.c}}
\DoxyCodeLine{\textcolor{comment}{  * Brief summary paragraph.}}
\DoxyCodeLine{\textcolor{comment}{  *}}
\DoxyCodeLine{\textcolor{comment}{  * With blank line paragraph delimiters and leading stars.}}
\DoxyCodeLine{\textcolor{comment}{  *}}
\DoxyCodeLine{\textcolor{comment}{  * /param foo parameter descriptions...}}
\DoxyCodeLine{\textcolor{comment}{  *}}
\DoxyCodeLine{\textcolor{comment}{  * /param bar ...in separate blank-\/line delimited paragraphs.}}
\DoxyCodeLine{\textcolor{comment}{  *}}
\DoxyCodeLine{\textcolor{comment}{  * Example:/code}}
\DoxyCodeLine{\textcolor{comment}{  *  code blocks that will never be reformated.}}
\DoxyCodeLine{\textcolor{comment}{  * /endcode}}
\DoxyCodeLine{\textcolor{comment}{  *}}
\DoxyCodeLine{\textcolor{comment}{  * Without blank-\/line comment delimiters. */}}
\DoxyCodeLine{}
\DoxyCodeLine{    \textcolor{keywordtype}{int} a;                      \textcolor{comment}{/**< brief attribute description */}}
\DoxyCodeLine{    \textcolor{keywordtype}{int} b;                      \textcolor{comment}{/**< multiline attribute description}}
\DoxyCodeLine{\textcolor{comment}{                                 *}}
\DoxyCodeLine{\textcolor{comment}{                                 * With blank line delimited paragraphs.*/}}

\end{DoxyCode}


There is a {\ttfamily 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\textquotesingle{}t handle well.

There is a {\ttfamily make tidyc} target that will reformat all code and comments with \href{https://github.com/dbaarda/tidyc}{\texttt{ tidyc}}. This will also correctly reformat all docbook comments, equivalent to running tidyc with the following arguments;


\begin{DoxyCode}{0}
\DoxyCodeLine{\$ tidyc -\/R -\/C -\/l80 -\/T FILE -\/T Rollsum -\/T rs\_result}

\end{DoxyCode}


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

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

Please try to update docs and tests in parallel with code changes.\hypertarget{md_CONTRIBUTING_autotoc_md6}{}\doxysubsection{Testing}\label{md_CONTRIBUTING_autotoc_md6}
Using {\ttfamily make check} will compile and run all tests. Additional code correctness checks can be run with {\ttfamily make clang-\/tidy} and {\ttfamily make iwyu}.

Note that {\ttfamily 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 Git\+Hub 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 \href{https://github.com/librsync/librsync/actions}{\texttt{ https\+://github.\+com/librsync/librsync/actions}}.\hypertarget{md_CONTRIBUTING_autotoc_md7}{}\doxysubsection{Documenting}\label{md_CONTRIBUTING_autotoc_md7}
\mbox{\hyperlink{md_NEWS}{NEWS.md}} contains a list of user-\/visible changes in the library between release versions. This includes changes to the way it\textquotesingle{}s packaged, bug fixes, portability notes, changes to the API, and so on. Add and update items under a \char`\"{}\+Changes in X.\+Y.\+Z\char`\"{} heading at the top of the file. Do this as you go along, so that we don\textquotesingle{}t need to work out what happened when it\textquotesingle{}s time for a release.

\mbox{\hyperlink{md_TODO}{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 \mbox{\hyperlink{md_NEWS}{NEWS.md}} when they are done. Regularly check to see if there is anything that needs removing or updating.\hypertarget{md_CONTRIBUTING_autotoc_md8}{}\doxysubsection{Submitting}\label{md_CONTRIBUTING_autotoc_md8}
Fixes or improvements in pull requests are welcome. Please\+:


\begin{DoxyItemize}
\item \mbox{[} \mbox{]} Send small PRs that address one issues each.
\item \mbox{[} \mbox{]} Update {\ttfamily NEWS.\+md} to say what you changed.
\item \mbox{[} \mbox{]} Add a test as a self-\/contained C file in {\ttfamily tests/} that passes or fails, and is hooked into {\ttfamily CMake\+Lists.\+txt}.
\item \mbox{[} \mbox{]} Keep the code style consistent with what\textquotesingle{}s already there, especially in keeping symbols with an {\ttfamily rs\+\_\+} prefix.
\end{DoxyItemize}\hypertarget{md_CONTRIBUTING_autotoc_md9}{}\doxysubsection{Releasing}\label{md_CONTRIBUTING_autotoc_md9}
If you are making a new tarball release of librsync, follow this checklist\+:


\begin{DoxyItemize}
\item Make a \char`\"{}\+Release vx.\+x.\+x\char`\"{} pull request containing updates ready for the release including;
\begin{DoxyItemize}
\item Review the changes included and decide if the release should be a major (non-\/backwards compatible change), minor (backwards compatible change), or micro (bugfix only change) version number change to get the new \char`\"{}\+X.\+Y.\+Z\char`\"{} version number.
\item NEWS.\+md -\/ make sure the top \char`\"{}\+Changes in X.\+Y.\+Z\char`\"{} is correct, and the date is correct. Make sure the changes since the last release are documented.
\item TODO.\+md -\/ check if anything needs to be removed or updated.
\item {\ttfamily CMake\+Lists.\+txt} -\/ version is correct.
\item {\ttfamily librsync.\+spec} -\/ make sure version and URL are right.
\end{DoxyItemize}
\item Run {\ttfamily make all doc check} in a clean checkout of the release pull request branch. Also check the Git\+Hub Actions \href{https://github.com/librsync/librsync/actions}{\texttt{ check and lint status}} of the last commit on github. If it all looks good merge the release pull request on github.
\item Draft a new release on github, typing in the release details including an overview, included changes, and known issues. The overview should give an indication of the magnitude of the changes and their impact, and the relative urgency to upgrade. The included changes should come from the NEWS.\+md for the release. It\textquotesingle{}s probably easiest to copy and edit the previous release.
\item After creating the release, download the {\ttfamily Source code (tar.\+gz)} release asset. Go to \char`\"{}\+Actions\char`\"{}, find the workflow run for the \char`\"{}\+Check\char`\"{} corresponding to the merge of the release pull request, and download the {\ttfamily install results windows-\/latest Release} artifact renamed to {\ttfamily librsync-\/win64-\/\+X.\+Y.\+Z.\+zip}. Edit the release, and upload the source code and windows artifacts. This ensures that the release includes a stable tarball (See \href{https://github.com/librsync/librsync/issues/146}{\texttt{ https\+://github.\+com/librsync/librsync/issues/146}} for details) and win64 install.
\item Run {\ttfamily make doc} on a clean checkout of the new release tag and {\ttfamily cp -\/av html/$\ast$} into a {\ttfamily rm -\/Rf $\ast$} emptied checkout of librsync.\+github.\+io and check it in. This ensures it includes deletes of obsolete files as well as new and updated files. Push this to update the online docs.
\item Create and merge a \char`\"{}\+Prepare v\+X.\+Y.\+Z+1.\char`\"{} pull request containing updates to prepare for the changes in the next release including;
\begin{DoxyItemize}
\item Bump the minor version in {\ttfamily CMake\+Lists.\+txt}.
\item Add a {\ttfamily NOT RELEASED YET} version entry in {\ttfamily NEWS.\+md}
\item Bump the minor version and add a {\ttfamily changelog} entry in {\ttfamily librsync.\+spec}. 
\end{DoxyItemize}
\end{DoxyItemize}