Common.h

This file provides OS-selection logic, includes and some general utilities.

License: GPL-3.0-or-later.

CBuild should be first header included in translation unit. On CBUILD_API_POSIX (default for modern Unixes) it defines _GNU_SOURCE.

Compiler defines

Valid compilers:

CBUILD_CC_CLANG - clang or its derivative.
CBUILD_CC_GCC - gcc or its derivative.

This selection can be overriden by manually defining valid compiler and CBUILD_CC_DEFINED.

Several compiler extensions are required from supported compiler:

Binary literals support (0b) either trough c standard (c23+) or as extension.
Attributes trough __attribute__((...)) syntax, some are supported trough [[...]] syntax if support is detected
- deprecated.
- format.
- noreturn.
- falltrough.
Unnamed structs/enums/unions.
typeof.
__VA_OPT__.
GNU statement expressions ({...}).
__auto_type.

Explicetely unsupported compilers:

TCC - no statement expression (at least).
MSVC - no extensions at all.

Debug

By default CBuild provides debug logging from most of its modules. All logging goes trough cbuild_log, so if your app does no need any messages in terminal you can disable CBuild’s logger (which will hide all messages). cbuild-cc-defines

OS defines

Valid OSes:

CBUILD_OS_LINUX - Any desktop Linux (excluding Android or ChromeOS for example).
CBUILD_OS_MACOS - MacOS.
CBUILD_OS_BSD - Any desktop BSD.
CBUILD_OS_UNIX - Generic Unix, should support at least POSIX.1-2001.
CBUILD_OS_WINDOWS - Windows.

Also, there are some auxiliary OS checks, valid values are:

CBUILD_OS_WINDOWS:
- CBUILD_OS_WINDOWS_CYGWIN- Windows under Cygwin.
CBUILD_OS_LINUX:
- CBUILD_OS_LINUX_GLIBC - Linux with glibc.
- CBUILD_OS_LINUX_UCLIBC - Linux with uclibc.
- CBUILD_OS_LINUX_MUSL - Linux with musl (fallback, because musl provides no way of detection). cbuild-os-defines

API defines

Valid APIs:

CBUILD_API_POSIX. POSIX.1-2001 (_POSIX_C_SOURCE == 200112L). Any detected extension can be used. Permorms detection for extensions on MacOS, BSD, Linux. Default for:
- CBUILD_OS_LINUX
- CBUILD_OS_MACOS
- CBUILD_OS_BSD
- CBUILD_OS_WINDOWS_CYGWIN
CBUILD_API_STRICT_POSIX POSIX.1-2001 (_POSIX_C_SOURCE == 200112L). Only three extension are used and one extension type is considered:
- MAP_ANON/MAP_ANONYMOUS. If none is available fallabck to shm_open is provided but needs dlopen and dlsym provided.
- sysconf(_SC_NPROCESSORS_ONLN). Literal 1 is used as fallback.
- ioctl and TIOCGWINSZ.
- Newer POSIX versions can be used if detected.
CBUILD_API_WINAPI WinAPI and possibly NT API. Not implemented for now. cbuild-api-defines

Platform selector

This selector include platform-specific headers and configures platforms’s libc. cbuild-platform-selector

cbuild_proc_t

typename cbuild_proc_t pid_t

Process handle

CBUILD_INVALID_PROC

#define CBUILD_INVALID_PROC

Invalid process handle

cbuild_fd_t

typename cbuild_fd_t int

File descriptor

CBUILD_INVALID_FD

#define CBUILD_INVALID_FD

Invalid file descriptor

cbuild_dir_t

typename cbuild_dir_t DIR*

Directory descriptor

CBUILD_INVALID_DIR

#define CBUILD_INVALID_DIR

Invalid directory descriptor

CBUILD_PTR_ERR

#define CBUILD_PTR_ERR

Additional error value for pointers (when error and not found are separate cases)

cbuild_dlib_t

typename cbuild_dlib_t void*

Handle for dynamic library

Normal platform-independent includes [lines:cbuild-includes]

cbuild-includes

Configuration values

All of this are defines that user can redefine.

There are few more configuration define not listed here:

CBUILD_PROFILER - Enable profiler features in modules.
CBUILD_LOG_CUSTOM_LEVELS - used to inject custom log levels in CBuild’s logger cbuild-configuration

CBUILD_INIT_CAPACITY

#define CBUILD_INIT_CAPACITY

Initial capacity of cbuild dynamic arrays. Size is in elements.

Type: size_t.

CBUILD_QUICK_SPRINTF_SIZE

#define CBUILD_QUICK_SPRINTF_SIZE

Size of stack buffer used to speedup sprintf for small strings.

Type: size_t.

CBUILD_FS_TMP_SIZE

#define CBUILD_FS_TMP_SIZE

Size of temporary buffer used for FS operations

Type: size_t.

CBUILD_TEMP_ARENA_SIZE

#define CBUILD_TEMP_ARENA_SIZE

Size of temporary allocator.

Type: size_t.

CBUILD_MAP_DEFAULT_HASH_FUNC

#define CBUILD_MAP_DEFAULT_HASH_FUNC

Default hash function for CBuild map. User can override it in runtime for specific map instance.

Type: size_t func(const void* key, size_t len).

CBUILD_SELFREBUILD_ARGS

#define CBUILD_SELFREBUILD_ARGS

Default arguments for cbuild_selfrebuild.

Type: Comma-separated list of const char*.

CBUILD_LOG_MIN_LEVEL

#define CBUILD_LOG_MIN_LEVEL

Minimal log level for cbuild_log.

Type: cbuild_log_level_t.

CBUILD_GLOB_CAPTURE_COUNT

#define CBUILD_GLOB_CAPTURE_COUNT

Number og “capture groups” glob supports. This is used for underlying regex engine.

CBUILDDEF

#define CBUILDDEF

This is prepended to all cbuild’s functions. Can be set to eg. static inline for build that use only one translation unit.

Type: function attributes.

Preprocessor configuration

This section provides several miscellaneous preprocessor macro.

Print hooks. These can not be overridden by user and should be edited here.
Macro helpers for ‘##’ and ‘#’ operators
Attribute abstractions to support both new C23 attributes and older gnu-style attributes.
Allocator hooks (__CBUILD_MALLOC, __CBUILD_REALLOC, __CBUILD_FREE) which can be overridden by defining CBUILD_CUSTOM_ALLOC cbuild-misc-preproc

CBUILD_UNUSED

#define CBUILD_UNUSED(val)

Mark some variable as unused.

name val Variable name.

CBUILD_TODO

#define CBUILD_TODO(message, ...)

Place TODO marker in code. Upon reaching it execution will abort with message.

const char* message Message that will be printed before aborting. printf-style.
...any[ …] Format string arguments.

CBUILD_UNREACHABLE

#define CBUILD_UNREACHABLE(message, ...)

Mark some code as unreachable. This will abort with message if executed.

const char* message Message that will be printed before aborting. printf-style.
...any[ …] Format string arguments.

cbuild_assert

#define cbuild_assert(expr, ...)

Assert that can pretty-print messages.

() => bool expr Any expression returns boolean.
format string … Printf-style format string and its arguments.

__cbuild_assert

CBUILD_ATTR_NORETURN(CBUILDDEF void __cbuild_assert(const char* file, unsigned int line,
const char* func, const char* expr, ...));

Pretty-printer for cbuild_assert.

const char* file File that should be reported.
unsigned int line Line that should be reported.
const char* func Function that should be reported.
const char* expr Expression that should be reported.
format string … Printf-style format string and its arguments.

cbuild_arr_len

#define cbuild_arr_len(array)

Get length of array whose size is know at compile-time

any* array Array, not just a pointer.

size_t Length of an array in elements.

cbuild_arr_get

#define cbuild_arr_get(array, index)

Get element from array with bound checking (array size should be know at compile-time) Abort execution if index is out of bounds.

any* array Array, not just a pointer.
size_t index

any Element from an array.

cbuild_shift

#define cbuild_shift(argv, argc)

Shift arguments from “standard” C array view - pointer and size as separate variables. Size will be decremented and pointer will be incremented.

any* argv Array.
size_t argc Length of an array.

any Shifted First element of an array.

cbuild_shift_expect

#define cbuild_shift_expect(argv, argc, ...)

Shift arguments from “standard” C array view - pointer and size as separate variables. Size will be decremented and pointer will be incremented. Allows for a used-defined message.

any* argv Array.
size_t argc Length of an array.
format string … Message that will be printed if array does not have enough elements.

any Shifted First element of an array.

cbuild_time_nanos

CBUILDDEF uint64_t cbuild_time_nanos(void);

Get time in nanoseconds.

uint64_t Nanoseconds from unspecified epoch.

CBUILD_NANOS_PER_SEC

#define CBUILD_NANOS_PER_SEC

Number of nanoseconds in one second

CBUILD_MAX

#define CBUILD_MAX(a, b)

Return bigger number from 2 numbers

CBUILD_MIN

#define CBUILD_MIN(a, b)

Return smaller number from 2 numbers

Internal API

These are internal function, so their API can break at any time. But they still can be considered mostly stable (eg. I does not break their API that often). Get name of program (argv[0]).

__cbuild_memrchr

CBUILDDEF void* __cbuild_memrchr(const void* s, int c, size_t n);

memrchr wrapper.

__cbuild_memmem

CBUILDDEF void* __cbuild_memmem(const void* haystack, size_t hsize,
const void* needle, size_t nsize);

memmem wrapper