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
In this repository14 other files it gives its agents.
- AGENTS.mdAGENTS.md
- cmakeSkill
- ekapkgs-repoSkill
- goSkill
- mesonSkill
- mk-many-variantsSkill
- nix-buildSkill
- nix-evalSkill
- packagingSkill
- portingSkill
- pythonSkill
- rustSkill
- structured-attrsSkill
- validationSkill
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
- Distinctive: line 23
Create derivations using stdenv.mkDerivation with cmake
- Distinctive: line 30
Use cmakeFlags and cmakeFlagsArray to pass options to CMake
- Distinctive: line 46
Use Ninja generator for faster builds
- Very specific: line 62
Should only be needed to be configured if the source directory already has a build directory
- Distinctive: line 67
Use this when CMakeLists.txt is in a subdirectory
- Distinctive: line 71
If set, builds in the source directory instead of a separate build directory
- Distinctive: line 88
Always use Release for production packages to ensure optimizations
- Very specific: line 94
If false/unset, adds -DBUILD_TESTING=OFF to disable building tests
- Distinctive: line 99
If set, enables parallel CTest execution
- Very specific: line 106
If set, doesn't add -DCMAKE_INSTALL_PREFIX=$prefix
- Distinctive: line 120
If set, skips fixing cmake files (replacing /usr and /opt with /var/empty)
- Very specific: line 351
Ensure the dependency is in buildInputs or propagatedBuildInputs
- Distinctive: line 352
Check if the dependency provides CMake config files, should be Foo-config.cmake or FooConfig.cmake
- Very specific: line 353
Verify CMAKE_PREFIX_PATH includes the dependency (it should automatically)
- Very specific: line 354
Use cmakeFlags = [ "-DFoo_DIR=${foo}/lib/cmake/Foo" ].
- Distinctive: line 363
Ensure the CMakeLists.txt uses GNUInstallDirs module variables
- Very specific: line 364
Check if dontAddPrefix is accidentally set
- Very specific: line 365
Verify CMAKE_INSTALL_PREFIX is being respected
- Very specific: line 376
Use enableParallelChecking = false.
- Very specific: line 377
Use checkPhase to manually run specific tests
- Very specific: line 378
Consider disabling problematic tests with cmakeFlags = [ "-DSKIP_TEST=ON" ].
- Very specific: line 386
Use cmake from a specific version: nativeBuildInputs = [ cmake.v4 ].
- Very specific: line 387
Check cmake versions. For example, cmake.variants.*.version
- Very specific: line 396
Verify cmakeBuildType is set appropriately (default: Release)
- Very specific: line 399
Check if CFLAGS/CXXFLAGS conflict with CMAKE_BUILD_TYPE
- Very specific: line 408
Use CMAKE_INSTALL_BINDIR, CMAKE_INSTALL_LIBDIR, etc.
- Distinctive: line 416
Only use Debug for debugging or development
- Distinctive: line 423
Add ninja to nativeBuildInputs
- Very specific: line 427
Use nix-build --verbose or nix build --print-build-logs
- Very specific: line 434
If using cmakeDir, dontUseCmakeBuildDir, etc., add a comment explaining why
≈ “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.
Files
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
- 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
- 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
- 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)
- 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
builddirectory - 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=OFFto disable building tests - Set to true to enable building and running tests
- Example:
doCheck = true;
- If false/unset, adds
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;
- If set, doesn't add
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 to1by cmake)- Automatically enabled by cmake setup-hook
- Rarely needs manual configuration
- Example:
enableParallelBuilding = false;to disable
enableParallelInstalling(default: automatically set to1by 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=$CCCMAKE_CXX_COMPILER=$CXXCMAKE_AR=$(command -v $AR)CMAKE_RANLIB=$(command -v $RANLIB)CMAKE_STRIP=$(command -v $STRIP)
Installation paths (using GNUInstallDirs)
CMAKE_INSTALL_PREFIX=$prefixCMAKE_INSTALL_BINDIR=${!outputBin}/binCMAKE_INSTALL_SBINDIR=${!outputBin}/sbinCMAKE_INSTALL_INCLUDEDIR=${!outputInclude}/includeCMAKE_INSTALL_OLDINCLUDEDIR=${!outputInclude}/includeCMAKE_INSTALL_MANDIR=${!outputMan}/share/manCMAKE_INSTALL_INFODIR=${!outputInfo}/share/infoCMAKE_INSTALL_DOCDIR=${!outputDoc}/share/doc/${shareDocName}CMAKE_INSTALL_LIBDIR=${!outputLib}/libCMAKE_INSTALL_LIBEXECDIR=${!outputLib}/libexecCMAKE_INSTALL_LOCALEDIR=${!outputLib}/share/localeCMAKE_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=ONCMAKE_FIND_USE_PACKAGE_REGISTRY=OFFCMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY=OFF
Search paths
NIXPKGS_CMAKE_PREFIX_PATHis what ekala and nixpkgs packages will append themselves, similar toCMAKE_PREFIX_PATHCMAKE_INCLUDE_PATH,CMAKE_LIBRARY_PATH,CMAKE_FRAMEWORK_PATHare 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:
- Ensure the dependency is in
buildInputsorpropagatedBuildInputs - Check if the dependency provides CMake config files, should be Foo-config.cmake or FooConfig.cmake
- Verify CMAKE_PREFIX_PATH includes the dependency (it should automatically)
- Use
cmakeFlags = [ "-DFoo_DIR=${foo}/lib/cmake/Foo" ];as a workaround - Some packages need
propagatedBuildInputsinstead 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:
- Ensure the CMakeLists.txt uses GNUInstallDirs module variables
- Check if
dontAddPrefixis accidentally set - Verify CMAKE_INSTALL_PREFIX is being respected
- 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:
- Tests may require network access (not allowed in sandbox)
- Tests may require /tmp or other paths - check test output
- Use
enableParallelChecking = false;if tests interfere with each other - Use
checkPhaseto manually run specific tests - Consider disabling problematic tests with
cmakeFlags = [ "-DSKIP_TEST=ON" ];
CMake version requirements
Problem: Package requires newer CMake than available
Solution:
- Use cmake from a specific version:
nativeBuildInputs = [ cmake.v4 ]; - Check cmake versions. For example,
cmake.variants.*.version - Override cmake version if needed
Build type issues
Problem: Package behaves incorrectly or is unoptimized
Solution:
- Verify
cmakeBuildTypeis set appropriately (default: Release) - Release builds are optimized, Debug builds have symbols
- Some packages require specific build types for certain features
- Check if CFLAGS/CXXFLAGS conflict with CMAKE_BUILD_TYPE
Best practices
- Always include cmake in nativeBuildInputs
- CMake is a build tool, not a runtime dependency
- Use GNUInstallDirs in CMakeLists.txt
- Ensures proper integration with Nix's multiple output system
- Use
CMAKE_INSTALL_BINDIR,CMAKE_INSTALL_LIBDIR, etc.
- Prefer cmakeFlags over patching CMakeLists.txt
- More maintainable and easier to understand
- Survives upstream updates better
- Use Release build type for production packages
- Ensures optimizations are enabled
- Only use Debug for debugging or development
- Disable tests by deafult
- Set
doCheck = false;, tests should be enabled throughpassthru.tests.unitTests = runUnitTests finalAttrs.finalPackage
- Set
- Consider Ninja for large projects
- Faster builds than Unix Makefiles
- Add ninja to nativeBuildInputs
- Check the build log for warnings
- CMake warnings often indicate configuration issues
- Use
nix-build --verboseornix build --print-build-logs
- Handle multiple outputs properly
- Define
outputs = [ "out" "dev" "doc" ];as needed - CMake setup-hook configures install dirs automatically
- Define
- Document non-standard cmake attributes
- If using
cmakeDir,dontUseCmakeBuildDir, etc., add a comment explaining why
- If using
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 MakefilesIntegration 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
];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
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.

