Building
Santa uses Bazel for building, testing and releases. The main
branch on GitHub is the source-of-truth with features developed in personal forks.
Cloning
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
Building
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.
Running
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
command+r
- From the utilities menu select
Terminal
- Disable the KEXT feature of SIP:
csrutil enable --without kext
- Reboot
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
Using Xcode
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.
generate_xcodeproj.sh santa.tulsiproj
Debugging
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.
process | user |
---|---|
santad | root |
Santa* | me |
santactl | me |
santabs | root |
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.
Tests
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
Releases
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