Santa uses Bazel for building, testing and releases. The
main branch on GitHub is the source-of-truth with features developed in personal forks.
Clone the source and change into the directory.
git clone https://github.com/google/santa
The above command will default to using the
main branch. All releases are built from tagged commits, so if you wanted to build, run or test a specific release you can checkout that tag:
git checkout 2022.5
If you want to list all the tags in reverse order:
git tag --sort=-creatordate
Build a debug version of Santa:
bazel build //Source/gui:Santa
This will build and sign all of the santa components (UI and services).
For developers who do not have access to Google’s code signing certificate and provisioning profiles, use the
--define=SANTA_BUILD_TYPE=adhoc flag. This will adhoc sign Santa and does not require provisioning profiles.
Note: In order to run an adhoc signed Santa SIP must be disabled. See the running section below.
bazel build //Source/gui:Santa --define=SANTA_BUILD_TYPE=adhoc
When working on Santa, it’s useful to have a way to quickly reload all of the Santa components. For this reason, there’s a special rule in the Santa BUILD file that will build Santa, unload Santa if it’s running, install the new Santa in the right place and attempt to load it.
Non-adhoc debug builds of Santa can only be run by Google developers. This is because of bundle id and provisioning profile restrictions bound to Apple developer accounts.
bazel run :reload
Non-Google developers can use an adhoc build to run development builds of Santa. System Integrity Protection (SIP) will need to be disabled in order to run an adhoc build.
This is only to be done a machine that is actively developing Santa.
- Boot into Recovery Mode:
- For Intel Macs reboot and hold down
- For Apple Silicon Macs press and hold the power button until “Loading startup options” appears. Click Options, then click Continue. If asked, select a volume to recover, then click Next.
- For Intel Macs reboot and hold down
- From the utilities menu select
- Disable the KEXT feature of SIP. The kext wording is legacy but the command still works well for loading adhoc signed system extensions:
csrutil enable --without kext
You should now be able to load and run a non-release version of Santa.
Build and run an adhoc debug version of Santa.
bazel run :reload --define=SANTA_BUILD_TYPE=adhoc
Note: if you are currently running a release or non-adhoc dev build of Santa, this new adhoc build will show up as a second instance of Santa. Remove the non-adhoc instance like so:
systemextensionsctl uninstall EQHXZ8M8AV com.google.santa.daemon
We don’t generally use Xcode when working on Santa but it’s very useful to be able to use an IDE when developing. We generally use clangd for this, using a tool that will extract the appropriate compile commands automatically from our Bazel build rules. To use this:
bazel run @hedron_compile_commands//:refresh_all to generate the
2) Follow the instructions for setting up your editor.
lldb can be used to debug Santa, similarly to any other project, with some exceptions. lldb can attach to com.google.santa.daemon, however any breakpoints in the decision making codepath can deadlock the machine.
Run all the logic / unit tests
bazel test :unit_tests --define=SANTA_BUILD_TYPE=adhoc --test_output=errors
Debug versions of Santa have the ability to set/override config settings using an override file, that will be applied over the top of the configuration from a profile.
- Create a plist in
For example to point Santa at a sync server running on localhost here would be the config-override file.
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
:warning: Warning Make sure the file is readable.
bazel run //:reloadto rebuild and restart the Santa daemon.
Creates a release build of Santa with a version based of the newest tag. Also saves the dsym files for each component of Santa. This makes debugging and interpreting future crashes much easier. Releases are handled by Google internal infrastructure.
bazel build --apple_generate_dsym -c opt //:release