1. Pre-requisites

Here the list of required component to be install to start developing rdiff-backup on Windows platform.

Tip
 all these steps are packed into the Ansible playbook playbook-provision.yml in the tools/windows directory, so that it becomes easy to do it automatically.

1.1. Upgrade your Windows OS

Don’t overlook this step. Visual Studio required an upgraded OS. Use Windows Update to upgrade your system. Then proceed with the installation.

1.2. Install Chocolatey

You can install all the dependencies on your own, but Chocolatey makes it much easier and repeatable. Hence our recommendation to install it.

Note
 the Ansible module win_chocolatey will install Chocolatey transparently if it isn’t already done.

1.3. Install all tools using Chocolatey

Install first the following packages (if there are no comments, the defaults are just fine):

  • git

  • 7zip

  • cmake, with something like choco install cmake --install-arguments="ADD_CMAKE_TO_PATH=System"

  • python3, with something like choco install python3 --version ${PYTHON_VERSION} --params "/InstallDir:C:\Python64 /InstallDir32:C:\Python32"

  • ruby

  • dotnetfx

  • vcredist140

Optionally you can also install:

  • cygwin, because it makes Windows bearable for Linux-aficionados

  • cyg-get (depends on cygwin)

  • vscode, Visual Studio Code (editor)

Then reboot, and continue with:

  • visualstudio2022buildtools

  • visualstudio2022-workload-python

  • visualstudio2022-workload-vctools

A last reboot is recommended here to make sure you’ve got the correct PATH.

1.4. Python dependencies

Once python is installed, you should have a pip available from command line. Open a terminal and execut the following commands to install the dependencies required to compile and run rdiff-backup.

pip.exe install --upgrade pywin32 pyinstaller wheel certifi setuptools-scm tox PyYAML

You could verify if packages are properly installed using:

python.exe -c 'import pywintypes, winnt, win32api, win32security, win32file, win32con'
Important
 you will want to do this once for the 32 bits and once for the 64 bits version of Python. Check the script tools/win_provision.sh for an example on how to do this.
Tip
 You can even call the script directly under Windows using the bash shell coming with Git, installed as C:/Program Files/Git/bin/bash.exe.

1.5. Install asciidoctor

This is required to render the documentation:

gem.cmd install asciidoctor

2. Build, test and package librsync and rdiff-backup

You can simply call the following scripts, again using Git’s bash shell, where arch is either 32 or 64:

tools/win_build_librsync.sh ${arch} ${WIN_LIBRSYNC_VERSION}
tools/win_build_rdiffbackup.sh ${arch} ${WIN_PYTHON_VERSION} yes
tools/win_test_rdiffbackup.sh ${arch} ${WIN_PYTHON_VERSION} yes
tools/win_package_rdiffbackup.sh ${arch}
Tip
 again, under tools/windows, the playbooks playbook-pipeline.yml shows how it can be automated using Ansible. Similarly you can also check .github/workflows/test_windows.yml for details of our pipeline.

3. Troubleshooting

3.1. Verify if Visual studio compiler is working

You could check if the compiler cl is working by calling:

cl.exe hello.c

Where the file hello.c contains:

#include <stdio.h>
int main() {
   // printf() displays the string inside quotation
   printf("Hello, World!");
   return 0;
}

The expected output should be as follow:

Compilateur d'optimisation Microsoft (R) C/C++ version 19.24.28314 pour x86
Copyright (C) Microsoft Corporation. Tous droits réservés.

hello.c
Microsoft (R) Incremental Linker Version 14.24.28314.0
Copyright (C) Microsoft Corporation.  All rights reserved.

/out:hello.exe
hello.obj

3.2. unresolved external symbol

If you see link errors like these:

_librsyncmodule.obj : error LNK2001: unresolved external symbol rs_sig_begin
_librsyncmodule.obj : error LNK2001: unresolved external symbol rs_job_free
_librsyncmodule.obj : error LNK2001: unresolved external symbol rs_loadsig_begin

then you have probably compiled librsync for the wrong architecture. Try both -A Win32/-A x64 switches when running cmake to build librsync.

If you see link errors like these:

cmodule.obj : error LNK2001: unresolved external symbol __imp__Py_BuildValue
cmodule.obj : error LNK2001: unresolved external symbol __imp__PyDict_SetItemString
cmodule.obj : error LNK2001: unresolved external symbol __imp__PyModule_GetDict

then you are using the wrong bitness build tools. Try both "x64 Native Tools Command Prompt for VS 2019" as well as "Developer Command Prompt for VS2019".

4. Debugging (from the command line)

I’m a Windows no-obs, and I use Windows through Vagrant, mostly from the command line (using vagrant ssh). Here are my notes on some tricks I learned, Windows is a weird beast for a Linux guy…​

4.1. Process handling

Get a list of processes: tasklist

Kill a process: taskkill /IM firefox.exe /F

To get the return code of the last command (the equivalent of $? under Linux), call echo %ERRORLEVEL%.

4.2. Files handling

To get a list of opened files, and the process accessing them:

openfiles /local ON
REM reboot
openfiles /query /fo csv | find /I "<path>"

With icacls you can list the (Windows) ACLs of a file.

With attrib you can set the read-only attribute of a file.

With fsutil file queryfileid FILENAME you can get the "inode" of a file.

4.3. Shells

Different shells might be useful:

  • cmd.exe is the default one.

  • PowerShell can be started with powershell.

  • Git comes with the bash shell "\Program Files\Git\bin\bash.exe"