diff --git a/.clang-format b/.clang-format new file mode 100644 index 0000000..0b8c0be --- /dev/null +++ b/.clang-format @@ -0,0 +1,17 @@ +BasedOnStyle: LLVM +IndentWidth: 4 +ColumnLimit: 140 +TabWidth: 4 +UseTab: Never +BreakBeforeBraces: Allman +AllowShortFunctionsOnASingleLine: Empty +PointerAlignment: Left +DerivePointerAlignment: false +SpaceBeforeParens: ControlStatements +SortIncludes: true +IncludeBlocks: Regroup +ReflowComments: true +ContinuationIndentWidth: 4 +BinPackParameters: false +BinPackArguments: false + \ No newline at end of file diff --git a/.clang-tidy b/.clang-tidy new file mode 100644 index 0000000..6793178 --- /dev/null +++ b/.clang-tidy @@ -0,0 +1,30 @@ +Checks: > + -*, + readability-* , + modernize-* , + -modernize-use-trailing-return-type, + -readability-magic-numbers, + +WarningsAsErrors: > + bugprone-* , + performance-* , + clang-analyzer-* + +HeaderFilterRegex: 'src/.*' +FormatStyle: file + +CheckOptions: + - key: modernize-use-auto.MinTypeNameLength + value: '5' + - key: modernize-use-auto.RemoveStars + value: 'false' + - key: readability-identifier-naming.VariableCase + value: lower_case + - key: readability-identifier-naming.MemberCase + value: lower_case + - key: readability-identifier-naming.PrivateMemberPrefix + value: '_' + - key: readability-function-size.ParameterThreshold + value: '8' + - key: readability-braces-around-statements.ShortStatementLines + value: '0' diff --git a/.devcontainer/Dockerfile.dev b/.devcontainer/Dockerfile.dev new file mode 100644 index 0000000..276d9fe --- /dev/null +++ b/.devcontainer/Dockerfile.dev @@ -0,0 +1,13 @@ +FROM fedora:42 + +RUN dnf install -y \ + clang \ + clang-tools-extra \ + clangd \ + clang-format \ + clang-tidy \ + clang-analyzer \ + cmake \ + git \ + ninja-build \ + && dnf clean all diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 0000000..2aecf4e --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,28 @@ +{ + "build": { + "dockerfile": "./Dockerfile.dev" + }, + "customizations": { + "vscode": { + "extensions": [ + "mhutchie.git-graph", + "ms-azuretools.vscode-docker", + "vivaxy.vscode-conventional-commits", + "github.vscode-github-actions", + "llvm-vs-code-extensions.vscode-clangd", + "ms-vscode.cmake-tools" + ] + } + }, + "runArgs": [ + "--network", + "host", + "--privileged", + "--device", + "/dev/bus/usb:/dev/bus/usb", + "--device-cgroup-rule=c 188:* rwm", + "--device-cgroup-rule=c 166:* rwm", + "--group-add=dialout", + "--volume=/dev/serial/by-id:/dev/serial/by-id:ro" + ] +} diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..2a66b50 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,45 @@ +name: Build & Release CPP-Unix-Bindings + +on: + push: + branches: [ "main" ] + pull_request: + branches: [ "**" ] + release: + types: [ created ] + +jobs: + build: + name: Build shared library + runs-on: ubuntu-latest + env: + CC: clang + CXX: clang++ + + steps: + - name: Checkout repository + uses: actions/checkout@v3 + + - name: Install build dependencies + run: | + sudo apt-get update + sudo apt-get install -y build-essential cmake clang make + + - name: Configure CMake + run: cmake -S . -B build -DCMAKE_BUILD_TYPE=Release + + - name: Compile + run: cmake --build build -j $(nproc) + + - name: Upload library artifact + uses: actions/upload-artifact@v4 + with: + name: libCPP-Unix-Bindings + path: build/libCPP-Unix-Bindings.so + retention-days: 14 + + - name: Attach library to release + if: github.event_name == 'release' + uses: softprops/action-gh-release@v1 + with: + files: build/libCPP-Unix-Bindings.so diff --git a/.gitignore b/.gitignore index b487b26..f80d786 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ .vscode/ build/ src/version_config.cpp -.cache/ \ No newline at end of file +.cache/ +compile_commands.json diff --git a/CMakeLists.txt b/CMakeLists.txt index d0359a3..e1886b7 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,4 +1,4 @@ -cmake_minimum_required(VERSION 3.10) +cmake_minimum_required(VERSION 3.30) set(VERSION_MAJOR 0) set(VERSION_MINOR 2) @@ -7,7 +7,32 @@ set(VERSION_PATCH 0) set(PROJECT_N CPP-Unix-Bindings) project(${PROJECT_N} VERSION ${VERSION_MAJOR}.${VERSION_MINOR}.${VERSION_PATCH}) -set(CMAKE_CXX_STANDARD 20) +# Generate compile_commands.json for clang-based tooling (clangd / clang-tidy) +set(CMAKE_EXPORT_COMPILE_COMMANDS ON) + +include(cmake/CPM.cmake) + +CPMAddPackage( + NAME "googletest" + GITHUB_REPOSITORY "google/googletest" + GIT_TAG "v1.17.0" + GIT_SHALLOW TRUE + OPTIONS "GTEST_BUILD_TESTS OFF" + OPTIONS "GTEST_BUILD_EXAMPLES OFF" + OPTIONS "GTEST_BUILD_DOCS OFF" +) + +# Ensure clang tooling can pick up compile_commands.json from project root +if(CMAKE_EXPORT_COMPILE_COMMANDS) + add_custom_target(copy-compile-commands ALL + COMMAND ${CMAKE_COMMAND} -E copy_if_different + ${CMAKE_BINARY_DIR}/compile_commands.json + ${PROJECT_SOURCE_DIR}/compile_commands.json + COMMENT "Copy compile_commands.json to project root" + VERBATIM) +endif() + +set(CMAKE_CXX_STANDARD 23) set(CMAKE_CXX_STANDARD_REQUIRED True) file(GLOB_RECURSE SRCS ${PROJECT_SOURCE_DIR}/src/**.cpp) @@ -51,4 +76,30 @@ set_target_properties(${PROJECT_N} PROPERTIES VERSION ${PROJECT_VERSION} SOVERSION ${PROJECT_VERSION_MAJOR}) -target_include_directories(${PROJECT_N} PUBLIC include) +target_include_directories(${PROJECT_N} PUBLIC ${PROJECT_SOURCE_DIR}/src) + +add_executable(serial_integration_tests tests/serial_test.cpp) +target_link_libraries(serial_integration_tests PRIVATE ${PROJECT_N} gtest_main) + +target_include_directories(serial_integration_tests PRIVATE ${PROJECT_SOURCE_DIR}/src) + +add_custom_command(TARGET serial_integration_tests POST_BUILD + COMMAND ${CMAKE_COMMAND} -E copy_if_different + $ + $ + COMMENT "Copy shared library next to test binary") + +# Unit test target covering additional API aspects +add_executable(serial_unit_tests tests/serial_unit_tests.cpp) +target_link_libraries(serial_unit_tests PRIVATE ${PROJECT_N} gtest_main) +target_include_directories(serial_unit_tests PRIVATE ${PROJECT_SOURCE_DIR}/src) + +add_custom_command(TARGET serial_unit_tests POST_BUILD + COMMAND ${CMAKE_COMMAND} -E copy_if_different + $ + $ + COMMENT "Copy shared library next to unit test binary") + +enable_testing() +add_test(NAME SerialEchoTest COMMAND serial_integration_tests /dev/ttyUSB0) +add_test(NAME SerialUnitTests COMMAND serial_unit_tests) diff --git a/README.md b/README.md index a1b6ea3..3e4d0c0 100644 --- a/README.md +++ b/README.md @@ -1 +1,79 @@ -# Serial \ No newline at end of file +# CPP-Unix-Bindings + +A compact C++23 library for talking to serial devices on Linux (e.g. Arduino). +The project builds a **shared library `libCPP-Unix-Bindings.so`** that can be used via +Deno's native FFI. + +--- + +## 1 Building the library + +```bash +# Clone +git clone https://github.com/Serial-IO/cpp-bindings-unix.git cpp-bindings-unix +cd cpp-bindings-unix + +# Dependencies (Debian/Ubuntu) +sudo apt-get install build-essential cmake clang make + +# Compile +cmake -S . -B build -DCMAKE_BUILD_TYPE=Release +cmake --build build -j + +# The resulting library will be located at +# build/libCPP-Unix-Bindings.so +``` + +> Because `CMAKE_EXPORT_COMPILE_COMMANDS` is enabled, the build also generates a +> `compile_commands.json` that is automatically copied to the project root — +> handy for clang-tools (clangd, clang-tidy, …). + +--- + +## 2 Using the library from **Deno** (v1.42 or newer) + +Deno ships with a first-class FFI API. + +```ts +// serial_deno.ts +const lib = Deno.dlopen('./build/libCPP-Unix-Bindings.so', { + serialOpen: { parameters: [ 'buffer', 'i32', 'i32', 'i32', 'i32' ], result: 'pointer' }, + serialClose: { parameters: [ 'pointer' ], result: 'void' }, + serialRead: { parameters: [ 'pointer', 'buffer', 'i32', 'i32', 'i32' ], result: 'i32' }, + serialWrite: { parameters: [ 'pointer', 'buffer', 'i32', 'i32', 'i32' ], result: 'i32' }, +}); + +const enc = new TextEncoder(); +const dec = new TextDecoder(); + +// Note: device path must be null-terminated +const handle = lib.symbols.serialOpen(enc.encode('/dev/ttyUSB0\0'), 115200, 8, 0, 0); + +const writeBuf = enc.encode('Hello\n'); +lib.symbols.serialWrite(handle, writeBuf, writeBuf.length, 100, 1); + +const readBuf = new Uint8Array(128); +const n = lib.symbols.serialRead(handle, readBuf, readBuf.length, 500, 1); +console.log(dec.decode(readBuf.subarray(0, n))); + +lib.symbols.serialClose(handle); +lib.close(); +``` + +--- + +## 3 C API reference + +| Function | Description | +|----------|-------------| +| `intptr_t serialOpen(const char* dev, int baud, int bits, int parity, int stop)` | Open a device and return a handle. | +| `void serialClose(intptr_t handle)` | Close the port. | +| `int serialRead(...)` | Read bytes with timeout. | +| `int serialWrite(...)` | Write bytes with timeout. | +| `int serialGetPortsInfo(char* buffer, int len, const char* sep)` | List ports under `/dev/serial/by-id`. | +| `void serialOnError(void (*)(int))` | Register an error callback. | +| *(others in `serial.h`)* | + +Return values ≤ 0 indicate error codes defined in `status_codes.h`. + +--- diff --git a/cmake/CPM.cmake b/cmake/CPM.cmake new file mode 100644 index 0000000..3636ee5 --- /dev/null +++ b/cmake/CPM.cmake @@ -0,0 +1,1363 @@ +# CPM.cmake - CMake's missing package manager +# =========================================== +# See https://github.com/cpm-cmake/CPM.cmake for usage and update instructions. +# +# MIT License +# ----------- +#[[ + Copyright (c) 2019-2023 Lars Melchior and contributors + + Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated documentation files (the "Software"), to deal + in the Software without restriction, including without limitation the rights + to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + copies of the Software, and to permit persons to whom the Software is + furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included in all + copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + SOFTWARE. +]] + +cmake_minimum_required(VERSION 3.14 FATAL_ERROR) + +# Initialize logging prefix +if(NOT CPM_INDENT) + set(CPM_INDENT + "CPM:" + CACHE INTERNAL "" + ) +endif() + +if(NOT COMMAND cpm_message) + function(cpm_message) + message(${ARGV}) + endfunction() +endif() + +if(DEFINED EXTRACTED_CPM_VERSION) + set(CURRENT_CPM_VERSION "${EXTRACTED_CPM_VERSION}${CPM_DEVELOPMENT}") +else() + set(CURRENT_CPM_VERSION 0.42.0) +endif() + +get_filename_component(CPM_CURRENT_DIRECTORY "${CMAKE_CURRENT_LIST_DIR}" REALPATH) +if(CPM_DIRECTORY) + if(NOT CPM_DIRECTORY STREQUAL CPM_CURRENT_DIRECTORY) + if(CPM_VERSION VERSION_LESS CURRENT_CPM_VERSION) + message( + AUTHOR_WARNING + "${CPM_INDENT} \ +A dependency is using a more recent CPM version (${CURRENT_CPM_VERSION}) than the current project (${CPM_VERSION}). \ +It is recommended to upgrade CPM to the most recent version. \ +See https://github.com/cpm-cmake/CPM.cmake for more information." + ) + endif() + if(${CMAKE_VERSION} VERSION_LESS "3.17.0") + include(FetchContent) + endif() + return() + endif() + + get_property( + CPM_INITIALIZED GLOBAL "" + PROPERTY CPM_INITIALIZED + SET + ) + if(CPM_INITIALIZED) + return() + endif() +endif() + +if(CURRENT_CPM_VERSION MATCHES "development-version") + message( + WARNING "${CPM_INDENT} Your project is using an unstable development version of CPM.cmake. \ +Please update to a recent release if possible. \ +See https://github.com/cpm-cmake/CPM.cmake for details." + ) +endif() + +set_property(GLOBAL PROPERTY CPM_INITIALIZED true) + +macro(cpm_set_policies) + # the policy allows us to change options without caching + cmake_policy(SET CMP0077 NEW) + set(CMAKE_POLICY_DEFAULT_CMP0077 NEW) + + # the policy allows us to change set(CACHE) without caching + if(POLICY CMP0126) + cmake_policy(SET CMP0126 NEW) + set(CMAKE_POLICY_DEFAULT_CMP0126 NEW) + endif() + + # The policy uses the download time for timestamp, instead of the timestamp in the archive. This + # allows for proper rebuilds when a projects url changes + if(POLICY CMP0135) + cmake_policy(SET CMP0135 NEW) + set(CMAKE_POLICY_DEFAULT_CMP0135 NEW) + endif() + + # treat relative git repository paths as being relative to the parent project's remote + if(POLICY CMP0150) + cmake_policy(SET CMP0150 NEW) + set(CMAKE_POLICY_DEFAULT_CMP0150 NEW) + endif() +endmacro() +cpm_set_policies() + +option(CPM_USE_LOCAL_PACKAGES "Always try to use `find_package` to get dependencies" + $ENV{CPM_USE_LOCAL_PACKAGES} +) +option(CPM_LOCAL_PACKAGES_ONLY "Only use `find_package` to get dependencies" + $ENV{CPM_LOCAL_PACKAGES_ONLY} +) +option(CPM_DOWNLOAD_ALL "Always download dependencies from source" $ENV{CPM_DOWNLOAD_ALL}) +option(CPM_DONT_UPDATE_MODULE_PATH "Don't update the module path to allow using find_package" + $ENV{CPM_DONT_UPDATE_MODULE_PATH} +) +option(CPM_DONT_CREATE_PACKAGE_LOCK "Don't create a package lock file in the binary path" + $ENV{CPM_DONT_CREATE_PACKAGE_LOCK} +) +option(CPM_INCLUDE_ALL_IN_PACKAGE_LOCK + "Add all packages added through CPM.cmake to the package lock" + $ENV{CPM_INCLUDE_ALL_IN_PACKAGE_LOCK} +) +option(CPM_USE_NAMED_CACHE_DIRECTORIES + "Use additional directory of package name in cache on the most nested level." + $ENV{CPM_USE_NAMED_CACHE_DIRECTORIES} +) + +set(CPM_VERSION + ${CURRENT_CPM_VERSION} + CACHE INTERNAL "" +) +set(CPM_DIRECTORY + ${CPM_CURRENT_DIRECTORY} + CACHE INTERNAL "" +) +set(CPM_FILE + ${CMAKE_CURRENT_LIST_FILE} + CACHE INTERNAL "" +) +set(CPM_PACKAGES + "" + CACHE INTERNAL "" +) +set(CPM_DRY_RUN + OFF + CACHE INTERNAL "Don't download or configure dependencies (for testing)" +) + +if(DEFINED ENV{CPM_SOURCE_CACHE}) + set(CPM_SOURCE_CACHE_DEFAULT $ENV{CPM_SOURCE_CACHE}) +else() + set(CPM_SOURCE_CACHE_DEFAULT OFF) +endif() + +set(CPM_SOURCE_CACHE + ${CPM_SOURCE_CACHE_DEFAULT} + CACHE PATH "Directory to download CPM dependencies" +) + +if(NOT CPM_DONT_UPDATE_MODULE_PATH AND NOT DEFINED CMAKE_FIND_PACKAGE_REDIRECTS_DIR) + set(CPM_MODULE_PATH + "${CMAKE_BINARY_DIR}/CPM_modules" + CACHE INTERNAL "" + ) + # remove old modules + file(REMOVE_RECURSE ${CPM_MODULE_PATH}) + file(MAKE_DIRECTORY ${CPM_MODULE_PATH}) + # locally added CPM modules should override global packages + set(CMAKE_MODULE_PATH "${CPM_MODULE_PATH};${CMAKE_MODULE_PATH}") +endif() + +if(NOT CPM_DONT_CREATE_PACKAGE_LOCK) + set(CPM_PACKAGE_LOCK_FILE + "${CMAKE_BINARY_DIR}/cpm-package-lock.cmake" + CACHE INTERNAL "" + ) + file(WRITE ${CPM_PACKAGE_LOCK_FILE} + "# CPM Package Lock\n# This file should be committed to version control\n\n" + ) +endif() + +include(FetchContent) + +# Try to infer package name from git repository uri (path or url) +function(cpm_package_name_from_git_uri URI RESULT) + if("${URI}" MATCHES "([^/:]+)/?.git/?$") + set(${RESULT} + ${CMAKE_MATCH_1} + PARENT_SCOPE + ) + else() + unset(${RESULT} PARENT_SCOPE) + endif() +endfunction() + +# Find the shortest hash that can be used eg, if origin_hash is +# cccb77ae9609d2768ed80dd42cec54f77b1f1455 the following files will be checked, until one is found +# that is either empty (allowing us to assign origin_hash), or whose contents matches ${origin_hash} +# +# * .../cccb.hash +# * .../cccb77ae.hash +# * .../cccb77ae9609.hash +# * .../cccb77ae9609d276.hash +# * etc +# +# We will be able to use a shorter path with very high probability, but in the (rare) event that the +# first couple characters collide, we will check longer and longer substrings. +function(cpm_get_shortest_hash source_cache_dir origin_hash short_hash_output_var) + # for compatibility with caches populated by a previous version of CPM, check if a directory using + # the full hash already exists + if(EXISTS "${source_cache_dir}/${origin_hash}") + set(${short_hash_output_var} + "${origin_hash}" + PARENT_SCOPE + ) + return() + endif() + + foreach(len RANGE 4 40 4) + string(SUBSTRING "${origin_hash}" 0 ${len} short_hash) + set(hash_lock ${source_cache_dir}/${short_hash}.lock) + set(hash_fp ${source_cache_dir}/${short_hash}.hash) + # Take a lock, so we don't have a race condition with another instance of cmake. We will release + # this lock when we can, however, if there is an error, we want to ensure it gets released on + # it's own on exit from the function. + file(LOCK ${hash_lock} GUARD FUNCTION) + + # Load the contents of .../${short_hash}.hash + file(TOUCH ${hash_fp}) + file(READ ${hash_fp} hash_fp_contents) + + if(hash_fp_contents STREQUAL "") + # Write the origin hash + file(WRITE ${hash_fp} ${origin_hash}) + file(LOCK ${hash_lock} RELEASE) + break() + elseif(hash_fp_contents STREQUAL origin_hash) + file(LOCK ${hash_lock} RELEASE) + break() + else() + file(LOCK ${hash_lock} RELEASE) + endif() + endforeach() + set(${short_hash_output_var} + "${short_hash}" + PARENT_SCOPE + ) +endfunction() + +# Try to infer package name and version from a url +function(cpm_package_name_and_ver_from_url url outName outVer) + if(url MATCHES "[/\\?]([a-zA-Z0-9_\\.-]+)\\.(tar|tar\\.gz|tar\\.bz2|zip|ZIP)(\\?|/|$)") + # We matched an archive + set(filename "${CMAKE_MATCH_1}") + + if(filename MATCHES "([a-zA-Z0-9_\\.-]+)[_-]v?(([0-9]+\\.)*[0-9]+[a-zA-Z0-9]*)") + # We matched - (ie foo-1.2.3) + set(${outName} + "${CMAKE_MATCH_1}" + PARENT_SCOPE + ) + set(${outVer} + "${CMAKE_MATCH_2}" + PARENT_SCOPE + ) + elseif(filename MATCHES "(([0-9]+\\.)+[0-9]+[a-zA-Z0-9]*)") + # We couldn't find a name, but we found a version + # + # In many cases (which we don't handle here) the url would look something like + # `irrelevant/ACTUAL_PACKAGE_NAME/irrelevant/1.2.3.zip`. In such a case we can't possibly + # distinguish the package name from the irrelevant bits. Moreover if we try to match the + # package name from the filename, we'd get bogus at best. + unset(${outName} PARENT_SCOPE) + set(${outVer} + "${CMAKE_MATCH_1}" + PARENT_SCOPE + ) + else() + # Boldly assume that the file name is the package name. + # + # Yes, something like `irrelevant/ACTUAL_NAME/irrelevant/download.zip` will ruin our day, but + # such cases should be quite rare. No popular service does this... we think. + set(${outName} + "${filename}" + PARENT_SCOPE + ) + unset(${outVer} PARENT_SCOPE) + endif() + else() + # No ideas yet what to do with non-archives + unset(${outName} PARENT_SCOPE) + unset(${outVer} PARENT_SCOPE) + endif() +endfunction() + +function(cpm_find_package NAME VERSION) + string(REPLACE " " ";" EXTRA_ARGS "${ARGN}") + find_package(${NAME} ${VERSION} ${EXTRA_ARGS} QUIET) + if(${CPM_ARGS_NAME}_FOUND) + if(DEFINED ${CPM_ARGS_NAME}_VERSION) + set(VERSION ${${CPM_ARGS_NAME}_VERSION}) + endif() + cpm_message(STATUS "${CPM_INDENT} Using local package ${CPM_ARGS_NAME}@${VERSION}") + CPMRegisterPackage(${CPM_ARGS_NAME} "${VERSION}") + set(CPM_PACKAGE_FOUND + YES + PARENT_SCOPE + ) + else() + set(CPM_PACKAGE_FOUND + NO + PARENT_SCOPE + ) + endif() +endfunction() + +# Create a custom FindXXX.cmake module for a CPM package This prevents `find_package(NAME)` from +# finding the system library +function(cpm_create_module_file Name) + if(NOT CPM_DONT_UPDATE_MODULE_PATH) + if(DEFINED CMAKE_FIND_PACKAGE_REDIRECTS_DIR) + # Redirect find_package calls to the CPM package. This is what FetchContent does when you set + # OVERRIDE_FIND_PACKAGE. The CMAKE_FIND_PACKAGE_REDIRECTS_DIR works for find_package in CONFIG + # mode, unlike the Find${Name}.cmake fallback. CMAKE_FIND_PACKAGE_REDIRECTS_DIR is not defined + # in script mode, or in CMake < 3.24. + # https://cmake.org/cmake/help/latest/module/FetchContent.html#fetchcontent-find-package-integration-examples + string(TOLOWER ${Name} NameLower) + file(WRITE ${CMAKE_FIND_PACKAGE_REDIRECTS_DIR}/${NameLower}-config.cmake + "include(\"\${CMAKE_CURRENT_LIST_DIR}/${NameLower}-extra.cmake\" OPTIONAL)\n" + "include(\"\${CMAKE_CURRENT_LIST_DIR}/${Name}Extra.cmake\" OPTIONAL)\n" + ) + file(WRITE ${CMAKE_FIND_PACKAGE_REDIRECTS_DIR}/${NameLower}-config-version.cmake + "set(PACKAGE_VERSION_COMPATIBLE TRUE)\n" "set(PACKAGE_VERSION_EXACT TRUE)\n" + ) + else() + file(WRITE ${CPM_MODULE_PATH}/Find${Name}.cmake + "include(\"${CPM_FILE}\")\n${ARGN}\nset(${Name}_FOUND TRUE)" + ) + endif() + endif() +endfunction() + +# Find a package locally or fallback to CPMAddPackage +function(CPMFindPackage) + set(oneValueArgs NAME VERSION GIT_TAG FIND_PACKAGE_ARGUMENTS) + + cmake_parse_arguments(CPM_ARGS "" "${oneValueArgs}" "" ${ARGN}) + + if(NOT DEFINED CPM_ARGS_VERSION) + if(DEFINED CPM_ARGS_GIT_TAG) + cpm_get_version_from_git_tag("${CPM_ARGS_GIT_TAG}" CPM_ARGS_VERSION) + endif() + endif() + + set(downloadPackage ${CPM_DOWNLOAD_ALL}) + if(DEFINED CPM_DOWNLOAD_${CPM_ARGS_NAME}) + set(downloadPackage ${CPM_DOWNLOAD_${CPM_ARGS_NAME}}) + elseif(DEFINED ENV{CPM_DOWNLOAD_${CPM_ARGS_NAME}}) + set(downloadPackage $ENV{CPM_DOWNLOAD_${CPM_ARGS_NAME}}) + endif() + if(downloadPackage) + CPMAddPackage(${ARGN}) + cpm_export_variables(${CPM_ARGS_NAME}) + return() + endif() + + cpm_find_package(${CPM_ARGS_NAME} "${CPM_ARGS_VERSION}" ${CPM_ARGS_FIND_PACKAGE_ARGUMENTS}) + + if(NOT CPM_PACKAGE_FOUND) + CPMAddPackage(${ARGN}) + cpm_export_variables(${CPM_ARGS_NAME}) + endif() + +endfunction() + +# checks if a package has been added before +function(cpm_check_if_package_already_added CPM_ARGS_NAME CPM_ARGS_VERSION) + if("${CPM_ARGS_NAME}" IN_LIST CPM_PACKAGES) + CPMGetPackageVersion(${CPM_ARGS_NAME} CPM_PACKAGE_VERSION) + if("${CPM_PACKAGE_VERSION}" VERSION_LESS "${CPM_ARGS_VERSION}") + message( + WARNING + "${CPM_INDENT} Requires a newer version of ${CPM_ARGS_NAME} (${CPM_ARGS_VERSION}) than currently included (${CPM_PACKAGE_VERSION})." + ) + endif() + cpm_get_fetch_properties(${CPM_ARGS_NAME}) + set(${CPM_ARGS_NAME}_ADDED NO) + set(CPM_PACKAGE_ALREADY_ADDED + YES + PARENT_SCOPE + ) + cpm_export_variables(${CPM_ARGS_NAME}) + else() + set(CPM_PACKAGE_ALREADY_ADDED + NO + PARENT_SCOPE + ) + endif() +endfunction() + +# Parse the argument of CPMAddPackage in case a single one was provided and convert it to a list of +# arguments which can then be parsed idiomatically. For example gh:foo/bar@1.2.3 will be converted +# to: GITHUB_REPOSITORY;foo/bar;VERSION;1.2.3 +function(cpm_parse_add_package_single_arg arg outArgs) + # Look for a scheme + if("${arg}" MATCHES "^([a-zA-Z]+):(.+)$") + string(TOLOWER "${CMAKE_MATCH_1}" scheme) + set(uri "${CMAKE_MATCH_2}") + + # Check for CPM-specific schemes + if(scheme STREQUAL "gh") + set(out "GITHUB_REPOSITORY;${uri}") + set(packageType "git") + elseif(scheme STREQUAL "gl") + set(out "GITLAB_REPOSITORY;${uri}") + set(packageType "git") + elseif(scheme STREQUAL "bb") + set(out "BITBUCKET_REPOSITORY;${uri}") + set(packageType "git") + # A CPM-specific scheme was not found. Looks like this is a generic URL so try to determine + # type + elseif(arg MATCHES ".git/?(@|#|$)") + set(out "GIT_REPOSITORY;${arg}") + set(packageType "git") + else() + # Fall back to a URL + set(out "URL;${arg}") + set(packageType "archive") + + # We could also check for SVN since FetchContent supports it, but SVN is so rare these days. + # We just won't bother with the additional complexity it will induce in this function. SVN is + # done by multi-arg + endif() + else() + if(arg MATCHES ".git/?(@|#|$)") + set(out "GIT_REPOSITORY;${arg}") + set(packageType "git") + else() + # Give up + message(FATAL_ERROR "${CPM_INDENT} Can't determine package type of '${arg}'") + endif() + endif() + + # For all packages we interpret @... as version. Only replace the last occurrence. Thus URIs + # containing '@' can be used + string(REGEX REPLACE "@([^@]+)$" ";VERSION;\\1" out "${out}") + + # Parse the rest according to package type + if(packageType STREQUAL "git") + # For git repos we interpret #... as a tag or branch or commit hash + string(REGEX REPLACE "#([^#]+)$" ";GIT_TAG;\\1" out "${out}") + elseif(packageType STREQUAL "archive") + # For archives we interpret #... as a URL hash. + string(REGEX REPLACE "#([^#]+)$" ";URL_HASH;\\1" out "${out}") + # We don't try to parse the version if it's not provided explicitly. cpm_get_version_from_url + # should do this at a later point + else() + # We should never get here. This is an assertion and hitting it means there's a problem with the + # code above. A packageType was set, but not handled by this if-else. + message(FATAL_ERROR "${CPM_INDENT} Unsupported package type '${packageType}' of '${arg}'") + endif() + + set(${outArgs} + ${out} + PARENT_SCOPE + ) +endfunction() + +# Check that the working directory for a git repo is clean +function(cpm_check_git_working_dir_is_clean repoPath gitTag isClean) + + find_package(Git REQUIRED) + + if(NOT GIT_EXECUTABLE) + # No git executable, assume directory is clean + set(${isClean} + TRUE + PARENT_SCOPE + ) + return() + endif() + + # check for uncommitted changes + execute_process( + COMMAND ${GIT_EXECUTABLE} status --porcelain + RESULT_VARIABLE resultGitStatus + OUTPUT_VARIABLE repoStatus + OUTPUT_STRIP_TRAILING_WHITESPACE ERROR_QUIET + WORKING_DIRECTORY ${repoPath} + ) + if(resultGitStatus) + # not supposed to happen, assume clean anyway + message(WARNING "${CPM_INDENT} Calling git status on folder ${repoPath} failed") + set(${isClean} + TRUE + PARENT_SCOPE + ) + return() + endif() + + if(NOT "${repoStatus}" STREQUAL "") + set(${isClean} + FALSE + PARENT_SCOPE + ) + return() + endif() + + # check for committed changes + execute_process( + COMMAND ${GIT_EXECUTABLE} diff -s --exit-code ${gitTag} + RESULT_VARIABLE resultGitDiff + OUTPUT_STRIP_TRAILING_WHITESPACE OUTPUT_QUIET + WORKING_DIRECTORY ${repoPath} + ) + + if(${resultGitDiff} EQUAL 0) + set(${isClean} + TRUE + PARENT_SCOPE + ) + else() + set(${isClean} + FALSE + PARENT_SCOPE + ) + endif() + +endfunction() + +# Add PATCH_COMMAND to CPM_ARGS_UNPARSED_ARGUMENTS. This method consumes a list of files in ARGN +# then generates a `PATCH_COMMAND` appropriate for `ExternalProject_Add()`. This command is appended +# to the parent scope's `CPM_ARGS_UNPARSED_ARGUMENTS`. +function(cpm_add_patches) + # Return if no patch files are supplied. + if(NOT ARGN) + return() + endif() + + # Find the patch program. + find_program(PATCH_EXECUTABLE patch) + if(CMAKE_HOST_WIN32 AND NOT PATCH_EXECUTABLE) + # The Windows git executable is distributed with patch.exe. Find the path to the executable, if + # it exists, then search `../usr/bin` and `../../usr/bin` for patch.exe. + find_package(Git QUIET) + if(GIT_EXECUTABLE) + get_filename_component(extra_search_path ${GIT_EXECUTABLE} DIRECTORY) + get_filename_component(extra_search_path_1up ${extra_search_path} DIRECTORY) + get_filename_component(extra_search_path_2up ${extra_search_path_1up} DIRECTORY) + find_program( + PATCH_EXECUTABLE patch HINTS "${extra_search_path_1up}/usr/bin" + "${extra_search_path_2up}/usr/bin" + ) + endif() + endif() + if(NOT PATCH_EXECUTABLE) + message(FATAL_ERROR "Couldn't find `patch` executable to use with PATCHES keyword.") + endif() + + # Create a temporary + set(temp_list ${CPM_ARGS_UNPARSED_ARGUMENTS}) + + # Ensure each file exists (or error out) and add it to the list. + set(first_item True) + foreach(PATCH_FILE ${ARGN}) + # Make sure the patch file exists, if we can't find it, try again in the current directory. + if(NOT EXISTS "${PATCH_FILE}") + if(NOT EXISTS "${CMAKE_CURRENT_LIST_DIR}/${PATCH_FILE}") + message(FATAL_ERROR "Couldn't find patch file: '${PATCH_FILE}'") + endif() + set(PATCH_FILE "${CMAKE_CURRENT_LIST_DIR}/${PATCH_FILE}") + endif() + + # Convert to absolute path for use with patch file command. + get_filename_component(PATCH_FILE "${PATCH_FILE}" ABSOLUTE) + + # The first patch entry must be preceded by "PATCH_COMMAND" while the following items are + # preceded by "&&". + if(first_item) + set(first_item False) + list(APPEND temp_list "PATCH_COMMAND") + else() + list(APPEND temp_list "&&") + endif() + # Add the patch command to the list + list(APPEND temp_list "${PATCH_EXECUTABLE}" "-p1" "<" "${PATCH_FILE}") + endforeach() + + # Move temp out into parent scope. + set(CPM_ARGS_UNPARSED_ARGUMENTS + ${temp_list} + PARENT_SCOPE + ) + +endfunction() + +# method to overwrite internal FetchContent properties, to allow using CPM.cmake to overload +# FetchContent calls. As these are internal cmake properties, this method should be used carefully +# and may need modification in future CMake versions. Source: +# https://github.com/Kitware/CMake/blob/dc3d0b5a0a7d26d43d6cfeb511e224533b5d188f/Modules/FetchContent.cmake#L1152 +function(cpm_override_fetchcontent contentName) + cmake_parse_arguments(PARSE_ARGV 1 arg "" "SOURCE_DIR;BINARY_DIR" "") + if(NOT "${arg_UNPARSED_ARGUMENTS}" STREQUAL "") + message(FATAL_ERROR "${CPM_INDENT} Unsupported arguments: ${arg_UNPARSED_ARGUMENTS}") + endif() + + string(TOLOWER ${contentName} contentNameLower) + set(prefix "_FetchContent_${contentNameLower}") + + set(propertyName "${prefix}_sourceDir") + define_property( + GLOBAL + PROPERTY ${propertyName} + BRIEF_DOCS "Internal implementation detail of FetchContent_Populate()" + FULL_DOCS "Details used by FetchContent_Populate() for ${contentName}" + ) + set_property(GLOBAL PROPERTY ${propertyName} "${arg_SOURCE_DIR}") + + set(propertyName "${prefix}_binaryDir") + define_property( + GLOBAL + PROPERTY ${propertyName} + BRIEF_DOCS "Internal implementation detail of FetchContent_Populate()" + FULL_DOCS "Details used by FetchContent_Populate() for ${contentName}" + ) + set_property(GLOBAL PROPERTY ${propertyName} "${arg_BINARY_DIR}") + + set(propertyName "${prefix}_populated") + define_property( + GLOBAL + PROPERTY ${propertyName} + BRIEF_DOCS "Internal implementation detail of FetchContent_Populate()" + FULL_DOCS "Details used by FetchContent_Populate() for ${contentName}" + ) + set_property(GLOBAL PROPERTY ${propertyName} TRUE) +endfunction() + +# Download and add a package from source +function(CPMAddPackage) + cpm_set_policies() + + set(oneValueArgs + NAME + FORCE + VERSION + GIT_TAG + DOWNLOAD_ONLY + GITHUB_REPOSITORY + GITLAB_REPOSITORY + BITBUCKET_REPOSITORY + GIT_REPOSITORY + SOURCE_DIR + FIND_PACKAGE_ARGUMENTS + NO_CACHE + SYSTEM + GIT_SHALLOW + EXCLUDE_FROM_ALL + SOURCE_SUBDIR + CUSTOM_CACHE_KEY + ) + + set(multiValueArgs URL OPTIONS DOWNLOAD_COMMAND PATCHES) + + list(LENGTH ARGN argnLength) + + # Parse single shorthand argument + if(argnLength EQUAL 1) + cpm_parse_add_package_single_arg("${ARGN}" ARGN) + + # The shorthand syntax implies EXCLUDE_FROM_ALL and SYSTEM + set(ARGN "${ARGN};EXCLUDE_FROM_ALL;YES;SYSTEM;YES;") + + # Parse URI shorthand argument + elseif(argnLength GREATER 1 AND "${ARGV0}" STREQUAL "URI") + list(REMOVE_AT ARGN 0 1) # remove "URI gh:<...>@version#tag" + cpm_parse_add_package_single_arg("${ARGV1}" ARGV0) + + set(ARGN "${ARGV0};EXCLUDE_FROM_ALL;YES;SYSTEM;YES;${ARGN}") + endif() + + cmake_parse_arguments(CPM_ARGS "" "${oneValueArgs}" "${multiValueArgs}" "${ARGN}") + + # Set default values for arguments + if(NOT DEFINED CPM_ARGS_VERSION) + if(DEFINED CPM_ARGS_GIT_TAG) + cpm_get_version_from_git_tag("${CPM_ARGS_GIT_TAG}" CPM_ARGS_VERSION) + endif() + endif() + + if(CPM_ARGS_DOWNLOAD_ONLY) + set(DOWNLOAD_ONLY ${CPM_ARGS_DOWNLOAD_ONLY}) + else() + set(DOWNLOAD_ONLY NO) + endif() + + if(DEFINED CPM_ARGS_GITHUB_REPOSITORY) + set(CPM_ARGS_GIT_REPOSITORY "https://github.com/${CPM_ARGS_GITHUB_REPOSITORY}.git") + elseif(DEFINED CPM_ARGS_GITLAB_REPOSITORY) + set(CPM_ARGS_GIT_REPOSITORY "https://gitlab.com/${CPM_ARGS_GITLAB_REPOSITORY}.git") + elseif(DEFINED CPM_ARGS_BITBUCKET_REPOSITORY) + set(CPM_ARGS_GIT_REPOSITORY "https://bitbucket.org/${CPM_ARGS_BITBUCKET_REPOSITORY}.git") + endif() + + if(DEFINED CPM_ARGS_GIT_REPOSITORY) + list(APPEND CPM_ARGS_UNPARSED_ARGUMENTS GIT_REPOSITORY ${CPM_ARGS_GIT_REPOSITORY}) + if(NOT DEFINED CPM_ARGS_GIT_TAG) + set(CPM_ARGS_GIT_TAG v${CPM_ARGS_VERSION}) + endif() + + # If a name wasn't provided, try to infer it from the git repo + if(NOT DEFINED CPM_ARGS_NAME) + cpm_package_name_from_git_uri(${CPM_ARGS_GIT_REPOSITORY} CPM_ARGS_NAME) + endif() + endif() + + set(CPM_SKIP_FETCH FALSE) + + if(DEFINED CPM_ARGS_GIT_TAG) + list(APPEND CPM_ARGS_UNPARSED_ARGUMENTS GIT_TAG ${CPM_ARGS_GIT_TAG}) + # If GIT_SHALLOW is explicitly specified, honor the value. + if(DEFINED CPM_ARGS_GIT_SHALLOW) + list(APPEND CPM_ARGS_UNPARSED_ARGUMENTS GIT_SHALLOW ${CPM_ARGS_GIT_SHALLOW}) + endif() + endif() + + if(DEFINED CPM_ARGS_URL) + # If a name or version aren't provided, try to infer them from the URL + list(GET CPM_ARGS_URL 0 firstUrl) + cpm_package_name_and_ver_from_url(${firstUrl} nameFromUrl verFromUrl) + # If we fail to obtain name and version from the first URL, we could try other URLs if any. + # However multiple URLs are expected to be quite rare, so for now we won't bother. + + # If the caller provided their own name and version, they trump the inferred ones. + if(NOT DEFINED CPM_ARGS_NAME) + set(CPM_ARGS_NAME ${nameFromUrl}) + endif() + if(NOT DEFINED CPM_ARGS_VERSION) + set(CPM_ARGS_VERSION ${verFromUrl}) + endif() + + list(APPEND CPM_ARGS_UNPARSED_ARGUMENTS URL "${CPM_ARGS_URL}") + endif() + + # Check for required arguments + + if(NOT DEFINED CPM_ARGS_NAME) + message( + FATAL_ERROR + "${CPM_INDENT} 'NAME' was not provided and couldn't be automatically inferred for package added with arguments: '${ARGN}'" + ) + endif() + + # Check if package has been added before + cpm_check_if_package_already_added(${CPM_ARGS_NAME} "${CPM_ARGS_VERSION}") + if(CPM_PACKAGE_ALREADY_ADDED) + cpm_export_variables(${CPM_ARGS_NAME}) + return() + endif() + + # Check for manual overrides + if(NOT CPM_ARGS_FORCE AND NOT "${CPM_${CPM_ARGS_NAME}_SOURCE}" STREQUAL "") + set(PACKAGE_SOURCE ${CPM_${CPM_ARGS_NAME}_SOURCE}) + set(CPM_${CPM_ARGS_NAME}_SOURCE "") + CPMAddPackage( + NAME "${CPM_ARGS_NAME}" + SOURCE_DIR "${PACKAGE_SOURCE}" + EXCLUDE_FROM_ALL "${CPM_ARGS_EXCLUDE_FROM_ALL}" + SYSTEM "${CPM_ARGS_SYSTEM}" + PATCHES "${CPM_ARGS_PATCHES}" + OPTIONS "${CPM_ARGS_OPTIONS}" + SOURCE_SUBDIR "${CPM_ARGS_SOURCE_SUBDIR}" + DOWNLOAD_ONLY "${DOWNLOAD_ONLY}" + FORCE True + ) + cpm_export_variables(${CPM_ARGS_NAME}) + return() + endif() + + # Check for available declaration + if(NOT CPM_ARGS_FORCE AND NOT "${CPM_DECLARATION_${CPM_ARGS_NAME}}" STREQUAL "") + set(declaration ${CPM_DECLARATION_${CPM_ARGS_NAME}}) + set(CPM_DECLARATION_${CPM_ARGS_NAME} "") + CPMAddPackage(${declaration}) + cpm_export_variables(${CPM_ARGS_NAME}) + # checking again to ensure version and option compatibility + cpm_check_if_package_already_added(${CPM_ARGS_NAME} "${CPM_ARGS_VERSION}") + return() + endif() + + if(NOT CPM_ARGS_FORCE) + if(CPM_USE_LOCAL_PACKAGES OR CPM_LOCAL_PACKAGES_ONLY) + cpm_find_package(${CPM_ARGS_NAME} "${CPM_ARGS_VERSION}" ${CPM_ARGS_FIND_PACKAGE_ARGUMENTS}) + + if(CPM_PACKAGE_FOUND) + cpm_export_variables(${CPM_ARGS_NAME}) + return() + endif() + + if(CPM_LOCAL_PACKAGES_ONLY) + message( + SEND_ERROR + "${CPM_INDENT} ${CPM_ARGS_NAME} not found via find_package(${CPM_ARGS_NAME} ${CPM_ARGS_VERSION})" + ) + endif() + endif() + endif() + + CPMRegisterPackage("${CPM_ARGS_NAME}" "${CPM_ARGS_VERSION}") + + if(DEFINED CPM_ARGS_GIT_TAG) + set(PACKAGE_INFO "${CPM_ARGS_GIT_TAG}") + elseif(DEFINED CPM_ARGS_SOURCE_DIR) + set(PACKAGE_INFO "${CPM_ARGS_SOURCE_DIR}") + else() + set(PACKAGE_INFO "${CPM_ARGS_VERSION}") + endif() + + if(DEFINED FETCHCONTENT_BASE_DIR) + # respect user's FETCHCONTENT_BASE_DIR if set + set(CPM_FETCHCONTENT_BASE_DIR ${FETCHCONTENT_BASE_DIR}) + else() + set(CPM_FETCHCONTENT_BASE_DIR ${CMAKE_BINARY_DIR}/_deps) + endif() + + cpm_add_patches(${CPM_ARGS_PATCHES}) + + if(DEFINED CPM_ARGS_DOWNLOAD_COMMAND) + list(APPEND CPM_ARGS_UNPARSED_ARGUMENTS DOWNLOAD_COMMAND ${CPM_ARGS_DOWNLOAD_COMMAND}) + elseif(DEFINED CPM_ARGS_SOURCE_DIR) + list(APPEND CPM_ARGS_UNPARSED_ARGUMENTS SOURCE_DIR ${CPM_ARGS_SOURCE_DIR}) + if(NOT IS_ABSOLUTE ${CPM_ARGS_SOURCE_DIR}) + # Expand `CPM_ARGS_SOURCE_DIR` relative path. This is important because EXISTS doesn't work + # for relative paths. + get_filename_component( + source_directory ${CPM_ARGS_SOURCE_DIR} REALPATH BASE_DIR ${CMAKE_CURRENT_BINARY_DIR} + ) + else() + set(source_directory ${CPM_ARGS_SOURCE_DIR}) + endif() + if(NOT EXISTS ${source_directory}) + string(TOLOWER ${CPM_ARGS_NAME} lower_case_name) + # remove timestamps so CMake will re-download the dependency + file(REMOVE_RECURSE "${CPM_FETCHCONTENT_BASE_DIR}/${lower_case_name}-subbuild") + endif() + elseif(CPM_SOURCE_CACHE AND NOT CPM_ARGS_NO_CACHE) + string(TOLOWER ${CPM_ARGS_NAME} lower_case_name) + set(origin_parameters ${CPM_ARGS_UNPARSED_ARGUMENTS}) + list(SORT origin_parameters) + if(CPM_ARGS_CUSTOM_CACHE_KEY) + # Application set a custom unique directory name + set(download_directory ${CPM_SOURCE_CACHE}/${lower_case_name}/${CPM_ARGS_CUSTOM_CACHE_KEY}) + elseif(CPM_USE_NAMED_CACHE_DIRECTORIES) + string(SHA1 origin_hash "${origin_parameters};NEW_CACHE_STRUCTURE_TAG") + cpm_get_shortest_hash( + "${CPM_SOURCE_CACHE}/${lower_case_name}" # source cache directory + "${origin_hash}" # Input hash + origin_hash # Computed hash + ) + set(download_directory ${CPM_SOURCE_CACHE}/${lower_case_name}/${origin_hash}/${CPM_ARGS_NAME}) + else() + string(SHA1 origin_hash "${origin_parameters}") + cpm_get_shortest_hash( + "${CPM_SOURCE_CACHE}/${lower_case_name}" # source cache directory + "${origin_hash}" # Input hash + origin_hash # Computed hash + ) + set(download_directory ${CPM_SOURCE_CACHE}/${lower_case_name}/${origin_hash}) + endif() + # Expand `download_directory` relative path. This is important because EXISTS doesn't work for + # relative paths. + get_filename_component(download_directory ${download_directory} ABSOLUTE) + list(APPEND CPM_ARGS_UNPARSED_ARGUMENTS SOURCE_DIR ${download_directory}) + + if(CPM_SOURCE_CACHE) + file(LOCK ${download_directory}/../cmake.lock) + endif() + + if(EXISTS ${download_directory}) + if(CPM_SOURCE_CACHE) + file(LOCK ${download_directory}/../cmake.lock RELEASE) + endif() + + cpm_store_fetch_properties( + ${CPM_ARGS_NAME} "${download_directory}" + "${CPM_FETCHCONTENT_BASE_DIR}/${lower_case_name}-build" + ) + cpm_get_fetch_properties("${CPM_ARGS_NAME}") + + if(DEFINED CPM_ARGS_GIT_TAG AND NOT (PATCH_COMMAND IN_LIST CPM_ARGS_UNPARSED_ARGUMENTS)) + # warn if cache has been changed since checkout + cpm_check_git_working_dir_is_clean(${download_directory} ${CPM_ARGS_GIT_TAG} IS_CLEAN) + if(NOT ${IS_CLEAN}) + message( + WARNING "${CPM_INDENT} Cache for ${CPM_ARGS_NAME} (${download_directory}) is dirty" + ) + endif() + endif() + + cpm_add_subdirectory( + "${CPM_ARGS_NAME}" + "${DOWNLOAD_ONLY}" + "${${CPM_ARGS_NAME}_SOURCE_DIR}/${CPM_ARGS_SOURCE_SUBDIR}" + "${${CPM_ARGS_NAME}_BINARY_DIR}" + "${CPM_ARGS_EXCLUDE_FROM_ALL}" + "${CPM_ARGS_SYSTEM}" + "${CPM_ARGS_OPTIONS}" + ) + set(PACKAGE_INFO "${PACKAGE_INFO} at ${download_directory}") + + # As the source dir is already cached/populated, we override the call to FetchContent. + set(CPM_SKIP_FETCH TRUE) + cpm_override_fetchcontent( + "${lower_case_name}" SOURCE_DIR "${${CPM_ARGS_NAME}_SOURCE_DIR}/${CPM_ARGS_SOURCE_SUBDIR}" + BINARY_DIR "${${CPM_ARGS_NAME}_BINARY_DIR}" + ) + + else() + # Enable shallow clone when GIT_TAG is not a commit hash. Our guess may not be accurate, but + # it should guarantee no commit hash get mis-detected. + if(NOT DEFINED CPM_ARGS_GIT_SHALLOW) + cpm_is_git_tag_commit_hash("${CPM_ARGS_GIT_TAG}" IS_HASH) + if(NOT ${IS_HASH}) + list(APPEND CPM_ARGS_UNPARSED_ARGUMENTS GIT_SHALLOW TRUE) + endif() + endif() + + # remove timestamps so CMake will re-download the dependency + file(REMOVE_RECURSE ${CPM_FETCHCONTENT_BASE_DIR}/${lower_case_name}-subbuild) + set(PACKAGE_INFO "${PACKAGE_INFO} to ${download_directory}") + endif() + endif() + + if(NOT "${DOWNLOAD_ONLY}") + cpm_create_module_file(${CPM_ARGS_NAME} "CPMAddPackage(\"${ARGN}\")") + endif() + + if(CPM_PACKAGE_LOCK_ENABLED) + if((CPM_ARGS_VERSION AND NOT CPM_ARGS_SOURCE_DIR) OR CPM_INCLUDE_ALL_IN_PACKAGE_LOCK) + cpm_add_to_package_lock(${CPM_ARGS_NAME} "${ARGN}") + elseif(CPM_ARGS_SOURCE_DIR) + cpm_add_comment_to_package_lock(${CPM_ARGS_NAME} "local directory") + else() + cpm_add_comment_to_package_lock(${CPM_ARGS_NAME} "${ARGN}") + endif() + endif() + + cpm_message( + STATUS "${CPM_INDENT} Adding package ${CPM_ARGS_NAME}@${CPM_ARGS_VERSION} (${PACKAGE_INFO})" + ) + + if(NOT CPM_SKIP_FETCH) + # CMake 3.28 added EXCLUDE, SYSTEM (3.25), and SOURCE_SUBDIR (3.18) to FetchContent_Declare. + # Calling FetchContent_MakeAvailable will then internally forward these options to + # add_subdirectory. Up until these changes, we had to call FetchContent_Populate and + # add_subdirectory separately, which is no longer necessary and has been deprecated as of 3.30. + # A Bug in CMake prevents us to use the non-deprecated functions until 3.30.3. + set(fetchContentDeclareExtraArgs "") + if(${CMAKE_VERSION} VERSION_GREATER_EQUAL "3.30.3") + if(${CPM_ARGS_EXCLUDE_FROM_ALL}) + list(APPEND fetchContentDeclareExtraArgs EXCLUDE_FROM_ALL) + endif() + if(${CPM_ARGS_SYSTEM}) + list(APPEND fetchContentDeclareExtraArgs SYSTEM) + endif() + if(DEFINED CPM_ARGS_SOURCE_SUBDIR) + list(APPEND fetchContentDeclareExtraArgs SOURCE_SUBDIR ${CPM_ARGS_SOURCE_SUBDIR}) + endif() + # For CMake version <3.28 OPTIONS are parsed in cpm_add_subdirectory + if(CPM_ARGS_OPTIONS AND NOT DOWNLOAD_ONLY) + foreach(OPTION ${CPM_ARGS_OPTIONS}) + cpm_parse_option("${OPTION}") + set(${OPTION_KEY} "${OPTION_VALUE}") + endforeach() + endif() + endif() + cpm_declare_fetch( + "${CPM_ARGS_NAME}" ${fetchContentDeclareExtraArgs} "${CPM_ARGS_UNPARSED_ARGUMENTS}" + ) + + cpm_fetch_package("${CPM_ARGS_NAME}" ${DOWNLOAD_ONLY} populated ${CPM_ARGS_UNPARSED_ARGUMENTS}) + if(CPM_SOURCE_CACHE AND download_directory) + file(LOCK ${download_directory}/../cmake.lock RELEASE) + endif() + if(${populated} AND ${CMAKE_VERSION} VERSION_LESS "3.30.3") + cpm_add_subdirectory( + "${CPM_ARGS_NAME}" + "${DOWNLOAD_ONLY}" + "${${CPM_ARGS_NAME}_SOURCE_DIR}/${CPM_ARGS_SOURCE_SUBDIR}" + "${${CPM_ARGS_NAME}_BINARY_DIR}" + "${CPM_ARGS_EXCLUDE_FROM_ALL}" + "${CPM_ARGS_SYSTEM}" + "${CPM_ARGS_OPTIONS}" + ) + endif() + cpm_get_fetch_properties("${CPM_ARGS_NAME}") + endif() + + set(${CPM_ARGS_NAME}_ADDED YES) + cpm_export_variables("${CPM_ARGS_NAME}") +endfunction() + +# Fetch a previously declared package +macro(CPMGetPackage Name) + if(DEFINED "CPM_DECLARATION_${Name}") + CPMAddPackage(NAME ${Name}) + else() + message(SEND_ERROR "${CPM_INDENT} Cannot retrieve package ${Name}: no declaration available") + endif() +endmacro() + +# export variables available to the caller to the parent scope expects ${CPM_ARGS_NAME} to be set +macro(cpm_export_variables name) + set(${name}_SOURCE_DIR + "${${name}_SOURCE_DIR}" + PARENT_SCOPE + ) + set(${name}_BINARY_DIR + "${${name}_BINARY_DIR}" + PARENT_SCOPE + ) + set(${name}_ADDED + "${${name}_ADDED}" + PARENT_SCOPE + ) + set(CPM_LAST_PACKAGE_NAME + "${name}" + PARENT_SCOPE + ) +endmacro() + +# declares a package, so that any call to CPMAddPackage for the package name will use these +# arguments instead. Previous declarations will not be overridden. +macro(CPMDeclarePackage Name) + if(NOT DEFINED "CPM_DECLARATION_${Name}") + set("CPM_DECLARATION_${Name}" "${ARGN}") + endif() +endmacro() + +function(cpm_add_to_package_lock Name) + if(NOT CPM_DONT_CREATE_PACKAGE_LOCK) + cpm_prettify_package_arguments(PRETTY_ARGN false ${ARGN}) + file(APPEND ${CPM_PACKAGE_LOCK_FILE} "# ${Name}\nCPMDeclarePackage(${Name}\n${PRETTY_ARGN})\n") + endif() +endfunction() + +function(cpm_add_comment_to_package_lock Name) + if(NOT CPM_DONT_CREATE_PACKAGE_LOCK) + cpm_prettify_package_arguments(PRETTY_ARGN true ${ARGN}) + file(APPEND ${CPM_PACKAGE_LOCK_FILE} + "# ${Name} (unversioned)\n# CPMDeclarePackage(${Name}\n${PRETTY_ARGN}#)\n" + ) + endif() +endfunction() + +# includes the package lock file if it exists and creates a target `cpm-update-package-lock` to +# update it +macro(CPMUsePackageLock file) + if(NOT CPM_DONT_CREATE_PACKAGE_LOCK) + get_filename_component(CPM_ABSOLUTE_PACKAGE_LOCK_PATH ${file} ABSOLUTE) + if(EXISTS ${CPM_ABSOLUTE_PACKAGE_LOCK_PATH}) + include(${CPM_ABSOLUTE_PACKAGE_LOCK_PATH}) + endif() + if(NOT TARGET cpm-update-package-lock) + add_custom_target( + cpm-update-package-lock COMMAND ${CMAKE_COMMAND} -E copy ${CPM_PACKAGE_LOCK_FILE} + ${CPM_ABSOLUTE_PACKAGE_LOCK_PATH} + ) + endif() + set(CPM_PACKAGE_LOCK_ENABLED true) + endif() +endmacro() + +# registers a package that has been added to CPM +function(CPMRegisterPackage PACKAGE VERSION) + list(APPEND CPM_PACKAGES ${PACKAGE}) + set(CPM_PACKAGES + ${CPM_PACKAGES} + CACHE INTERNAL "" + ) + set("CPM_PACKAGE_${PACKAGE}_VERSION" + ${VERSION} + CACHE INTERNAL "" + ) +endfunction() + +# retrieve the current version of the package to ${OUTPUT} +function(CPMGetPackageVersion PACKAGE OUTPUT) + set(${OUTPUT} + "${CPM_PACKAGE_${PACKAGE}_VERSION}" + PARENT_SCOPE + ) +endfunction() + +# declares a package in FetchContent_Declare +function(cpm_declare_fetch PACKAGE) + if(${CPM_DRY_RUN}) + cpm_message(STATUS "${CPM_INDENT} Package not declared (dry run)") + return() + endif() + + FetchContent_Declare(${PACKAGE} ${ARGN}) +endfunction() + +# returns properties for a package previously defined by cpm_declare_fetch +function(cpm_get_fetch_properties PACKAGE) + if(${CPM_DRY_RUN}) + return() + endif() + + set(${PACKAGE}_SOURCE_DIR + "${CPM_PACKAGE_${PACKAGE}_SOURCE_DIR}" + PARENT_SCOPE + ) + set(${PACKAGE}_BINARY_DIR + "${CPM_PACKAGE_${PACKAGE}_BINARY_DIR}" + PARENT_SCOPE + ) +endfunction() + +function(cpm_store_fetch_properties PACKAGE source_dir binary_dir) + if(${CPM_DRY_RUN}) + return() + endif() + + set(CPM_PACKAGE_${PACKAGE}_SOURCE_DIR + "${source_dir}" + CACHE INTERNAL "" + ) + set(CPM_PACKAGE_${PACKAGE}_BINARY_DIR + "${binary_dir}" + CACHE INTERNAL "" + ) +endfunction() + +# adds a package as a subdirectory if viable, according to provided options +function( + cpm_add_subdirectory + PACKAGE + DOWNLOAD_ONLY + SOURCE_DIR + BINARY_DIR + EXCLUDE + SYSTEM + OPTIONS +) + + if(NOT DOWNLOAD_ONLY AND EXISTS ${SOURCE_DIR}/CMakeLists.txt) + set(addSubdirectoryExtraArgs "") + if(EXCLUDE) + list(APPEND addSubdirectoryExtraArgs EXCLUDE_FROM_ALL) + endif() + if("${SYSTEM}" AND "${CMAKE_VERSION}" VERSION_GREATER_EQUAL "3.25") + # https://cmake.org/cmake/help/latest/prop_dir/SYSTEM.html#prop_dir:SYSTEM + list(APPEND addSubdirectoryExtraArgs SYSTEM) + endif() + if(OPTIONS) + foreach(OPTION ${OPTIONS}) + cpm_parse_option("${OPTION}") + set(${OPTION_KEY} "${OPTION_VALUE}") + endforeach() + endif() + set(CPM_OLD_INDENT "${CPM_INDENT}") + set(CPM_INDENT "${CPM_INDENT} ${PACKAGE}:") + add_subdirectory(${SOURCE_DIR} ${BINARY_DIR} ${addSubdirectoryExtraArgs}) + set(CPM_INDENT "${CPM_OLD_INDENT}") + endif() +endfunction() + +# downloads a previously declared package via FetchContent and exports the variables +# `${PACKAGE}_SOURCE_DIR` and `${PACKAGE}_BINARY_DIR` to the parent scope +function(cpm_fetch_package PACKAGE DOWNLOAD_ONLY populated) + set(${populated} + FALSE + PARENT_SCOPE + ) + if(${CPM_DRY_RUN}) + cpm_message(STATUS "${CPM_INDENT} Package ${PACKAGE} not fetched (dry run)") + return() + endif() + + FetchContent_GetProperties(${PACKAGE}) + + string(TOLOWER "${PACKAGE}" lower_case_name) + + if(NOT ${lower_case_name}_POPULATED) + if(${CMAKE_VERSION} VERSION_GREATER_EQUAL "3.30.3") + if(DOWNLOAD_ONLY) + # MakeAvailable will call add_subdirectory internally which is not what we want when + # DOWNLOAD_ONLY is set. Populate will only download the dependency without adding it to the + # build + FetchContent_Populate( + ${PACKAGE} + SOURCE_DIR "${CPM_FETCHCONTENT_BASE_DIR}/${lower_case_name}-src" + BINARY_DIR "${CPM_FETCHCONTENT_BASE_DIR}/${lower_case_name}-build" + SUBBUILD_DIR "${CPM_FETCHCONTENT_BASE_DIR}/${lower_case_name}-subbuild" + ${ARGN} + ) + else() + FetchContent_MakeAvailable(${PACKAGE}) + endif() + else() + FetchContent_Populate(${PACKAGE}) + endif() + set(${populated} + TRUE + PARENT_SCOPE + ) + endif() + + cpm_store_fetch_properties( + ${CPM_ARGS_NAME} ${${lower_case_name}_SOURCE_DIR} ${${lower_case_name}_BINARY_DIR} + ) + + set(${PACKAGE}_SOURCE_DIR + ${${lower_case_name}_SOURCE_DIR} + PARENT_SCOPE + ) + set(${PACKAGE}_BINARY_DIR + ${${lower_case_name}_BINARY_DIR} + PARENT_SCOPE + ) +endfunction() + +# splits a package option +function(cpm_parse_option OPTION) + string(REGEX MATCH "^[^ ]+" OPTION_KEY "${OPTION}") + string(LENGTH "${OPTION}" OPTION_LENGTH) + string(LENGTH "${OPTION_KEY}" OPTION_KEY_LENGTH) + if(OPTION_KEY_LENGTH STREQUAL OPTION_LENGTH) + # no value for key provided, assume user wants to set option to "ON" + set(OPTION_VALUE "ON") + else() + math(EXPR OPTION_KEY_LENGTH "${OPTION_KEY_LENGTH}+1") + string(SUBSTRING "${OPTION}" "${OPTION_KEY_LENGTH}" "-1" OPTION_VALUE) + endif() + set(OPTION_KEY + "${OPTION_KEY}" + PARENT_SCOPE + ) + set(OPTION_VALUE + "${OPTION_VALUE}" + PARENT_SCOPE + ) +endfunction() + +# guesses the package version from a git tag +function(cpm_get_version_from_git_tag GIT_TAG RESULT) + string(LENGTH ${GIT_TAG} length) + if(length EQUAL 40) + # GIT_TAG is probably a git hash + set(${RESULT} + 0 + PARENT_SCOPE + ) + else() + string(REGEX MATCH "v?([0123456789.]*).*" _ ${GIT_TAG}) + set(${RESULT} + ${CMAKE_MATCH_1} + PARENT_SCOPE + ) + endif() +endfunction() + +# guesses if the git tag is a commit hash or an actual tag or a branch name. +function(cpm_is_git_tag_commit_hash GIT_TAG RESULT) + string(LENGTH "${GIT_TAG}" length) + # full hash has 40 characters, and short hash has at least 7 characters. + if(length LESS 7 OR length GREATER 40) + set(${RESULT} + 0 + PARENT_SCOPE + ) + else() + if(${GIT_TAG} MATCHES "^[a-fA-F0-9]+$") + set(${RESULT} + 1 + PARENT_SCOPE + ) + else() + set(${RESULT} + 0 + PARENT_SCOPE + ) + endif() + endif() +endfunction() + +function(cpm_prettify_package_arguments OUT_VAR IS_IN_COMMENT) + set(oneValueArgs + NAME + FORCE + VERSION + GIT_TAG + DOWNLOAD_ONLY + GITHUB_REPOSITORY + GITLAB_REPOSITORY + BITBUCKET_REPOSITORY + GIT_REPOSITORY + SOURCE_DIR + FIND_PACKAGE_ARGUMENTS + NO_CACHE + SYSTEM + GIT_SHALLOW + EXCLUDE_FROM_ALL + SOURCE_SUBDIR + ) + set(multiValueArgs URL OPTIONS DOWNLOAD_COMMAND) + cmake_parse_arguments(CPM_ARGS "" "${oneValueArgs}" "${multiValueArgs}" ${ARGN}) + + foreach(oneArgName ${oneValueArgs}) + if(DEFINED CPM_ARGS_${oneArgName}) + if(${IS_IN_COMMENT}) + string(APPEND PRETTY_OUT_VAR "#") + endif() + if(${oneArgName} STREQUAL "SOURCE_DIR") + string(REPLACE ${CMAKE_SOURCE_DIR} "\${CMAKE_SOURCE_DIR}" CPM_ARGS_${oneArgName} + ${CPM_ARGS_${oneArgName}} + ) + endif() + string(APPEND PRETTY_OUT_VAR " ${oneArgName} ${CPM_ARGS_${oneArgName}}\n") + endif() + endforeach() + foreach(multiArgName ${multiValueArgs}) + if(DEFINED CPM_ARGS_${multiArgName}) + if(${IS_IN_COMMENT}) + string(APPEND PRETTY_OUT_VAR "#") + endif() + string(APPEND PRETTY_OUT_VAR " ${multiArgName}\n") + foreach(singleOption ${CPM_ARGS_${multiArgName}}) + if(${IS_IN_COMMENT}) + string(APPEND PRETTY_OUT_VAR "#") + endif() + string(APPEND PRETTY_OUT_VAR " \"${singleOption}\"\n") + endforeach() + endif() + endforeach() + + if(NOT "${CPM_ARGS_UNPARSED_ARGUMENTS}" STREQUAL "") + if(${IS_IN_COMMENT}) + string(APPEND PRETTY_OUT_VAR "#") + endif() + string(APPEND PRETTY_OUT_VAR " ") + foreach(CPM_ARGS_UNPARSED_ARGUMENT ${CPM_ARGS_UNPARSED_ARGUMENTS}) + string(APPEND PRETTY_OUT_VAR " ${CPM_ARGS_UNPARSED_ARGUMENT}") + endforeach() + string(APPEND PRETTY_OUT_VAR "\n") + endif() + + set(${OUT_VAR} + ${PRETTY_OUT_VAR} + PARENT_SCOPE + ) + +endfunction() diff --git a/examples/serial_echo.ts b/examples/serial_echo.ts new file mode 100644 index 0000000..91c6fcd --- /dev/null +++ b/examples/serial_echo.ts @@ -0,0 +1,134 @@ +// @ts-nocheck +// deno run --allow-ffi --allow-read examples/serial_echo.ts + +interface CliOptions { + lib: string; + port?: string; +} + +function parseArgs(): CliOptions { + const opts: CliOptions = { lib: "./build/libCPP-Unix-Bindings.so" }; + + for (let i = 0; i < Deno.args.length; ++i) { + const arg = Deno.args[i]; + if (arg === "--lib" && i + 1 < Deno.args.length) { + opts.lib = Deno.args[++i]; + } else if (arg === "--port" && i + 1 < Deno.args.length) { + opts.port = Deno.args[++i]; + } else { + console.warn(`Unknown argument '${arg}' ignored.`); + } + } + return opts; +} + +// ----------------------------------------------------------------------------- +// Helper utilities for C interop +// ----------------------------------------------------------------------------- +const encoder = new TextEncoder(); +const decoder = new TextDecoder(); + +function cString(str: string): Uint8Array { + // Encodes JavaScript string as null-terminated UTF-8 byte array. + const bytes = encoder.encode(str); + const buf = new Uint8Array(bytes.length + 1); + buf.set(bytes, 0); + buf[bytes.length] = 0; + return buf; +} + +function pointer(view: Uint8Array): Deno.UnsafePointer { + return Deno.UnsafePointer.of(view) as Deno.UnsafePointer; +} + +// ----------------------------------------------------------------------------- +// Load dynamic library +// ----------------------------------------------------------------------------- +const { lib, port: cliPort } = parseArgs(); + +const dylib = Deno.dlopen( + lib, + { + serialOpen: { parameters: ["pointer", "i32", "i32", "i32", "i32"], result: "pointer" }, + serialClose: { parameters: ["pointer"], result: "void" }, + serialWrite: { parameters: ["pointer", "pointer", "i32", "i32", "i32"], result: "i32" }, + serialReadUntil: { + parameters: ["pointer", "pointer", "i32", "i32", "i32", "pointer"], + result: "i32", + }, + serialGetPortsInfo: { parameters: ["pointer", "i32", "pointer"], result: "i32" }, + } as const, +); + +// ----------------------------------------------------------------------------- +// 1. List available ports +// ----------------------------------------------------------------------------- +const sepBuf = cString(";"); +const portsBuf = new Uint8Array(4096); +dylib.symbols.serialGetPortsInfo( + pointer(portsBuf), + portsBuf.length, + pointer(sepBuf), +); + +const cPortsStr = decoder.decode(portsBuf.subarray(0, portsBuf.indexOf(0))); +const ports = cPortsStr ? cPortsStr.split(";") : []; +console.log("Available ports:"); +for (const p of ports) { + console.log(" •", p); +} +if (ports.length === 0) { + console.error("No serial ports found (ttyUSB). Exiting."); + dylib.close(); + Deno.exit(1); +} + +// ----------------------------------------------------------------------------- +// 2. Echo test on selected port +// ----------------------------------------------------------------------------- +const portPath = cliPort ?? ports[0]; +console.log(`\nUsing port: ${portPath}`); + +const portBuf = cString(portPath); +const handle = dylib.symbols.serialOpen(pointer(portBuf), 115200, 8, 0, 0); +if (handle === null) { + console.error("Failed to open port!"); + dylib.close(); + Deno.exit(1); +} + +// Give MCU a moment to reboot (similar to C++ tests) +await new Promise((r) => setTimeout(r, 2000)); + +const msg = "HELLO\n"; +const msgBuf = encoder.encode(msg); +const written = dylib.symbols.serialWrite(handle, pointer(msgBuf), msgBuf.length, 100, 1); +if (written !== msgBuf.length) { + console.error(`Write failed (wrote ${written}/${msgBuf.length})`); + dylib.symbols.serialClose(handle); + dylib.close(); + Deno.exit(1); +} + +const readBuf = new Uint8Array(64); +const untilBuf = new Uint8Array(["\n".charCodeAt(0)]); + +const read = dylib.symbols.serialReadUntil(handle, pointer(readBuf), readBuf.length, 500, 1, pointer(untilBuf)); +if (read <= 0) { + console.error("Read failed or timed out."); + dylib.symbols.serialClose(handle); + dylib.close(); + Deno.exit(1); +} + +const echo = decoder.decode(readBuf.subarray(0, read)); +console.log(`Echo response (${read} bytes): '${echo}'`); + +if (echo === msg) { + console.log("Echo test: ✅ success"); +} else { + console.error("Echo test: ❌ mismatch"); +} + +dylib.symbols.serialClose(handle); +dylib.close(); diff --git a/src/error/error_helpers.h b/src/error/error_helpers.h deleted file mode 100644 index 92f56a0..0000000 --- a/src/error/error_helpers.h +++ /dev/null @@ -1,6 +0,0 @@ -#pragma once - -template -constexpr auto error(const T& stat) -> int { - return static_cast(stat); -} \ No newline at end of file diff --git a/src/error/init_comm_state_errors.h b/src/error/init_comm_state_errors.h deleted file mode 100644 index 5de7bfb..0000000 --- a/src/error/init_comm_state_errors.h +++ /dev/null @@ -1,7 +0,0 @@ -#pragma once - -enum class initCommStateErrors { - GET_COMM_STATE = -1, - SET_COMM_STATE = -2 -}; - diff --git a/src/error/init_timeouts_errors.h b/src/error/init_timeouts_errors.h deleted file mode 100644 index 7cb8d2e..0000000 --- a/src/error/init_timeouts_errors.h +++ /dev/null @@ -1,7 +0,0 @@ -#pragma once - -enum class initTimeoutsErrors { - GET_COMM_TIMEOUTS = -1, - SET_COMM_TIMEOUTS = -2 -}; - diff --git a/src/error/open_errors.h b/src/error/open_errors.h deleted file mode 100644 index ec000bc..0000000 --- a/src/error/open_errors.h +++ /dev/null @@ -1,7 +0,0 @@ -#pragma once - -enum class openErrors { - INVALID_HANDLE = -1, - SET_COMM_STATE_ERROR = -2 -}; - diff --git a/src/functions/serial_close.cpp b/src/functions/serial_close.cpp deleted file mode 100644 index e69de29..0000000 diff --git a/src/functions/serial_close.h b/src/functions/serial_close.h deleted file mode 100644 index e69de29..0000000 diff --git a/src/functions/serial_open.cpp b/src/functions/serial_open.cpp deleted file mode 100644 index e69de29..0000000 diff --git a/src/functions/serial_open.h b/src/functions/serial_open.h deleted file mode 100644 index e69de29..0000000 diff --git a/src/functions/serial_read.cpp b/src/functions/serial_read.cpp deleted file mode 100644 index e69de29..0000000 diff --git a/src/functions/serial_read.h b/src/functions/serial_read.h deleted file mode 100644 index e69de29..0000000 diff --git a/src/functions/serial_write.cpp b/src/functions/serial_write.cpp deleted file mode 100644 index e69de29..0000000 diff --git a/src/functions/serial_write.h b/src/functions/serial_write.h deleted file mode 100644 index e69de29..0000000 diff --git a/src/serial.cpp b/src/serial.cpp new file mode 100644 index 0000000..82aec05 --- /dev/null +++ b/src/serial.cpp @@ -0,0 +1,402 @@ +#include "serial.h" + +#include "status_codes.h" + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +// ----------------------------------------------------------------------------- +// Global callback function pointers (default nullptr) +// ----------------------------------------------------------------------------- +void (*error_callback)(int) = nullptr; +void (*read_callback)(int) = nullptr; +void (*write_callback)(int) = nullptr; + +// ----------------------------------------------------------------------------- +// Internal helpers & types +// ----------------------------------------------------------------------------- +namespace +{ + +struct SerialPortHandle +{ + int fd; + termios original; // keep original settings so we can restore on close +}; + +// Map integer baudrate to POSIX speed_t. Only common rates are supported. +auto to_speed_t(int baud) -> speed_t +{ + switch (baud) + { + case 0: + return B0; + case 50: + return B50; + case 75: + return B75; + case 110: + return B110; + case 134: + return B134; + case 150: + return B150; + case 200: + return B200; + case 300: + return B300; + case 600: + return B600; + case 1200: + return B1200; + case 1800: + return B1800; + case 2400: + return B2400; + case 4800: + return B4800; + case 9600: + return B9600; + case 19200: + return B19200; + case 38400: + return B38400; + case 57600: + return B57600; + case 115200: + return B115200; + case 230400: + return B230400; +#ifdef B460800 + case 460800: + return B460800; +#endif +#ifdef B921600 + case 921600: + return B921600; +#endif + default: + return B9600; // fallback + } +} + +inline void invokeError(int code) +{ + if (error_callback != nullptr) + { + error_callback(code); + } +} + +} // namespace + +// ----------------------------------------------------------------------------- +// Public API implementation +// ----------------------------------------------------------------------------- + +intptr_t serialOpen(void* port, int baudrate, int dataBits, int parity, int stopBits) +{ + if (port == nullptr) + { + invokeError(std::to_underlying(StatusCodes::INVALID_HANDLE_ERROR)); + return 0; + } + + auto port_name = std::string_view{static_cast(port)}; + int fd = open(port_name.data(), O_RDWR | O_NOCTTY | O_SYNC); + if (fd < 0) + { + invokeError(std::to_underlying(StatusCodes::INVALID_HANDLE_ERROR)); + return 0; + } + + auto* handle = new SerialPortHandle{.fd = fd, .original = {}}; + + termios tty{}; + if (tcgetattr(fd, &tty) != 0) + { + invokeError(std::to_underlying(StatusCodes::GET_STATE_ERROR)); + close(fd); + delete handle; + return 0; + } + handle->original = tty; // save original + + // Basic flags: local connection, enable receiver + tty.c_cflag |= (CLOCAL | CREAD); + + // Baudrate + const speed_t speed = to_speed_t(baudrate); + cfsetispeed(&tty, speed); + cfsetospeed(&tty, speed); + + // Data bits + tty.c_cflag &= ~CSIZE; + switch (dataBits) + { + case 5: + tty.c_cflag |= CS5; + break; + case 6: + tty.c_cflag |= CS6; + break; + case 7: + tty.c_cflag |= CS7; + break; + default: + tty.c_cflag |= CS8; + break; + } + + // Parity + if (parity == 0) + { + tty.c_cflag &= ~PARENB; + } + else + { + tty.c_cflag |= PARENB; + if (parity == 1) + { + tty.c_cflag &= ~PARODD; // even + } + else + { + tty.c_cflag |= PARODD; // odd + } + } + + // Stop bits + if (stopBits == 2) + { + tty.c_cflag |= CSTOPB; + } + else + { + tty.c_cflag &= ~CSTOPB; + } + + // Raw mode (no echo/processing) + tty.c_iflag = 0; + tty.c_oflag = 0; + tty.c_lflag = 0; + + tty.c_cc[VMIN] = 0; // non-blocking by default + tty.c_cc[VTIME] = 10; // 1s read timeout + + if (tcsetattr(fd, TCSANOW, &tty) != 0) + { + invokeError(std::to_underlying(StatusCodes::SET_STATE_ERROR)); + close(fd); + delete handle; + return 0; + } + + return reinterpret_cast(handle); +} + +void serialClose(int64_t handlePtr) +{ + auto* handle = reinterpret_cast(handlePtr); + if (handle == nullptr) + { + return; + } + + tcsetattr(handle->fd, TCSANOW, &handle->original); // restore + if (close(handle->fd) != 0) + { + invokeError(std::to_underlying(StatusCodes::CLOSE_HANDLE_ERROR)); + } + delete handle; +} + +static int waitFdReady(int fd, int timeoutMs, bool wantWrite) +{ + timeoutMs = std::max(timeoutMs, 0); + + fd_set set; + FD_ZERO(&set); + FD_SET(fd, &set); + + timeval tv{}; + tv.tv_sec = timeoutMs / 1000; + tv.tv_usec = (timeoutMs % 1000) * 1000; + + int res = select(fd + 1, wantWrite ? nullptr : &set, wantWrite ? &set : nullptr, nullptr, &tv); + return res; // 0 timeout, -1 error, >0 ready +} + +int serialRead(int64_t handlePtr, void* buffer, int bufferSize, int timeout, int /*multiplier*/) +{ + auto* handle = reinterpret_cast(handlePtr); + if (handle == nullptr) + { + invokeError(std::to_underlying(StatusCodes::INVALID_HANDLE_ERROR)); + return 0; + } + + if (waitFdReady(handle->fd, timeout, false) <= 0) + { + return 0; // timeout or error (we ignore error for now) + } + + ssize_t n = read(handle->fd, buffer, bufferSize); + if (n < 0) + { + invokeError(std::to_underlying(StatusCodes::READ_ERROR)); + return 0; + } + if (read_callback != nullptr) + { + read_callback(static_cast(n)); + } + return static_cast(n); +} + +int serialWrite(int64_t handlePtr, const void* buffer, int bufferSize, int timeout, int /*multiplier*/) +{ + auto* handle = reinterpret_cast(handlePtr); + if (handle == nullptr) + { + invokeError(std::to_underlying(StatusCodes::INVALID_HANDLE_ERROR)); + return 0; + } + + if (waitFdReady(handle->fd, timeout, true) <= 0) + { + return 0; // timeout or error + } + + ssize_t n = write(handle->fd, buffer, bufferSize); + if (n < 0) + { + invokeError(std::to_underlying(StatusCodes::WRITE_ERROR)); + return 0; + } + if (write_callback != nullptr) + { + write_callback(static_cast(n)); + } + return static_cast(n); +} + +int serialReadUntil(int64_t handlePtr, void* buffer, int bufferSize, int timeout, int /*multiplier*/, void* untilCharPtr) +{ + auto* handle = reinterpret_cast(handlePtr); + if (handle == nullptr) + { + invokeError(std::to_underlying(StatusCodes::INVALID_HANDLE_ERROR)); + return 0; + } + + char until_char = *static_cast(untilCharPtr); + int total = 0; + auto* buf = static_cast(buffer); + + while (total < bufferSize) + { + int res = serialRead(handlePtr, buf + total, 1, timeout, 1); + if (res <= 0) + { + break; // timeout or error + } + if (buf[total] == until_char) + { + total += 1; + break; + } + total += res; + } + + if (read_callback != nullptr) + { + read_callback(total); + } + return total; +} + +int serialGetPortsInfo(void* buffer, int bufferSize, void* separatorPtr) +{ + auto sep = std::string_view{static_cast(separatorPtr)}; + std::string result; + + namespace fs = std::filesystem; + + const fs::path by_id_dir{"/dev/serial/by-id"}; + if (!fs::exists(by_id_dir) || !fs::is_directory(by_id_dir)) + { + invokeError(std::to_underlying(StatusCodes::NOT_FOUND_ERROR)); + return 0; + } + + try + { + for (const auto& entry : fs::directory_iterator{by_id_dir}) + { + if (!entry.is_symlink()) + { + continue; + } + + std::error_code ec; + fs::path canonical = fs::canonical(entry.path(), ec); + if (ec) + { + continue; // skip entries we cannot resolve + } + + result += canonical.string(); + result += sep; + } + } + catch (const fs::filesystem_error&) + { + invokeError(std::to_underlying(StatusCodes::NOT_FOUND_ERROR)); + return 0; + } + + if (!result.empty()) + { + // Remove the trailing separator + result.erase(result.size() - sep.size()); + } + + if (static_cast(result.size()) + 1 > bufferSize) + { + invokeError(std::to_underlying(StatusCodes::BUFFER_ERROR)); + return 0; + } + + std::memcpy(buffer, result.c_str(), result.size() + 1); + return result.empty() ? 0 : 1; // number of ports not easily counted here +} + +// Currently stubbed helpers (no-ops) +void serialClearBufferIn(int64_t /*unused*/) {} +void serialClearBufferOut(int64_t /*unused*/) {} +void serialAbortRead(int64_t /*unused*/) {} +void serialAbortWrite(int64_t /*unused*/) {} + +// Callback registration +void serialOnError(void (*func)(int code)) +{ + error_callback = func; +} +void serialOnRead(void (*func)(int bytes)) +{ + read_callback = func; +} +void serialOnWrite(void (*func)(int bytes)) +{ + write_callback = func; +} diff --git a/src/serial.cpp.txt b/src/serial.cpp.txt deleted file mode 100644 index 2b40e3d..0000000 --- a/src/serial.cpp.txt +++ /dev/null @@ -1,271 +0,0 @@ -// #include -// #include -// #include // File control definitions -// #include // Used for TCGETS2, which is required for custom baud rates -// #include // UNIX standard function definitions - -// #include -// #include -// #include - -// #include "serial.h" - -// namespace { -// static int hSerialPort; -// static termios2 tty; -// static std::string data; -// } // namespace - -// void (*errorCallback)(int errorCode); -// void (*readCallback)(int bytes); -// void (*writeCallback)(int bytes); - -// auto serialOpen(void* port, -// const int baudrate, -// const int dataBits, -// const int parity, -// const int stopBits) -> intptr_t { -// char* portName = static_cast(port); -// // Open new serial connection -// hSerialPort = open(portName, O_RDWR); - -// // Error if open fails -// if (hSerialPort == -1) { -// errorCallback(status(StatusCodes::INVALID_HANDLE_ERROR)); -// return -1; -// } - -// // Get the current com configuration -// if (ioctl(hSerialPort, TCGETS2, &tty) == -1) { -// errorCallback(status(StatusCodes::GET_STATE_ERROR)); -// return -1; -// } - -// // clang-format off -// tty.c_cflag &= ~PARENB; // Clear parity bit, disabling parity (most common) -// tty.c_cflag &= ~CSTOPB; // Clear stop field, only one stop bit used in communication (most common) -// tty.c_cflag &= ~CSIZE; // Clear all bits that set the data size -// tty.c_cflag |= CS8; // 8 bits per byte (most common) -// tty.c_cflag &= ~CRTSCTS; // Disable RTS/CTS hardware flow control (most common) -// tty.c_cflag |= CREAD | CLOCAL; // Turn on READ & ignore ctrl lines (CLOCAL = 1) - -// tty.c_lflag &= ~ICANON; -// tty.c_lflag &= ~ECHO; // Disable echo -// tty.c_lflag &= ~ECHOE; // Disable erasure -// tty.c_lflag &= ~ECHONL; // Disable new-line echo -// tty.c_lflag &= ~ISIG; // Disable interpretation of INTR, QUIT and SUSP -// tty.c_iflag &= ~(IXON | IXOFF | IXANY); // Turn off s/w flow ctrl -// tty.c_iflag &= ~(IGNBRK | BRKINT | PARMRK | ISTRIP | INLCR | IGNCR | ICRNL); // Disable any special handling of received bytes -// tty.c_oflag &= ~OPOST; // Prevent special interpretation of output bytes (e.g. newline chars) -// tty.c_oflag &= ~ONLCR; // Prevent conversion of newline to carriage return/line feed - -// tty.c_cc[VTIME] = 10; // Wait for up to 1s (10 deciseconds), returning as soon as any data is received. -// tty.c_cc[VMIN] = 0; -// // clang-format on - -// // Set in/out baud rate to be 9600 -// // cfsetispeed(&tty, B9600); -// // cfsetospeed(&tty, B9600); -// tty.c_ispeed = baudrate; -// tty.c_ospeed = baudrate; - -// // Data bits -// tty.c_cflag &= -// ~CSIZE; // CSIZE is a mask for the number of bits per character - -// switch (dataBits) { -// case 5: -// tty.c_cflag |= CS5; -// break; -// case 6: -// tty.c_cflag |= CS6; -// break; -// case 7: -// tty.c_cflag |= CS7; -// break; -// default: -// tty.c_cflag |= CS8; -// break; -// } - -// // parity -// switch (parity) { -// case 0: -// tty.c_cflag &= ~PARENB; -// break; -// case 1: -// tty.c_cflag |= PARENB; -// tty.c_cflag &= ~PARODD; // Clearing PARODD makes the parity even -// break; -// case 2: -// tty.c_cflag |= PARENB; -// tty.c_cflag |= PARODD; -// break; -// } - -// // stop bits -// // Set num. stop bits -// switch (stopBits) { -// case 0: -// tty.c_cflag &= ~CSTOPB; -// break; -// // TODO case 1: 1.5 would break the code -// case 2: -// tty.c_cflag |= CSTOPB; -// break; -// } - -// // Save tty settings, also checking for error -// if (ioctl(hSerialPort, TCSETS2, &tty) == -1) { -// errorCallback(status(StatusCodes::SET_STATE_ERROR)); -// return -1; -// } - -// return static_cast(hSerialPort); -// } - -// void serialClose(int64_t pointer) { -// // Error if close fails -// if (close(hSerialPort) == -1) { -// errorCallback(status(StatusCodes::CLOSE_HANDLE_ERROR)); -// return; -// } - -// return; -// } - -// auto serialRead(int64_t pointer, -// void* buffer, -// const int bufferSize, -// const int timeout, -// const int multiplier) -> int { -// if (ioctl(hSerialPort, TCGETS2, &tty) == -1) { -// errorCallback(status(StatusCodes::SET_STATE_ERROR)); -// return 0; -// } - -// if (timeout > 0 && timeout < 100) { -// tty.c_cc[VTIME] = 1; -// } else { -// tty.c_cc[VTIME] = timeout / 100; -// } - -// tty.c_cc[VMIN] = bufferSize; - -// if (ioctl(hSerialPort, TCSETS2, &tty) == -1) { -// errorCallback(status(StatusCodes::SET_STATE_ERROR)); -// return 0; -// } - -// int bytesRead = read(hSerialPort, static_cast(buffer), bufferSize); - -// if (bytesRead >= 0) { -// return bytesRead; -// } - -// errorCallback(status(StatusCodes::READ_ERROR)); -// return 0; -// } - -// auto serialReadUntil(int64_t pointer, -// void* buffer, -// const int bufferSize, -// const int timeout, -// const int multiplier, -// void* searchString) -> int { -// data = ""; - -// for (int i{0}; i < bufferSize && -// data.find(std::string(static_cast(searchString))) == -// std::string::npos; -// i++) { -// char bufferChar[1]; - -// // Error if read fails -// int bytesRead = read(hSerialPort, static_cast(bufferChar), 1); -// if (bytesRead == -1) { -// errorCallback(status(StatusCodes::READ_ERROR)); -// return 0; -// } - -// if (bytesRead == 0) { -// break; -// } - -// data.append(std::string(bufferChar, bytesRead)); -// } - -// memcpy(buffer, data.c_str(), data.length() + 1); - -// readCallback(data.length()); - -// return data.length(); -// } - -// auto serialWrite(int64_t pointer, -// void* buffer, -// const int bufferSize, -// const int timeout, -// const int multiplier) -> int { -// const char* tmp = static_cast(buffer); - -// int bytesWritten = write(hSerialPort, tmp, bufferSize); - -// if (bytesWritten == -1) { -// errorCallback(status(StatusCodes::WRITE_ERROR)); -// return 0; -// } - -// writeCallback(bytesWritten); -// return bytesWritten; -// } - -// auto serialOnError(void (*func)(int code)) -> void { errorCallback = func; }; - -// auto serialOnRead(void (*func)(int bytes)) -> void { readCallback = func; }; - -// auto serialOnWrite(void (*func)(int bytes)) -> void { writeCallback = func; }; - -// auto serialGetPortsInfo(void* buffer, const int bufferSize, void* separator) -// -> int { -// std::string result = ""; - -// int portsCounter = 0; - -// DIR* dir = opendir("/dev/serial/by-id"); -// if (dir == nullptr) { -// // Handle directory not found error -// return -1; // Return an appropriate error code or define your own -// } - -// struct dirent* entry; -// while ((entry = readdir(dir)) != nullptr) { -// if (entry->d_type == DT_LNK) { -// std::string symlinkPath = "/dev/serial/by-id/"; -// symlinkPath += entry->d_name; - -// char canonicalPath[PATH_MAX]; -// if (realpath(symlinkPath.c_str(), canonicalPath) != nullptr) { -// result += std::string(canonicalPath) + -// std::string(static_cast(separator)); -// portsCounter++; -// } -// } -// } - -// closedir(dir); - -// // Remove last trailing comma -// if (result.length() > 0) { -// result.erase(result.length() - 1); -// } - -// if (result.length() + 1 <= bufferSize) { -// memcpy(buffer, result.c_str(), result.length() + 1); -// } else { -// errorCallback(status(StatusCodes::BUFFER_ERROR)); -// return 0; -// } - -// return portsCounter; -// } diff --git a/src/serial.h b/src/serial.h index 4fb70fe..73a2c4e 100644 --- a/src/serial.h +++ b/src/serial.h @@ -1,5 +1,46 @@ #pragma once -#include "functions/serial_open.h" -#include "functions/serial_close.h" -#include "functions/serial_read.h" -#include "functions/serial_write.h" +#include + +#define MODULE_API __attribute__((visibility("default"))) + +#ifdef __cplusplus +extern "C" +{ +#endif + + // Version helpers generated at configure time + MODULE_API unsigned int getMajorVersion(); + MODULE_API unsigned int getMinorVersion(); + MODULE_API unsigned int getPatchVersion(); + + // Basic serial API + MODULE_API intptr_t + serialOpen(void* port, int baudrate, int dataBits, int parity /*0-none,1-even,2-odd*/ = 0, int stopBits /*0-1bit,2-2bit*/ = 0); + + MODULE_API void serialClose(int64_t handle); + + MODULE_API int serialRead(int64_t handle, void* buffer, int bufferSize, int timeout /*ms*/, int multiplier); + + MODULE_API int serialReadUntil(int64_t handle, void* buffer, int bufferSize, int timeout, int multiplier, void* untilChar); + + MODULE_API int serialWrite(int64_t handle, const void* buffer, int bufferSize, int timeout, int multiplier); + + MODULE_API int serialGetPortsInfo(void* buffer, int bufferSize, void* separator); + + MODULE_API void serialClearBufferIn(int64_t handle); + MODULE_API void serialClearBufferOut(int64_t handle); + MODULE_API void serialAbortRead(int64_t handle); + MODULE_API void serialAbortWrite(int64_t handle); + + // Optional callback hooks (can be nullptr) + extern void (*error_callback)(int errorCode); + extern void (*read_callback)(int bytes); + extern void (*write_callback)(int bytes); + + MODULE_API void serialOnError(void (*func)(int code)); + MODULE_API void serialOnRead(void (*func)(int bytes)); + MODULE_API void serialOnWrite(void (*func)(int bytes)); + +#ifdef __cplusplus +} +#endif diff --git a/src/serial.h.txt b/src/serial.h.txt deleted file mode 100644 index a63fa93..0000000 --- a/src/serial.h.txt +++ /dev/null @@ -1,65 +0,0 @@ -#pragma once -#include - -#define MODULE_API - -extern void (*errorCallback)(int errorCode); -extern void (*readCallback)(int bytes); -extern void (*writeCallback)(int bytes); - -#ifdef __cplusplus -extern "C" { -#endif - -MODULE_API auto getMajorVersion() -> unsigned int; -MODULE_API auto getMinorVersion() -> unsigned int; -MODULE_API auto getPatchVersion() -> unsigned int; - -MODULE_API auto serialOpen(void* port, - const int baudrate, - const int dataBits, - const int parity = 0, - const int stopBits = 0) -> intptr_t; - -MODULE_API void serialClose(int64_t pointer); - -MODULE_API auto serialRead(int64_t pointer, - void* buffer, - const int bufferSize, - const int timeout, - const int multiplier) -> int; - -MODULE_API auto serialReadUntil(int64_t pointer, - void* buffer, - const int bufferSize, - const int timeout, - const int multiplier, - void* untilChar) -> int; - -MODULE_API auto serialWrite(int64_t pointer, - void* buffer, - const int bufferSize, - const int timeout, - const int multiplier) -> int; - -MODULE_API auto serialGetPortsInfo(void* buffer, - const int bufferSize, - void* separator) -> int; - -MODULE_API void serialClearBufferIn(int64_t pointer); - -MODULE_API void serialClearBufferOut(int64_t pointer); - -MODULE_API void serialAbortRead(int64_t pointer); - -MODULE_API void serialAbortWrite(int64_t pointer); - -MODULE_API auto serialOnError(void (*func)(int code)) -> void; - -MODULE_API auto serialOnRead(void (*func)(int bytes)) -> void; - -MODULE_API auto serialOnWrite(void (*func)(int bytes)) -> void; - -#ifdef __cplusplus -} -#endif diff --git a/src/status_codes.h b/src/status_codes.h index 599ce31..3eabfd8 100644 --- a/src/status_codes.h +++ b/src/status_codes.h @@ -1,23 +1,18 @@ #pragma once enum class StatusCodes { - SUCCESS = 0, - CLOSE_HANDLE_ERROR = -1, - INVALID_HANDLE_ERROR = -2, - READ_ERROR = -3, - WRITE_ERROR = -4, - GET_STATE_ERROR = -5, - SET_STATE_ERROR = -6, - SET_TIMEOUT_ERROR = -7, - BUFFER_ERROR = -8, - NOT_FOUND_ERROR = -9, - CLEAR_BUFFER_IN_ERROR = -10, - CLEAR_BUFFER_OUT_ERROR = -11, - ABORT_READ_ERROR = -12, - ABORT_WRITE_ERROR = -13, + SUCCESS = 0, + CLOSE_HANDLE_ERROR = -1, + INVALID_HANDLE_ERROR = -2, + READ_ERROR = -3, + WRITE_ERROR = -4, + GET_STATE_ERROR = -5, + SET_STATE_ERROR = -6, + SET_TIMEOUT_ERROR = -7, + BUFFER_ERROR = -8, + NOT_FOUND_ERROR = -9, + CLEAR_BUFFER_IN_ERROR = -10, + CLEAR_BUFFER_OUT_ERROR = -11, + ABORT_READ_ERROR = -12, + ABORT_WRITE_ERROR = -13, }; - -template -constexpr auto status(const T& stat) -> int { - return static_cast(stat); -} \ No newline at end of file diff --git a/tests/serial_test.cpp b/tests/serial_test.cpp new file mode 100644 index 0000000..71a795f --- /dev/null +++ b/tests/serial_test.cpp @@ -0,0 +1,104 @@ +// Simple integration test for CPP-Unix-Bindings +// ------------------------------------------------ +// This executable opens the given serial port, sends a test +// string and verifies that the same string is echoed back +// by the micro-controller. +// +// ------------------------------------------------ +// Arduino sketch to flash for the tests +// ------------------------------------------------ +/* + // --- BEGIN ARDUINO CODE --- + void setup() { + Serial.begin(115200); + // Wait until the host opens the port (optional but handy) + while (!Serial) { + ; + } + } + + void loop() { + if (Serial.available()) { + char c = Serial.read(); + Serial.write(c); // echo back + } + } + // --- END ARDUINO CODE --- +*/ +// ------------------------------------------------ + +#include "serial.h" + +#include +#include +#include +#include +#include +#include + +namespace +{ +const char* default_port = "/dev/ttyUSB0"; +} // namespace + +TEST(SerialEchoTest, EchoMessage) +{ + const std::string test_msg = "HELLO"; + + intptr_t handle = serialOpen((void*)default_port, 115200, 8, 0, 0); + ASSERT_NE(handle, 0) << "Failed to open port " << default_port; + + // Opening a serial connection toggles DTR on most Arduino boards, which + // triggers a reset. Give the micro-controller a moment to reboot before we + // start talking to it, otherwise the first bytes might be lost. + std::this_thread::sleep_for(std::chrono::seconds(2)); + + // Send message + int written = serialWrite(handle, (void*)test_msg.c_str(), static_cast(test_msg.size()), 100, 1); + ASSERT_EQ(written, static_cast(test_msg.size())) << "Write failed"; + + // Read echo + char buffer[16] = {0}; + int read_bytes = serialRead(handle, buffer, static_cast(test_msg.size()), 500, 1); + ASSERT_EQ(read_bytes, static_cast(test_msg.size())) << "Read failed (got " << read_bytes << ")"; + + ASSERT_EQ(std::strncmp(buffer, test_msg.c_str(), test_msg.size()), 0) << "Data mismatch: expected " << test_msg << ", got " << buffer; + + serialClose(handle); +} + +TEST(SerialReadUntilTest, ReadUntilChar) +{ + const std::string test_msg = "WORLD\n"; // include terminator newline + + intptr_t handle = serialOpen((void*)default_port, 115200, 8, 0, 0); + ASSERT_NE(handle, 0) << "Failed to open port " << default_port; + + // Give the board time to reset after opening the port. + std::this_thread::sleep_for(std::chrono::seconds(2)); + + // Send message (write includes the terminator char) + int written = serialWrite(handle, (void*)test_msg.c_str(), static_cast(test_msg.size()), 100, 1); + ASSERT_EQ(written, static_cast(test_msg.size())) << "Write failed"; + + // Read back until newline (inclusive) + std::array buffer{0}; + char until = '\n'; + int read_bytes = serialReadUntil(handle, buffer.data(), static_cast(buffer.size()), 500, 1, &until); + ASSERT_EQ(read_bytes, static_cast(test_msg.size())) << "serialReadUntil returned unexpected length"; + + ASSERT_EQ(std::strncmp(buffer.data(), test_msg.c_str(), test_msg.size()), 0) + << "Data mismatch: expected " << test_msg << ", got " << buffer.data(); + + serialClose(handle); +} + +int main(int argc, char** argv) +{ + ::testing::InitGoogleTest(&argc, argv); + if (argc > 1) + { + default_port = argv[1]; + } + return RUN_ALL_TESTS(); +} diff --git a/tests/serial_unit_tests.cpp b/tests/serial_unit_tests.cpp new file mode 100644 index 0000000..dcfd6b6 --- /dev/null +++ b/tests/serial_unit_tests.cpp @@ -0,0 +1,118 @@ +#include "serial.h" +#include "status_codes.h" + +#include +#include +#include +#include + +namespace +{ +// Helper storage for callback tests +std::atomic* g_err_ptr = nullptr; + +void errorCallback(int code) +{ + if (g_err_ptr != nullptr) + { + *g_err_ptr = code; + } +} +} // namespace + +// ------------------------------- Error path -------------------------------- +TEST(SerialOpenTest, InvalidPathInvokesErrorCallback) +{ + std::atomic err_code{0}; + + g_err_ptr = &err_code; + serialOnError(errorCallback); + + intptr_t handle = serialOpen((void*)"/dev/__does_not_exist__", 115200, 8, 0, 0); + EXPECT_EQ(handle, 0); + EXPECT_EQ(err_code.load(), static_cast(StatusCodes::INVALID_HANDLE_ERROR)); + + // Reset to nullptr so other tests don't see our callback + serialOnError(nullptr); +} + +// ------------------------ serialGetPortsInfo checks ------------------------ +TEST(SerialGetPortsInfoTest, BufferTooSmallTriggersError) +{ + char sep[] = ";"; + char buffer[4]; + std::atomic err_code{0}; + + g_err_ptr = &err_code; + serialOnError(errorCallback); + + int res = serialGetPortsInfo(buffer, sizeof(buffer), sep); + EXPECT_EQ(res, 0); // function indicates failure via 0 + EXPECT_EQ(err_code.load(), static_cast(StatusCodes::BUFFER_ERROR)); + + serialOnError(nullptr); +} + +TEST(SerialGetPortsInfoTest, LargeBufferReturnsZeroOrOne) +{ + char sep[] = ";"; + char buffer[4096] = {0}; + + std::atomic err_code{0}; + g_err_ptr = &err_code; + serialOnError(errorCallback); + + int res = serialGetPortsInfo(buffer, sizeof(buffer), sep); + EXPECT_GE(res, 0); + // res is 0 (no ports) or 1 (ports found) + EXPECT_LE(res, 1); + // Acceptable error codes: none or NOT_FOUND_ERROR (e.g., dir missing) + if (err_code != 0) + { + EXPECT_EQ(err_code.load(), static_cast(StatusCodes::NOT_FOUND_ERROR)); + } + + serialOnError(nullptr); +} + +// ---------------------------- Port listing helper --------------------------- +TEST(SerialGetPortsInfoTest, PrintAvailablePorts) +{ + char sep[] = ";"; + char buffer[4096] = {0}; + + int res = serialGetPortsInfo(buffer, sizeof(buffer), sep); + EXPECT_GE(res, 0); + + std::string ports_str(buffer); + if (!ports_str.empty()) + { + std::cout << "\nAvailable serial ports (by-id):\n"; + size_t start = 0; + while (true) + { + size_t pos = ports_str.find(sep, start); + std::string token = ports_str.substr(start, pos - start); + std::cout << " " << token << "\n"; + if (pos == std::string::npos) + { + break; + } + start = pos + std::strlen(sep); + } + } + else + { + std::cout << "\nNo serial devices found in /dev/serial/by-id\n"; + } +} + +// --------------------------- Stubbed no-op APIs ---------------------------- +TEST(SerialStubbedFunctions, DoNotCrash) +{ + serialClearBufferIn(0); + serialClearBufferOut(0); + serialAbortRead(0); + serialAbortWrite(0); + SUCCEED(); // reached here without segfaults +}