nx-cmake
TypeScript icon, indicating that this package has built-in type declarations

0.7.2 • Public • Published

nx-cmake CI GitHub package.json version (subfolder of monorepo)

Motivation

This Nx plugin was developed to enhance the developer experience when working with C or C++ projects. It streamlines the setup of CMake, automates boilerplate generation, and optimizes dependency management and caching strategies, making it quick and easy to kickstart a new C or C++ project within your Nx workspace.

Key Features

Comprehensive Support for CMake, C, and C++ in a Monorepo

  • The plugin installs essential CMake utility functions and creates a CMakeLists.txt file in the root of your workspace, facilitating CMake usage within a monorepo setup.
  • It scans the workspace for additional CMakeLists.txt files and generates a global include directory at the root, accessible to all projects.
  • Optionally, you can generate opinionated formatting and linting rules for use with tools like clang-format and clang-tidy.
  • Automatically updates the nx.json file at the root of your workspace for optimal caching behavior, target pipelines, and plugin initialization.

Streamlined Generation of Binaries and Libraries

  • After initializing the plugin, you can leverage the provided generators to create binaries.
  • By default, binaries (applications) are placed in the bin directory, while libraries are stored in the libs directory.
  • Binaries act as basic wrappers around libraries, simplifying testing.
  • When creating a binary, two projects are generated: the primary binary and a testing binary.
  • The library project receives a 'lib' prefix, and the test project is prefixed with 'test,' based on the chosen generator name.
  • Libraries can be easily included in other projects using #include </dirNameOfLibrary/pathInLibrary/fileNameOfLibrary.h>.

Automatic Project Inference

  • Each CMakeLists.txt file instructs the plugin to register a new project and adds it to the project graph managed by the Nx daemon.
  • Project configurations are automatically inferred for each CMakeLists.txt file, determining the appropriate project type.
  • The plugin's generators create a project.json file, mirroring the inferred settings from the CMakeLists.txt. Changes to this file can override inferred settings, offering flexibility.

Efficient Project Graph Processing

  • Inferred projects are integrated into the project graph, enabling dependency analysis between them.
  • Importing code from one library automatically updates the project graph, establishing dependencies.
  • The Nx daemon's caching mechanisms optimize dependency tracking and graph calculations, particularly for larger projects.
  • Dependency detection relies on gcc -MM, which tracks source file dependencies.
  • The plugin performs a transitive reduction on the graph to minimize edges, ensuring dependencies are resolved in the correct order. This enhances caching efficiency and supports parallelization of tasks.

Getting Started

Prerequisites

Before getting started with this plugin, ensure you have the following tools installed:

  • Nx v16.9 or higher (v2 plugin API)
  • Node.js LTS (Node.js v20.9.0 or later) – Download Node.js
  • CMake v3.21 or higher – Download CMake
  • GCC (with POSIX thread model and mutex support)
  • Make
  • GDB
  • clang-format
  • clang-tidy

Windows

Installing Node.js

Node.js LTS can be downloaded here

Using chocolatey:

choco install nodejs-lts
Installing CMake

CMake can be downloaded here

Using chocolatey:

choco install cmake

NOTE: Make sure to add CMake to the PATH:

Add-Content $env:PATH "C:\Program Files\CMake\bin"
Installing MSYS2 and tools

It is required to install MSYS2.

Afterwards, make sure to have the msys2 system in the PATH:

Add-Content $env:PATH "C:\msys64"
Add-Content $env:PATH "C:\msys64\usr\bin"
Add-Content $env:PATH "C:\msys64\ucrt64\bin"

Using chocolatey:

choco install msys2 

NOTE: chocolatey installs msys2 into C:\tools\msys64 instead.

Add-Content $env:PATH "C:\tools\msys64"
Add-Content $env:PATH "C:\tools\msys64\usr\bin"
Add-Content $env:PATH "C:\tools\msys64\ucrt64\bin"

Afterwards, launch a new shell and install the required tools:

pacman -S mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-make mingw-w64-ucrt-x86_64-cmake mingw-w64-ucrt-x86_64-gdb mingw-w64-ucrt-x86_64-clang mingw-w64-ucrt-x86_64-clang-tools-extra

Installation

Installing from a preset

Using pnpm:

npx create-nx-workspace@latest <repoName> --preset=nx-cmake --pm pnpm

Using yarn:

npx create-nx-workspace@latest <repoName> --preset=nx-cmake --pm yarn

Using yarn:

npx create-nx-workspace@latest <repoName> --preset=nx-cmake --pm npm

Installing in an existing workspace

pnpm add -D nx-cmake
yarn add -D nx-cmake
npm install -D nx-cmake

After installing:

nx g nx-cmake:init

Generators

Use Nx Console to see the full list of options for each generator. In general, settings in nx.json have higher precedence.

Generators provide the following options:

nx-cmake:init (aliases: install, i)

Initialize this plugin and set up the boilerplate to support CMake, C and C++

Options Description Type Default
--language Whether to use C or C++ by default for generators. "C", "C++" "C"
--cmakeConfigDir Where the configuration for CMake will be generated. string ".cmake"
--appsDir Where the binaries will be generated. string "bin"
--libsDir Where the libraries will be generated. string "libs"
--addClangPreset Generate a clang preset. boolean true

nx-cmake:binary (aliases: bin, b)

Generate a C or C++ binary

Options Description Type Default
--name The name of the binary to generate. string N/A
--language Whether to use C or C++. "C", "C++" "C++"
--generateTests Whether to generate tests using googletest for C++ or cmocka for C. boolean true

nx-cmake:library (aliases: lib, l)

Generate a C or C++ library that can be used in binaries or other libraries

Options Description Type Default
--name The name of the library to generate. string N/A
--language Whether to use C or C++. "C", "C++" "C++"
--generateTests Whether to generate tests using googletest for C++ or CMocka for C. boolean true

nx-cmake:link (aliases: ld)

Link a library to another library or binary

Options Description Type Default
--source The source project in which another library will be linked into. string N/A
--target The target library to link into the source project. string N/A

Executors

All the executors support these additional properties:

Options Description Type Default
--args Optional arguments which will be forwarded to the underlying command string[] N/A

nx-cmake:cmake

Configure a C or C++ library with CMake

Options Description Type Default
--release Configure a C or C++ library with CMake in release mode. boolean false

nx-cmake:compile

Compile a C or C++ library with Make

Options Description Type Default
--release Build a C or C++ library with Make in release mode. boolean false

nx-cmake:fmt

Format a C or C++ project with clang-format

Options Description Type Default
--verbose Whether to print verbose output when formatting a C or C++ project with clang-format. boolean true
--editFilesInPlace Whether to format files in place. boolean true

nx-cmake:lint

Lint a C or C++ project with clang-tidy

Options Description Type Default
--release Wheter to lint in release mode boolean false

nx-cmake:test

Test a C library using CMocka or C++ library using googletest

Options Description Type Default
--release Test a C library using CMocka or a C++ library using googletest. boolean false
--outputOnFailure Whether to print output on test failure. boolean true

nx-cmake:execute

Execute a C or C++ binary

Options Description Type Default
--release Execute a C or C++ binary in release mode. boolean false

nx-cmake:debug

Debug a C or C++ project using gdb

Options Description Type Default
--release Debug a C or C++ project using gdb in release mode. boolean false

Contributing

All contributions are welcome.

Acknowledgements

This project was inspired by monodon.

Social

X (formerly Twitter) Follow

Package Sidebar

Install

npm i nx-cmake

Weekly Downloads

64

Version

0.7.2

License

MIT

Unpacked Size

406 kB

Total Files

689

Last publish

Collaborators

  • clemenscodes