Skip to content

Environment Setup and Build

Build System Guide

Overview

Before normal use, you need to complete dependency installation, configuration management, and component compilation.

  • Dependency installation: Install libraries such as CUDA/LLVM/Eigen/AdaptiveCpp. See other documents for details.
  • Configuration management: Load necessary environment variables and set compilation options according to project requirements.
  • Component compilation: Compile the components you need and perform basic testing.

This document mainly covers configuration management and component compilation.

File Descriptions

env_scan.sh - Dependency Scanning Tool

Purpose: After dependencies are installed, this script generates an environment variable configuration file.

  • Environment variables are essentially required for compilation in psum.

Features:

  • Searches for dependency libraries in predefined paths
  • Detects the following dependencies: LLVM, AdaptiveCpp, Eigen, CUDA, BLAS, UMFPACK
  • Automatically generates the env_load.sh environment configuration file
  • Sets environment variables for compilation tools, header files, and library files
  • Supports search depth configuration (default 3 levels, adjustable via -d parameter)

Usage: 

bash env_scan.sh           # Default depth 3
bash env_scan.sh -d 4      # Maximum search depth 4 levels

Search Priority:

    1. Paths referenced by existing environment variables
    1. Paths under the user's home directory
    1. Heuristic search paths such as /usr, /opt, /usr/local, /data/apps, /share, /public

env_scan.sh should work correctly when all dependencies are properly installed and the environment is straightforward. For complex situations, such as running on a cluster, it is recommended to first use module load or other configuration methods before calling env_scan.sh. This may improve search results because env_scan.sh prioritizes paths already set in environment variables.

env_load.sh - Environment Loader (Auto-generated)

Purpose: Sets environment variables for all dependency libraries

Features:

  • Automatically generated by env_scan.sh, includes a generation timestamp
  • Sets the following environment variables:
  • PATH: Executable file paths
  • CPATH: Header file search paths
  • LIBRARY_PATH: Compile-time library search paths
  • LD_LIBRARY_PATH: Runtime library search paths

Usage: 

source env_load.sh

If env_load.sh is unreliable, you should set environment variables manually. This file is not tracked by git.

config.mk - Default Build Configuration

Purpose: Provides default compiler and build option configuration for Makefiles

Configuration Items:

  • Compiler settings: CXX, NVCC, ACPP
  • Feature toggles: USE_EIGEN, USE_UMFPACK, USE_CUDA (0=disable, 1=enable)
  • CUDA architecture: CUDA_ARCH (default sm_75)
  • Backend selection: USE_CUDA_SPARSELU_GPU, USE_EIGEN_SPARSELU_CPU
  • General compilation options: -O3 -std=c++20
  • Library linking: CUDA, UMFPACK, Eigen related libraries

Users can view the default configuration here and override settings in config.mk.local as needed.

config.mk.local - User Local Configuration (Optional)

Purpose: Overrides default compilation configuration

Features:

  • This file takes priority over config.mk. Users can override default settings according to their needs

Example Content: 

CUDA_ARCH := sm_80  # Change the default CUDA architecture
USE_CUDA := 0       # Override the default value if no CUDA environment is available

This file is not tracked by git.

build.sh - Component Compilation Script

Purpose: Compiles and tests project components. psum's main functionality is provided as header-only, so only a few components need to be compiled.

Execution Steps:

  1. Load env_load.sh environment variables
  2. Compile field solver backends (C++/CUDA)
  3. Test field solver components
  4. Compile pypsum serialization module (Python/C++ interop)
  5. Test pypsum module interoperability

Usage: 

bash build.sh

build.sh should be run after env_load.sh environment variables have been created.

runCheck.sh - Smoke Test Script

Use test/runCheck.sh to further verify that the environment is configured correctly.

Build Process

First-time Build

Applies to: First-time project clone, system environment changes, or when component compilation configuration needs adjustment

# 0. Environment pre-configuration (if needed)
# module load cuda llvm openblas umfpack eigen

# 1. Scan system dependencies
bash env_scan.sh

# 2. Check if the generated environment configuration is correct
cat env_load.sh

# 3. Create custom configuration (if needed)
# To modify CUDA architecture or disable certain features, create config.mk.local

# 4. Execute component build
bash build.sh

# 5. Load environment variables
source env_load.sh # Although build.sh loads them automatically, you need to manually load them in the current bash session

# Compile your project

Regular Use

Applies to: Environment is already configured, only need to compile projects

# 1. Load environment variables
source env_load.sh

# Compile your project

File Relationships

  • env_scan.sh scans the system and automatically generates env_load.sh

  • build.sh depends on env_load.sh and component makefile or build.sh files

  • Component makefile files include config.mk

  • config.mk attempts to load config.mk.local and override default values