9# ClickHouse Build Skill
10
11Build ClickHouse in build or build_${buildType} or build/${buildType} directory (e.g., build, build_debug, build_asan...)
12
13## Arguments
14
15- $0 (optional): Build type - one of: Release, Debug, RelWithDebInfo, ASAN, TSAN, MSAN, UBSAN. Default: RelWithDebInfo
16- $1 (optional): Target - specific target to build (e.g., clickhouse-server, clickhouse-client, clickhouse). Default: clickhouse
17- $2+ (optional): Additional cmake/ninja options
18
19## Build Types
20
21| Type | Description | CMake Flags |
22|------|-------------|-------------|
23| Release | Optimized production build | -DCMAKE_BUILD_TYPE=Release |
24| Debug | Debug build with symbols | -DCMAKE_BUILD_TYPE=Debug |
25| RelWithDebInfo | Optimized with debug info | -DCMAKE_BUILD_TYPE=RelWithDebInfo |
26| ASAN | AddressSanitizer (memory errors) | -DCMAKE_BUILD_TYPE=Debug -DSANITIZE=address |
27| TSAN | ThreadSanitizer (data races) | -DCMAKE_BUILD_TYPE=Debug -DSANITIZE=thread |
28| MSAN | MemorySanitizer (uninitialized reads) | -DCMAKE_BUILD_TYPE=Debug -DSANITIZE=memory |
29| UBSAN | UndefinedBehaviorSanitizer | -DCMAKE_BUILD_TYPE=Debug -DSANITIZE=undefined |
30
31## Common Targets
32
33- clickhouse - Main all-in-one binary
34- clickhouse-server - Server component
35- clickhouse-client - Client component
36- clickhouse-local - Local query processor
37- clickhouse-benchmark - Benchmarking tool
38
39## Build Process
40
41**IMPORTANT:** This skill assumes the build directory is already configured with CMake. Do NOT run cmake or create build directories - only run ninja.
42
431. **Determine build configuration:**
44 - Build type: $0 or RelWithDebInfo if not specified
45 - Target: $1 or clickhouse if not specified
46 - Build directory: build/${buildType} (e.g., build/RelWithDebInfo, build/Debug, build/ASAN)
47
482. **Create log file and start the build:**
49
50 **Step 2a: Create temporary log file first:**
51 ```bash
52 mktemp /tmp/build_clickhouse_XXXXXX.log
53 ```
54 - This will print the log file path
55 - **IMMEDIATELY report to the user:**
56 - "Build logs will be written to: [log file path]"
57 - Then display in a copyable code block:
58 ```bash
59 tail -f [log file path]
60 ```
61 - Example: "You can monitor the build in real-time with:" followed by the tail command in a code block
62
63 **Step 2b: Start the ninja build:**
64 ```bash
65 cd build/${buildType} && ninja [target] > [log file path] 2>&1
66 ```
67
68 **Important:**
69 - Do NOT create build directories or run cmake configuration
70 - The build directory must already exist and be configured
71 - Use the log file path from step 2a
72 - Redirect both stdout and stderr to the log file using > "$logfile" 2>&1
73 - Run the build in the background using run_in_background: true
74 - **After starting the build**, report: "Build started in the background. Waiting for completion..."
75
763. **Wait for build completion:**
77 - Use TaskOutput with block=true to wait for the background task to finish
78 - The log file path is already known from step 2a
79 - Pass the log file path to the Task agent in step 4
80
814. **Report results:**
82
83 **ALWAYS use Task tool to analyze results** (both success and failure):
84 - Use Task tool with subagent_type=general-purpose to analyze the build output
85 - **Pass the log file path from step 2a** to the Task agent - let it read the file directly
86 - Example Task prompt: "Read and analyze the build output from: /tmp/build_clickhouse_abc123.log"
87 - The Task agent should read the file and provide:
88
89 **If build succeeds:**
90 - Confirm build completed successfully
91 - Report binary location: build/${buildType}/programs/[target]
92 - Mention any warnings if present
93 - Report build time if available
94 - Keep response concise
95
96 **If build fails:**
97 - Parse the build output to identify what failed (compilation, linking, etc.)
98 - Extract and highlight the specific error messages with file paths and line numbers
99 - Identify compilation errors with the exact error text
100 - For linker errors, identify missing symbols or libraries
101 - For template errors, simplify and extract the core issue from verbose C++ template error messages
102 - Provide the root cause if identifiable
103 - Provide a concise summary with:
104 - What component/file failed to build
105 - The specific error type (syntax error, undefined symbol, etc.)
106 - File path and line number where error occurred
107 - The actual error message
108 - Brief explanation of likely cause if identifiable
109 - Filter out excessive verbose compiler output and focus on the actual errors
110
111 - Return ONLY the Task agent's summary to the user
112 - Do NOT return the full raw build output
113
114 **After receiving the summary:**
115 - If build succeeded: Proceed to step 5 to check for running server
116 - If build failed:
117 - Present the summary to the user first
118 - **MANDATORY:** Use AskUserQuestion to prompt: "Do you want deeper analysis of this build failure?"
119 - Option 1: "Yes, investigate further" - Description: "Launch a subagent to investigate the root cause across the codebase"
120 - Option 2: "No, I'll fix it myself" - Description: "Skip deeper analysis and proceed without investigation"
121 - If user chooses "Yes, investigate further":
122 - **CRITICAL: DO NOT read files, edit code, or fix the issue yourself**
123 - **MANDATORY: Use Task tool to launch a subagent for deep analysis only (NO FIXES)**
124 - Use Task tool with subagent_type=Explore to search for related code patterns, similar errors, or find where symbols/functions are defined
125 - For complex errors involving multiple files or dependencies, use Task tool with subagent_type=general-purpose to investigate missing symbols, headers, or dependencies
126 - Provide specific prompts to the agent based on the error type:
127 - Compilation errors: "Analyze the compilation error in [file:line]. Find where [symbol/class/function] is defined in the codebase and explain the root cause. Do NOT fix the code."
128 - Linker errors: "Investigate why [symbol] is undefined and find its implementation. Explain what's causing the linker error. Do NOT fix the code."
129 - Header errors: "Find which header file provides [missing declaration] and explain what's missing. Do NOT fix the code."
130 - Template errors: "Investigate the template instantiation issue with [template name] and explain the root cause. Do NOT fix the code."
131 - The subagent should only investigate and analyze, NOT edit or fix code
132 - **CRITICAL: Return ONLY the agent's summary of findings to the user**
133 - **DO NOT return full investigation details, raw file contents, or excessive verbose output**
134 - **Present findings in a well-organized summary format**
135 - If user chooses "No, I'll fix it myself":
136 - Skip deeper analysis
137 - Skip step 5 (no need to check for running server if build failed)
138
1395. **MANDATORY: Check for running server and offer to stop it (only after successful build):**
140
141 **IMPORTANT:** This step MUST be performed after every successful build. Do not skip this step.
142
143 **Use Task tool with subagent_type=general-purpose to handle server checking and stopping:**
144
145 ```
146 Task tool with subagent_type=general-purpose
147 Prompt: "Check if a ClickHouse server is currently running and handle it.
148
149 Steps:
150 1. Check for running ClickHouse server:
151 pgrep -f \"clickhouse[- ]server\" | xargs -I {} ps -p {} -o pid,cmd --no-headers 2>/dev/null | grep -v \"cmake|ninja|Building\"
152
153 2. If a server is running:
154 - Report the PID and explain it's using the old binary
155 - Use AskUserQuestion to ask: \"A ClickHouse server is currently running. Do you want to stop it so the new build can be used?\"
156 - Option 1: \"Yes, stop the server\" - Description: \"Stop the running server (you'll need to start it manually later)\"
157 - Option 2: \"No, keep it running\" - Description: \"Keep the old server running (won't use the new build)\"
158 - If user chooses \"Yes, stop the server\":
159 - Run: pkill -f \"clickhouse[- ]server\"
160 - Wait 1 second: sleep 1
161 - Verify stopped: pgrep -f \"clickhouse[- ]server\" should return nothing
162 - Report: \"Server stopped. To start the new version, run: ./build/${buildType}/programs/clickhouse server --config-file ./programs/server/config.xml\"
163 - If user chooses \"No, keep it running\":
164 - Report: \"Server remains running with the old binary. You'll need to manually restart it to use the new build.\"
165
166 3. If no server is running:
167 - Report: \"No ClickHouse server is currently running.\"
168
169 Keep the response concise and only report the outcome to the user."
170 ```
171
172 - Wait for the Task agent to complete
173 - Return the Task agent's summary to the user
174
1756. **MANDATORY: Provide final summary to user:**
176
177 After completing all steps, always provide a concise final summary to the user:
178
179 **For successful builds:**
180 - Confirm the build completed successfully
181 - Report the binary location: build/${buildType}/programs/[target]
182 - Report the server status outcome from step 5
183
184 **For failed builds:**
185 - Already handled in step 4 with error analysis and optional investigation
186
187 **Example final summary for successful build:**
188 ```
189 Build completed successfully!
190
191 Binary: build/RelWithDebInfo/programs/clickhouse
192 Server status: No ClickHouse server is currently running.
193 ```
194
195 Keep the summary brief and clear.
196
197## Examples
198
199- /build - Build clickhouse target in RelWithDebInfo mode (default)
200- /build Debug clickhouse-server - Build server in Debug mode
201- /build ASAN - Build with AddressSanitizer
202- /build Release clickhouse-client - Build only the client in Release mode
203
204## Notes
205
206- Always run from repository root
207- **NEVER** create build directories or run cmake - the build directory must already be configured
208- Build directories follow pattern: build/${buildType} (e.g., build/Debug, build/ASAN)
209- Binaries are located in: build/${buildType}/programs/
210- This skill only runs incremental builds with ninja
211- To configure a new build directory, the user must manually run CMake first
212- For a clean build, the user should remove build/${buildType} and reconfigure manually
213- **MANDATORY:** After successful builds, this skill MUST check for running ClickHouse servers and ask the user if they want to stop them to use the new build
214- **MANDATORY:** ALL build output (success or failure) MUST be analyzed by a Task agent with subagent_type=general-purpose
215- **MANDATORY:** ALWAYS provide a final summary to the user at the end of the skill execution (step 6)
216- **CRITICAL:** Build output is redirected to a unique log file created with mktemp. The log file path is reported to the user in a copyable format BEFORE starting the build, allowing real-time monitoring with tail -f. The log file path is saved from step 2a and passed to the Task agent for analysis. This keeps large build logs out of the main context.
217- **Subagents available:** Task tool is used to analyze all build output (by reading from output file) and provide concise summaries. Additional agents (Explore or general-purpose) can be used for deeper investigation of complex build errors
218