Skip to main content
IntelliJ IDEA is the recommended IDE for development work on the Halo measurement system. This guide walks you through setting up IntelliJ with the Bazel plugin for optimal development experience.

​
Requirements

IntelliJ IDEA

Version 2024.1 or later (Community or Ultimate Edition)

Bazel Plugin

Official JetBrains Bazel plugin
The project is known to be compatible with IntelliJ IDEA 2024.1 Community Edition as of April 2024.

​
Installation

1

Install IntelliJ IDEA

Download and install IntelliJ IDEA (Community Edition is sufficient).
2

Install Bazel Plugin

  1. Open IntelliJ IDEA
  2. Go to Settings/Preferences → Plugins
  3. Search for “Bazel” in the Marketplace
  4. Install the Bazel plugin
  5. Restart IntelliJ IDEA
3

Install ktfmt Plugin (Optional)

For automatic Kotlin formatting:
  1. Go to Settings/Preferences → Plugins
  2. Search for “ktfmt”
  3. Install the ktfmt plugin
  4. This will replace the default “Reformat Code” action

​
Project Setup

1

Import Bazel Project

  1. Open IntelliJ IDEA
  2. Select File → Import Bazel Project
  3. Choose the repository root as the workspace directory
  4. Click Next
2

Configure Project View

IntelliJ will create a .bazelproject file. Ensure it includes the following configuration:
directories:
  .

test_sources:
  src/test/*

derive_targets_from_directories: true

additional_languages:
  kotlin
3

Sync Project

Click Sync Project with BUILD Files or press the sync button in the toolbar.
The kotlin entry in additional_languages is required for proper code completion and navigation in Kotlin files.

​
.bazelproject File

The .bazelproject file configures how IntelliJ interacts with your Bazel workspace.

​
Basic Configuration

directories:
  .

test_sources:
  src/test/*

derive_targets_from_directories: true

additional_languages:
  kotlin

​
Configuration Options

OptionDescription
directoriesDirectories to include in the project (. includes all)
test_sourcesPatterns for test source directories
derive_targets_from_directoriesAuto-discover Bazel targets from directories
additional_languagesLanguages requiring special support (e.g., kotlin)

​
Advanced Configuration (Optional)

directories:
  .
  -bazel-container-output

test_sources:
  src/test/*

derive_targets_from_directories: true

additional_languages:
  kotlin

targets:
  //src/main/...
  //src/test/...

import_run_configurations:
  //src/main/kotlin/org/wfanet/measurement/...
Exclude the bazel-container-output directory if you use containerized builds to avoid indexing generated files.

​
Code Navigation Features

Once configured, IntelliJ provides powerful navigation capabilities:

Go to Definition

Ctrl+Click (Cmd+Click on macOS) on symbols to jump to their definition

Find Usages

Alt+F7 to find all usages of a symbol across the project

Navigate to Class

Ctrl+N (Cmd+O on macOS) to quickly find classes by name

Navigate to File

Ctrl+Shift+N (Cmd+Shift+O on macOS) to find any file

​
Running and Debugging

​
Run Bazel Targets

1

Create Run Configuration

  1. Right-click on a Bazel target in the project view
  2. Select Run ‘[target name]’
  3. IntelliJ automatically creates a run configuration
2

Execute

Click the Run button or press Shift+F10

​
Debug Bazel Targets

1

Set Breakpoints

Click in the gutter next to line numbers to set breakpoints
2

Start Debugging

  1. Right-click on a Bazel target
  2. Select Debug ‘[target name]’
  3. Or press Shift+F9 with an existing run configuration
3

Use Debug Controls

  • F8 - Step over
  • F7 - Step into
  • Shift+F8 - Step out
  • F9 - Resume program

​
Testing in IntelliJ

​
Run Tests

1. Right-click on a test class or method
2. Select "Run 'TestName'"

​
View Test Results

Test results appear in the Run tool window with:
  • ✅ Passed tests in green
  • ❌ Failed tests in red
  • Stack traces for failures
  • Console output from tests

​
Formatting and Code Style

​
Configure ktfmt

If you installed the ktfmt plugin:
1

Enable ktfmt

  1. Go to Settings/Preferences → Editor → ktfmt Settings
  2. Check Enable ktfmt
  3. Select Google (internal) style
2

Format on Save (Optional)

  1. Go to Settings/Preferences → Tools → Actions on Save
  2. Check Reformat code

​
Manual Formatting

Format code using:
  • Ctrl+Alt+L (Cmd+Option+L on macOS) - Format current file
  • Ctrl+Alt+Shift+L - Show reformat dialog with options
Use ktfmt with --google-style to match project standards. The IntelliJ plugin automatically applies this style.

​
Code Completion

The Bazel plugin provides intelligent code completion for:
  • Kotlin/Java/C++ code
  • Protocol buffer definitions
  • Bazel BUILD files
  • Starlark (.bzl) files
If code completion isn’t working, try syncing the project: Bazel → Sync → Sync Project with BUILD Files

​
Troubleshooting

​
Sync Issues

If the project isn’t syncing correctly:
1

Invalidate Caches

File → Invalidate Caches / Restart → Invalidate and Restart
2

Re-sync Project

Bazel → Sync → Sync Project with BUILD Files
3

Check .bazelproject

Verify the .bazelproject file includes additional_languages: kotlin

​
Missing Dependencies

If IntelliJ can’t resolve dependencies: 
# From terminal, ensure Bazel builds successfully:
bazel build //src/main/...
bazel build //src/test/...

# Then re-sync in IntelliJ

​
Performance Issues

For large projects:
  1. Limit indexed directories in .bazelproject: 
    directories:
  src/main/kotlin
  src/test/kotlin
  2. Increase IntelliJ memory:
    • Help → Change Memory Settings
    • Set to at least 4096 MB

​
Alternative: Containerized Development

If your host environment has glibc compatibility issues, you can run IntelliJ inside the build container: 
# Run container with X11 forwarding
docker run -it --rm \
  -v "$PWD":/workspace \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -e DISPLAY=$DISPLAY \
  ghcr.io/world-federation-of-advertisers/bazel \
  /bin/bash

# Install IntelliJ inside container
# Then launch with X11 forwarding to your host display
This approach is more complex and should only be used if local development isn’t possible.

​
Next Steps

Building

Learn how to build the project

Testing

Run and write tests

Dev Standards

Follow code review and commit standards

Contributing

Start contributing to the project

Build docs developers (and LLMs) love

Get started for freeTalk to us