v0.7.18 - Fixed duplicate login modal bug and improved header layout
This commit is contained in:
Your Name
457
docs/c_utils_lib_architecture.md
Normal file
457
docs/c_utils_lib_architecture.md
Normal file
@@ -0,0 +1,457 @@
|
||||
# c_utils_lib Architecture Plan
|
||||
|
||||
## Overview
|
||||
|
||||
`c_utils_lib` is a standalone C utility library designed to provide reusable, general-purpose functions for C projects. It serves as a learning repository and a practical toolkit for common C programming tasks.
|
||||
|
||||
## Design Philosophy
|
||||
|
||||
1. **Zero External Dependencies**: Only standard C library dependencies
|
||||
2. **Modular Design**: Each utility is independent and can be used separately
|
||||
3. **Learning-Oriented**: Well-documented code suitable for learning C
|
||||
4. **Production-Ready**: Battle-tested utilities from real projects
|
||||
5. **Cross-Platform**: Works on Linux, macOS, and other POSIX systems
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
c_utils_lib/
|
||||
├── README.md # Main documentation
|
||||
├── LICENSE # MIT License
|
||||
├── VERSION # Current version (e.g., v0.1.0)
|
||||
├── build.sh # Build script
|
||||
├── Makefile # Build system
|
||||
├── .gitignore # Git ignore rules
|
||||
│
|
||||
├── include/ # Public headers
|
||||
│ ├── c_utils.h # Main header (includes all utilities)
|
||||
│ ├── debug.h # Debug/logging system
|
||||
│ ├── version.h # Version utilities
|
||||
│ ├── string_utils.h # String utilities (future)
|
||||
│ └── memory_utils.h # Memory utilities (future)
|
||||
│
|
||||
├── src/ # Implementation files
|
||||
│ ├── debug.c # Debug system implementation
|
||||
│ ├── version.c # Version utilities implementation
|
||||
│ ├── string_utils.c # String utilities (future)
|
||||
│ └── memory_utils.c # Memory utilities (future)
|
||||
│
|
||||
├── examples/ # Usage examples
|
||||
│ ├── debug_example.c # Debug system example
|
||||
│ ├── version_example.c # Version utilities example
|
||||
│ └── Makefile # Examples build system
|
||||
│
|
||||
├── tests/ # Unit tests
|
||||
│ ├── test_debug.c # Debug system tests
|
||||
│ ├── test_version.c # Version utilities tests
|
||||
│ ├── run_tests.sh # Test runner
|
||||
│ └── Makefile # Tests build system
|
||||
│
|
||||
└── docs/ # Additional documentation
|
||||
├── API.md # Complete API reference
|
||||
├── INTEGRATION.md # How to integrate into projects
|
||||
├── VERSIONING.md # Versioning system guide
|
||||
└── CONTRIBUTING.md # Contribution guidelines
|
||||
```
|
||||
|
||||
## Initial Utilities (v0.1.0)
|
||||
|
||||
### 1. Debug System (`debug.h`, `debug.c`)
|
||||
|
||||
**Purpose**: Unified logging and debugging system with configurable verbosity levels.
|
||||
|
||||
**Features**:
|
||||
- 5 debug levels: NONE, ERROR, WARN, INFO, DEBUG, TRACE
|
||||
- Timestamp formatting
|
||||
- File/line information at TRACE level
|
||||
- Macro-based API for zero-cost when disabled
|
||||
- Thread-safe (future enhancement)
|
||||
|
||||
**API**:
|
||||
```c
|
||||
// Initialization
|
||||
void debug_init(int level);
|
||||
|
||||
// Logging macros
|
||||
DEBUG_ERROR(format, ...);
|
||||
DEBUG_WARN(format, ...);
|
||||
DEBUG_INFO(format, ...);
|
||||
DEBUG_LOG(format, ...);
|
||||
DEBUG_TRACE(format, ...);
|
||||
|
||||
// Global debug level
|
||||
extern debug_level_t g_debug_level;
|
||||
```
|
||||
|
||||
**Usage Example**:
|
||||
```c
|
||||
#include <c_utils/debug.h>
|
||||
|
||||
int main() {
|
||||
debug_init(DEBUG_LEVEL_INFO);
|
||||
DEBUG_INFO("Application started");
|
||||
DEBUG_ERROR("Critical error: %s", error_msg);
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Version Utilities (`version.h`, `version.c`)
|
||||
|
||||
**Purpose**: Reusable versioning system for C projects using git tags.
|
||||
|
||||
**Features**:
|
||||
- Automatic version extraction from git tags
|
||||
- Semantic versioning support (MAJOR.MINOR.PATCH)
|
||||
- Version comparison functions
|
||||
- Header file generation for embedding version info
|
||||
- Build number tracking
|
||||
|
||||
**API**:
|
||||
```c
|
||||
// Version structure
|
||||
typedef struct {
|
||||
int major;
|
||||
int minor;
|
||||
int patch;
|
||||
char* git_hash;
|
||||
char* build_date;
|
||||
} version_info_t;
|
||||
|
||||
// Get version from git
|
||||
int version_get_from_git(version_info_t* version);
|
||||
|
||||
// Generate version header file
|
||||
int version_generate_header(const char* output_path, const char* prefix);
|
||||
|
||||
// Compare versions
|
||||
int version_compare(version_info_t* v1, version_info_t* v2);
|
||||
|
||||
// Format version string
|
||||
char* version_to_string(version_info_t* version);
|
||||
```
|
||||
|
||||
**Usage Example**:
|
||||
```c
|
||||
#include <c_utils/version.h>
|
||||
|
||||
// In your build system:
|
||||
version_generate_header("src/version.h", "MY_APP");
|
||||
|
||||
// In your code:
|
||||
#include "version.h"
|
||||
printf("Version: %s\n", MY_APP_VERSION);
|
||||
```
|
||||
|
||||
**Integration with Projects**:
|
||||
```bash
|
||||
# In project Makefile
|
||||
version.h:
|
||||
c_utils_lib/bin/generate_version src/version.h MY_PROJECT
|
||||
```
|
||||
|
||||
## Build System
|
||||
|
||||
### Static Library Output
|
||||
|
||||
```
|
||||
libc_utils.a # Static library for linking
|
||||
```
|
||||
|
||||
### Build Targets
|
||||
|
||||
```bash
|
||||
make # Build static library
|
||||
make examples # Build examples
|
||||
make test # Run tests
|
||||
make install # Install to system (optional)
|
||||
make clean # Clean build artifacts
|
||||
```
|
||||
|
||||
### Build Script (`build.sh`)
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Simplified build script similar to nostr_core_lib
|
||||
|
||||
case "$1" in
|
||||
lib|"")
|
||||
make
|
||||
;;
|
||||
examples)
|
||||
make examples
|
||||
;;
|
||||
test)
|
||||
make test
|
||||
;;
|
||||
clean)
|
||||
make clean
|
||||
;;
|
||||
install)
|
||||
make install
|
||||
;;
|
||||
*)
|
||||
echo "Usage: ./build.sh [lib|examples|test|clean|install]"
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
```
|
||||
|
||||
## Versioning System Design
|
||||
|
||||
### How It Works
|
||||
|
||||
1. **Git Tags as Source of Truth**
|
||||
- Version tags: `v0.1.0`, `v0.2.0`, etc.
|
||||
- Follows semantic versioning
|
||||
|
||||
2. **Automatic Header Generation**
|
||||
- Script reads git tags
|
||||
- Generates header with version macros
|
||||
- Includes build date and git hash
|
||||
|
||||
3. **Reusable Across Projects**
|
||||
- Each project calls `version_generate_header()`
|
||||
- Customizable prefix (e.g., `C_RELAY_VERSION`, `NOSTR_CORE_VERSION`)
|
||||
- No hardcoded version numbers in source
|
||||
|
||||
### Example Generated Header
|
||||
|
||||
```c
|
||||
// Auto-generated by c_utils_lib version system
|
||||
#ifndef MY_PROJECT_VERSION_H
|
||||
#define MY_PROJECT_VERSION_H
|
||||
|
||||
#define MY_PROJECT_VERSION "v0.1.0"
|
||||
#define MY_PROJECT_VERSION_MAJOR 0
|
||||
#define MY_PROJECT_VERSION_MINOR 1
|
||||
#define MY_PROJECT_VERSION_PATCH 0
|
||||
#define MY_PROJECT_GIT_HASH "a1b2c3d"
|
||||
#define MY_PROJECT_BUILD_DATE "2025-10-15"
|
||||
|
||||
#endif
|
||||
```
|
||||
|
||||
### Integration Pattern
|
||||
|
||||
```makefile
|
||||
# In consuming project's Makefile
|
||||
VERSION_SCRIPT = c_utils_lib/bin/generate_version
|
||||
|
||||
src/version.h: .git/refs/tags/*
|
||||
$(VERSION_SCRIPT) src/version.h MY_PROJECT
|
||||
|
||||
my_app: src/version.h src/main.c
|
||||
$(CC) src/main.c -o my_app -Ic_utils_lib/include -Lc_utils_lib -lc_utils
|
||||
```
|
||||
|
||||
## Future Utilities (Roadmap)
|
||||
|
||||
### String Utilities (`string_utils.h`)
|
||||
- Safe string operations (bounds checking)
|
||||
- String trimming, splitting, joining
|
||||
- Case conversion
|
||||
- Pattern matching helpers
|
||||
|
||||
### Memory Utilities (`memory_utils.h`)
|
||||
- Safe allocation wrappers
|
||||
- Memory pool management
|
||||
- Leak detection helpers (debug builds)
|
||||
- Arena allocators
|
||||
|
||||
### Configuration Utilities (`config_utils.h`)
|
||||
- INI file parsing
|
||||
- JSON configuration (using cJSON)
|
||||
- Environment variable helpers
|
||||
- Command-line argument parsing
|
||||
|
||||
### File Utilities (`file_utils.h`)
|
||||
- Safe file operations
|
||||
- Directory traversal
|
||||
- Path manipulation
|
||||
- File watching (inotify wrapper)
|
||||
|
||||
### Time Utilities (`time_utils.h`)
|
||||
- Timestamp formatting
|
||||
- Duration calculations
|
||||
- Timer utilities
|
||||
- Rate limiting helpers
|
||||
|
||||
## Integration Guide
|
||||
|
||||
### As Git Submodule
|
||||
|
||||
```bash
|
||||
# In your project
|
||||
git submodule add https://github.com/yourusername/c_utils_lib.git
|
||||
git submodule update --init --recursive
|
||||
|
||||
# Build the library
|
||||
cd c_utils_lib && ./build.sh lib && cd ..
|
||||
|
||||
# Update your Makefile
|
||||
INCLUDES += -Ic_utils_lib/include
|
||||
LIBS += -Lc_utils_lib -lc_utils
|
||||
```
|
||||
|
||||
### In Your Makefile
|
||||
|
||||
```makefile
|
||||
# Check if c_utils_lib is built
|
||||
c_utils_lib/libc_utils.a:
|
||||
cd c_utils_lib && ./build.sh lib
|
||||
|
||||
# Link against it
|
||||
my_app: c_utils_lib/libc_utils.a src/main.c
|
||||
$(CC) src/main.c -o my_app \
|
||||
-Ic_utils_lib/include \
|
||||
-Lc_utils_lib -lc_utils
|
||||
```
|
||||
|
||||
### In Your Code
|
||||
|
||||
```c
|
||||
// Option 1: Include everything
|
||||
#include <c_utils/c_utils.h>
|
||||
|
||||
// Option 2: Include specific utilities
|
||||
#include <c_utils/debug.h>
|
||||
#include <c_utils/version.h>
|
||||
|
||||
int main() {
|
||||
debug_init(DEBUG_LEVEL_INFO);
|
||||
DEBUG_INFO("Starting application version %s", MY_APP_VERSION);
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
## Migration Plan for c-relay
|
||||
|
||||
### Phase 1: Extract Debug System
|
||||
1. Create `c_utils_lib` repository
|
||||
2. Move [`debug.c`](../src/debug.c) and [`debug.h`](../src/debug.h)
|
||||
3. Create build system
|
||||
4. Add basic tests
|
||||
|
||||
### Phase 2: Add Versioning System
|
||||
1. Extract version generation logic from c-relay
|
||||
2. Create reusable version utilities
|
||||
3. Update c-relay to use new system
|
||||
4. Update nostr_core_lib to use new system
|
||||
|
||||
### Phase 3: Add as Submodule
|
||||
1. Add `c_utils_lib` as submodule to c-relay
|
||||
2. Update c-relay Makefile
|
||||
3. Update includes in c-relay source files
|
||||
4. Remove old debug files from c-relay
|
||||
|
||||
### Phase 4: Documentation & Examples
|
||||
1. Create comprehensive README
|
||||
2. Add usage examples
|
||||
3. Write integration guide
|
||||
4. Document API
|
||||
|
||||
## Benefits
|
||||
|
||||
### For c-relay
|
||||
- Cleaner separation of concerns
|
||||
- Reusable utilities across projects
|
||||
- Easier to maintain and test
|
||||
- Consistent logging across codebase
|
||||
|
||||
### For Learning C
|
||||
- Real-world utility implementations
|
||||
- Best practices examples
|
||||
- Modular design patterns
|
||||
- Build system examples
|
||||
|
||||
### For Future Projects
|
||||
- Drop-in utility library
|
||||
- Proven, tested code
|
||||
- Consistent patterns
|
||||
- Time savings
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Unit Tests
|
||||
- Test each utility independently
|
||||
- Mock external dependencies
|
||||
- Edge case coverage
|
||||
- Memory leak detection (valgrind)
|
||||
|
||||
### Integration Tests
|
||||
- Test with real projects (c-relay, nostr_core_lib)
|
||||
- Cross-platform testing
|
||||
- Performance benchmarks
|
||||
|
||||
### Continuous Integration
|
||||
- GitHub Actions for automated testing
|
||||
- Multiple compiler versions (gcc, clang)
|
||||
- Multiple platforms (Linux, macOS)
|
||||
- Static analysis (cppcheck, clang-tidy)
|
||||
|
||||
## Documentation Standards
|
||||
|
||||
### Code Documentation
|
||||
- Doxygen-style comments
|
||||
- Function purpose and parameters
|
||||
- Return value descriptions
|
||||
- Usage examples in comments
|
||||
|
||||
### API Documentation
|
||||
- Complete API reference in `docs/API.md`
|
||||
- Usage examples for each function
|
||||
- Common patterns and best practices
|
||||
- Migration guides
|
||||
|
||||
### Learning Resources
|
||||
- Detailed explanations of implementations
|
||||
- Links to relevant C standards
|
||||
- Common pitfalls and how to avoid them
|
||||
- Performance considerations
|
||||
|
||||
## License
|
||||
|
||||
MIT License - permissive and suitable for learning and commercial use.
|
||||
|
||||
## Version History
|
||||
|
||||
- **v0.1.0** (Planned)
|
||||
- Initial release
|
||||
- Debug system
|
||||
- Version utilities
|
||||
- Basic documentation
|
||||
|
||||
- **v0.2.0** (Future)
|
||||
- String utilities
|
||||
- Memory utilities
|
||||
- Enhanced documentation
|
||||
|
||||
- **v0.3.0** (Future)
|
||||
- Configuration utilities
|
||||
- File utilities
|
||||
- Time utilities
|
||||
|
||||
## Success Criteria
|
||||
|
||||
1. ✅ Successfully integrated into c-relay
|
||||
2. ✅ Successfully integrated into nostr_core_lib
|
||||
3. ✅ All tests passing
|
||||
4. ✅ Documentation complete
|
||||
5. ✅ Examples working
|
||||
6. ✅ Zero external dependencies (except standard library)
|
||||
7. ✅ Cross-platform compatibility verified
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. Create repository structure
|
||||
2. Implement debug system
|
||||
3. Implement version utilities
|
||||
4. Create build system
|
||||
5. Write tests
|
||||
6. Create documentation
|
||||
7. Integrate into c-relay
|
||||
8. Publish to GitHub
|
||||
|
||||
---
|
||||
|
||||
**Note**: This is a living document. Update as the library evolves and new utilities are added.
|
||||
621
docs/c_utils_lib_implementation_plan.md
Normal file
621
docs/c_utils_lib_implementation_plan.md
Normal file
@@ -0,0 +1,621 @@
|
||||
# c_utils_lib Implementation Plan
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a step-by-step implementation plan for creating the `c_utils_lib` library and integrating it into the c-relay project.
|
||||
|
||||
## Phase 1: Repository Setup & Structure
|
||||
|
||||
### Step 1.1: Create Repository Structure
|
||||
|
||||
**Location**: Create outside c-relay project (sibling directory)
|
||||
|
||||
```bash
|
||||
# Create directory structure
|
||||
mkdir -p c_utils_lib/{include,src,examples,tests,docs,bin}
|
||||
cd c_utils_lib
|
||||
|
||||
# Create subdirectories
|
||||
mkdir -p include/c_utils
|
||||
mkdir -p tests/results
|
||||
```
|
||||
|
||||
### Step 1.2: Initialize Git Repository
|
||||
|
||||
```bash
|
||||
cd c_utils_lib
|
||||
git init
|
||||
git branch -M main
|
||||
```
|
||||
|
||||
### Step 1.3: Create Core Files
|
||||
|
||||
**Files to create**:
|
||||
1. `README.md` - Main documentation
|
||||
2. `LICENSE` - MIT License
|
||||
3. `VERSION` - Version file (v0.1.0)
|
||||
4. `.gitignore` - Git ignore rules
|
||||
5. `Makefile` - Build system
|
||||
6. `build.sh` - Build script
|
||||
|
||||
## Phase 2: Debug System Implementation
|
||||
|
||||
### Step 2.1: Move Debug Files
|
||||
|
||||
**Source files** (from c-relay):
|
||||
- `src/debug.c` → `c_utils_lib/src/debug.c`
|
||||
- `src/debug.h` → `c_utils_lib/include/c_utils/debug.h`
|
||||
|
||||
**Modifications needed**:
|
||||
1. Update header guard in `debug.h`:
|
||||
```c
|
||||
#ifndef C_UTILS_DEBUG_H
|
||||
#define C_UTILS_DEBUG_H
|
||||
```
|
||||
|
||||
2. No namespace changes needed (keep simple API)
|
||||
|
||||
3. Add header documentation:
|
||||
```c
|
||||
/**
|
||||
* @file debug.h
|
||||
* @brief Debug and logging system with configurable verbosity levels
|
||||
*
|
||||
* Provides a simple, efficient logging system with 5 levels:
|
||||
* - ERROR: Critical errors
|
||||
* - WARN: Warnings
|
||||
* - INFO: Informational messages
|
||||
* - DEBUG: Debug messages
|
||||
* - TRACE: Detailed trace with file:line info
|
||||
*/
|
||||
```
|
||||
|
||||
### Step 2.2: Create Main Header
|
||||
|
||||
**File**: `include/c_utils/c_utils.h`
|
||||
|
||||
```c
|
||||
#ifndef C_UTILS_H
|
||||
#define C_UTILS_H
|
||||
|
||||
/**
|
||||
* @file c_utils.h
|
||||
* @brief Main header for c_utils_lib - includes all utilities
|
||||
*
|
||||
* Include this header to access all c_utils_lib functionality.
|
||||
* Alternatively, include specific headers for modular usage.
|
||||
*/
|
||||
|
||||
// Version information
|
||||
#define C_UTILS_VERSION "v0.1.0"
|
||||
#define C_UTILS_VERSION_MAJOR 0
|
||||
#define C_UTILS_VERSION_MINOR 1
|
||||
#define C_UTILS_VERSION_PATCH 0
|
||||
|
||||
// Include all utilities
|
||||
#include "debug.h"
|
||||
#include "version.h"
|
||||
|
||||
#endif /* C_UTILS_H */
|
||||
```
|
||||
|
||||
## Phase 3: Version Utilities Implementation
|
||||
|
||||
### Step 3.1: Design Version API
|
||||
|
||||
**File**: `include/c_utils/version.h`
|
||||
|
||||
```c
|
||||
#ifndef C_UTILS_VERSION_H
|
||||
#define C_UTILS_VERSION_H
|
||||
|
||||
#include <time.h>
|
||||
|
||||
/**
|
||||
* @brief Version information structure
|
||||
*/
|
||||
typedef struct {
|
||||
int major;
|
||||
int minor;
|
||||
int patch;
|
||||
char git_hash[41]; // SHA-1 hash (40 chars + null)
|
||||
char build_date[32]; // ISO 8601 format
|
||||
char version_string[64]; // "vX.Y.Z" format
|
||||
} version_info_t;
|
||||
|
||||
/**
|
||||
* @brief Extract version from git tags
|
||||
* @param version Output version structure
|
||||
* @return 0 on success, -1 on error
|
||||
*/
|
||||
int version_get_from_git(version_info_t* version);
|
||||
|
||||
/**
|
||||
* @brief Generate version header file for a project
|
||||
* @param output_path Path to output header file
|
||||
* @param prefix Prefix for macros (e.g., "MY_APP")
|
||||
* @return 0 on success, -1 on error
|
||||
*/
|
||||
int version_generate_header(const char* output_path, const char* prefix);
|
||||
|
||||
/**
|
||||
* @brief Compare two versions
|
||||
* @return -1 if v1 < v2, 0 if equal, 1 if v1 > v2
|
||||
*/
|
||||
int version_compare(const version_info_t* v1, const version_info_t* v2);
|
||||
|
||||
/**
|
||||
* @brief Format version as string
|
||||
* @param version Version structure
|
||||
* @param buffer Output buffer
|
||||
* @param buffer_size Size of output buffer
|
||||
* @return Number of characters written
|
||||
*/
|
||||
int version_to_string(const version_info_t* version, char* buffer, size_t buffer_size);
|
||||
|
||||
#endif /* C_UTILS_VERSION_H */
|
||||
```
|
||||
|
||||
### Step 3.2: Implement Version Utilities
|
||||
|
||||
**File**: `src/version.c`
|
||||
|
||||
Key functions to implement:
|
||||
1. `version_get_from_git()` - Execute `git describe --tags` and parse
|
||||
2. `version_generate_header()` - Generate header file with macros
|
||||
3. `version_compare()` - Semantic version comparison
|
||||
4. `version_to_string()` - Format version string
|
||||
|
||||
### Step 3.3: Create Version Generation Script
|
||||
|
||||
**File**: `bin/generate_version`
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Generate version header for a project
|
||||
|
||||
OUTPUT_FILE="$1"
|
||||
PREFIX="$2"
|
||||
|
||||
if [ -z "$OUTPUT_FILE" ] || [ -z "$PREFIX" ]; then
|
||||
echo "Usage: $0 <output_file> <prefix>"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Get version from git
|
||||
if [ -d .git ]; then
|
||||
VERSION=$(git describe --tags --always 2>/dev/null || echo "v0.0.0")
|
||||
GIT_HASH=$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")
|
||||
else
|
||||
VERSION="v0.0.0"
|
||||
GIT_HASH="unknown"
|
||||
fi
|
||||
|
||||
# Parse version
|
||||
CLEAN_VERSION=$(echo "$VERSION" | sed 's/^v//' | cut -d- -f1)
|
||||
MAJOR=$(echo "$CLEAN_VERSION" | cut -d. -f1)
|
||||
MINOR=$(echo "$CLEAN_VERSION" | cut -d. -f2)
|
||||
PATCH=$(echo "$CLEAN_VERSION" | cut -d. -f3)
|
||||
BUILD_DATE=$(date -u +"%Y-%m-%d %H:%M:%S UTC")
|
||||
|
||||
# Generate header
|
||||
cat > "$OUTPUT_FILE" << EOF
|
||||
/* Auto-generated by c_utils_lib version system */
|
||||
/* DO NOT EDIT - This file is automatically generated */
|
||||
|
||||
#ifndef ${PREFIX}_VERSION_H
|
||||
#define ${PREFIX}_VERSION_H
|
||||
|
||||
#define ${PREFIX}_VERSION "v${CLEAN_VERSION}"
|
||||
#define ${PREFIX}_VERSION_MAJOR ${MAJOR}
|
||||
#define ${PREFIX}_VERSION_MINOR ${MINOR}
|
||||
#define ${PREFIX}_VERSION_PATCH ${PATCH}
|
||||
#define ${PREFIX}_GIT_HASH "${GIT_HASH}"
|
||||
#define ${PREFIX}_BUILD_DATE "${BUILD_DATE}"
|
||||
|
||||
#endif /* ${PREFIX}_VERSION_H */
|
||||
EOF
|
||||
|
||||
echo "Generated $OUTPUT_FILE with version v${CLEAN_VERSION}"
|
||||
```
|
||||
|
||||
## Phase 4: Build System
|
||||
|
||||
### Step 4.1: Create Makefile
|
||||
|
||||
**File**: `Makefile`
|
||||
|
||||
```makefile
|
||||
# c_utils_lib Makefile
|
||||
|
||||
CC = gcc
|
||||
AR = ar
|
||||
CFLAGS = -Wall -Wextra -std=c99 -O2 -g
|
||||
INCLUDES = -Iinclude
|
||||
|
||||
# Directories
|
||||
SRC_DIR = src
|
||||
INCLUDE_DIR = include
|
||||
BUILD_DIR = build
|
||||
EXAMPLES_DIR = examples
|
||||
TESTS_DIR = tests
|
||||
|
||||
# Source files
|
||||
SOURCES = $(wildcard $(SRC_DIR)/*.c)
|
||||
OBJECTS = $(SOURCES:$(SRC_DIR)/%.c=$(BUILD_DIR)/%.o)
|
||||
|
||||
# Output library
|
||||
LIBRARY = libc_utils.a
|
||||
|
||||
# Default target
|
||||
all: $(LIBRARY)
|
||||
|
||||
# Create build directory
|
||||
$(BUILD_DIR):
|
||||
mkdir -p $(BUILD_DIR)
|
||||
|
||||
# Compile source files
|
||||
$(BUILD_DIR)/%.o: $(SRC_DIR)/%.c | $(BUILD_DIR)
|
||||
$(CC) $(CFLAGS) $(INCLUDES) -c $< -o $@
|
||||
|
||||
# Create static library
|
||||
$(LIBRARY): $(OBJECTS)
|
||||
$(AR) rcs $@ $^
|
||||
@echo "Built $(LIBRARY)"
|
||||
|
||||
# Build examples
|
||||
examples: $(LIBRARY)
|
||||
$(MAKE) -C $(EXAMPLES_DIR)
|
||||
|
||||
# Run tests
|
||||
test: $(LIBRARY)
|
||||
$(MAKE) -C $(TESTS_DIR)
|
||||
$(TESTS_DIR)/run_tests.sh
|
||||
|
||||
# Install to system (optional)
|
||||
install: $(LIBRARY)
|
||||
install -d /usr/local/lib
|
||||
install -m 644 $(LIBRARY) /usr/local/lib/
|
||||
install -d /usr/local/include/c_utils
|
||||
install -m 644 $(INCLUDE_DIR)/c_utils/*.h /usr/local/include/c_utils/
|
||||
@echo "Installed to /usr/local"
|
||||
|
||||
# Uninstall from system
|
||||
uninstall:
|
||||
rm -f /usr/local/lib/$(LIBRARY)
|
||||
rm -rf /usr/local/include/c_utils
|
||||
@echo "Uninstalled from /usr/local"
|
||||
|
||||
# Clean build artifacts
|
||||
clean:
|
||||
rm -rf $(BUILD_DIR) $(LIBRARY)
|
||||
$(MAKE) -C $(EXAMPLES_DIR) clean 2>/dev/null || true
|
||||
$(MAKE) -C $(TESTS_DIR) clean 2>/dev/null || true
|
||||
|
||||
# Help
|
||||
help:
|
||||
@echo "c_utils_lib Build System"
|
||||
@echo ""
|
||||
@echo "Targets:"
|
||||
@echo " all Build static library (default)"
|
||||
@echo " examples Build examples"
|
||||
@echo " test Run tests"
|
||||
@echo " install Install to /usr/local"
|
||||
@echo " uninstall Remove from /usr/local"
|
||||
@echo " clean Clean build artifacts"
|
||||
@echo " help Show this help"
|
||||
|
||||
.PHONY: all examples test install uninstall clean help
|
||||
```
|
||||
|
||||
### Step 4.2: Create Build Script
|
||||
|
||||
**File**: `build.sh`
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# c_utils_lib build script
|
||||
|
||||
set -e
|
||||
|
||||
case "$1" in
|
||||
lib|"")
|
||||
echo "Building c_utils_lib..."
|
||||
make
|
||||
;;
|
||||
examples)
|
||||
echo "Building examples..."
|
||||
make examples
|
||||
;;
|
||||
test)
|
||||
echo "Running tests..."
|
||||
make test
|
||||
;;
|
||||
clean)
|
||||
echo "Cleaning..."
|
||||
make clean
|
||||
;;
|
||||
install)
|
||||
echo "Installing..."
|
||||
make install
|
||||
;;
|
||||
*)
|
||||
echo "Usage: ./build.sh [lib|examples|test|clean|install]"
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
|
||||
echo "Done!"
|
||||
```
|
||||
|
||||
## Phase 5: Examples & Tests
|
||||
|
||||
### Step 5.1: Create Debug Example
|
||||
|
||||
**File**: `examples/debug_example.c`
|
||||
|
||||
```c
|
||||
#include <c_utils/debug.h>
|
||||
|
||||
int main() {
|
||||
// Initialize with INFO level
|
||||
debug_init(DEBUG_LEVEL_INFO);
|
||||
|
||||
DEBUG_INFO("Application started");
|
||||
DEBUG_WARN("This is a warning");
|
||||
DEBUG_ERROR("This is an error");
|
||||
|
||||
// This won't print (level too high)
|
||||
DEBUG_LOG("This debug message won't show");
|
||||
|
||||
// Change level to DEBUG
|
||||
g_debug_level = DEBUG_LEVEL_DEBUG;
|
||||
DEBUG_LOG("Now debug messages show");
|
||||
|
||||
// Change to TRACE to see file:line info
|
||||
g_debug_level = DEBUG_LEVEL_TRACE;
|
||||
DEBUG_TRACE("Trace with file:line information");
|
||||
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
### Step 5.2: Create Version Example
|
||||
|
||||
**File**: `examples/version_example.c`
|
||||
|
||||
```c
|
||||
#include <c_utils/version.h>
|
||||
#include <stdio.h>
|
||||
|
||||
int main() {
|
||||
version_info_t version;
|
||||
|
||||
// Get version from git
|
||||
if (version_get_from_git(&version) == 0) {
|
||||
char version_str[64];
|
||||
version_to_string(&version, version_str, sizeof(version_str));
|
||||
|
||||
printf("Version: %s\n", version_str);
|
||||
printf("Git Hash: %s\n", version.git_hash);
|
||||
printf("Build Date: %s\n", version.build_date);
|
||||
}
|
||||
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
### Step 5.3: Create Test Suite
|
||||
|
||||
**File**: `tests/test_debug.c`
|
||||
|
||||
```c
|
||||
#include <c_utils/debug.h>
|
||||
#include <stdio.h>
|
||||
#include <string.h>
|
||||
|
||||
int test_debug_init() {
|
||||
debug_init(DEBUG_LEVEL_INFO);
|
||||
return (g_debug_level == DEBUG_LEVEL_INFO) ? 0 : -1;
|
||||
}
|
||||
|
||||
int test_debug_levels() {
|
||||
// Test that higher levels don't print at lower settings
|
||||
debug_init(DEBUG_LEVEL_ERROR);
|
||||
// Would need to capture stdout to verify
|
||||
return 0;
|
||||
}
|
||||
|
||||
int main() {
|
||||
int failed = 0;
|
||||
|
||||
printf("Running debug tests...\n");
|
||||
|
||||
if (test_debug_init() != 0) {
|
||||
printf("FAIL: test_debug_init\n");
|
||||
failed++;
|
||||
} else {
|
||||
printf("PASS: test_debug_init\n");
|
||||
}
|
||||
|
||||
if (test_debug_levels() != 0) {
|
||||
printf("FAIL: test_debug_levels\n");
|
||||
failed++;
|
||||
} else {
|
||||
printf("PASS: test_debug_levels\n");
|
||||
}
|
||||
|
||||
return failed;
|
||||
}
|
||||
```
|
||||
|
||||
## Phase 6: Documentation
|
||||
|
||||
### Step 6.1: Create README.md
|
||||
|
||||
Key sections:
|
||||
1. Overview and purpose
|
||||
2. Quick start guide
|
||||
3. Installation instructions
|
||||
4. Usage examples
|
||||
5. API reference (brief)
|
||||
6. Integration guide
|
||||
7. Contributing guidelines
|
||||
8. License
|
||||
|
||||
### Step 6.2: Create API Documentation
|
||||
|
||||
**File**: `docs/API.md`
|
||||
|
||||
Complete API reference with:
|
||||
- Function signatures
|
||||
- Parameter descriptions
|
||||
- Return values
|
||||
- Usage examples
|
||||
- Common patterns
|
||||
|
||||
### Step 6.3: Create Integration Guide
|
||||
|
||||
**File**: `docs/INTEGRATION.md`
|
||||
|
||||
How to integrate into projects:
|
||||
1. As git submodule
|
||||
2. Makefile integration
|
||||
3. Code examples
|
||||
4. Migration from standalone utilities
|
||||
|
||||
## Phase 7: Integration with c-relay
|
||||
|
||||
### Step 7.1: Add as Submodule
|
||||
|
||||
```bash
|
||||
cd /path/to/c-relay
|
||||
git submodule add <repo-url> c_utils_lib
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
### Step 7.2: Update c-relay Makefile
|
||||
|
||||
```makefile
|
||||
# Add to c-relay Makefile
|
||||
C_UTILS_LIB = c_utils_lib/libc_utils.a
|
||||
|
||||
# Update includes
|
||||
INCLUDES += -Ic_utils_lib/include
|
||||
|
||||
# Update libs
|
||||
LIBS += -Lc_utils_lib -lc_utils
|
||||
|
||||
# Add dependency
|
||||
$(C_UTILS_LIB):
|
||||
cd c_utils_lib && ./build.sh lib
|
||||
|
||||
# Update main target
|
||||
$(TARGET): $(C_UTILS_LIB) ...
|
||||
```
|
||||
|
||||
### Step 7.3: Update c-relay Source Files
|
||||
|
||||
**Changes needed**:
|
||||
|
||||
1. Update includes:
|
||||
```c
|
||||
// Old
|
||||
#include "debug.h"
|
||||
|
||||
// New
|
||||
#include <c_utils/debug.h>
|
||||
```
|
||||
|
||||
2. Remove old debug files:
|
||||
```bash
|
||||
git rm src/debug.c src/debug.h
|
||||
```
|
||||
|
||||
3. Update all files that use debug system:
|
||||
- `src/main.c`
|
||||
- `src/config.c`
|
||||
- `src/dm_admin.c`
|
||||
- `src/websockets.c`
|
||||
- `src/subscriptions.c`
|
||||
- Any other files using DEBUG_* macros
|
||||
|
||||
### Step 7.4: Test Integration
|
||||
|
||||
```bash
|
||||
cd c-relay
|
||||
make clean
|
||||
make
|
||||
./make_and_restart_relay.sh
|
||||
```
|
||||
|
||||
Verify:
|
||||
- Compilation succeeds
|
||||
- Debug output works correctly
|
||||
- No functionality regressions
|
||||
|
||||
## Phase 8: Version System Integration
|
||||
|
||||
### Step 8.1: Update c-relay Makefile for Versioning
|
||||
|
||||
```makefile
|
||||
# Add version generation
|
||||
src/version.h: .git/refs/tags/*
|
||||
c_utils_lib/bin/generate_version src/version.h C_RELAY
|
||||
|
||||
# Add dependency
|
||||
$(TARGET): src/version.h ...
|
||||
```
|
||||
|
||||
### Step 8.2: Update c-relay to Use Generated Version
|
||||
|
||||
Replace hardcoded version in `src/main.h` with:
|
||||
```c
|
||||
#include "version.h"
|
||||
// Use C_RELAY_VERSION instead of hardcoded VERSION
|
||||
```
|
||||
|
||||
## Timeline Estimate
|
||||
|
||||
- **Phase 1**: Repository Setup - 1 hour
|
||||
- **Phase 2**: Debug System - 2 hours
|
||||
- **Phase 3**: Version Utilities - 4 hours
|
||||
- **Phase 4**: Build System - 2 hours
|
||||
- **Phase 5**: Examples & Tests - 3 hours
|
||||
- **Phase 6**: Documentation - 3 hours
|
||||
- **Phase 7**: c-relay Integration - 2 hours
|
||||
- **Phase 8**: Version Integration - 2 hours
|
||||
|
||||
**Total**: ~19 hours
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] c_utils_lib builds successfully
|
||||
- [ ] All tests pass
|
||||
- [ ] Examples compile and run
|
||||
- [ ] c-relay integrates successfully
|
||||
- [ ] Debug output works in c-relay
|
||||
- [ ] Version generation works
|
||||
- [ ] Documentation complete
|
||||
- [ ] No regressions in c-relay functionality
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. Review this plan with stakeholders
|
||||
2. Create repository structure
|
||||
3. Implement debug system
|
||||
4. Implement version utilities
|
||||
5. Create build system
|
||||
6. Write tests and examples
|
||||
7. Create documentation
|
||||
8. Integrate into c-relay
|
||||
9. Test thoroughly
|
||||
10. Publish to GitHub
|
||||
|
||||
## Notes
|
||||
|
||||
- Keep the API simple and intuitive
|
||||
- Focus on zero external dependencies
|
||||
- Prioritize learning value in code comments
|
||||
- Make integration as easy as possible
|
||||
- Document everything thoroughly
|
||||
Reference in New Issue
Block a user