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 cd 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 0.9.33
If you want to list all the tags in reverse order:
git tag --sort=-creatordate
Build a debug version of Santa:
bazel build //Source/santa_driver
Build a release (optimized) version of Santa:
bazel build //Source/santa_driver -c opt
The output for these commands will be a
santa-driver.zip file under
bazel-bin which, when extracted, will contain all of Santa and should be installed under
/Library/Extensions. However, if you’re working on Santa and want a quick way to reload everything, see the next section.
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 compile a new santa-driver, unload Santa if it’s running, install the new Santa in the right place and attempt to load it.
On macOS 10.11+ System Integrity Protection (SIP) prevents loading of kernel extensions that are not signed by an Apple KEXT signing certificate. To be able to load and test a non-release version of Santa, SIP will have to be configured to allow non-Apple KEXT signing certificates.
This is only to be done a machine that is actively developing, unloading and loading kernel extensions.
- Boot into Recovery Mode: Reboot and hold down
- From the utilities menu select
- Disable the KEXT feature of SIP:
csrutil enable --without kext
You should now be able to load and run a non-release version of Santa.
Build and run a debug version of Santa.
bazel run :reload
Build and run a release version of Santa.
bazel run :reload -c opt
While Bazel is a very convenient and powerful build system, it can still be useful to use Xcode for actually working on the code. If you’d like to use Xcode you can use Tulsi to generate an
.xcodeproj from the BUILD file which will use Bazel for actually doing the builds.
Xcode and lldb can be used to debug Santa, similarly to any other project, with some exceptions. Instead of clicking the play button to launch and attach to a process, you can attach to an already running, or soon to by running, component of Santa. To do this select the Debug menu and choose
Attach to Process by PID or Name…. Below are the four components of Santa and who to debug the process as.
Note: santa-driver (the kernel extension) cannot be debugged by attaching with Xcode.
Note: Xcode can attach to santad without interruption, however any breakpoints in the decision making codepath can deadlock the machine. Using lldb directly to attach to santad will deadlock the machine.
Xcode will then wait for the process to start. Issue this command to restart all the Santa processes in debug mode.
*The Santa (GUI) process is the only component of Santa that can be launched and debugged from Xcode directly. All the other components are launched with privileges and/or are scoped to an XPC service that launchd scopes to a hosting bundle. Thus the need for the
Attach to Process by PID or Name… technique. See the ipc document for for details.
bazel run :reload
Now the process is attached in Xcode and you can debug your day away.
Run all the logic / unit tests
bazel test :unit_tests
Run all of santa-driver kernel extension tests
bazel run //Source/santa_driver:kernel_tests
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 or kernel panics much easier.
bazel build :release