diff --git a/CHANGELOG.md b/CHANGELOG.md index 102b2aa6a65bef6ac2ec2c4c029469d1742ed612..fe99ea7e8d769276dc9c7f76ac9f6e571e50d0a4 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 52d741980b1315741808dd26b36282da59bfc13e..8fdfaa38c94fafa85a222225fc1dee96ce17a67a 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 ded9d4f15734d1cc84a9fd376178ed7a7704ed94..aabbd76c011d32d0667660239aa6fed887135ebb 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 8bb021ea607450f85bfbe1d8cb5f2f9e9733ec89..d2914d03c633fd5f5fd2a3ff4bbe9de9cd1b7ad5 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 ac36caeeb6688810c2385363eb51773722261ba4..8f9c7a8b6998a8fcd6c7546aa327a55ed8a856d6 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 7134ec881190da9bb76de45c9bbfe4f0808f8467..67f6a404b2e6df7619868495a7f025c6078376bc 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 982c527289359b57e6f781313c423fa5bd965f6f..1387ce265683b9f9d7d1c71767edb5499d13d3cf 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 fe28c650278b6c6dbf42aa02809ba90f6b47a0d9..f6e94e16606cb5e6d838173ef1cab76b6c536ea8 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 ca60d7941acd8a4f83dc4237cfd38c2b051cd2a6..17a15fcf3c2ef036781ddbab55c9cada86ea35da 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 0000000000000000000000000000000000000000..aaae5c9745974cc22eaf8a50f242e8df7bf084ec --- /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 449be8026208d1897624f66dbf8bb4ad57adba68..76b781e7567a0ad6647d4f8736230938ebbca282 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 c3f3c8eba51274e025d0c804c5dac213d650818b..dfeb8e2d49c2d3f0f9750ecdd450246bce41d378 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 73ab44d944490efa266fdaed820b323eb4272fb8..bb68b29ec0dcd2d285a713f1aa8f35a7b2a067c6 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 0000000000000000000000000000000000000000..f81513e0ebd50403195f69008839489f696b0865 --- /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 0000000000000000000000000000000000000000..462a9ddcf598bb8699f9c395b4a9726718345b5e --- /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 c144df3172fcf742924c96d416861a571276103d..a816d9f00b7730d67096ca7a2b739b6696bd896a 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 2daccd269207cf2b2efe6d809eb7b6577a35638d..700832f564608e6ad8bb398810bc03440da78166 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