Developer FAQ

FAQ for Netatalk Developers

How can I create stand-alone patch files?

This describes the traditional method of creating plain text patch files. If you prefer to not use GitHub, you can create a patch file and submit it to the netatalk-devel mailing list.

Assuming your patches are the last three commits on your current local git branch, this is the easiest way to create patches from them:

$ git format-patch -3

This will create three patch files in your current directory that you can then send to the mailing list.

Note that if you have a number of patches against a specific branch and don't feel like counting them, the following works as well (e.g. against the main branch):

$ git format-patch origin/main

This will create one patch file for every patch that is in your local branch but not in origin/main.

If you have more patches which belong together it's sometimes useful to export them into one file:

$ git format-patch --stdout origin/main > develop-featureX-01.patches.txt

How can I debug process crashes?

We need a stack-backtrace (SBT) from a corefile with debugging symbols.

• Compile Netatalk with debugging symbols and without optimizations, e.g. when building with Meson:

meson setup build -Dbuildtype=debug
meson compile -vC build
meson install -vC build

• Enable global corefile generation (Linux, Solaris)
• Enable corefile generation for Netatalk by adding:

ulimit -c unlimited

... at the beginning of the Netatalk start script and restart Netatalk.

• Reproduce issue
• Get SBT (example for a crash of afpd and gdb):

$ gdb path/to/afpd path/to/corefile
(gdb) bt full
...
(gdb) exit

How can I run the netatalk tests?

See Testing

How do I revert a commit?

The "git reset" command allows you to reset the HEAD of the branch to any given point in history. To go back one commit, run

$ git reset HEAD^

This will keep your local changes and you can make any additional changes before re-committing the new work. Also see the "git commit --amend" command and the "git reset" man page for other examples.

If the branch has already been pushed to remote, you can force-push the amended branch. Please be careful with force pushing, since it can be a destructive action.

$ git push origin my-work-branch --force

How can I maintain a feature branch against the upstream Netatalk branches?

You clone the Netatalk repository as per the instructions above. Then you make a new feature branch:

$ git checkout -b feature_foo main

Now you do your development in your feature branch. Any time the main branch gets too different to the code in your feature branch you should rebase your feature branch. The rebase rewinds your feature branch to the point there it was branched. Then it updates your feature branch to the HEAD of the main branch and re-applies your changes.

$ git rebase main
First, rewinding head to replay your work on top of it...
HEAD is now at 357f003... Add WERR_SERVICE_ALREADY_RUNNING.
...
Wrote tree 02299ef7c1cfa093248bfd9c6e3812805718845e
Committed: e20a8c521d7860d9b7bd724ed5ea19c7306530ab

Rebase works best when you use it for local branches that are never pushed to a public repository, see Why won't "git push" work after I rebased a branch?.

How can I develop and test on other architectures?

You can use QEMU to emulate machines of other architectures than that of your physical machine. On macOS, you can use the UTM frontend for QEMU.

It is also possible to run QEMU in Docker, which allows for instantly spinning up a fully functional environment.

The following example uses Docker images by the multiarch project. Note that this only works on amd64 hosts at the time of writing.

These steps will create the QEMU mulitarch container, and then use it for emulating the IBM s390x architecture with a pre-configured Debian Testing container.

docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
docker run -ti --platform linux/s390x --volume s390xhome:/home --name s390x_deb s390x/debian:testing
docker exec -ti s390x_deb /bin/bash