diff --git a/CONFIGURE.md b/CONFIGURE.md index 593649379..b69391035 100644 --- a/CONFIGURE.md +++ b/CONFIGURE.md @@ -1,13 +1,16 @@ +Options for configuring liboqs builds +===================================== + The following options can be passed to CMake before the build file generation process to customize the way liboqs is built. The syntax for doing so is: `cmake .. [ARGS] [-D=]...`, where `` is: - [BUILD_SHARED_LIBS](#BUILD_SHARED_LIBS) - [CMAKE_BUILD_TYPE](#CMAKE_BUILD_TYPE) - [CMAKE_INSTALL_PREFIX](#CMAKE_INSTALL_PREFIX) - [OQS_BUILD_ONLY_LIB](#OQS_BUILD_ONLY_LIB) -- [OQS_ENABLE_KEM_\/OQS_ENABLE_SIG_\](#OQS_ENABLE_KEM_\/OQS_ENABLE_SIG_\) +- [OQS_ENABLE_KEM_ALG/OQS_ENABLE_SIG_ALG](#OQS_ENABLE_KEM_ALG/OQS_ENABLE_SIG_ALG) - [OQS_MINIMAL_BUILD](#OQS_MINIMAL_BUILD) - [OQS_DIST_BUILD](#OQS_DIST_BUILD) -- [OQS_USE_\_INSTRUCTIONS](OQS_USE_\_INSTRUCTIONS) +- [OQS_USE_CPUFEATURE_INSTRUCTIONS](OQS_USE_CPUFEATURE_INSTRUCTIONS) - [OQS_USE_OPENSSL](#OQS_USE_OPENSSL) - [OQS_OPT_TARGET](#OQS_OPT_TARGET) - [OQS_SPEED_USE_ARM_PMU](#OQS_SPEED_USE_ARM_PMU) @@ -30,9 +33,11 @@ Can be set to the following values: See the [CMake documentation](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html). -## OQS_ENABLE_KEM_\/OQS_ENABLE_SIG_\ +## OQS_ENABLE_KEM_ALG/OQS_ENABLE_SIG_ALG -This can be set to `ON` or `OFF`, and is `ON` by default. When `OFF`, `` and its code are excluded from the build process. When `ON`, made available are additional options whereby individual variants of `` can be excluded from the build process. +Note: `ALG` in `OQS_ENABLE_KEM_ALG/OQS_ENABLE_SIG_ALG` should be replaced with the specific algorithm name as demonstrated below. + +This can be set to `ON` or `OFF`, and is `ON` by default. When `OFF`, `ALG` and its code are excluded from the build process. When `ON`, made available are additional options whereby individual variants of `ALG` can be excluded from the build process. For example: if `OQS_ENABLE_KEM_BIKE` is set to `ON`, the options `OQS_ENABLE_KEM_bike1_l1_cpa`, `OQS_ENABLE_KEM_bike1_l1_fo`, `OQS_ENABLE_KEM_bike1_l3_cpa`, `OQS_ENABLE_KEM_bike1_l3_fo` are made available (and are set to be `ON` by default). @@ -58,7 +63,9 @@ When built for distribution, the library will run on any CPU of the target archi When built for use on a single machine, the library will only include the best available code for the target micro-architecture (see [OQS_OPT_TARGET](#OQS_OPT_TARGET)). -## OQS_USE_\_INSTRUCTIONS +## OQS_USE_CPUFEATURE_INSTRUCTIONS + +Note: `CPUFEATURE` in `OQS_USE_CPUFEATURE_INSTRUCTIONS` should be replaced with the specific CPU feature as noted below. These can be set to `ON` or `OFF` and take an effect if liboqs is built for use on a single machine. By default, the CPU features are automatically determined and set to `ON` or `OFF` based on the CPU features available on the build system. The default values can be overridden by providing CMake build options. The available options on x86-64 are: `OQS_USE_ADX_INSTRUCTIONS`, `OQS_USE_AES_INSTRUCTIONS`, `OQS_USE_AVX_INSTRUCTIONS`, `OQS_USE_AVX2_INSTRUCTIONS`, `OQS_USE_AVX512_INSTRUCTIONS`, `OQS_USE_BMI1_INSTRUCTIONS`, `OQS_USE_BMI2_INSTRUCTIONS`, `OQS_USE_PCLMULQDQ_INSTRUCTIONS`, `OQS_USE_VPCLMULQDQ_INSTRUCTIONS`, `OQS_USE_POPCNT_INSTRUCTIONS`, `OQS_USE_SSE_INSTRUCTIONS`, `OQS_USE_SSE2_INSTRUCTIONS` and `OQS_USE_SSE3_INSTRUCTIONS`. The available options on ARM64v8 are `OQS_USE_ARM_AES_INSTRUCTIONS`, `OQS_USE_ARM_SHA2_INSTRUCTIONS`, `OQS_USE_ARM_SHA3_INSTRUCTIONS` and `OQS_USE_ARM_NEON_INSTRUCTIONS`. @@ -97,4 +104,6 @@ This has effect when the compiler is Clang and when [CMAKE_BUILD_TYPE](#CMAKE_BU ## OQS_ENABLE_TEST_CONSTANT_TIME -This is used in conjunction with `tests/test_constant_time.py` to use Valgrind to look for instances of secret-dependent control flow. liboqs must also be compiled with [CMAKE_BUILD_TYPE](#CMAKE_BUILD_TYPE) set to `Debug`. See the documentation in [`tests/test_constant_time.py`](https://github.com/open-quantum-safe/liboqs/blob/main/tests/test_constant_time.py) for more information on usage. +This is used in conjunction with `tests/test_constant_time.py` to use Valgrind to look for instances of secret-dependent control flow. liboqs must also be compiled with [CMAKE_BUILD_TYPE](#CMAKE_BUILD_TYPE) set to `Debug`. + +See the documentation in [`tests/test_constant_time.py`](https://github.com/open-quantum-safe/liboqs/blob/main/tests/test_constant_time.py) for more information on usage. diff --git a/scripts/doxyfy.py b/scripts/doxyfy.py index 537521d28..9b29610dc 100644 --- a/scripts/doxyfy.py +++ b/scripts/doxyfy.py @@ -18,6 +18,14 @@ def anchorstring(str): i=i+1 return doxyref +def reformat_anchors(s): + if "](#" in s: + i = s.index("](#") + 3 + j = s[i:].index(")") + i + return s[0:i] + anchorstring(s[i:j]) + s[j:] + else: + return s + if len(sys.argv) != 3 or not Path(sys.argv[1]).is_file(): print("Expecting original and new file location. Exiting.") exit(1) @@ -41,6 +49,8 @@ with open(sys.argv[2], "w") as outfile: ll = possibleanchor else: # create anchor markup just in case... possibleanchor=line.strip()+" {#"+anchorstring(line.strip())+"}\n" + if ll is not None: + ll = reformat_anchors(ll) # write last line if ll is not None: outfile.write(ll) ll = nl diff --git a/scripts/run_doxygen.sh b/scripts/run_doxygen.sh index 90e17e054..7cca0bc19 100755 --- a/scripts/run_doxygen.sh +++ b/scripts/run_doxygen.sh @@ -1,4 +1,4 @@ -#!/bin/sh +#!/bin/bash # SPDX-License-Identifier: MIT @@ -7,11 +7,18 @@ if [ "$#" -ne 2 ]; then exit 1 fi +# Doxygen can't handle Github Markdown so we temporarily reformat it cp README.md README.md-orig python3 scripts/doxyfy.py README.md-orig README.md +cp CONFIGURE.md CONFIGURE.md-orig +python3 scripts/doxyfy.py CONFIGURE.md-orig CONFIGURE.md # run doxygen: $1 $2 +EXITCODE=$? -# remove helper README +# undo the Github Markdown reformatting mv README.md-orig README.md +mv CONFIGURE.md-orig CONFIGURE.md + +exit ${EXITCODE} \ No newline at end of file