Merge pull request #1 from connectivecpp/develop

Merge develop to main

Author: cliffg-softwarelibre

.github/workflows/build_run_unit_test_cmake.yml

@@ -0,0 +1,31 @@
+# Build, run unit tests
+name: CMake build and run unit test matrix
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+env:
+  BUILD_TYPE: Release
+jobs:
+  build_matrix:
+    strategy:
+      matrix:
+        # os: [ubuntu-latest, windows-latest, macos-14]
+        os: [ubuntu-latest]
+    runs-on: ${{ matrix.os }}
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+      - name: create-build-dir
+        run: mkdir build
+      - name: configure-cmake
+        run: cd build && cmake -D BINARY_SERIALIZE_BUILD_TESTS:BOOL=ON -D BINARY_SERIALIZE_BUILD_EXAMPLES:BOOL=ON ..
+      - name: build
+        run: cd build && cmake --build . --config $BUILD_TYPE
+      - name: run-unit-test
+        run: cd build && ctest -C $BUILD_TYPE

.github/workflows/gen_docs.yml

@@ -0,0 +1,28 @@
+# Build, run unit tests
+name: Generate documentation
+
+on:
+  push:
+    branches:
+      - main
+jobs:
+  build_matrix:
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+    runs-on: ${{ matrix.os }}
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+      - name: run-doxygen
+        uses: mattnotmitt/[email protected]
+        with:
+          working-directory: doc
+      - name: deploy-pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./doc/doc_output/html

CMakeLists.txt

@@ -0,0 +1,51 @@
+# Copyright (c) 2024 by Cliff Green
+#
+# https://github.com/connectivecpp/binary-serialize
+#
+# I'm still learning CMake, so improvement suggestions are always welcome.
+#
+# Distributed under the Boost Software License, Version 1.0.
+# (See accompanying file LICENSE.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+cmake_minimum_required ( VERSION 3.14 FATAL_ERROR )
+
+project ( binary_serialize 
+	  LANGUAGES CXX 
+	  DESCRIPTION "Binary serialization with std::format like syntax"
+	  HOMEPAGE_URL "https://github.com/connectivecpp/binary-serialize/" )
+
+  option ( BINARY_SERIALIZE_BUILD_TESTS "Build unit tests" OFF )
+  option ( BINARY_SERIALIZE_BUILD_EXAMPLES "Build examples" OFF )
+  option ( BINARY_SERIALIZE_INSTALL "Install header only library" OFF )
+
+# add library targets
+
+add_library ( binary_serialize INTERFACE )
+add_library ( chops::binary_serialize ALIAS binary_serialize )
+
+# configure library target
+
+target_include_directories ( binary_serialize INTERFACE
+                             $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/>
+			     $<INSTALL_INTERFACE:include/> )
+target_compile_features ( binary_serialize INTERFACE cxx_std_20 )
+
+# check to build unit tests
+if ( ${BINARY_SERIALIZE_BUILD_TESTS} )
+  enable_testing()
+  add_subdirectory ( test )
+endif ()
+
+# check to build example code
+if ( ${BINARY_SERIALIZE_BUILD_EXAMPLES} )
+  add_subdirectory ( example )
+endif ()
+
+# check to install
+if ( ${BINARY_SERIALIZE_INSTALL} )
+  set ( CPACK_RESOURCE_FILE_LICENSE ${CMAKE_CURRENT_SOURCE_DIR}/LICENSE.txt )
+  include ( CPack )
+endif ()
+
+# end of file
+

README.md

@@ -1,2 +1,64 @@
-# binary-serialize
-A minimal library for binary serialization, using compile time specifier strings similar to std::format
+# Binary Serialize, Header-Only C++ 20 Binary Serialization Classes and Functions
+
+#### Unit Test and Documentation Generation Workflow Status
+
+![GH Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/connectivecpp/binary-serialize/build_run_unit_test_cmake.yml?branch=main&label=GH%20Actions%20build,%20unit%20tests%20on%20main)
+
+![GH Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/connectivecpp/binary-serialize/build_run_unit_test_cmake.yml?branch=develop&label=GH%20Actions%20build,%20unit%20tests%20on%20develop)
+
+![GH Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/connectivecpp/binary-serialize/gen_docs.yml?branch=main&label=GH%20Actions%20generate%20docs)
+
+![GH Tag](https://img.shields.io/github/v/tag/connectivecpp/binary-serialize?label=GH%20tag)
+
+## Overview
+
+The `binary_serialize` functions and classes provide serializing and unserializing of binary data. Serialization provides a way to transform application objects into and out of byte streams that can be sent over a network (or used for file IO).
+
+The serialization functionality in this repository is useful when explicit control is needed for every bit and byte. This allows a developer to match an existing wire protocol or encoding scheme or to define his or her own wire protocol. Support is provided for fundamental arithmetic types as well as certain C++ vocabulary types such as `std::optional`. Both big and little endian support is provided.
+
+## Generated Documentation
+
+The generated Doxygen documentation for `binary_serialize` is [here](https://connectivecpp.github.io/binary-serialize/).
+
+## Dependencies
+
+The `binary_serialize` header files do not have any third-party dependencies. It uses C++ standard library headers only. The unit test code does have dependencies as noted below.
+
+## C++ Standard
+
+`binary_serialize`  uses C++ 20 features, including  ... (fill in details here) ... the "spaceship" operator (`<=>`), `std::span`, and `concepts` / `requires`.
+
+## Supported Compilers
+
+Continuous integration workflows build and unit test on g++ (through Ubuntu), MSVC (through Windows), and clang (through macOS).
+
+## Unit Test Dependencies
+
+The unit test code uses [Catch2](https://github.com/catchorg/Catch2). If the `BINARY_SERIALIZE_BUILD_TESTS` flag is provided to Cmake (see commands below) the Cmake configure / generate will download the Catch2 library as appropriate using the [CPM.cmake](https://github.com/cpm-cmake/CPM.cmake) dependency manager. If Catch2 (v3 or greater) is already installed using a different package manager (such as Conan or vcpkg), the `CPM_USE_LOCAL_PACKAGES` variable can be set which results in `find_package` being attempted. Note that v3 (or later) of Catch2 is required.
+
+The unit test uses utilities from Connective C++'s [utility-rack](https://github.com/connectivecpp/utility-rack).
+
+Specific version (or branch) specs for the dependenies are in `test/CMakeLists.txt`.
+
+## Build and Run Unit Tests
+
+To build and run the unit test program:
+
+First clone the `binary-serialize` repository, then create a build directory in parallel to the `binary-serialize` directory (this is called "out of source" builds, which is recommended), then `cd` (change directory) into the build directory. The CMake commands:
+
+```
+cmake -D BINARY_SERIALIZE_BUILD_TESTS:BOOL=ON ../binary-serialize
+
+cmake --build .
+
+ctest
+```
+
+For additional test output, run the unit test individually, for example:
+
+```
+test/binary_serialize_test -s
+```
+
+The example can be built by adding `-D BINARY_SERIALIZE_BUILD_EXAMPLES:BOOL=ON` to the CMake configure / generate step.
+

cmake/download_cpm.cmake

@@ -0,0 +1,10 @@
+
+# copied from CPM.cmake GitHub site
+# download CPM.cmake
+
+file(
+  DOWNLOAD
+  https://github.com/cpm-cmake/CPM.cmake/releases/download/v0.39.0/CPM.cmake
+  ${CMAKE_CURRENT_BINARY_DIR}/cmake/CPM.cmake
+)
+include(${CMAKE_CURRENT_BINARY_DIR}/cmake/CPM.cmake)