laantungir/c-relay
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 7 Wiki Activity

v0.7.18 - Fixed duplicate login modal bug and improved header layout

Browse Source
This commit is contained in:
Your Name
2025-10-15 15:31:44 -04:00
parent 4435cdf5b6
commit 87325927ed
16 changed files with 4965 additions and 4747 deletions
Download Patch File Download Diff File Expand all files Collapse all files

621
docs/c_utils_lib_implementation_plan.md Normal file
View 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