libuuid-cmake

A CMake build for the libuuid library from util-linux

Libuuid is a portable, BSD-licensed library that is part of the util-linux bundle. The whole bundle comes with autoconf and meson build scripts, which, while not terribly complicated to use, aren't very friendly to CMake projects. The libuuid library is also available through Linux package managers, Conan, and possibly other sources, but these, again, introduce friction into a simple CMake workflow.

This project allows you to use libuuid directly from CMake with no extra steps or complications.

Requirements

• CMake 3.21 or newer
• Internet connection when configuring CMake. Note that this project automatically fetches libuuid sources from GitHub.

Versioning

The tags in this repository have the following form:

util-linux-tag[.revN]

Where util-linux-tag is the release tag in util-linux such as v2.39, v2.39.1, etc.

The optional revision field is used when there are changes/bug fixes, etc. in this repository. The numeric value N is incremented by 1 every time a new revision is released. Thus, v2.39.rev1 is a newer revision than v2.39, and both include libuuid version v2.39.

Usage

Dependency with FetchContent

include(FetchContent)
...
FetchContent_Declare(libuuid
    GIT_REPOSITORY  https://github.com/gershnik/libuuid-cmake.git
    GIT_TAG         v2.39.1
    GIT_SHALLOW     TRUE
)
...
FetchContent_MakeAvailable(libuuid)
...
target_link_libraries(mytarget
PRIVATE
  uuid::uuid
)

ℹ️ What is FetchContent?

Dependency in a subdirectory

1. Download or clone this repository into SOME_PATH
2. Add it as a subdirectory

add_subdirectory(SOME_PATH)
...
target_link_libraries(mytarget
PRIVATE
  uuid::uuid
)

Regardless of which method you use, the uuid.h header will be available via

#include <uuid/uuid.h>

Building and installing on your system

You can also build and install libuuid on your system using CMake (this is only useful on non-Linux platforms, since on Linux you might as well just use the original util-linux build). Note that man pages will only be generated if you have Asciidoctor available.

1. Download or clone this repository into SOME_PATH
2. Do something like this on the command line

cd SOME_PATH
cmake -S . -B build 
cmake --build build

#Optional
#ctest --test-dir build --output-on-failure

sudo cmake --install build
#or for custom prefix
cmake --install build --prefix some-dir

The installation above sets things up so that you can do find_package(uuid) from CMake as well as use pkg-config --libs --cflags uuid if you have pkg-config available.

Note that by default, cmake installs under /usr/local, which might not be in the list of places your pkg-config looks into. If so, you might need to do:

export PKG_CONFIG_PATH=/usr/local/share/pkgconfig

Settings and targets

Choosing static or shared libraries

There are 3 variables that affect the type of library built:

• LIBUUID_SHARED - if set, enables shared library target even if it otherwise wouldn't be enabled
• LIBUUID_STATIC - if set, enables static library target even if it otherwise wouldn't be enabled
• BUILD_SHARED_LIBS - see below

If you don't explicitly set either LIBUUID_SHARED or LIBUUID_STATIC, the behavior is as follows:

• If the libuuid project is not a top-level project, then the enabled variant depends on BUILD_SHARED_LIBS. If BUILD_SHARED_LIBS is ON, then the shared library target will be enabled. Otherwise, the static one.
• If the libuuid project is a top-level project, then both variants are enabled.

You can set() LIBUUID_SHARED, LIBUUID_STATIC and BUILD_SHARED_LIBS in your CMake script prior to adding libuuid or specify them on the CMake command line.

The exposed targets can be:

• uuid::uuid_static - the static library
• uuid::uuid_shared - the shared library
• uuid::uuid - the "default" one. If only one of the static/shared variants is enabled, this one points to it. If both variants are enabled, then this alias points to uuid::uuid_shared if BUILD_SHARED_LIBS is ON or uuid::uuid_static otherwise.

libuuid configuration

Two additional CMake settings expose functionality originally available via configure flags of the util-linux autoconf build. These are:

• LIBUUID_RUNSTATEDIR for --runstatedir. Default is /run
• LIBUUID_LOCALSTATEDIR for --localstatedir. Default is /var

The precise effects of each original flag on libuuid are poorly documented. From source code examination, localstatedir can be used as a root directory for storage of local clock state, and runstatedir as a root location for Unix domain sockets to communicate with the uuidd daemon.