From bbc71110d689284a5696e9b3c9338652391786f2 Mon Sep 17 00:00:00 2001 From: Paolo Tricerri Date: Mon, 14 Jul 2025 13:22:14 +0000 Subject: [PATCH 1/2] OpenRNG 25.07 See CHANGELOG.md for a detailed list of new available features, bug fixes, and performance improvements. The IMPLEMENTATION_STATUS.md file has been updated to reflect the current list of implemented and non-implemented functions. Documentation on how to build and install OpenRNG is available in README.md --- .gitlab-ci.yml | 2 +- CHANGELOG.md | 6 +++++ CMakeLists.txt | 15 +++++++++++- README.md | 26 +++++++++++++++++++++ bench/CMakeLists.txt | 2 +- docs/CMakeLists.txt | 2 +- docs/Doxyfile.in | 10 ++++---- docs/rng-introduction.md | 8 +++++++ include/openrng.h | 15 ++++++++++++ src/refng/include/refng_vsl.h | 2 +- src/utils/version.hpp | 14 +++++++++++ src/vsl.cmake | 14 ++++++++++- src/vsl/c_api.cpp | 5 ++++ test/CMakeLists.txt | 21 +++++++++++++---- test/services/get_library_version.cpp | 22 +++++++++++++++++ tools/check_library_version/check_library.c | 25 ++++++++++++++++++++ tools/create_api/create_api_from_header.py | 26 ++++++++++----------- tools/create_api/openrng.h.json | 18 ++++++++++++++ 18 files changed, 205 insertions(+), 28 deletions(-) create mode 100644 src/utils/version.hpp create mode 100644 test/services/get_library_version.cpp create mode 100644 tools/check_library_version/check_library.c diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index bdb83f5..3bb9f20 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -1,7 +1,7 @@ default: image: ubuntu:22.04 tags: - - arm64-shared + - arm64 before_script: - apt update --yes - DEBIAN_FRONTEND=noninteractive apt install --yes cmake g++ git gcovr diff --git a/CHANGELOG.md b/CHANGELOG.md index 102b2aa..fe99ea7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,12 @@ All notable changes to this project will be documented in this file. ### Security +## 25.07 + +### Added + - New function returning the library version + + ## 25.04 ### Added diff --git a/CMakeLists.txt b/CMakeLists.txt index 52d7419..8fdfaa3 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,5 +1,16 @@ cmake_minimum_required(VERSION 3.15) -project(rng VERSION 25.04 LANGUAGES C CXX) + +# Defining the library version +set(OPENRNG_MAJOR "25") +set(OPENRNG_MINOR "07") +set(OPENRNG_PATCH "-1") + +set(OPENRNG_VERSION "${OPENRNG_MAJOR}.${OPENRNG_MINOR}") +if(NOT OPENRNG_PATCH STREQUAL "-1") + set(OPENRNG_VERSION "${OPENRNG_VERSION}.${OPENRNG_PATCH}") +endif() + +project(rng VERSION ${OPENRNG_VERSION} LANGUAGES C CXX) include(CTest) # Set build type to Release if not specified. @@ -60,6 +71,8 @@ endif() # Disable GLIBCXX assertions to avoid libstdc++ dependency add_compile_definitions(_GLIBCXX_NO_ASSERTIONS) +find_package(Python3 REQUIRED COMPONENTS Interpreter) + if (WIN32) # Disable _CRT_SECURE and _CRT_NONSTDC for portability. We want to continue # using fopen, getpid, etc. on WIN32. diff --git a/README.md b/README.md index ded9d4f..aabbd76 100644 --- a/README.md +++ b/README.md @@ -59,6 +59,32 @@ make install The install path is configured with `CMAKE_INSTALL_PREFIX`. The default value of `CMAKE_INSTALL_PREFIX` is system dependent. +By default, OpenRNG builds with lp64 interface. To build with ilp64 interface, add +the `-DOPENRNG_INTERFACE=ilp64` to the cmake command. + +By default, OpenRNG builds a static library. To build a shared library, add the +`-DBUILD_SHARED_LIBS=On` to the cmake command. + +### Download, build and install OpenRNG on Windows + +This section describes the steps and the environment required to build and install +OpenRNG on Windows. Before building the library, the following tools have to be +installed: + + - Python, version 3 required. + - LLVM + - CMake, version 3.15 required. + - Ninja + +The current build process on Windows was tested with LLVM-20 and Ninja 1.12.1. +Once installed and the OpenRNG repo is cloned, run from the source folder, + +``` +cmake -B build -S . -G "Ninja" -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ +cmake --build build --target install +``` + +to build and install the library. ## Documentation diff --git a/bench/CMakeLists.txt b/bench/CMakeLists.txt index 8bb021e..d2914d0 100644 --- a/bench/CMakeLists.txt +++ b/bench/CMakeLists.txt @@ -15,7 +15,7 @@ set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${DIST_JSON} ${GE # Invoke benchmark generation script at configure-time file(MAKE_DIRECTORY ${GENERATE_DIR}) execute_process( - COMMAND python3 ${GENERATE_SCRIPT} ${GENERATE_DIR} + COMMAND ${Python3_EXECUTABLE} ${GENERATE_SCRIPT} ${GENERATE_DIR} INPUT_FILE ${DIST_JSON} RESULT_VARIABLE generate_status ERROR_VARIABLE generate_error diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index ac36cae..8f9c7a8 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -3,7 +3,7 @@ find_package(Doxygen REQUIRED) # Doxygen requires latex for parsing math environments. find_package(LATEX REQUIRED) -configure_file(Doxyfile.in Doxyfile @ONLY) +configure_file(${CMAKE_SOURCE_DIR}/docs/Doxyfile.in Doxyfile @ONLY) add_custom_target(html COMMAND ${DOXYGEN_EXECUTABLE} diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index 7134ec8..67f6a40 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -228,10 +228,10 @@ TAB_SIZE = 4 # "Side Effects:". You can put \n's in the value part of an alias to insert # newlines. -ALIASES = armplref="|pl| |release|" \ - feedback=":ref:\`feedback\`" \ - int64libs=":ref:\`int64libs\`" \ - accesspl=":ref:\`access-pl\`" +ALIASES = armplref="OpenRng" \ + feedback="" \ + int64libs="the README.md file" \ + accesspl="the README.md file" # This tag can be used to specify a number of word-keyword mappings (TCL only). # A mapping has the form "name=value". For example adding "class=itcl::class" @@ -641,7 +641,7 @@ GENERATE_DEPRECATEDLIST= YES # sections, marked by \if ... \endif and \cond # ... \endcond blocks. -ENABLED_SECTIONS = +ENABLED_SECTIONS = OPENRNG_STANDALONE # The MAX_INITIALIZER_LINES tag determines the maximum number of lines that the # initial value of a variable or macro / define can have for it to appear in the diff --git a/docs/rng-introduction.md b/docs/rng-introduction.md index 982c527..1387ce2 100644 --- a/docs/rng-introduction.md +++ b/docs/rng-introduction.md @@ -16,6 +16,14 @@ or floating point values might give different answers between Arm and x86 systems because the accuracy of various operations is different between the two libraries. +\if OPENRNG_STANDALONE + +In this page, the hyperlinks to the different sections of the documentation and +those to the VSL functions will not work unless the documentation is built using +doxygen as described in the README file. + +\endif + This release does not include all of the random number functions from VSL. The documentation lists both the implemented and missing functionalities in the tables in the next sections. We will improve coverage of the missing functions diff --git a/include/openrng.h b/include/openrng.h index fe28c65..f6e94e1 100644 --- a/include/openrng.h +++ b/include/openrng.h @@ -3607,6 +3607,21 @@ int vslsNewAbstractStream(VSLStreamStatePtr *stream, const openrng_int_t n, const float sbuf[], const float a, const float b, const sUpdateFuncPtr scallback); +/** + * \ingroup groupService + * + * This function returns the current major, minor, and patch version of OpenRNG. + * For instance, for OpenRNG 25.04.1, the major version is 25, the minor version + * is 4 and, the patch version is 1. If any of three element is not set, for + * instance for release 24.10, then the missing element, that is the patch + * version would be set to -1 as default. + * + * \param[out] major The 32-bit integer representing the current major version. + * \param[out] minor The 32-bit integer representing the current minor version. + * \param[out] patch The 32-bit integer representing the current patch version. + */ +void openRngGetVersion(int32_t *major, int32_t *minor, int32_t *patch); + #ifdef __cplusplus } #endif diff --git a/src/refng/include/refng_vsl.h b/src/refng/include/refng_vsl.h index ca60d79..17a15fc 100644 --- a/src/refng/include/refng_vsl.h +++ b/src/refng/include/refng_vsl.h @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its + * SPDX-FileCopyrightText: Copyright 2024-2025 Arm Limited and/or its * affiliates * * SPDX-License-Identifier: MIT OR Apache-2.0 WITH LLVM-exception diff --git a/src/utils/version.hpp b/src/utils/version.hpp new file mode 100644 index 0000000..aaae5c9 --- /dev/null +++ b/src/utils/version.hpp @@ -0,0 +1,14 @@ +/* + * SPDX-FileCopyrightText: Copyright 2024-2025 Arm Limited and/or its + * affiliates + * + * SPDX-License-Identifier: MIT OR Apache-2.0 WITH LLVM-exception + */ + +#pragma once + +inline void getLibraryVersion(int32_t *major, int32_t *minor, int32_t *patch) { + *major = OPENRNG_MAJOR; + *minor = OPENRNG_MINOR; + *patch = OPENRNG_PATCH; +} diff --git a/src/vsl.cmake b/src/vsl.cmake index 449be80..76b781e 100644 --- a/src/vsl.cmake +++ b/src/vsl.cmake @@ -3,6 +3,11 @@ if(OPENRNG_LIB_SUFFIX) set_target_properties(openrng PROPERTIES OUTPUT_NAME "openrng_${OPENRNG_LIB_SUFFIX}") endif() +# Passing the library version to the target +target_compile_definitions(openrng PUBLIC OPENRNG_MAJOR=${OPENRNG_MAJOR}) +target_compile_definitions(openrng PUBLIC OPENRNG_MINOR=${OPENRNG_MINOR}) +target_compile_definitions(openrng PUBLIC OPENRNG_PATCH=${OPENRNG_PATCH}) + # # Set VERSION and SOVERSION. This can help system administrators with upgrading # or downgrading OpenRNG. @@ -30,7 +35,7 @@ endif() # SOVERSION: If the ABI has changed since the previous release, this number # needs to be bumped. # -set_target_properties(openrng PROPERTIES VERSION 25.04 SOVERSION 2) +set_target_properties(openrng PROPERTIES VERSION ${OPENRNG_VERSION} SOVERSION 2) # CMAKE_SYSTEM_PROCESSOR is the target processor, if not set, it will default to # the host platform. If you want to change CMAKE_SYSTEM_PROCESSOR, you will also @@ -105,6 +110,13 @@ set(CMAKE_CXX_IMPLICIT_LINK_LIBRARIES "") set(CMAKE_CXX_IMPLICIT_LINK_DIRECTORIES "") set_target_properties(test_linking_with_c_compiler PROPERTIES LINKER_LANGUAGE C) +# Test library version +add_executable(library_version ${OPENRNG_ROOT}/tools/check_library_version/check_library.c) +target_link_libraries(library_version openrng) +set(CMAKE_CXX_IMPLICIT_LINK_LIBRARIES "") +set(CMAKE_CXX_IMPLICIT_LINK_DIRECTORIES "") +set_target_properties(library_version PROPERTIES LINKER_LANGUAGE C) + # Enable optimization records and inspect assembly (only in later versions of GCC/clang). # Outputs reports to the same directory as the obj files. if(OPENRNG_ENABLE_OPT_RECORDS) diff --git a/src/vsl/c_api.cpp b/src/vsl/c_api.cpp index c3f3c8e..dfeb8e2 100644 --- a/src/vsl/c_api.cpp +++ b/src/vsl/c_api.cpp @@ -23,6 +23,7 @@ #include #include #include +#include #include #include @@ -794,4 +795,8 @@ int vslsNewAbstractStream(VSLStreamStatePtr *, const openrng_int_t, const sUpdateFuncPtr) { return VSL_ERROR_FEATURE_NOT_IMPLEMENTED; } + +void openRngGetVersion(int32_t *major, int32_t *minor, int32_t *patch) { + return getLibraryVersion(major, minor, patch); +} } diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt index 73ab44d..bb68b29 100644 --- a/test/CMakeLists.txt +++ b/test/CMakeLists.txt @@ -40,7 +40,7 @@ else() set(CMAKE_CXX_CLANG_TIDY ${MY_ORIGINAL_CLANG_TIDY_CMD}) endif(OPENRNG_LOCAL_CATCH) -add_executable(tests +set(TEST_SOURCES distributions/bernoulli.cpp distributions/binomial.cpp distributions/cauchy.cpp @@ -73,6 +73,17 @@ add_executable(tests services/uniform_bit64.cpp services/save_load_state.cpp ) + +if(NOT OPENRNG_TEST_TARGET) + list(APPEND TEST_SOURCES + services/get_library_version.cpp + ) +endif() + +add_executable(tests + ${TEST_SOURCES} +) + target_link_libraries(tests PRIVATE refng vsl @@ -85,13 +96,15 @@ target_compile_options(tests PUBLIC -Wno-psabi # Disable warnings about std::pair ABI changing. ) +target_compile_definitions(tests PRIVATE $) + # Create the supports_autogen.h header at configure time. set(CREATE_SUPPORT_DEFINES_DIR ${OPENRNG_ROOT}/tools/create_support_defines) set(CREATE_SUPPORT_DEFINES_SCRIPT ${CREATE_SUPPORT_DEFINES_DIR}/create_support_defines.py) set(INPUT_JSON ${CREATE_SUPPORT_DEFINES_DIR}/generators.json) set(OUTPUT_HEADER ${CMAKE_CURRENT_BINARY_DIR}/supports_autogen.h) execute_process( - COMMAND python3 ${CREATE_SUPPORT_DEFINES_SCRIPT} + COMMAND ${Python3_EXECUTABLE} ${CREATE_SUPPORT_DEFINES_SCRIPT} INPUT_FILE ${INPUT_JSON} OUTPUT_FILE ${OUTPUT_HEADER} RESULT_VARIABLE CREATE_SUPPORT_DEFINES_STATUS @@ -119,14 +132,14 @@ catch_discover_tests( ) add_test(NAME check-json-interface - COMMAND python3 ${OPENRNG_ROOT}/tools/create_api/create_api_from_header.py ${OPENRNG_ROOT}/include/openrng.h + COMMAND ${Python3_EXECUTABLE} ${OPENRNG_ROOT}/tools/create_api/create_api_from_header.py ${OPENRNG_ROOT}/include/openrng.h WORKING_DIRECTORY ${OPENRNG_ROOT}/tools/create_api ) # check-copyright-headers relies on being in a git repository if (GIT_HASH) add_test(NAME check-copyright-headers - COMMAND python3 ${OPENRNG_ROOT}/tools/copyright_header/copyright_header.py + COMMAND ${Python3_EXECUTABLE} ${OPENRNG_ROOT}/tools/copyright_header/copyright_header.py WORKING_DIRECTORY ${OPENRNG_ROOT} ) endif() diff --git a/test/services/get_library_version.cpp b/test/services/get_library_version.cpp new file mode 100644 index 0000000..f81513e --- /dev/null +++ b/test/services/get_library_version.cpp @@ -0,0 +1,22 @@ +/* + * SPDX-FileCopyrightText: Copyright 2025 Arm Limited and/or its + * affiliates + * + * SPDX-License-Identifier: MIT OR Apache-2.0 WITH LLVM-exception + */ + +#include +#include +#include +#include + +TEST_CASE("Check library version", "[openrng_only]") { + int o_major; + int o_minor; + int o_patch; + openRngGetVersion(&o_major, &o_minor, &o_patch); + + REQUIRE(o_major == OPENRNG_MAJOR); + REQUIRE(o_minor == OPENRNG_MINOR); + REQUIRE(o_patch == OPENRNG_PATCH); +} \ No newline at end of file diff --git a/tools/check_library_version/check_library.c b/tools/check_library_version/check_library.c new file mode 100644 index 0000000..462a9dd --- /dev/null +++ b/tools/check_library_version/check_library.c @@ -0,0 +1,25 @@ +/* + * SPDX-FileCopyrightText: Copyright 2025 Arm Limited and/or its + * affiliates + * + * SPDX-License-Identifier: MIT OR Apache-2.0 WITH LLVM-exception + */ + +#include +#include "openrng.h" + +int main() { + int major; + int minor; + int patch; + + openRngGetVersion(&major, &minor, &patch); + + // Format the output string as YY.MM + printf("%d.%02d", major, minor); + if( patch != -1 ){ + printf(".%d", patch); + } + + return 0; +} \ No newline at end of file diff --git a/tools/create_api/create_api_from_header.py b/tools/create_api/create_api_from_header.py index c144df3..a816d9f 100755 --- a/tools/create_api/create_api_from_header.py +++ b/tools/create_api/create_api_from_header.py @@ -33,13 +33,13 @@ def separate_arguments(arguments_str: str) -> list: def create_api_from_header(include_file: Path) -> list: - # We know the function declaration in OpenRNG returns an int and - # they are all of the form `int *`. Therefore this script does not - # support functions that return anything apart from int. - re_fct = '^int\s+([a-zA-Z0-9]+)\(([a-zA-Z\*\[\],\s]+)\);\n$' + # The interface functions are mostly of the form int * but there + # one exception due to the function getting the library version. + # Therefore the return argument of the regex is either void or int. + re_fct = '^(void|int)\s+([a-zA-Z0-9]+)\(([0-9_a-zA-Z\*\[\],\s]+)\);\n$' re_fct = re.compile(re_fct) - re_multiline_fct = '^int\s+([a-zA-Z0-9]+)\(([a-zA-Z0-9*_\[\],\s]+),\n$' + re_multiline_fct = '^(void|int)\s+([a-zA-Z0-9]+)\(([a-zA-Z0-9*_\[\],\s]+),\n$' re_multiline_fct = re.compile(re_multiline_fct) otherlines_fct = '\s+([a-zA-Z0-9*_\[\],\s]+)(,|\);)\n' @@ -57,22 +57,22 @@ def create_api_from_header(include_file: Path) -> list: more_than_one_line = re_multiline_fct.match(lines[l_c]) if one_line_fct: details = {} - details['returnType' ] = 'int' - details['name'] = one_line_fct.group(1) + details['returnType' ] = one_line_fct.group(1) + details['name'] = one_line_fct.group(2) arguments = [] - if one_line_fct.group(2) != "void": - arguments = separate_arguments(one_line_fct.group(2)) + if one_line_fct.group(3) != "void": + arguments = separate_arguments(one_line_fct.group(3)) details['parameters'] = arguments functions.append(details) if more_than_one_line: details = {} - details['returnType' ] = 'int' - details['name'] = more_than_one_line.group(1) + details['returnType' ] = more_than_one_line.group(1) + details['name'] = more_than_one_line.group(2) - assert more_than_one_line.group(2) != "void", f"{more_than_one_line.group(2)}" - arguments = separate_arguments(more_than_one_line.group(2)) + assert more_than_one_line.group(3) != "void", f"{more_than_one_line.group(3)}" + arguments = separate_arguments(more_than_one_line.group(3)) next_line = l_c + 1 done_at_least_once = False diff --git a/tools/create_api/openrng.h.json b/tools/create_api/openrng.h.json index 2daccd2..700832f 100644 --- a/tools/create_api/openrng.h.json +++ b/tools/create_api/openrng.h.json @@ -1507,5 +1507,23 @@ "type": "const sUpdateFuncPtr" } ] + }, + { + "returnType": "void", + "name": "openRngGetVersion", + "parameters": [ + { + "name": "major", + "type": "int32_t*" + }, + { + "name": "minor", + "type": "int32_t*" + }, + { + "name": "patch", + "type": "int32_t*" + } + ] } ] \ No newline at end of file -- GitLab From 3c3c6762cb5d59e377220106aea94c28cea1d84f Mon Sep 17 00:00:00 2001 From: Paolo Tricerri Date: Tue, 15 Jul 2025 08:14:47 +0000 Subject: [PATCH 2/2] Change CI Runner The new runner arm64 seems is not picked up by the pipeline. As many runners seem to have the tag arm64-shared, we change to that to see if the runners pick up the job. --- .gitlab-ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 3bb9f20..bdb83f5 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -1,7 +1,7 @@ default: image: ubuntu:22.04 tags: - - arm64 + - arm64-shared before_script: - apt update --yes - DEBIAN_FRONTEND=noninteractive apt install --yes cmake g++ git gcovr -- GitLab