The C Library Plugin provides the tasks, configurations and conventions for a building C library.

Usage

Example 1. Applying the C Library Plugin
build.gradle
plugins {
   id 'dev.nokee.c-library'
}
build.gradle.kts
plugins {
   id("dev.nokee.c-library")
}

Build variants

The C Library Plugin understands the following dimensions. Read the introduction to build variants for more information.

Operating system family - defaults to the build host

The operating system family expresses which environment the library targets. The supported operating system family are Windows, Linux, and macOS.

Machine architecture - defaults to the build host

The machine architecture expresses which architecture the library targets. The supported architecture are Intel instruction set for both 32 and 64 bit often referred as x86 and x86-64.

Both dimensions are configured together as part of the target machine. Nokee uses the target machine to decide which toolchain to choose based on availability on the host machine.

The target machine can be configured as follows:

Example 2. Configure application target machines
build.gradle
library {
    targetMachines = [
        machines.linux.x86_64,
        machines.windows.x86, machines.windows.x86_64,
        machines.macOS.x86_64
    ]
}
build.gradle.kts
library {
    targetMachines.set(listOf(machines.linux.x86_64,
        machines.windows.x86, machines.windows.x86_64,
        machines.macOS.x86_64))
}

Tasks

The following diagram shows the relationships between tasks added by this plugin.

c library task graph
Figure 1. C Library Plugin default task graph

Variant-dependent Tasks

The C Library Plugin creates tasks based on the variants of the library component. Read the introduction to build variants for more information. The following diagram shows the relationship between variant-dependent tasks.

c library variant task graph
Figure 2. C Library Plugin variant-dependent task graph
compileVariantC (e.g. compileWindowsC and compileLinuxC) - CCompile

Depends on: All tasks that contribute source files to the compilation

Compiles C source files using the selected compiler.

objectsVariant (e.g. objectsWindows and objectsLinux) - Task (lifecycle)

Depends on: compileVariantC

Aggregates tasks that compile the source files to object files for the specific variant of this library.

linkVariant (e.g. linkWindows and linkLinux) - LinkSharedLibrary (shared linkage)

Depends on: All tasks which contribute to the link libraries, including linkVariant and createVariant tasks from projects that are resolved via project dependencies

Links shared library from compiled object files using the selected linker.

sharedLibraryVariant (e.g. sharedLibraryWindows and sharedLibraryLinux) - Task (lifecycle)

Depends on: sharedLibraryVariant

Aggregates tasks that creates the shared library binary for the specific variant of this library.

createVariant (e.g. createDebug and createRelease) - CreateStaticLibrary (static linkage)

Creates static library from compiled object files using selected archiver.

staticLibraryVariant (e.g. staticLibraryWindows and staticLibraryLinux) - Task (lifecycle)

Depends on: createVariant

Aggregates tasks that creates the static library binary for the specific variant of this library.

assembleVariant (e.g. assembleWindows and assembleLinux) - Task (lifecycle)

Depends on: linkVariant (shared linkage) or createVariant (static linkage)

Aggregates tasks that assemble the specific variant of this library.

Lifecycle Tasks

The C Library Plugin attaches some of its tasks to the standard lifecycle tasks documented in the Base Plugin chapter - which the C Library Plugin applies automatically:

assemble - Task (lifecycle)

Depends on: link task for the current host, if present

Aggregate task that assembles the variant of the library for the current host (if present) in the project. This task is added by the Base Plugin.

check - Task (lifecycle)

Aggregate task that performs verification tasks, such as running the tests. Some plugins add their own verification task to check. This task is added by the Base Plugin.

build - Task (lifecycle)

Depends on: check, assemble

Aggregate tasks that perform a full build of the project. This task is added by the Base Plugin.

clean - Delete

Deletes the build directory and everything in it, i.e. the path specified by the Project.getBuildDir() project property. This task is added by the Base Plugin.

Dependency management

Just like the tasks created by the C Library Plugin, multiple configurations are created based on the variants of the library component. Read the introduction to build variants for more information. The following graph describes the configurations added by the C Library Plugin:

native library configurations
Figure 3. C Library Plugin configurations

  • The configurations in white are the ones a user should use to declare dependencies

  • The configurations in pink, also known as consumable denoted by (C), are the ones used when a component runs against the library

  • The configurations in blue, also known as resolvable denoted by (R), are internal to the component, for its own use

The following configurations are used to declare dependencies:

api

Used for declaring API dependencies (see API vs implementation section). This is where you should declare dependencies which are transitively exported to consumers, for compile, link, and runtime.

implementation extends api

Used for declaring implementation dependencies for all variants of the main component (see API vs implementation section). This is where you should declare dependencies which are purely internal and not meant to be exposed to consumers of any variants.

variantImplementation (e.g. windowsImplementation and linuxImplementation) extends implementation

Used for declaring implementation dependencies for a specific variant of the main component (see API vs implementation section). This is where you should declare dependencies which are purely internal and not meant to be exposed to consumers of this specific variant.

The following configurations are used by downstream consumers that depend on the library component:

variantCompileElements (e.g. windowsCompileElements and linuxCompileElements) extends variantImplementation

Used for compiling against the library. This configuration is meant to be used by consumers, to retrieve all the elements necessary to compile against the library.

variantLinkElements (e.g. windowsLinkElements and linuxLinkElements) extends variantImplementation

Used for linking against the library. This configuration is meant to be used by consumers, to retrieve all the elements necessary to link against the library.

variantRuntimeElements (e.g. windowsRuntimeElements and linuxRuntimeElements) extends variantImplementation

Used for executing the library. This configuration is meant to be used by consumers, to retrieve all the elements necessary to run the library.

The following configurations are used by the application itself:

variantHeaderSearchPaths (e.g. windowsHeaderSearchPaths and linuxHeaderSearchPaths) extends variantImplementation

Used for compiling the library. This configuration contains the compile include roots of the library and is therefore used when invoking the C compiler to compile it.

variantLinkLibraries (e.g. windowsLinkLibraries and linuxLinkLibraries) extends variantImplementation

Used for linking the library. This configuration contains the libraries of the library and is therefore used when invoking the C linker to link it.

variantRuntimeLibraries (e.g. windowsRuntimeLibraries and linuxRuntimeLibraries) extends variantImplementation

Used for executing the library. This configuration contains the runtime libraries of the library.

Conventions

The C Library Plugin adds conventions for sources and tasks, shown below.

Project layout

The C Library Plugin assumes the project layout shown below. None of these directories need to exist or have anything in them. The C Library Plugin will compile whatever it finds and ignore anything missing.

src/main/c

C source with extension of .c

src/main/headers

Headers - headers needed to compile the application

Compile Task

The C Library Plugin adds a CCompile instance for each variant of the library component to build (e.g. compileWindowsC and compileLinuxC). Read the introduction to build variants for more information. Some of the most common configuration options are shown below.

compilerArgs

[]
headerSearchPaths

configurations.variantHeaderSearchPaths + ${project.projectDir}/src/main/headers
toolChain

automatically selected based on target machine

The C++ Library Plugin adds a LinkSharedLibrary instance for each variant of the library containing shared linkage as a dimension - e.g. linkWindows and linkLinux. Read the introduction to build variants for more information. Some of the most common configuration options are shown below.

linkedFile

$buildDir/lib/main/variant/libBaseName[.so|dylib] (*nix) or $buildDir\lib\main\variant\baseName.dll (Windows)
linkerArgs

[]
toolChain

automatically selected based on target machine

Create Task

The C Library Plugin adds a CreateStaticLibrary instance for each variant of the library containing static linkage as a dimension - e.g. createWindows and createLinux. Read the introduction to build variants for more information. Some of the most common configuration options are shown below.

outputFile

$buildDir/lib/main/variant/libBaseName.a (*nix) or $buildDir\lib\main\variant\baseName.lib (Windows)
archiverArgs

[]
toolChain

automatically selected based on target machine