Delivered as StarLet-<ident>.tar.gz, unpacking into starlet-<ident>/.
A small, freestanding-friendly C library of OpenVMS-flavoured building blocks for systems and embedded work. Portable C11 (GCC/Clang); tested on x86-64 and ARMv8 (RK33xx/RK35xx), with a hardware CRC-32 path on ARMv8.
| Module | Prefix | What it provides |
|---|---|---|
utility_routines |
__util$ / $LOG |
Logging ($LOG, $LOG_FAO, $TRACE, $DUMPHEX), OpenVMS-style message catalogues ($PUTMSG_FAO), ASCIC counted strings, hex/UUID conversion, base64, CRC-32, command-line and config-file option parsing, spinlock-protected queues, wildcard matching (* a run, %/? one octet). |
avproto |
__tlv$ |
A compact binary Tag-Length-Value protocol: a fixed header plus TLV records, all in network byte order. |
cli_routines |
__cli$ |
A DCL-style command-line parser: verb [p1..p8] [/qualifier[=value]], with per-value type validation. |
starlet |
__util$ |
Portable analogues of OpenVMS system services: the FAO formatter (__util$faol, driving the $FAO/$PUTMSG_FAO/$LOG_FAO macros) with numeric, string, time and address directives (MAC, IPv4, RFC 5952 IPv6, UUID), and binary-time routines (__util$bintim/asctim/add_times/sub_times). |
Routines follow the OpenVMS condition-value convention: the low bit of the returned status is set on success.
cc -std=gnu11 -O2 -c utility_routines.c avproto.c cli_routines.c starlet.c
cc *.o -o your_app # link with your application- Define
__MODULE__(and optionally__FAC__) before including a header, so log records carry the right prefix. - Build with
-DNDEBUGto compile out$TRACE/asserts in release. - On ARMv8 the hardware CRC-32 of
__util$crc32c(IEEE 802.3 CRC-32) is chosen at run time; no-marchflag is needed.
A CMakeLists.txt is also provided. It builds the static-library target starlet
(all four modules) and exports its include directory, so consumers get the headers
automatically when they link it. The executable target needs a main() of your own.
As a git submodule. Vendor the sources under your tree and add the subdirectory:
git submodule add https://<host>/utility_routines.git external/utility_routinesadd_subdirectory(external/utility_routines)
add_executable(my_app main.c)
target_link_libraries(my_app PRIVATE starlet) # headers come with the targetWithout a submodule (CMake 3.11+, FetchContent). Let CMake fetch it at configure time:
include(FetchContent)
FetchContent_Declare(utility_routines
GIT_REPOSITORY https://<host>/utility_routines.git
GIT_TAG main) # or a release tag / commit
FetchContent_MakeAvailable(utility_routines)
add_executable(my_app main.c)
target_link_libraries(my_app PRIVATE starlet)Then in your code:
#define __MODULE__ "MYAPP$"
#include "utility_routines.h" /* and avproto.h / cli_routines.h / starlet.h as needed */The ARMv8 hardware CRC engine is selected at run time (target attributes), so no -march option is needed.
Regression tests under tests/ (all exit non-zero on failure, so they drop
straight into a build pipeline):
test_status_convention— locks in the OpenVMS condition-value convention (1 & status— odd is success, even is failure):__util$bintim,__util$asctim, theCLI$K_TIME/CLI$K_MACvalue types and the severity of theSTS$K_*/FAO$K_*codes.test_cli_features— qualifier defaults, negatable qualifiers (including "last wins" for a repeated/X//NOX), value lists,__cli$presentand required qualifiers.test_tlv— a full__tlv$PDU round-trip (header, word/longword/qword byte-order conversion, octet blocks, lookup and a missing tag).test_cli_help— the built-in/HELP,-h,--helpdetection, and that a barehelptoken stays an ordinary verb or parameter value.test_log_overflow— the logging routines truncate oversized records in bounds and never write past their buffers.test_setlogfd—__util$setlogfd()points the log at a given descriptor without opening a file or seizing the standard streams.test_putmsg_fao— the$PUTMSG_FAOcatalogue path: FAO-formatted records, severity-independent lookup, and the facility name stamped into each record.test_cli_nested/test_cli_filepath—SHOW STATISTICS-style sub-verbs;/-paths staying parameter values while/qualifierskeep parsing.test_fao_addr— the!%M/!%I/!%6/!%Uaddress directives, RFC 5952 corner cases, byte parity withinet_ntop.test_log_prefix— the cached log-record prefix stays byte-identical to the historical rendering; the tid column matches the kernel's.test_pattern_match— fixed vectors, a 500k-case fuzz against the former recursive matcher, the?alias, and the pathological multi-star pattern returning at once.test_log_fao— the$LOG_FAOenvelope, FAO body, address directives and the zero-parameter form.test_base64—__util$base64/__util$unbase64: the RFC 4648 vectors, a random round-trip over every length, unpadded input, the courtesy NUL, and the rejections (a foreign octet, a misplaced=, a dangling sextet, a short buffer with the needed length still reported).test_crc32—__util$crc32c(the IEEE CRC-32) against a bitwise reference: the check values, every length up to 2048 at every alignment, a run continued at every split point, a 4 MB buffer. CTest runs it twice: with the fastest engine of the processor (PCLMULQDQ on x86-64, the CRC32 instructions on ARMv8) and underSTARLET_CRC32=SOFTWARE(the tables).
A GitHub Actions workflow (.github/workflows/ci.yml) runs them on every push and
pull request (and by hand), on x86-64 and aarch64 (ubuntu-24.04, ubuntu-24.04-arm):
via CTest and standalone under ASan/UBSan with glibc, then again with musl-gcc
(CTest plus the standalone suite statically linked against musl, -Werror throughout).
With CMake (no build type named means Release; -DCMAKE_BUILD_TYPE=Debug for
the build with the library's own tracing):
cmake -B build && cmake --build build && ctest --test-dir buildOr standalone, without CMake:
sh tests/run.sh # honours CC and CFLAGSBuild and install once:
cmake -B build
cmake --build build
cmake --install build --prefix /usr/local # or any prefixThen consume it from another project with no add_subdirectory() /
FetchContent() - the package name is StarLet, the target is
StarLet::starlet (the static library of all four modules):
find_package(StarLet REQUIRED)
add_executable(app main.c)
target_link_libraries(app PRIVATE StarLet::starlet)The install ships the four public headers, libstarlet.a, and the
StarLetConfig.cmake / StarLetConfigVersion.cmake / StarLetTargets.cmake
files under <prefix>/lib/cmake/StarLet. Version requests are honoured with
same-major-version compatibility, e.g. find_package(StarLet 1.7 REQUIRED).
Binary or source packages can be produced with cpack from the build dir.
The manuals are in doc/, in English and Russian, as markdown and PDF, laid out like
the OpenVMS manuals:
- STARLET Programmer's Guide (STARLET-PG-0171) -
doc/starlet_programmers_guide.pdf,doc/starlet_programmers_guide_ru.pdf: the ideas, the heritage, how to use each part; Appendix D lists what changed in 1.7.0 and 1.7.1. - STARLET Reference Manual (STARLET-RM-0171) -
doc/starlet_reference_manual.pdf,doc/starlet_reference_manual_ru.pdf: every routine and macro (Format / Returns / Arguments / Description / Condition Values Returned / Example), the FAO directives, the condition values, an index.
They replace Routines_Reference_EN.pdf / Routines_Reference_RU.pdf of 1.6.x.
A tag that is v + the project() VERSION of CMakeLists.txt, exactly
(v1.7.2 for project(StarLet VERSION 1.7.2)), makes a GitHub Release by
.github/workflows/release.yml: the library is built and its tests are run
(CTest, -Werror) on x86-64 and aarch64, with glibc and with musl-gcc,
and the sources tarball StarLet-<version>.tar.gz (unpacking into
starlet-<version>/), the Debian packages libstarlet-dev_<version>_amd64.deb
and _arm64.deb (built on Debian 12, checked on Debian 12, 13 and Ubuntu 24.04:
the library, the headers, the CMake package and the manuals under /usr) and
SHA256SUMS are attached. The packages come with 1.7.3 and later. A tag that is not the
version of its tree is refused.
Every push and every pull request is built and tested by
.github/workflows/ci.yml, the badge at the top.
A release carries SHA256SUMS.minisig, a
minisign signature of SHA256SUMS.
The public key is in minisign.pub here (the same key signs the kits of
AlphaEmu, BATCH, HELP and BroTwins):
RWQl4NAqFsHKkNoHkS52WSZSk+2kb+e58DWYpoi/jVFa6TqOTAm3Ph14
Put the files you took next to SHA256SUMS and SHA256SUMS.minisig, then:
minisign -Vm SHA256SUMS -P RWQl4NAqFsHKkNoHkS52WSZSk+2kb+e58DWYpoi/jVFa6TqOTAm3Ph14
sha256sum -c --ignore-missing SHA256SUMS
The first must say Signature and comment signature verified, the second
OK for every file. Anything else - the file is not the one released: do
not use it.
Whitesmiths indentation, tabs, $-in-identifier VMS naming (a GCC extension),
s_ prefix for static routines, VMS-style file/history headers. The tree builds
clean under -Wall -Wextra -std=gnu11.
Apache License 2.0 — see LICENSE.
StarLet Squad and Ruslan R. Laishev (AKA: BadAss SysMan)