This chapter is a very opinionated way of starting programming for rdiff-backup.
If you are a seasoned Python programmer, you might want to skip it.
We are only assuming that:
-
You have Linux.
-
You are somewhat confident with the command line, SSH and an editor of your choice.
-
You have a GitHub account we’ll call MYGHUSER with an SSH key assigned.
-
APT_DNF_ZYPPER is a placeholder for whatever package manager is used on your Linux version, and you have the necessary access rights to call it via sudo (sudo pacman -S … is also fine instead, or whatever).
Once you’re ready, start with the dependencies:
-
Fork the rdiff-backup repository into your user MYGHUSER.
-
Go through the following commands once:
sudo apt update # only under Debian/Ubuntu
sudo pacman -Sy # only under pacman-based distros
sudo APT_DNF_ZYPPER install git findutils python3
sudo apt install python3-venv # only under Debian/Ubuntu
git clone git@github.com:rdiff-backup/rdiff-backup-filesrepo.git
sudo tar xf rdiff-backup-filesrepo/rdiff-backup_testfiles.tar
sudo ./rdiff-backup-filesrepo/rdiff-backup_testfiles.fix.sh #(1)
git clone git@github.com:MYGHUSER/rdiff-backup.git
cd rdiff-backup
python3 -m venv .venv #(2)
. .venv/bin/activate #(3)
pip install bindep #(4)
pip install --upgrade pip #(5)
pip install powerline-status #(6)
sudo dnf config-manager --set-enabled crb # only under CentOS & Co
sudo dnf install epel-release # only under CentOS & Co
sudo APT_DNF_ZYPPER install $(bindep -b devel) #(7)
pip install -r requirements.txt
pip install . #(8)
which rdiff-backup #(9)
rdiff-backup --version #(10)
-
This command must be called as the user with which you’ll test.
Don’t call it directly as root.
-
This create a Virtual Environment so that you keep your system clean.
-
It’s really a single point followed by .venv/….
Anyway, after that command, your prompt should have (.venv) prefix.
If not, something is wrong and should be fixed before continuing.
-
bindep allows us to define non-Python dependencies in bindep.txt.
-
If pip tells you to do so, it’s just annoying.
-
If using vim from within the venv gives you powerline warnings; again annoying…
You may ignore potential deprecation warnings.
-
This might fail under the more exotic Linux versions, feel free to provide a patch to bindep.txt or raise an issue together with the output of bindep --profiles.
-
You’re installing rdiff-backup from the Git repository.
-
This should point at the rdiff-backup installed within the venv …/.venv/bin/rdiff-backup.
-
The version is typically longer than usual and with a dev in it.
At this point, you can use rdiff-backup almost as normal, e.g. rdiff-backup info or rdiff-backup --help.
If you’ve done everything correctly, any other command should work as well (try it out before continuing) with the exception of remote commands.
Because rdiff-backup isn’t in your PATH on the other side of an SSH connection, it will fail (or you will use the wrong version of rdiff-backup).
There are multiple ways to address this issue:
-
Use a --remote-schema explicitly pointing at the right rdiff-backup e.g. rdiff-backup --remote-schema "ssh -C {h} $(which rdiff-backup) server" -v5 backup docs localhost::/tmp/bak.
-
Use a fake remote schema not using SSH as in rdiff-backup --remote-schema "mkdir -p {h}; cd {h}; rdiff-backup server" -v5 backup docs fake.myown.d::/tmp/bak (don’t forget to rmdir fake.myown.d after).
This is the approach used by most of the test suite so that tests don’t rely on SSH.
-
Install your own version of rdiff-backup at user or even system level using pip.
But this can be dangerous so only do it if you know what you’re doing (and hence how to do it).
|
Tip
|
you can leave the venv with deactivate, then the (.venv) prefix disappears.
|
If everything went well till now, you can start to do changes to the code.
Each time you’ll do so, you’ll want to install it again and test your changes:
-
Verify that you’re in the venv (check the prefix), activate it if necessary with source .venv/bin/activate.
-
Fix your code with black src testing setup.py.
-
Install your latest version of rdiff-backup with pip install ..
-
There are many ways to test it, but the minimal set is tox -e check-static followed by tox -e py.
|
Important
|
Please don’t submit code which hasn’t passed both tests!
Also read the rest of this document and its companions in their entirety and comply with our guidlines and conventions.
If you encounter issues or have doubts, ask on the mailing list after having registered.
|
-
Once successful, you’re ready for your first Pull Request (PR).
|
Note
|
The above instructions have been cursorily tested in containers using podman with the images opensuse/tumbleweed, debian, ubuntu, archlinux, manjarolinux/base, quay.io/centos/centos:stream10.
In general, the packages vim and sudo had to be installed and a user with sudo-rights created (e.g. useradd -m -G wheel myuser).
Full testing hasn’t been done as the container’s file system doesn’t allow the creation of certain special files.
|