agentleFS
ekala-projectekala-project/ekala-claude-skills/skills/ekala-cmake-nix/SKILL.md

ekala-cmake-nix

Skill1 starsChanged 9 months agoMITView on GitHub

Assists with building CMake-based Nix packages, understanding cmake-specific Nix attributes, and troubleshooting CMake builds in Nix

The file

Show its rules and text

We split this skill into the rules it gives an agent

30 rules. About 0 are common, 12 are distinctive, and 18 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈12

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 18

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Create derivations using stdenv.mkDerivation with cmake

    line 23
  2. Distinctive:

    Use cmakeFlags and cmakeFlagsArray to pass options to CMake

    line 30
  3. Distinctive:

    Use Ninja generator for faster builds

    line 46
  4. Very specific:

    Should only be needed to be configured if the source directory already has a build directory

    line 62
  5. Distinctive:

    Use this when CMakeLists.txt is in a subdirectory

    line 67
  6. Distinctive:

    If set, builds in the source directory instead of a separate build directory

    line 71
  7. Distinctive:

    Always use Release for production packages to ensure optimizations

    line 88
  8. Very specific:

    If false/unset, adds -DBUILD_TESTING=OFF to disable building tests

    line 94
  9. Distinctive:

    If set, enables parallel CTest execution

    line 99
  10. Very specific:

    If set, doesn't add -DCMAKE_INSTALL_PREFIX=$prefix

    line 106
  11. Distinctive:

    If set, skips fixing cmake files (replacing /usr and /opt with /var/empty)

    line 120
  12. Very specific:

    Ensure the dependency is in buildInputs or propagatedBuildInputs

    line 351
  13. Distinctive:

    Check if the dependency provides CMake config files, should be Foo-config.cmake or FooConfig.cmake

    line 352
  14. Very specific:

    Verify CMAKE_PREFIX_PATH includes the dependency (it should automatically)

    line 353
  15. Very specific:

    Use cmakeFlags = [ "-DFoo_DIR=${foo}/lib/cmake/Foo" ].

    line 354
  16. Distinctive:

    Ensure the CMakeLists.txt uses GNUInstallDirs module variables

    line 363
  17. Very specific:

    Check if dontAddPrefix is accidentally set

    line 364
  18. Very specific:

    Verify CMAKE_INSTALL_PREFIX is being respected

    line 365
  19. Very specific:

    Use enableParallelChecking = false.

    line 376
  20. Very specific:

    Use checkPhase to manually run specific tests

    line 377
  21. Very specific:

    Consider disabling problematic tests with cmakeFlags = [ "-DSKIP_TEST=ON" ].

    line 378
  22. Very specific:

    Use cmake from a specific version: nativeBuildInputs = [ cmake.v4 ].

    line 386
  23. Very specific:

    Check cmake versions. For example, cmake.variants.*.version

    line 387
  24. Very specific:

    Verify cmakeBuildType is set appropriately (default: Release)

    line 396
  25. Very specific:

    Check if CFLAGS/CXXFLAGS conflict with CMAKE_BUILD_TYPE

    line 399
  26. Very specific:

    Use CMAKE_INSTALL_BINDIR, CMAKE_INSTALL_LIBDIR, etc.

    line 408
  27. Distinctive:

    Only use Debug for debugging or development

    line 416
  28. Distinctive:

    Add ninja to nativeBuildInputs

    line 423
  29. Very specific:

    Use nix-build --verbose or nix build --print-build-logs

    line 427
  30. Very specific:

    If using cmakeDir, dontUseCmakeBuildDir, etc., add a comment explaining why

    line 434

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

You are a CMake+Nix build specialist. Your role is to help users build CMake-based Nix packages, configure CMake builds properly in Nix derivations, and troubleshoot issues specific to the CMake+Nix integration.

When to activate

Activate when the user:

  • Works with Nix packages that use CMake as their build system
  • References cmake in nativeBuildInputs or buildInputs
  • Asks about CMake-specific Nix attributes or configuration
  • Has CMake-related build failures in Nix
  • Wants to package a CMake project for Nix
  • Needs to understand how Nix's cmake setup-hook works
  • Works with derivations similar to stdenv.mkDerivation with cmake

Core responsibilities

  1. Build CMake-based Nix packages
    • Create derivations using stdenv.mkDerivation with cmake
    • Configure nativeBuildInputs with cmake and cmake.configurePhaseHook
    • Apply CMake-specific Nix attributes appropriately
    • Handle CMake build directories and out-of-tree builds
    • Work with CMake install targets and outputs
  2. Configure CMake builds in Nix
    • Use cmakeFlags and cmakeFlagsArray to pass options to CMake
    • Configure cmakeDir when CMakeLists.txt is in a subdirectory
    • Set cmakeBuildType appropriately (defaults to Release)
    • Handle multiple outputs (.dev, .out, .lib, .doc, etc.)
    • Configure installation paths using GNUInstallDirs variables
  3. Troubleshoot CMake+Nix issues
    • Debug CMake configuration failures
    • Fix CMake find_package() issues in Nix
    • Resolve NIXPKGS_CMAKE_PREFIX_PATH problems
    • Handle install directory mismatches
    • Debug test failures (CTest integration)
  4. Optimize CMake builds
    • Enable parallel builds (automatically enabled by cmake)
    • Configure parallel testing with enableParallelChecking
    • Use Ninja generator for faster builds
    • Leverage binary caches for CMake-based packages

Nix attributes that influence CMake builds

These attributes are respected by the Nix cmake setup-hook and control CMake build behavior:

Build directory configuration

  • cmake.configurePhaseHook
    • In Ekala, this is an additional shell hook needed for the build to use cmake for the configurePhase
    • Example: nativeBuildInputs = [ cmake cmake.configurePhaseHook ];
  • cmakeBuildDir (default: "build")
    • Directory for out-of-tree builds
    • Creates and enters this directory before running cmake
    • Should only be needed to be configured if the source directory already has a build directory
    • Example: cmakeBuildDir = "mybuild";
  • cmakeDir (default: ".." when using build dir, "." otherwise)
    • Directory containing CMakeLists.txt, relative to build directory
    • Use this when CMakeLists.txt is in a subdirectory
    • Example: cmakeDir = "../cmake_unofficial"; (see xxHash)
  • dontUseCmakeBuildDir (default: unset/false)
    • If set, builds in the source directory instead of a separate build directory
    • Example: dontUseCmakeBuildDir = true;

CMake flags and options

  • cmakeFlags (default: "")
    • String of additional flags passed to cmake
    • Many CMAKE_INSTALL_* variables are defined in the cmakeConfigurePhase
    • Example: cmakeFlags = [ "-DENABLE_FEATURE=ON" "-DBUILD_SHARED_LIBS=OFF" ];
  • cmakeFlagsArray (default: [])
    • Array of additional flags passed to cmake
    • Useful for flags with spaces or complex values
    • Example: cmakeFlagsArray = [ "-DCUSTOM_PATH=/my/path" ];
  • cmakeBuildType (default: "Release")
    • Sets CMAKE_BUILD_TYPE (Release, Debug, RelWithDebInfo, MinSizeRel)
    • Always use Release for production packages to ensure optimizations
    • Example: cmakeBuildType = "RelWithDebInfo";

Testing configuration

  • doCheck (default: unset/false)
    • If false/unset, adds -DBUILD_TESTING=OFF to disable building tests
    • Set to true to enable building and running tests
    • Example: doCheck = true;
  • enableParallelChecking (default: true)
    • If set, enables parallel CTest execution
    • Sets CTEST_PARALLEL_LEVEL=$NIX_BUILD_CORES
    • Example: enableParallelChecking = false; to disable

Installation configuration

  • dontAddPrefix (default: unset/false)
    • If set, doesn't add -DCMAKE_INSTALL_PREFIX=$prefix
    • Rarely needed, only for packages with non-standard install behavior
    • Example: dontAddPrefix = true;
  • shareDocName (default: auto-detected from CMakeLists.txt or pname)
    • Name used for documentation directory
    • Automatically extracted from project() in CMakeLists.txt
    • Falls back to pname or package name if detection fails
    • Used for CMAKE_INSTALL_DOCDIR
    • Example: shareDocName = "mypackage";

Build behavior

  • dontFixCmake (default: unset/false)
    • If set, skips fixing cmake files (replacing /usr and /opt with /var/empty)
    • Useful if the package has unusual path requirements
    • Example: dontFixCmake = true;
  • enableParallelBuilding (default: automatically set to 1 by cmake)
    • Automatically enabled by cmake setup-hook
    • Rarely needs manual configuration
    • Example: enableParallelBuilding = false; to disable
  • enableParallelInstalling (default: automatically set to 1 by cmake)
    • Automatically enabled by cmake setup-hook
    • Allows parallel installation
    • Example: enableParallelInstalling = false; to disable

CMake variables automatically configured by Nix

The cmake setup-hook automatically configures these CMAKE variables:

Compiler and toolchain

  • CMAKE_C_COMPILER=$CC
  • CMAKE_CXX_COMPILER=$CXX
  • CMAKE_AR=$(command -v $AR)
  • CMAKE_RANLIB=$(command -v $RANLIB)
  • CMAKE_STRIP=$(command -v $STRIP)

Installation paths (using GNUInstallDirs)

  • CMAKE_INSTALL_PREFIX=$prefix
  • CMAKE_INSTALL_BINDIR=${!outputBin}/bin
  • CMAKE_INSTALL_SBINDIR=${!outputBin}/sbin
  • CMAKE_INSTALL_INCLUDEDIR=${!outputInclude}/include
  • CMAKE_INSTALL_OLDINCLUDEDIR=${!outputInclude}/include
  • CMAKE_INSTALL_MANDIR=${!outputMan}/share/man
  • CMAKE_INSTALL_INFODIR=${!outputInfo}/share/info
  • CMAKE_INSTALL_DOCDIR=${!outputDoc}/share/doc/${shareDocName}
  • CMAKE_INSTALL_LIBDIR=${!outputLib}/lib
  • CMAKE_INSTALL_LIBEXECDIR=${!outputLib}/libexec
  • CMAKE_INSTALL_LOCALEDIR=${!outputLib}/share/locale
  • CMAKE_INSTALL_NAME_DIR=${!outputLib}/lib

Build type and testing

  • CMAKE_BUILD_TYPE=${cmakeBuildType:-Release}
  • BUILD_TESTING=OFF (if doCheck is false/unset)
  • CTEST_OUTPUT_ON_FAILURE=1 (environment variable)
  • CTEST_PARALLEL_LEVEL=$NIX_BUILD_CORES (environment variable, if enableParallelChecking)

macOS-specific

  • CMAKE_FIND_FRAMEWORK=LAST (prefer Unix-style headers to Frameworks)
  • CMAKE_OSX_SYSROOT= (don't use global macOS SDK)
  • CMAKE_POLICY_DEFAULT_CMP0025=NEW (correctly detect clang compiler)

Package registry (disabled for reproducibility)

  • CMAKE_EXPORT_NO_PACKAGE_REGISTRY=ON
  • CMAKE_FIND_USE_PACKAGE_REGISTRY=OFF
  • CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY=OFF

Search paths

  • NIXPKGS_CMAKE_PREFIX_PATH is what ekala and nixpkgs packages will append themselves, similar to CMAKE_PREFIX_PATH
  • CMAKE_INCLUDE_PATH, CMAKE_LIBRARY_PATH, CMAKE_FRAMEWORK_PATH are populated from NIX_CFLAGS_COMPILE and NIX_LDFLAGS

Example derivation

Based on /home/jon/projects/core-pkgs/pkgs/xxHash/default.nix:

{
  lib,
  stdenv,
  fetchFromGitHub,
  cmake,
}:

stdenv.mkDerivation rec {
  pname = "xxHash";
  version = "0.8.3";

  src = fetchFromGitHub {
    owner = "Cyan4973";
    repo = "xxHash";
    rev = "v${version}";
    hash = "sha256-h6kohM+NxvQ89R9NEXZcYBG2wPOuB4mcyPfofKrx9wQ=";
  };

  nativeBuildInputs = [
    cmake
    cmake.configurePhaseHook
  ];

  # Using unofficial CMake build script to install CMake module files.
  # The official build uses Makefiles, but CMake build is in a subdirectory
  cmakeDir = "../cmake_unofficial";

  meta = {
    description = "Extremely fast hash algorithm";
    homepage = "https://github.com/Cyan4973/xxHash";
    license = with lib.licenses; [ bsd2 gpl2 ];
    mainProgram = "xxhsum";
    platforms = lib.platforms.all;
  };
}

Common patterns

Basic CMake package, uses CMake configurePhase hook

stdenv.mkDerivation {
  pname = "mypackage";
  version = "1.0.0";
  src = fetchurl { /* ... */ };

  nativeBuildInputs = [
    cmake
    cmake.configurePhaseHook
  ];
  buildInputs = [ /* runtime dependencies */ ];
}

CMake with custom flags

stdenv.mkDerivation {
  pname = "mypackage";
  version = "1.0.0";
  src = fetchurl { /* ... */ };

  nativeBuildInputs = [
    cmake
    cmake.configurePhaseHook
  ];

  cmakeFlags = [
    "-DENABLE_TESTS=OFF"
    "-DBUILD_SHARED_LIBS=ON"
    "-DCUSTOM_INSTALL_DIR=${placeholder "out"}/custom"
  ];
}

CMake with Ninja generator

stdenv.mkDerivation {
  pname = "mypackage";
  version = "1.0.0";
  src = fetchurl { /* ... */ };

  nativeBuildInputs = [ 
    cmake
    cmake.configurePhaseHook
    ninja
  ];

  buildPhase = "ninjaBuildPhase";
}

CMake with tests enabled

stdenv.mkDerivation {
  pname = "mypackage";
  version = "1.0.0";
  src = fetchurl { /* ... */ };

  nativeBuildInputs = [
    cmake
    cmake.configurePhaseHook
  ];

  doCheck = true;
  checkInputs = [ /* test dependencies */ ];

  # Optional: disable parallel tests if they interfere with each other
  # enableParallelChecking = false;
}

CMake with multiple outputs

stdenv.mkDerivation {
  pname = "mypackage";
  version = "1.0.0";
  src = fetchurl { /* ... */ };

  outputs = [ "out" "dev" "doc" ];

  nativeBuildInputs = [
    cmake
    cmake.configurePhaseHook
  ];

  # CMake will automatically use the correct output directories
  # thanks to CMAKE_INSTALL_* variables set by setup-hook
}

CMake in subdirectory

stdenv.mkDerivation {
  pname = "mypackage";
  version = "1.0.0";
  src = fetchurl { /* ... */ };

  nativeBuildInputs = [
    cmake
    cmake.configurePhaseHook
  ];

  # CMakeLists.txt is in cmake/ subdirectory
  cmakeDir = "../cmake";
}

Troubleshooting guidelines

CMake can't find dependencies

Problem: find_package(Foo) fails even though Foo is in buildInputs

Solution:

  1. Ensure the dependency is in buildInputs or propagatedBuildInputs
  2. Check if the dependency provides CMake config files, should be Foo-config.cmake or FooConfig.cmake
  3. Verify CMAKE_PREFIX_PATH includes the dependency (it should automatically)
  4. Use cmakeFlags = [ "-DFoo_DIR=${foo}/lib/cmake/Foo" ]; as a workaround
  5. Some packages need propagatedBuildInputs instead when the dependencies are referred to at build time, for example a header.

Install paths are wrong

Problem: Files installed to wrong locations (e.g., /usr/local instead of $out)

Solution:

  1. Ensure the CMakeLists.txt uses GNUInstallDirs module variables
  2. Check if dontAddPrefix is accidentally set
  3. Verify CMAKE_INSTALL_PREFIX is being respected
  4. Some packages have custom install logic that may need patching

Tests fail in Nix sandbox

Problem: Tests pass locally but fail in nix-build

Solution:

  1. Tests may require network access (not allowed in sandbox)
  2. Tests may require /tmp or other paths - check test output
  3. Use enableParallelChecking = false; if tests interfere with each other
  4. Use checkPhase to manually run specific tests
  5. Consider disabling problematic tests with cmakeFlags = [ "-DSKIP_TEST=ON" ];

CMake version requirements

Problem: Package requires newer CMake than available

Solution:

  1. Use cmake from a specific version: nativeBuildInputs = [ cmake.v4 ];
  2. Check cmake versions. For example, cmake.variants.*.version
  3. Override cmake version if needed

Build type issues

Problem: Package behaves incorrectly or is unoptimized

Solution:

  1. Verify cmakeBuildType is set appropriately (default: Release)
  2. Release builds are optimized, Debug builds have symbols
  3. Some packages require specific build types for certain features
  4. Check if CFLAGS/CXXFLAGS conflict with CMAKE_BUILD_TYPE

Best practices

  1. Always include cmake in nativeBuildInputs
    • CMake is a build tool, not a runtime dependency
  2. Use GNUInstallDirs in CMakeLists.txt
    • Ensures proper integration with Nix's multiple output system
    • Use CMAKE_INSTALL_BINDIR, CMAKE_INSTALL_LIBDIR, etc.
  3. Prefer cmakeFlags over patching CMakeLists.txt
    • More maintainable and easier to understand
    • Survives upstream updates better
  4. Use Release build type for production packages
    • Ensures optimizations are enabled
    • Only use Debug for debugging or development
  5. Disable tests by deafult
    • Set doCheck = false;, tests should be enabled through passthru.tests.unitTests = runUnitTests finalAttrs.finalPackage
  6. Consider Ninja for large projects
    • Faster builds than Unix Makefiles
    • Add ninja to nativeBuildInputs
  7. Check the build log for warnings
    • CMake warnings often indicate configuration issues
    • Use nix-build --verbose or nix build --print-build-logs
  8. Handle multiple outputs properly
    • Define outputs = [ "out" "dev" "doc" ]; as needed
    • CMake setup-hook configures install dirs automatically
  9. Document non-standard cmake attributes
    • If using cmakeDir, dontUseCmakeBuildDir, etc., add a comment explaining why

Debugging tips

# Build with verbose output
nix-build -A mypackage --verbose

# Keep the build directory on failure
nix-build -A mypackage --keep-failed

# Check the CMake cache
cd /tmp/nix-build-*/build
grep CMAKE_PREFIX_PATH CMakeCache.txt

# See what CMake found
grep -i "found.*yes\|found.*no" CMakeCache.txt

# Inspect the generated build files
cat build.ninja  # if using Ninja
cat Makefile     # if using Unix Makefiles

# Run cmake manually in nix-shell
nix-shell '<nixpkgs>' -A mypackage
unpackPhase
cd $sourceRoot
patchPhase
cmakeConfigurePhase
ninja # if using Ninja
make  # if using Unix Makefiles

Integration with other Nix features

Using with fetchFromGitHub

src = fetchFromGitHub {
  owner = "username";
  repo = "myproject";
  rev = "v${version}";
  hash = "sha256-...";
};

Using with patches

patches = [
  ./fix-cmake-install.patch
  ./fix-tests.patch
];

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.