@@ -58,6 +58,40 @@ make linux_amd64 MODULES=cli,os,java
5858make linux_amd64 MODULES=all
5959```
6060
61+ #### 3. Individual Component Build
62+ ``` bash
63+ # Build individual components for current platform
64+ make cli # Build CLI tool only
65+ make os # Build OS experiment scenarios
66+ make cloud # Build cloud experiment scenarios
67+ make middleware # Build middleware experiment scenarios
68+ make java # Build Java experiment scenarios
69+ make cplus # Build C/C++ experiment scenarios
70+ make cri # Build CRI experiment scenarios
71+ make kubernetes # Build Kubernetes experiment scenarios
72+ make nsexec # Build nsexec (Linux only)
73+ make upx # Compress binaries with UPX
74+ make check_yaml # Download check specification YAML files
75+ ```
76+
77+ #### 4. Build Preparation and Utilities
78+ ``` bash
79+ # Generate version information from Git
80+ make generate_version
81+
82+ # Sync go.mod dependencies with Makefile branch configuration
83+ make sync_go_mod
84+
85+ # Prepare build environment (clean and create directories)
86+ make pre_build
87+
88+ # Package build artifacts
89+ make package
90+
91+ # Clean all build artifacts
92+ make clean
93+ ```
94+
6195### Component List
6296
6397| Component | Description | Notes |
@@ -128,6 +162,10 @@ make build_linux_amd64_image
128162
129163# Build Linux ARM64 image
130164make build_linux_arm64_image
165+
166+ # Build with specific modules
167+ make build_linux_amd64_image MODULES=cli,os
168+ make build_linux_arm64_image MODULES=all
131169```
132170
133171### Image Push
@@ -136,19 +174,34 @@ make build_linux_arm64_image
136174make push_image
137175```
138176
177+ ### Container Runtime Configuration
178+ The build system automatically detects available container runtimes:
179+ - ** Docker** (default)
180+ - ** Podman** (if Docker is not available)
181+
182+ You can manually specify the container runtime:
183+ ``` bash
184+ # Use Docker explicitly
185+ make nsexec CONTAINER_RUNTIME=docker
186+
187+ # Use Podman explicitly
188+ make nsexec CONTAINER_RUNTIME=podman
189+ ```
190+
139191## Cross-Platform Compilation
140192
141193### nsexec Cross-Platform Compilation
142194The nsexec component supports cross-compilation from macOS to Linux:
143195
144196#### Automatic Compiler Detection
145- The system automatically detects available cross-compilation toolchains:
146- - ` musl-gcc `
147- - ` /usr/local/musl/bin/musl-gcc `
148- - ` x86_64-linux-musl-gcc `
149- - ` aarch64-linux-musl-gcc `
150- - ` gcc `
151- - ` aarch64-linux-gnu-gcc `
197+ The system automatically detects available cross-compilation toolchains in this order:
198+ 1 . ` musl-gcc ` (for amd64)
199+ 2 . ` /usr/local/musl/bin/musl-gcc ` (for amd64)
200+ 3 . ` x86_64-linux-musl-gcc ` (for amd64)
201+ 4 . ` aarch64-linux-musl-gcc ` (for arm64)
202+ 5 . ` gcc ` (fallback for both architectures)
203+ 6 . ` aarch64-linux-gnu-gcc ` (for arm64)
204+ 7 . ` container ` (if no suitable compiler found)
152205
153206#### Containerized Compilation
154207If no suitable cross-compilation toolchain is available, containers can be used for compilation:
@@ -160,19 +213,55 @@ make nsexec CONTAINER_RUNTIME=docker
160213make nsexec CONTAINER_RUNTIME=podman
161214```
162215
216+ ### Cross-Platform Build with Containers
217+ ``` bash
218+ # Build Linux AMD64 using musl container
219+ make cross_build_linux_amd64_by_container
220+
221+ # Build Linux ARM64 using ARM container
222+ make cross_build_linux_arm64_by_container
223+ ```
224+
225+ ### UPX Binary Compression
226+ The build system supports UPX compression for smaller binary sizes:
227+ ``` bash
228+ # Compress binaries with UPX (Linux and Windows only)
229+ make upx
230+
231+ # UPX is automatically applied during packaging for supported platforms
232+ ```
233+
234+ ** Supported platforms for UPX:**
235+ - Linux (amd64, arm64)
236+ - Windows (amd64)
237+
238+ ** Installation:**
239+ - macOS: ` brew install upx `
240+ - Ubuntu/Debian: ` apt-get install upx-ucl `
241+ - CentOS/RHEL: ` yum install upx `
242+
163243## Build Configuration
164244
165245### Environment Variables
166- - ` GOOS ` : Target operating system
167- - ` GOARCH ` : Target architecture
168- - ` BLADE_VERSION ` : Version number
169- - ` CONTAINER_RUNTIME ` : Container runtime (docker/podman)
170- - ` MODULES ` : List of components to build
246+ - ` GOOS ` : Target operating system (linux, darwin, windows)
247+ - ` GOARCH ` : Target architecture (amd64, arm64)
248+ - ` BLADE_VERSION ` : Version number (auto-detected from Git tags or set manually)
249+ - ` CONTAINER_RUNTIME ` : Container runtime (docker/podman, auto-detected)
250+ - ` MODULES ` : Comma-separated list of components to build
251+ - ` GOPATH ` : Go workspace path (for containerized builds)
171252
172253### Build Flags
173- - ` CGO_ENABLED=0 ` : Disable CGO
254+ - ` CGO_ENABLED=0 ` : Disable CGO for static linking
174255- ` GO111MODULE=on ` : Enable Go modules
175- - Static linking flags: ` -ldflags="-s -w" `
256+ - Static linking flags: ` -ldflags="-s -w" ` (strip debug info and symbols)
257+ - Version injection: ` -X ` flags for embedding version information
258+
259+ ### Version Information Injection
260+ The build process automatically injects version information into binaries:
261+ - Version number from Git tags or environment
262+ - Build environment (` uname -mv ` )
263+ - Build timestamp
264+ - Component-specific version information
176265
177266## Build Artifacts
178267
@@ -188,6 +277,14 @@ target/
188277### File Naming
189278- Executable files: ` blade ` (Linux/macOS) or ` blade.exe ` (Windows)
190279- Compressed packages: ` chaosblade-{version}-{platform}_{arch}.tar.gz `
280+ - YAML specification files: ` chaosblade-{component}-spec-{version}.yaml `
281+ - Check specification: ` chaosblade-check-spec-{version}.yaml `
282+
283+ ### Build Cache
284+ The build system uses a cache directory to store downloaded dependencies:
285+ - Cache location: ` target/cache/ `
286+ - Cached components: All external repositories (os, cloud, middleware, etc.)
287+ - Cache management: Automatic clone/update of cached repositories
191288
192289## Common Command Examples
193290
@@ -224,6 +321,38 @@ make linux_amd64 MODULES=all
224321make build_linux_amd64_image
225322make build_linux_arm64_image
226323make push_image
324+
325+ # Build images with specific modules
326+ make build_linux_amd64_image MODULES=cli,os
327+ make build_linux_arm64_image MODULES=all
328+ ```
329+
330+ ### Cross-Platform Build
331+ ``` bash
332+ # Build Linux versions using containers
333+ make cross_build_linux_amd64_by_container
334+ make cross_build_linux_arm64_by_container
335+ ```
336+
337+ ### Utility Commands
338+ ``` bash
339+ # Generate version information
340+ make generate_version
341+
342+ # Sync dependencies
343+ make sync_go_mod
344+
345+ # Compress binaries
346+ make upx
347+
348+ # Download check specifications
349+ make check_yaml
350+
351+ # Run tests
352+ make test
353+
354+ # Clean build artifacts
355+ make clean
227356```
228357
229358## Troubleshooting
@@ -264,6 +393,49 @@ podman info
264393make nsexec CONTAINER_RUNTIME=docker
265394```
266395
396+ #### 4. UPX Compression Issues
397+ ``` bash
398+ # Check if UPX is installed
399+ which upx
400+
401+ # Install UPX on different platforms
402+ # macOS
403+ brew install upx
404+
405+ # Ubuntu/Debian
406+ sudo apt-get install upx-ucl
407+
408+ # CentOS/RHEL
409+ sudo yum install upx
410+ ```
411+
412+ #### 5. Cross-Compilation Issues
413+ ``` bash
414+ # Check available cross-compilers
415+ which musl-gcc
416+ which aarch64-linux-gnu-gcc
417+
418+ # Install cross-compilation tools
419+ # Ubuntu/Debian
420+ sudo apt-get install musl-tools gcc-aarch64-linux-gnu
421+
422+ # macOS
423+ brew install FiloSottile/musl-cross/musl-cross
424+ ```
425+
426+ #### 6. Git Version Issues
427+ ``` bash
428+ # Check Git version
429+ git --version
430+
431+ # Update Git if needed
432+ # Ubuntu/Debian
433+ sudo apt-get update && sudo apt-get install git
434+
435+ # macOS
436+ brew install git
437+ ```
438+
267439### Clean Build Artifacts
268440``` bash
269441# Clean all build artifacts
0 commit comments