Skip to main content

Getting Started

The SoCMake source code is available on GitHub.

Dependencies​

SoCMake requires CMake >= 3.27.0 and either make or ninja.

pip install cmake
pip install ninja

The fastest way to get started is using the one-time bootstrap installation.

Step 1: Install Bootstrap​

Run this command once on your system:

curl -fsSL https://raw.githubusercontent.com/HEP-SoC/SoCMake/develop/bootstrap/bootstrap.sh | sh

Follow the instructions of the bootstrap script

This installs bootstrap files to ~/.local/lib/cmake/socmake that automatically fetch the correct SoCMake version for each project.

Step 2: Create Your Project​

Create a CMakeLists.txt file in your project root:

CMakeLists.txt
cmake_minimum_required(VERSION 3.27)
project(test NONE)

find_package(socmake REQUIRED)
# Here SoCMake functions are available

Step 3: Configure the Project​

Create a build directory and run CMake:

mkdir build && cd build
cmake ..

You should see output similar to:

-- Configuring done (1.7s)
-- Generating done (0.0s)
-- Build files have been written to: ../build

That's it! You're ready to use SoCMake. Continue to the Examples page to start building hardware.

Alternative Setup Methods​

Using FetchContent or CPM.cmake (per-project installation)

If you prefer not to use the bootstrap installation, you can fetch SoCMake directly within each project using CMake's built-in FetchContent or the CPM.cmake package manager.

info

These methods download SoCMake during the configuration phase of each project. The bootstrap method shares a single installation across all projects and is generally more convenient.

Directory Structure​

Create the following project structure:

my_project/
├── CMakeLists.txt
└── deps/
    ├── deps.cmake
    └── CPM.cmake      # Only needed for CPM method

Step 1: deps/deps.cmake​

Choose one of the following approaches:

CPM.cmake provides better caching and version management than FetchContent.

deps/deps.cmake
set(CPM_DOWNLOAD_VERSION 0.38.1)
include(${CMAKE_CURRENT_LIST_DIR}/CPM.cmake)

CPMAddPackage(
    NAME SoCMake
    GIT_TAG master  # or specify VERSION for versioning
    GIT_REPOSITORY "https://github.com/HEP-SoC/SoCMake.git"
)

You'll also need to create deps/CPM.cmake:

deps/CPM.cmake
if(CPM_SOURCE_CACHE)
  set(CPM_DOWNLOAD_LOCATION "${CPM_SOURCE_CACHE}/cpm/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
elseif(DEFINED ENV{CPM_SOURCE_CACHE})
  set(CPM_DOWNLOAD_LOCATION "$ENV{CPM_SOURCE_CACHE}/cpm/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
else()
  set(CPM_DOWNLOAD_LOCATION "${CMAKE_BINARY_DIR}/cmake/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
endif()

# Expand relative path. This is important if the provided path contains a tilde (~)
get_filename_component(CPM_DOWNLOAD_LOCATION ${CPM_DOWNLOAD_LOCATION} ABSOLUTE)

function(download_cpm)
  message(STATUS "Downloading CPM.cmake to ${CPM_DOWNLOAD_LOCATION}")
  file(DOWNLOAD
       https://github.com/cpm-cmake/CPM.cmake/releases/download/v${CPM_DOWNLOAD_VERSION}/CPM.cmake
       ${CPM_DOWNLOAD_LOCATION}
  )
endfunction()

if(NOT (EXISTS ${CPM_DOWNLOAD_LOCATION}))
  download_cpm()
else()
  # resume download if it previously failed
  file(READ ${CPM_DOWNLOAD_LOCATION} check)
  if("${check}" STREQUAL "")
    download_cpm()
  endif()
  unset(check)
endif()

include(${CPM_DOWNLOAD_LOCATION})

Step 2: CMakeLists.txt​

Create your main CMakeLists.txt file:

CMakeLists.txt
cmake_minimum_required(VERSION 3.27)
project(my_project NONE)

include("deps/deps.cmake")

# All SoCMake functions are now available

Step 3: Configure the Project​

CMake uses out-of-source builds, keeping source files and build artifacts in separate directories:

mkdir build
cd build
cmake ..

Expected output:

-- Downloading CPM.cmake to .../build/cmake/CPM_0.38.1.cmake
-- CPM: Adding package SoCMake@master
-- Configuring done
-- Generating done
-- Build files have been written to: .../build

Dependency Location​

By default, packages are downloaded to ${CMAKE_BINARY_DIR}/_deps/. You can change this by setting FETCHCONTENT_BASE_DIR before the first package fetch.

Shared Dependencies for Larger Projects

For projects with multiple subdirectories (like verification/, documentation/, etc.), add this to the top of deps/deps.cmake:

set(FETCHCONTENT_BASE_DIR ${CMAKE_CURRENT_LIST_DIR}/_deps)

This downloads dependencies once at the repository root, making them available across all subdirectories.