Comprehensive guide for building the Cellframe SDK from source code with advanced build configurations, cross-platform support, optimization options, and detailed troubleshooting procedures.
## Overview
This guide provides complete instructions for building the Cellframe SDK from source code across all supported platforms. Building from source offers maximum customization, access to latest features, and the ability to modify and extend the SDK for specific requirements.
**Build Benefits:**
- Access to latest development features
- Custom module selection and configuration
- Platform-specific optimizations
- Debug builds for development
- Integration with existing build systems
## Document Structure
- [[#Overview|Overview]]
- [[#Prerequisites|Prerequisites]]
- [[#System Requirements|System Requirements]]
- [[#Development Environment|Development Environment]]
- [[#Platform Dependencies|Platform Dependencies]]
- [[#Source Code Management|Source Code Management]]
- [[#Repository Cloning|Repository Cloning]]
- [[#Submodule Management|Submodule Management]]
- [[#Branch Selection|Branch Selection]]
- [[#Build Configuration|Build Configuration]]
- [[#CMake Configuration|CMake Configuration]]
- [[#Module Selection|Module Selection]]
- [[#Build Types|Build Types]]
- [[#Advanced Options|Advanced Options]]
- [[#Platform-Specific Builds|Platform-Specific Builds]]
- [[#Linux Build Process|Linux Build Process]]
- [[#macOS Build Process|macOS Build Process]]
- [[#Windows Build Process|Windows Build Process]]
- [[#Build Automation|Build Automation]]
- [[#Installation & Packaging|Installation & Packaging]]
- [[#Testing & Verification|Testing & Verification]]
- [[#Troubleshooting|Troubleshooting]]
## Prerequisites
### System Requirements
#### Minimum Hardware Requirements
- **CPU:** x86_64 or ARM64 processor
- **RAM:** 8GB minimum, 16GB recommended for parallel builds
- **Storage:** 5GB free space for full build with debug symbols
- **Network:** Broadband internet for dependency downloads
#### Software Requirements
- **CMake:** 3.10+ (3.16+ recommended)
- **C Compiler:** C11-compliant compiler
- Linux: GCC 7+ or Clang 8+
- macOS: Xcode 11+ or Clang 10+
- Windows: MSVC 2019+ (Visual Studio 16.0+)
- **Git:** 2.20+ with submodule support
- **Python:** 3.6+ for build automation scripts
### Development Environment
#### Essential Build Tools
```bash
#!/bin/bash
# Development Environment Setup Script
setup_build_environment() {
log_it "=== Setting Up Cellframe SDK Build Environment ==="
local platform=$(uname -s)
case "$platform" in
"Linux")
setup_linux_environment
;;
"Darwin")
setup_macos_environment
;;
*)
log_it "ERROR: Unsupported platform: $platform"
return 1
;;
esac
}
log_it() {
echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1"
}
```
#### Code Analysis Tools (Optional)
```bash
# Static analysis and formatting tools
install_analysis_tools() {
log_it "Installing code analysis tools..."
# Install clang-format for code formatting
if command -v apt-get &> /dev/null; then
sudo apt-get install -y clang-format
elif command -v brew &> /dev/null; then
brew install clang-format
fi
# Install cppcheck for static analysis
if command -v apt-get &> /dev/null; then
sudo apt-get install -y cppcheck
elif command -v brew &> /dev/null; then
brew install cppcheck
fi
log_it "✓ Analysis tools installed"
}
```
### Platform Dependencies
#### Linux Development Environment
```bash
setup_linux_environment() {
log_it "=== Setting Up Linux Build Environment ==="
# Detect Linux distribution
if [ -f /etc/os-release ]; then
. /etc/os-release
DISTRO=$ID
VERSION=$VERSION_ID
else
log_it "ERROR: Cannot detect Linux distribution"
return 1
fi
log_it "Detected: $DISTRO $VERSION"
case "$DISTRO" in
"ubuntu"|"debian")
setup_debian_environment
;;
"fedora"|"rhel"|"centos")
setup_redhat_environment
;;
"arch")
setup_arch_environment
;;
*)
log_it "WARNING: Unsupported distribution, trying generic setup"
setup_generic_environment
;;
esac
}
setup_debian_environment() {
log_it "Setting up Debian/Ubuntu build environment..."
# Update package database
sudo apt-get update
# Install essential build tools
sudo apt-get install -y \
build-essential \
cmake \
git \
python3 \
python3-pip \
pkg-config \
autotools-dev \
autoconf \
libtool
# Install development libraries
sudo apt-get install -y \
libssl-dev \
libjson-c-dev \
libsqlite3-dev \
libmagic-dev \
libcurl4-openssl-dev \
libpthread-stubs0-dev \
zlib1g-dev
# Install optional tools
sudo apt-get install -y \
ninja-build \
ccache \
valgrind \
gdb
log_it "✓ Debian/Ubuntu environment ready"
}
```
## Source Code Management
### Repository Cloning
#### Complete Source Retrieval
```bash
#!/bin/bash
# Cellframe SDK Source Management Script
clone_cellframe_sdk() {
log_it "=== Cloning Cellframe SDK Source Code ==="
local target_dir="${1:-cellframe-sdk}"
local branch="${2:-master}"
log_it "Target directory: $target_dir"
log_it "Branch: $branch"
# Check if directory exists
if [ -d "$target_dir" ]; then
log_it "Directory exists, checking for updates..."
cd "$target_dir"
# Verify it's a git repository
if [ ! -d ".git" ]; then
log_it "ERROR: Directory exists but is not a git repository"
return 1
fi
# Check remote URL
local current_url=$(git remote get-url origin 2>/dev/null)
local expected_url="https://gitlab.demlabs.net/cellframe/cellframe-sdk.git"
if [ "$current_url" != "$expected_url" ]; then
log_it "WARNING: Remote URL mismatch"
log_it "Current: $current_url"
log_it "Expected: $expected_url"
fi
# Fetch and checkout branch
git fetch origin
git checkout "$branch"
git pull origin "$branch"
else
log_it "Cloning repository..."
if ! git clone --recursive -b "$branch" \
https://gitlab.demlabs.net/cellframe/cellframe-sdk.git "$target_dir"; then
log_it "ERROR: Failed to clone repository"
return 1
fi
cd "$target_dir"
fi
log_it "✓ Source code ready"
return 0
}
```
### Submodule Management
#### Advanced Submodule Operations
```bash
manage_submodules() {
log_it "=== Managing Git Submodules ==="
# Initialize and update all submodules
log_it "Initializing submodules..."
if ! git submodule update --init --recursive; then
log_it "ERROR: Failed to initialize submodules"
return 1
fi
# Check submodule status
log_it "Checking submodule status..."
git submodule status --recursive
# Update submodules to latest commits
log_it "Updating submodules to latest commits..."
git submodule update --remote --merge
# Verify submodule integrity
verify_submodules
log_it "✓ Submodules managed successfully"
}
verify_submodules() {
log_it "Verifying submodule integrity..."
local failed_modules=()
# Check each submodule
while IFS= read -r line; do
local status=$(echo "$line" | cut -c1)
local path=$(echo "$line" | awk '{print $2}')
case "$status" in
"-")
failed_modules+=("$path (not initialized)")
;;
"+")
log_it "WARNING: Submodule $path has uncommitted changes"
;;
" ")
log_it "✓ Submodule $path OK"
;;
esac
done < <(git submodule status --recursive)
if [ ${#failed_modules[@]} -gt 0 ]; then
log_it "ERROR: Failed submodules detected:"
for module in "${failed_modules[@]}"; do
log_it " - $module"
done
return 1
fi
log_it "✓ All submodules verified"
return 0
}
```
## Build Configuration
### CMake Configuration
#### Advanced CMake Setup
```bash
configure_build() {
log_it "=== Configuring Cellframe SDK Build ==="
local build_type="${1:-Release}"
local build_dir="${2:-build}"
local install_prefix="${3:-/opt/cellframe-sdk}"
log_it "Build type: $build_type"
log_it "Build directory: $build_dir"
log_it "Install prefix: $install_prefix"
# Create and enter build directory
if [ -d "$build_dir" ]; then
log_it "Cleaning existing build directory..."
rm -rf "$build_dir"
fi
mkdir "$build_dir"
cd "$build_dir"
# Prepare CMake arguments
local cmake_args=(
"-DCMAKE_BUILD_TYPE=$build_type"
"-DCMAKE_INSTALL_PREFIX=$install_prefix"
"-DBUILD_SHARED_LIBS=ON"
"-DBUILD_TESTING=ON"
"-DENABLE_PYTHON_NODE_CFG=ON"
)
# Platform-specific configurations
configure_platform_specific_options cmake_args
# Add user-defined options
add_user_build_options cmake_args
# Run CMake configuration
log_it "Running CMake configuration..."
if ! cmake "${cmake_args[@]}" ..; then
log_it "ERROR: CMake configuration failed"
show_cmake_error_log
return 1
fi
log_it "✓ Build configured successfully"
return 0
}
configure_platform_specific_options() {
local -n args=$1
case "$(uname -s)" in
"Linux")
args+=("-DWITH_GDB_SERVER_EX=ON")
args+=("-DWITH_MEMCACHED=ON")
;;
"Darwin")
args+=("-DOPENSSL_ROOT_DIR=/usr/local/opt/openssl")
args+=("-DCMAKE_FIND_FRAMEWORK=LAST")
;;
"MINGW"*|"CYGWIN"*)
args+=("-G" "Visual Studio 16 2019" "-A" "x64")
;;
esac
}
```
### Module Selection
#### Granular Module Configuration
```bash
configure_modules() {
log_it "=== Configuring Cellframe SDK Modules ==="
local module_config="${1:-full}"
case "$module_config" in
"minimal")
configure_minimal_modules
;;
"standard")
configure_standard_modules
;;
"full")
configure_full_modules
;;
"custom")
configure_custom_modules
;;
*)
log_it "ERROR: Unknown module configuration: $module_config"
return 1
;;
esac
}
configure_minimal_modules() {
log_it "Configuring minimal module set..."
export CELLFRAME_MODULES="dap-sdk core common crypto chain wallet"
local cmake_args=(
"-DDAP_MODULES=$CELLFRAME_MODULES"
"-DBUILD_CRYPTO_TESTS=OFF"
"-DBUILD_CHAIN_TESTS=OFF"
)
log_it "Minimal modules: $CELLFRAME_MODULES"
}
configure_full_modules() {
log_it "Configuring full module set..."
export CELLFRAME_MODULES="dap-sdk core common crypto chain wallet mempool mining network channels consensus services"
# Enable all consensus mechanisms
export CELLFRAME_CONSENSUS="cs-dag-poa cs-esbocs cs-none"
# Enable all services
export CELLFRAME_SERVICES="srv-stake srv-voting srv-bridge srv-xchange srv-vpn srv-mining-pool srv-app srv-data"
local cmake_args=(
"-DDAP_MODULES=$CELLFRAME_MODULES"
"-DCELLFRAME_CONSENSUS=$CELLFRAME_CONSENSUS"
"-DCELLFRAME_SERVICES=$CELLFRAME_SERVICES"
"-DBUILD_ALL_TESTS=ON"
"-DWITH_PYTHON_ENV=ON"
)
log_it "Full modules: $CELLFRAME_MODULES"
log_it "Consensus: $CELLFRAME_CONSENSUS"
log_it "Services: $CELLFRAME_SERVICES"
}
```
### Build Types
#### Comprehensive Build Configurations
```bash
setup_build_type() {
local build_type="$1"
case "$build_type" in
"Debug")
setup_debug_build
;;
"Release")
setup_release_build
;;
"RelWithDebInfo")
setup_release_debug_build
;;
"MinSizeRel")
setup_minimal_build
;;
"Profile")
setup_profile_build
;;
*)
log_it "ERROR: Unknown build type: $build_type"
return 1
;;
esac
}
setup_debug_build() {
log_it "Configuring Debug build..."
export CMAKE_ARGS=(
"-DCMAKE_BUILD_TYPE=Debug"
"-DDAP_DEBUG=ON"
"-DDAP_MEMSAN=ON"
"-DDAP_SYS_DEBUG=ON"
"-DCMAKE_C_FLAGS_DEBUG=-g3 -O0 -DDEBUG -Wall -Wextra"
"-DENABLE_DETAILED_LOG=ON"
"-DBUILD_WITH_GDB_DRIVER=ON"
)
log_it "Debug build configured with memory sanitization"
}
setup_release_build() {
log_it "Configuring Release build..."
export CMAKE_ARGS=(
"-DCMAKE_BUILD_TYPE=Release"
"-DDAP_DEBUG=OFF"
"-DCMAKE_C_FLAGS_RELEASE=-O3 -DNDEBUG -march=native"
"-DCMAKE_INTERPROCEDURAL_OPTIMIZATION=ON"
"-DSTRIP_DEBUG_SYMBOLS=ON"
)
log_it "Release build configured with optimizations"
}
```
## Platform-Specific Builds
### Linux Build Process
#### Complete Linux Build Pipeline
```bash
build_linux() {
log_it "=== Building Cellframe SDK on Linux ==="
local cores=$(nproc)
local build_jobs=$((cores > 1 ? cores - 1 : 1))
log_it "Using $build_jobs parallel jobs (of $cores cores)"
# Set build environment
export CC=${CC:-gcc}
export CXX=${CXX:-g++}
export CFLAGS="${CFLAGS} -fPIC"
export CXXFLAGS="${CXXFLAGS} -fPIC"
# Configure ccache if available
if command -v ccache &> /dev/null; then
log_it "Using ccache for faster builds..."
export CC="ccache $CC"
export CXX="ccache $CXX"
fi
# Build with make
log_it "Starting compilation..."
if ! make -j"$build_jobs" VERBOSE=1; then
log_it "ERROR: Compilation failed"
show_build_error_summary
return 1
fi
log_it "✓ Linux build completed successfully"
return 0
}
show_build_error_summary() {
log_it "=== Build Error Summary ==="
# Show last 50 lines of build output
if [ -f "build.log" ]; then
log_it "Last 50 lines of build output:"
tail -n 50 build.log
fi
# Check for common error patterns
check_common_build_errors
}
```
### macOS Build Process
#### macOS-Specific Build Configuration
```bash
build_macos() {
log_it "=== Building Cellframe SDK on macOS ==="
# Set macOS-specific environment
export MACOSX_DEPLOYMENT_TARGET=10.14
export CPPFLAGS="-I/usr/local/include $CPPFLAGS"
export LDFLAGS="-L/usr/local/lib $LDFLAGS"
# Configure OpenSSL paths
if [ -d "/usr/local/opt/openssl" ]; then
export OPENSSL_ROOT_DIR="/usr/local/opt/openssl"
export PKG_CONFIG_PATH="/usr/local/opt/openssl/lib/pkgconfig:$PKG_CONFIG_PATH"
fi
# Use all available cores
local cores=$(sysctl -n hw.ncpu)
log_it "Building with $cores parallel jobs..."
# Build
if ! make -j"$cores"; then
log_it "ERROR: macOS build failed"
return 1
fi
log_it "✓ macOS build completed successfully"
return 0
}
```
### Windows Build Process
#### Windows Build Automation
```powershell
# Windows PowerShell Build Script
function Build-CellframeSDK {
param(
[string]$BuildType = "Release",
[string]$Platform = "x64",
[int]$Jobs = $env:NUMBER_OF_PROCESSORS
)
Write-Host "=== Building Cellframe SDK on Windows ===" -ForegroundColor Green
# Verify Visual Studio environment
if (-not $env:VCINSTALLDIR) {
Write-Error "Visual Studio environment not detected. Run from Developer Command Prompt."
return $false
}
# Create build directory
if (Test-Path "build") {
Remove-Item -Path "build" -Recurse -Force
}
New-Item -ItemType Directory -Name "build"
Set-Location "build"
# Configure with CMake
Write-Host "Configuring with CMake..." -ForegroundColor Yellow
$cmakeArgs = @(
"-G", "Visual Studio 16 2019",
"-A", $Platform,
"-DCMAKE_BUILD_TYPE=$BuildType",
"-DBUILD_SHARED_LIBS=ON",
".."
)
& cmake @cmakeArgs
if ($LASTEXITCODE -ne 0) {
Write-Error "CMake configuration failed"
return $false
}
# Build
Write-Host "Building with $Jobs parallel jobs..." -ForegroundColor Yellow
& cmake --build . --config $BuildType --parallel $Jobs
if ($LASTEXITCODE -ne 0) {
Write-Error "Build failed"
return $false
}
Write-Host "✓ Windows build completed successfully" -ForegroundColor Green
return $true
}
```
## Build Automation
### Automated Build Scripts
#### Universal Build Script
```bash
#!/bin/bash
# Universal Cellframe SDK Build Script
build_cellframe_sdk() {
log_it "=== Automated Cellframe SDK Build ==="
local config_file="${1:-build.conf}"
# Load build configuration
if [ -f "$config_file" ]; then
source "$config_file"
log_it "Loaded configuration from $config_file"
else
log_it "Using default build configuration"
set_default_build_config
fi
# Execute build pipeline
execute_build_pipeline
}
execute_build_pipeline() {
local steps=(
"prepare_environment"
"clone_source_code"
"configure_build_system"
"compile_source"
"run_tests"
"create_packages"
)
for step in "${steps[@]}"; do
log_it "Executing: $step"
if ! "$step"; then
log_it "ERROR: Build step failed: $step"
return 1
fi
log_it "✓ Completed: $step"
done
log_it "✓ Automated build completed successfully"
}
```
## Installation & Packaging
### Installation Procedures
#### System Installation
```bash
install_cellframe_sdk() {
log_it "=== Installing Cellframe SDK ==="
local install_prefix="${1:-/opt/cellframe-sdk}"
# Install using make
if ! sudo make install; then
log_it "ERROR: Installation failed"
return 1
fi
# Configure system environment
configure_system_environment "$install_prefix"
# Create symbolic links
create_system_links "$install_prefix"
# Update library cache
if command -v ldconfig &> /dev/null; then
sudo ldconfig
fi
log_it "✓ Installation completed successfully"
}
configure_system_environment() {
local prefix="$1"
# Create environment configuration
cat > /tmp/cellframe-sdk.conf << EOF
# Cellframe SDK Environment Configuration
export CELLFRAME_SDK_ROOT="$prefix"
export PATH="\$PATH:$prefix/bin"
export LD_LIBRARY_PATH="\$LD_LIBRARY_PATH:$prefix/lib"
export PKG_CONFIG_PATH="\$PKG_CONFIG_PATH:$prefix/lib/pkgconfig"
export CPATH="\$CPATH:$prefix/include"
EOF
# Install system-wide
sudo cp /tmp/cellframe-sdk.conf /etc/profile.d/cellframe-sdk.sh
sudo chmod +x /etc/profile.d/cellframe-sdk.sh
log_it "✓ System environment configured"
}
```
## Testing & Verification
### Comprehensive Testing
#### Build Verification
```bash
verify_build() {
log_it "=== Verifying Cellframe SDK Build ==="
# Run basic tests
if ! run_basic_tests; then
log_it "ERROR: Basic tests failed"
return 1
fi
# Test library loading
if ! test_library_loading; then
log_it "ERROR: Library loading tests failed"
return 1
fi
# Verify installation
if ! verify_installation_completeness; then
log_it "ERROR: Installation verification failed"
return 1
fi
log_it "✓ Build verification completed successfully"
}
run_basic_tests() {
log_it "Running basic tests..."
if [ -d "tests" ]; then
cd tests
if ! ctest --output-on-failure; then
return 1
fi
cd ..
fi
log_it "✓ Basic tests passed"
}
```
## Troubleshooting
### Advanced Troubleshooting
#### Build Error Diagnosis
```bash
diagnose_build_errors() {
log_it "=== Diagnosing Build Errors ==="
# Check system requirements
check_system_requirements
# Verify dependencies
verify_build_dependencies
# Analyze build logs
analyze_build_logs
# Generate diagnostic report
generate_diagnostic_report
}
check_system_requirements() {
log_it "Checking system requirements..."
local errors=()
# Check CMake version
local cmake_version=$(cmake --version | head -n1 | cut -d' ' -f3)
if ! version_compare "$cmake_version" "3.10.0"; then
errors+=("CMake version too old: $cmake_version (required: 3.10+)")
fi
# Check compiler
if ! command -v gcc &> /dev/null && ! command -v clang &> /dev/null; then
errors+=("No suitable C compiler found")
fi
# Report errors
if [ ${#errors[@]} -gt 0 ]; then
log_it "System requirement errors:"
for error in "${errors[@]}"; do
log_it " ✗ $error"
done
return 1
fi
log_it "✓ System requirements satisfied"
}
```
### Common Issues & Solutions
#### Dependency Resolution
```bash
resolve_dependency_issues() {
log_it "=== Resolving Dependency Issues ==="
# Check for missing libraries
local missing_libs=$(check_missing_libraries)
if [ -n "$missing_libs" ]; then
log_it "Missing libraries detected:"
echo "$missing_libs"
# Provide installation instructions
provide_installation_instructions "$missing_libs"
else
log_it "✓ All dependencies satisfied"
fi
}
provide_installation_instructions() {
local missing="$1"
log_it "Installation instructions:"
if command -v apt-get &> /dev/null; then
log_it "Ubuntu/Debian:"
log_it " sudo apt-get install $(echo "$missing" | sed 's/lib/-dev /g')"
fi
if command -v dnf &> /dev/null; then
log_it "Fedora/RHEL:"
log_it " sudo dnf install $(echo "$missing" | sed 's/lib/-devel /g')"
fi
if command -v brew &> /dev/null; then
log_it "macOS:"
log_it " brew install $missing"
fi
}
```
### Getting Support
For additional help and resources:
#### Documentation Resources
- **[[Installation Guide|Installation Guide]]** - Complete installation procedures
- **[[First Application|First Application]]** - Getting started tutorial
- **[[Development Guide|Development Guide]]** - Development best practices
- **[[Modules/Module Overview|Module Documentation]]** - Complete SDK reference
#### Community Support
- **Forum:** [Cellframe Community Forum](https://forum.cellframe.net)
- **Issues:** [GitLab Issue Tracker](https://gitlab.demlabs.net/cellframe/cellframe-sdk/issues)
- **Chat:** [Telegram Developer Chat](https://t.me/cellframe_dev_en)
#### Professional Support
- **Enterprise:**
[email protected]
- **Development:**
[email protected]
---
**See also:** [[Installation Guide|Installation Guide]], [[First Application|First Application]], [[Architecture Overview|Architecture Overview]], [[Development Guide|Development Guide]]