|
@@ -1,88 +1,25 @@
|
|
|
# Terminal Logging Style Guide
|
|
|
|
|
|
-This guide defines the terminal output style for all bash scripts in the Spine Runtimes project.
|
|
|
-
|
|
|
-## Design Principles
|
|
|
-
|
|
|
-1. **Minimal visual noise** - Use color sparingly for emphasis, not decoration
|
|
|
-2. **Clear hierarchy** - Different levels of information have distinct visual treatments
|
|
|
-3. **Consistent spacing** - Clean vertical rhythm throughout output
|
|
|
-4. **Accessible** - Readable and meaningful even without colors
|
|
|
-5. **Scannable** - Easy to quickly identify successes, failures, and important information
|
|
|
-
|
|
|
-## Visual Hierarchy
|
|
|
-
|
|
|
-### 1. Title (`log_title`)
|
|
|
-- **Purpose**: Main script/tool name
|
|
|
-- **Style**: Bold with vertical spacing
|
|
|
-- **Usage**: Once at the beginning of script execution
|
|
|
-
|
|
|
-```bash
|
|
|
-log_title "Spine-C++ Build"
|
|
|
-```
|
|
|
-
|
|
|
-### 2. Action + Result (inline format)
|
|
|
-- **Purpose**: Individual operations with immediate result
|
|
|
-- **Style**: Action on same line as result for density
|
|
|
-- **Usage**: `log_action` followed immediately by `log_ok/fail/warn/skip`
|
|
|
-
|
|
|
-```bash
|
|
|
-log_action "Building all variants"
|
|
|
-log_ok # Green ✓ on same line
|
|
|
-
|
|
|
-log_action "Testing headless-test"
|
|
|
-log_fail # Red ✗ on same line
|
|
|
-```
|
|
|
-
|
|
|
-**Results**:
|
|
|
-- `log_ok` - Green ✓ (success)
|
|
|
-- `log_fail` - Red ✗ (failure)
|
|
|
-- `log_warn` - Yellow ! (warning)
|
|
|
-- `log_skip` - Gray - (skipped)
|
|
|
-
|
|
|
-### 4. Error Output (`log_error_output`)
|
|
|
-- **Purpose**: Full error output when operations fail
|
|
|
-- **Style**: Normal text (not grayed), prominent
|
|
|
-- **Usage**: Show command output after failures
|
|
|
-
|
|
|
-```bash
|
|
|
-log_action "Building"
|
|
|
-if BUILD_OUTPUT=$(command 2>&1); then
|
|
|
- log_ok
|
|
|
-else
|
|
|
- log_fail
|
|
|
- log_error_output "$BUILD_OUTPUT"
|
|
|
-fi
|
|
|
-```
|
|
|
-
|
|
|
-### 5. Detail (`log_detail`)
|
|
|
-- **Purpose**: Secondary information, debug info (not errors)
|
|
|
-- **Style**: Gray text, indented
|
|
|
-- **Usage**: Additional context, platform info
|
|
|
+## Functions
|
|
|
|
|
|
```bash
|
|
|
-log_detail "Platform: Darwin"
|
|
|
-log_detail "Branch: main"
|
|
|
-```
|
|
|
-
|
|
|
-### 6. Summary (`log_summary`)
|
|
|
-- **Purpose**: Final result or conclusion
|
|
|
-- **Style**: Bold with vertical spacing
|
|
|
-- **Usage**: End of script execution
|
|
|
+source ../formatters/logging/logging.sh
|
|
|
|
|
|
-```bash
|
|
|
-log_summary "✓ All tests passed (5/5)"
|
|
|
-log_summary "✗ Tests failed (3/5)"
|
|
|
+log_title "Script Name" # Bold title
|
|
|
+log_action "Doing something" # Action with inline result
|
|
|
+log_ok # Green ✓
|
|
|
+log_fail # Red ✗
|
|
|
+log_warn # Yellow !
|
|
|
+log_skip # Gray -
|
|
|
+log_error_output "$OUTPUT" # Show command output on errors
|
|
|
+log_detail "Extra info" # Gray secondary text
|
|
|
+log_summary "✓ All done" # Bold conclusion
|
|
|
```
|
|
|
|
|
|
-## Complete Example
|
|
|
+## Pattern
|
|
|
|
|
|
```bash
|
|
|
-#!/bin/bash
|
|
|
-source ../formatters/logging/logging.sh
|
|
|
-
|
|
|
log_title "Spine-C++ Build"
|
|
|
-log_detail "Platform: $(uname)"
|
|
|
|
|
|
log_action "Configuring debug build"
|
|
|
if CMAKE_OUTPUT=$(cmake --preset=debug . 2>&1); then
|
|
@@ -101,88 +38,20 @@ else
|
|
|
log_error_output "$BUILD_OUTPUT"
|
|
|
exit 1
|
|
|
fi
|
|
|
-
|
|
|
-log_summary "✓ Build successful"
|
|
|
```
|
|
|
|
|
|
-## Output Preview
|
|
|
+## Output
|
|
|
|
|
|
-**Success case:**
|
|
|
```
|
|
|
Spine-C++ Build
|
|
|
-Platform: Darwin
|
|
|
-
|
|
|
Configuring debug build... ✓
|
|
|
Building... ✓
|
|
|
-
|
|
|
-✓ Build successful
|
|
|
-```
|
|
|
-
|
|
|
-**Failure case:**
|
|
|
```
|
|
|
-Spine-C++ Build
|
|
|
-Platform: Darwin
|
|
|
-
|
|
|
- Configuring debug build... ✗
|
|
|
-CMake Error: Could not find cmake file...
|
|
|
-(full error output shown prominently)
|
|
|
-```
|
|
|
-
|
|
|
-## Error Handling Best Practices
|
|
|
|
|
|
-1. **Capture output**: Use `OUTPUT=$(command 2>&1)` to capture both stdout and stderr
|
|
|
-2. **Check exit codes**: Always check if critical operations succeeded
|
|
|
-3. **Show errors prominently**: Use `log_error_output` for command failures (not grayed)
|
|
|
-4. **Fail fast**: Exit immediately on critical failures
|
|
|
-5. **Use inline results**: `log_action` + `log_ok/fail` for dense, scannable output
|
|
|
-
|
|
|
-## Calling Other Scripts
|
|
|
-
|
|
|
-When calling other bash scripts that have their own logging:
|
|
|
-
|
|
|
-1. **Trust their logging**: Don't wrap calls in redundant log actions
|
|
|
-2. **Capture output for errors**: Use `OUTPUT=$(script.sh 2>&1)` to capture output and only show on failure
|
|
|
-3. **Let them handle success**: Avoid "script completed" messages when the script shows its own status
|
|
|
-
|
|
|
-**Good**:
|
|
|
-```bash
|
|
|
-# Let the script handle its own logging
|
|
|
-../formatters/format.sh cpp
|
|
|
-
|
|
|
-# Or capture output and only show on error
|
|
|
-if output=$(./setup.sh 2>&1); then
|
|
|
- log_ok "Setup completed"
|
|
|
-else
|
|
|
- log_fail "Setup failed"
|
|
|
- log_detail "$output"
|
|
|
-fi
|
|
|
-```
|
|
|
-
|
|
|
-**Avoid**:
|
|
|
-```bash
|
|
|
-# This creates duplicate logging
|
|
|
-log_action "Formatting C++ files"
|
|
|
-../formatters/format.sh cpp
|
|
|
-log_ok "C++ formatting completed"
|
|
|
-```
|
|
|
-
|
|
|
-```bash
|
|
|
-if BUILD_OUTPUT=$(./build.sh clean release 2>&1); then
|
|
|
- log_ok "Build completed"
|
|
|
-else
|
|
|
- log_fail "Build failed"
|
|
|
- log_detail "$BUILD_OUTPUT"
|
|
|
- exit 1
|
|
|
-fi
|
|
|
-```
|
|
|
-
|
|
|
-## Usage
|
|
|
-
|
|
|
-1. Source the utilities in your script:
|
|
|
-```bash
|
|
|
-source ../formatters/logging/logging.sh
|
|
|
-```
|
|
|
+## Rules
|
|
|
|
|
|
-2. Follow the hierarchy patterns shown above
|
|
|
-3. Use appropriate functions for each type of output
|
|
|
-4. Test output both with and without color support
|
|
|
+- Always capture command output of commands following log_action: `OUTPUT=$(command 2>&1)`
|
|
|
+- Show errors prominently with `log_error_output`
|
|
|
+- Use inline results: `log_action` + `log_ok/fail`
|
|
|
+- Let sub-scripts handle their own logging, e.g. do not log "Building Spine-C++" when calling `spine-cpp/build.sh`
|
|
|
+- Do not capture output of sub-scripts like you do for "normal" commands. That would swallow their logging.
|