nx-cmaker

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-cmaker --pm pnpm

Using yarn:

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

Using yarn:

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

Installing in an existing workspace

pnpm add -D nx-cmaker

yarn add -D nx-cmaker

npm install -D nx-cmaker

After installing:

nx g nx-cmaker: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-cmaker: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-cmaker: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-cmaker: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-cmaker: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-cmaker: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-cmaker: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-cmaker: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-cmaker:lint

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

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

nx-cmaker: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-cmaker:execute

Execute a C or C++ binary

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

nx-cmaker: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