Complete installation instructions for the Cellframe SDK across all supported platforms with comprehensive dependency management, verification procedures, and troubleshooting guidance. ## Overview This guide provides step-by-step installation instructions for the Cellframe SDK on Linux, macOS, and Windows platforms. The SDK can be installed from source, package managers, or Docker containers, with detailed verification and troubleshooting procedures for each method. **Supported Platforms:** - Linux (Ubuntu 18.04+, Debian 10+, CentOS 8+, Fedora 32+, Arch Linux) - macOS (10.14+) - Windows (10+ with Visual Studio 2019+) ## Document Structure - [[#Overview|Overview]] - [[#Prerequisites|Prerequisites]] - [[#System Requirements|System Requirements]] - [[#Development Tools|Development Tools]] - [[#Platform Dependencies|Platform Dependencies]] - [[#Installation Methods|Installation Methods]] - [[#Source Installation|Source Installation]] - [[#Package Manager Installation|Package Manager Installation]] - [[#Docker Installation|Docker Installation]] - [[#Platform-Specific Instructions|Platform-Specific Instructions]] - [[#Linux Installation|Linux Installation]] - [[#macOS Installation|macOS Installation]] - [[#Windows Installation|Windows Installation]] - [[#Verification & Testing|Verification & Testing]] - [[#Troubleshooting|Troubleshooting]] ## Prerequisites ### System Requirements #### Minimum Hardware Requirements - **CPU:** x86_64 (Intel/AMD 64-bit) or ARM64 - **RAM:** 4GB minimum, 8GB recommended - **Storage:** 2GB free disk space for SDK installation - **Network:** Internet connection for downloading dependencies #### Software Requirements - **C Compiler:** GCC 7+ or Clang 8+ or MSVC 2019+ - **Build System:** CMake 3.10+ - **Version Control:** Git 2.20+ - **Python:** 3.6+ (for build scripts and tools) ### Development Tools #### Core Build Tools ```bash # Essential compilation tools gcc/clang # C compiler with C99 support cmake # Cross-platform build system generator make/ninja # Build automation tool git # Version control system pkg-config # Library metadata management python3 # Build scripts and tooling ``` #### Required Libraries ```bash # Core dependencies openssl # Cryptographic library (1.1.0+) sqlite3 # Database engine (3.25+) json-c # JSON parsing library libmagic # File type detection libcurl # HTTP/HTTPS client library pthread # POSIX threads library ``` ### Platform Dependencies #### Linux (Debian/Ubuntu) ```bash #!/bin/bash # Cellframe SDK Linux Dependencies Installation Script log_it() { echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1" } install_ubuntu_dependencies() { log_it "=== Installing Cellframe SDK Dependencies on Ubuntu/Debian ===" # Update package database log_it "Updating package database..." if ! sudo apt-get update; then log_it "ERROR: Failed to update package database" return 1 fi # Install build tools log_it "Installing build tools..." if ! sudo apt-get install -y build-essential cmake git python3 pkg-config; then log_it "ERROR: Failed to install build tools" return 1 fi # Install development libraries log_it "Installing development libraries..." if ! sudo apt-get install -y \ libssl-dev \ libjson-c-dev \ libsqlite3-dev \ libmagic-dev \ libcurl4-openssl-dev \ libpthread-stubs0-dev; then log_it "ERROR: Failed to install development libraries" return 1 fi # Verify installations log_it "Verifying installations..." for cmd in gcc cmake git python3 pkg-config; do if ! command -v "$cmd" &> /dev/null; then log_it "ERROR: $cmd not found after installation" return 1 fi log_it "✓ $cmd: $(command -v "$cmd")" done log_it "✓ Ubuntu/Debian dependencies installed successfully" return 0 } # Execute installation install_ubuntu_dependencies if [ $? -eq 0 ]; then log_it "Dependencies installation completed successfully" else log_it "Dependencies installation failed" exit 1 fi ``` #### Linux (CentOS/RHEL/Fedora) ```bash #!/bin/bash # Cellframe SDK CentOS/RHEL/Fedora Dependencies Installation Script install_centos_dependencies() { log_it "=== Installing Cellframe SDK Dependencies on CentOS/RHEL/Fedora ===" # Detect package manager if command -v dnf &> /dev/null; then PKG_MGR="dnf" elif command -v yum &> /dev/null; then PKG_MGR="yum" else log_it "ERROR: No supported package manager found" return 1 fi log_it "Using package manager: $PKG_MGR" # Install development tools log_it "Installing development tools..." if ! sudo $PKG_MGR groupinstall -y "Development Tools"; then log_it "ERROR: Failed to install development tools" return 1 fi # Install specific packages log_it "Installing specific packages..." if ! sudo $PKG_MGR install -y \ cmake \ git \ python3 \ pkgconfig \ openssl-devel \ json-c-devel \ sqlite-devel \ file-devel \ libcurl-devel; then log_it "ERROR: Failed to install packages" return 1 fi log_it "✓ CentOS/RHEL/Fedora dependencies installed successfully" return 0 } install_centos_dependencies ``` #### macOS ```bash #!/bin/bash # Cellframe SDK macOS Dependencies Installation Script install_macos_dependencies() { log_it "=== Installing Cellframe SDK Dependencies on macOS ===" # Check for Xcode Command Line Tools log_it "Checking Xcode Command Line Tools..." if ! xcode-select -p &> /dev/null; then log_it "Installing Xcode Command Line Tools..." xcode-select --install log_it "Please complete Xcode Command Line Tools installation and re-run this script" return 1 fi log_it "✓ Xcode Command Line Tools found" # Check for Homebrew log_it "Checking Homebrew installation..." if ! command -v brew &> /dev/null; then log_it "Installing Homebrew..." /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" if [ $? -ne 0 ]; then log_it "ERROR: Failed to install Homebrew" return 1 fi fi log_it "✓ Homebrew found: $(brew --version | head -n1)" # Install dependencies log_it "Installing dependencies via Homebrew..." if ! brew install cmake pkg-config openssl json-c sqlite libmagic curl; then log_it "ERROR: Failed to install dependencies" return 1 fi # Set environment variables log_it "Setting environment variables..." echo 'export PKG_CONFIG_PATH="/usr/local/opt/openssl/lib/pkgconfig:$PKG_CONFIG_PATH"' >> ~/.zshrc echo 'export LDFLAGS="-L/usr/local/opt/openssl/lib"' >> ~/.zshrc echo 'export CPPFLAGS="-I/usr/local/opt/openssl/include"' >> ~/.zshrc log_it "✓ macOS dependencies installed successfully" log_it "Note: Please run 'source ~/.zshrc' or restart terminal" return 0 } install_macos_dependencies ``` ## Installation Methods ### Source Installation The recommended installation method for development and customization. #### Step 1: Repository Cloning ```bash #!/bin/bash # Cellframe SDK Source Installation Script install_from_source() { log_it "=== Installing Cellframe SDK from Source ===" # Set installation directory INSTALL_DIR="${1:-/opt/cellframe-sdk}" BUILD_DIR="cellframe-sdk-build" log_it "Installation directory: $INSTALL_DIR" log_it "Build directory: $BUILD_DIR" # Clone repository log_it "Cloning Cellframe SDK repository..." if [ -d "cellframe-sdk" ]; then log_it "Repository already exists, updating..." cd cellframe-sdk if ! git pull origin master; then log_it "ERROR: Failed to update repository" return 1 fi else if ! git clone --recursive https://gitlab.demlabs.net/cellframe/cellframe-sdk.git; then log_it "ERROR: Failed to clone repository" return 1 fi cd cellframe-sdk fi # Initialize submodules log_it "Initializing submodules..." if ! git submodule update --init --recursive; then log_it "ERROR: Failed to initialize submodules" return 1 fi log_it "✓ Repository cloned and submodules initialized" return 0 } ``` #### Step 2: Build Configuration ```bash configure_build() { log_it "=== Configuring Build ===" # Create build directory if [ -d "$BUILD_DIR" ]; then log_it "Cleaning existing build directory..." rm -rf "$BUILD_DIR" fi mkdir "$BUILD_DIR" cd "$BUILD_DIR" # Configure with CMake log_it "Running CMake configuration..." CMAKE_ARGS=( "-DCMAKE_BUILD_TYPE=Release" "-DCMAKE_INSTALL_PREFIX=$INSTALL_DIR" "-DDAP_DEBUG=OFF" "-DBUILD_TESTS=ON" "-DWITH_PYTHON=ON" ) if ! cmake "${CMAKE_ARGS[@]}" ..; then log_it "ERROR: CMake configuration failed" return 1 fi log_it "✓ Build configured successfully" return 0 } ``` #### Step 3: Compilation ```bash compile_sdk() { log_it "=== Compiling Cellframe SDK ===" # Determine number of CPU cores if command -v nproc &> /dev/null; then CORES=$(nproc) elif command -v sysctl &> /dev/null; then CORES=$(sysctl -n hw.ncpu) else CORES=4 fi log_it "Compiling with $CORES parallel jobs..." # Compile if ! make -j"$CORES"; then log_it "ERROR: Compilation failed" log_it "Trying with single core..." if ! make -j1; then log_it "ERROR: Single-core compilation also failed" return 1 fi fi log_it "✓ Compilation completed successfully" return 0 } ``` #### Step 4: Installation ```bash install_sdk() { log_it "=== Installing Cellframe SDK ===" # Install if ! sudo make install; then log_it "ERROR: Installation failed" return 1 fi # Set up environment setup_environment log_it "✓ Installation completed successfully" return 0 } setup_environment() { log_it "Setting up environment variables..." # Create environment setup script cat > /tmp/cellframe-env.sh << 'EOF' #!/bin/bash # Cellframe SDK Environment Setup export CELLFRAME_SDK_PATH="/opt/cellframe-sdk" export PATH="$PATH:$CELLFRAME_SDK_PATH/bin" export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:$CELLFRAME_SDK_PATH/lib" export PKG_CONFIG_PATH="$PKG_CONFIG_PATH:$CELLFRAME_SDK_PATH/lib/pkgconfig" export CPATH="$CPATH:$CELLFRAME_SDK_PATH/include" EOF # Install system-wide sudo cp /tmp/cellframe-env.sh /etc/profile.d/ sudo chmod +x /etc/profile.d/cellframe-env.sh # Source for current session source /tmp/cellframe-env.sh log_it "✓ Environment configured" } ``` ### Package Manager Installation #### APT Repository (Debian/Ubuntu) ```bash install_apt_repository() { log_it "=== Installing from APT Repository ===" # Add repository key log_it "Adding repository key..." if ! wget -O - https://debian.pub.demlabs.net/public.key | sudo apt-key add -; then log_it "ERROR: Failed to add repository key" return 1 fi # Add repository log_it "Adding repository..." RELEASE=$(lsb_release -cs) echo "deb https://debian.pub.demlabs.net/$RELEASE $RELEASE main" | \ sudo tee /etc/apt/sources.list.d/cellframe.list # Update and install log_it "Updating package database..." if ! sudo apt-get update; then log_it "ERROR: Failed to update package database" return 1 fi log_it "Installing Cellframe SDK..." if ! sudo apt-get install -y cellframe-sdk-dev; then log_it "ERROR: Failed to install Cellframe SDK" return 1 fi log_it "✓ APT installation completed successfully" return 0 } ``` ### Docker Installation ```dockerfile # Cellframe SDK Docker Development Environment FROM ubuntu:20.04 LABEL maintainer="Cellframe Team" LABEL description="Cellframe SDK Development Environment" LABEL version="1.0" # Prevent interactive prompts during installation ENV DEBIAN_FRONTEND=noninteractive # Install dependencies RUN apt-get update && apt-get install -y \ build-essential \ cmake \ git \ python3 \ pkg-config \ libssl-dev \ libjson-c-dev \ libsqlite3-dev \ libmagic-dev \ libcurl4-openssl-dev \ && rm -rf /var/lib/apt/lists/* # Create development user RUN useradd -m -s /bin/bash developer && \ usermod -aG sudo developer # Set working directory WORKDIR /workspace # Clone and build Cellframe SDK RUN git clone --recursive https://gitlab.demlabs.net/cellframe/cellframe-sdk.git && \ cd cellframe-sdk && \ mkdir build && \ cd build && \ cmake -DCMAKE_BUILD_TYPE=Release .. && \ make -j$(nproc) && \ make install # Set environment variables ENV PATH="/opt/cellframe-sdk/bin:${PATH}" ENV LD_LIBRARY_PATH="/opt/cellframe-sdk/lib:${LD_LIBRARY_PATH}" ENV PKG_CONFIG_PATH="/opt/cellframe-sdk/lib/pkgconfig:${PKG_CONFIG_PATH}" # Switch to development user USER developer # Set default command CMD ["/bin/bash"] ``` ## Platform-Specific Instructions ### Linux Installation #### Ubuntu/Debian Complete Installation ```bash #!/bin/bash # Complete Ubuntu/Debian Installation Script complete_ubuntu_installation() { log_it "=== Complete Cellframe SDK Installation on Ubuntu/Debian ===" # Install dependencies if ! install_ubuntu_dependencies; then return 1 fi # Install from source if ! install_from_source "/opt/cellframe-sdk"; then return 1 fi # Verify installation if ! verify_installation; then return 1 fi log_it "✓ Complete installation finished successfully" return 0 } ``` ### macOS Installation #### Homebrew Integration ```bash macos_complete_installation() { log_it "=== Complete macOS Installation ===" # Install dependencies if ! install_macos_dependencies; then return 1 fi # Set macOS-specific CMake options export CMAKE_ARGS=( "-DCMAKE_BUILD_TYPE=Release" "-DCMAKE_INSTALL_PREFIX=/usr/local/cellframe-sdk" "-DOPENSSL_ROOT_DIR=/usr/local/opt/openssl" "-DPKG_CONFIG_PATH=/usr/local/opt/openssl/lib/pkgconfig" ) # Install from source with macOS settings if ! install_from_source "/usr/local/cellframe-sdk"; then return 1 fi log_it "✓ macOS installation completed successfully" return 0 } ``` ### Windows Installation #### Visual Studio Setup ```powershell # Windows PowerShell Installation Script function Install-CellframeSDK { Write-Host "=== Installing Cellframe SDK on Windows ===" -ForegroundColor Green # Check Visual Studio $vsPath = "${env:ProgramFiles(x86)}\Microsoft Visual Studio\2019\*\*\VC\vcvarsall.bat" if (-not (Test-Path $vsPath)) { Write-Error "Visual Studio 2019 or later required" return $false } # Clone repository Write-Host "Cloning repository..." -ForegroundColor Yellow if (Test-Path "cellframe-sdk") { Remove-Item -Path "cellframe-sdk" -Recurse -Force } git clone --recursive https://gitlab.demlabs.net/cellframe/cellframe-sdk.git if ($LASTEXITCODE -ne 0) { Write-Error "Failed to clone repository" return $false } Set-Location cellframe-sdk # Create build directory if (Test-Path "build") { Remove-Item -Path "build" -Recurse -Force } New-Item -ItemType Directory -Name "build" Set-Location build # Configure and build Write-Host "Configuring with CMake..." -ForegroundColor Yellow cmake -G "Visual Studio 16 2019" -A x64 ` -DCMAKE_BUILD_TYPE=Release ` -DCMAKE_INSTALL_PREFIX="C:\Program Files\Cellframe SDK" .. if ($LASTEXITCODE -ne 0) { Write-Error "CMake configuration failed" return $false } Write-Host "Building..." -ForegroundColor Yellow cmake --build . --config Release --parallel if ($LASTEXITCODE -ne 0) { Write-Error "Build failed" return $false } # Install Write-Host "Installing..." -ForegroundColor Yellow cmake --install . --config Release if ($LASTEXITCODE -ne 0) { Write-Error "Installation failed" return $false } Write-Host "✓ Windows installation completed successfully" -ForegroundColor Green return $true } # Execute installation Install-CellframeSDK ``` ## Verification & Testing ### Installation Verification ```bash verify_installation() { log_it "=== Verifying Cellframe SDK Installation ===" # Check installation directory INSTALL_DIR="/opt/cellframe-sdk" if [ ! -d "$INSTALL_DIR" ]; then log_it "ERROR: Installation directory not found: $INSTALL_DIR" return 1 fi # Check critical files CRITICAL_FILES=( "$INSTALL_DIR/lib/libdap_core.so" "$INSTALL_DIR/lib/libdap_crypto.so" "$INSTALL_DIR/include/dap_common.h" "$INSTALL_DIR/include/dap_enc_key.h" ) for file in "${CRITICAL_FILES[@]}"; do if [ ! -f "$file" ]; then log_it "ERROR: Critical file missing: $file" return 1 fi log_it "✓ Found: $file" done # Test library loading log_it "Testing library loading..." if ! ldd "$INSTALL_DIR/lib/libdap_core.so" &> /dev/null; then log_it "ERROR: Failed to load core library" return 1 fi log_it "✓ Library loading test passed" return 0 } ``` ### Compilation Test ```bash test_compilation() { log_it "=== Testing Compilation ===" # Create test program cat > /tmp/cellframe_test.c << 'EOF' #include <dap_common.h> #include <dap_enc_key.h> #include <stdio.h> int main() { printf("=== Cellframe SDK Compilation Test ===\n"); // Initialize DAP SDK if (dap_common_init("test_app", NULL, NULL) != 0) { printf("ERROR: Failed to initialize DAP SDK\n"); return 1; } printf("✓ DAP SDK initialized successfully\n"); // Test crypto initialization if (dap_enc_key_init() != 0) { printf("ERROR: Failed to initialize crypto\n"); return 1; } printf("✓ Crypto subsystem initialized\n"); // Create test key dap_enc_key_t *key = dap_enc_key_new_generate(DAP_ENC_KEY_TYPE_SIG_DILITHIUM, NULL, 0, NULL, 0, 0); if (!key) { printf("ERROR: Failed to generate test key\n"); return 1; } printf("✓ Post-quantum key generated successfully\n"); // Cleanup dap_enc_key_delete(key); dap_enc_key_deinit(); dap_common_deinit(); printf("✓ All tests passed - Cellframe SDK working correctly\n"); return 0; } EOF # Compile test program log_it "Compiling test program..." if ! gcc /tmp/cellframe_test.c \ -I"$INSTALL_DIR/include" \ -L"$INSTALL_DIR/lib" \ -ldap_core -ldap_crypto \ -o /tmp/cellframe_test; then log_it "ERROR: Compilation failed" return 1 fi # Run test program log_it "Running test program..." export LD_LIBRARY_PATH="$INSTALL_DIR/lib:$LD_LIBRARY_PATH" if ! /tmp/cellframe_test; then log_it "ERROR: Test program execution failed" return 1 fi # Cleanup rm -f /tmp/cellframe_test.c /tmp/cellframe_test log_it "✓ Compilation test completed successfully" return 0 } ``` ## Troubleshooting ### Common Installation Issues #### Missing Dependencies Error ```bash resolve_missing_dependencies() { log_it "=== Resolving Missing Dependencies ===" # Check for common missing libraries MISSING_LIBS=() # Check OpenSSL if ! pkg-config --exists openssl; then MISSING_LIBS+=("openssl development headers") log_it "✗ OpenSSL development headers missing" else log_it "✓ OpenSSL found: $(pkg-config --modversion openssl)" fi # Check JSON-C if ! pkg-config --exists json-c; then MISSING_LIBS+=("json-c development headers") log_it "✗ JSON-C development headers missing" else log_it "✓ JSON-C found: $(pkg-config --modversion json-c)" fi # Check SQLite3 if ! pkg-config --exists sqlite3; then MISSING_LIBS+=("sqlite3 development headers") log_it "✗ SQLite3 development headers missing" else log_it "✓ SQLite3 found: $(pkg-config --modversion sqlite3)" fi # Provide installation instructions if [ ${#MISSING_LIBS[@]} -gt 0 ]; then log_it "Missing dependencies detected:" for lib in "${MISSING_LIBS[@]}"; do log_it " - $lib" done log_it "Installation commands:" log_it "Ubuntu/Debian: sudo apt-get install libssl-dev libjson-c-dev libsqlite3-dev" log_it "CentOS/RHEL: sudo dnf install openssl-devel json-c-devel sqlite-devel" log_it "macOS: brew install openssl json-c sqlite" return 1 fi log_it "✓ All dependencies satisfied" return 0 } ``` #### Build Configuration Issues ```bash resolve_build_issues() { log_it "=== Resolving Build Configuration Issues ===" # Check CMake version CMAKE_VERSION=$(cmake --version | head -n1 | cut -d' ' -f3) CMAKE_MAJOR=$(echo "$CMAKE_VERSION" | cut -d'.' -f1) CMAKE_MINOR=$(echo "$CMAKE_VERSION" | cut -d'.' -f2) if [ "$CMAKE_MAJOR" -lt 3 ] || ([ "$CMAKE_MAJOR" -eq 3 ] && [ "$CMAKE_MINOR" -lt 10 ]); then log_it "ERROR: CMake 3.10+ required, found $CMAKE_VERSION" log_it "Ubuntu: sudo apt-get install cmake" log_it "CentOS: sudo dnf install cmake" log_it "macOS: brew install cmake" return 1 fi log_it "✓ CMake version acceptable: $CMAKE_VERSION" # Clear CMake cache if exists if [ -f "CMakeCache.txt" ]; then log_it "Clearing CMake cache..." rm -f CMakeCache.txt rm -rf CMakeFiles/ fi # Check submodules log_it "Checking Git submodules..." if ! git submodule status | grep -q '^+\|^-'; then log_it "Updating submodules..." git submodule update --init --recursive fi log_it "✓ Build configuration resolved" return 0 } ``` #### Runtime Library Issues ```bash resolve_runtime_issues() { log_it "=== Resolving Runtime Library Issues ===" # Check library path configuration if [ ! -f "/etc/ld.so.conf.d/cellframe.conf" ]; then log_it "Configuring library paths..." echo '/opt/cellframe-sdk/lib' | sudo tee /etc/ld.so.conf.d/cellframe.conf sudo ldconfig log_it "✓ Library paths configured" fi # Test library loading log_it "Testing library loading..." export LD_LIBRARY_PATH="/opt/cellframe-sdk/lib:$LD_LIBRARY_PATH" if ! ldd /opt/cellframe-sdk/lib/libdap_core.so | grep -q "not found"; then log_it "✓ All libraries loading correctly" return 0 else log_it "ERROR: Some libraries not found:" ldd /opt/cellframe-sdk/lib/libdap_core.so | grep "not found" return 1 fi } ``` ### Getting Support #### Documentation Resources - **[[Modules/Module Overview|Module Documentation]]** - Complete SDK module reference - **[[Architecture Overview|Architecture Overview]]** - System architecture and design - **[[Building from Source|Building from Source]]** - Detailed build instructions - **[[Development Guide|Development Guide]]** - Development best practices #### Community Support - **Forum:** [Cellframe Community Forum](https://forum.cellframe.net) - **Issues:** [GitLab Issue Tracker](https://gitlab.demlabs.net/cellframe/cellframe-sdk/issues) - **Documentation:** [Official Documentation](https://docs.cellframe.net) #### Professional Support - **Enterprise Support:** Contact [email protected] - **Development Services:** Contact [email protected] --- **See also:** [[Building from Source|Building from Source]], [[First Application|First Application]], [[Architecture Overview|Architecture Overview]], [[Development Guide|Development Guide]]