Bringing everything up

Author: cliffg-softwarelibre

CMakeLists.txt

@@ -0,0 +1,51 @@
+# Copyright (c) 2024 by Cliff Green
+#
+# https://github.com/connectivecpp/shared-buffer
+#
+# 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 ( shared_buffer 
+	  LANGUAGES CXX 
+	  DESCRIPTION "Reference counted character buffer classes"
+	  HOMEPAGE_URL "https://github.com/connectivecpp/shared-buffer/" )
+
+option ( SHARED_BUFFER_BUILD_TESTS "Build unit tests" OFF )
+option ( SHARED_BUFFER_BUILD_EXAMPLES "Build examples" OFF )
+option ( SHARED_BUFFER_INSTALL "Install header only library" OFF )
+
+# add library targets
+
+add_library ( shared_buffer INTERFACE )
+add_library ( chops::shared_buffer ALIAS shared_buffer )
+
+# configure library target
+
+target_include_directories ( shared_buffer INTERFACE
+                             $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/>
+			     $<INSTALL_INTERFACE:include/> )
+target_compile_features ( shared_buffer INTERFACE cxx_std_20 )
+
+# check to build unit tests
+if ( ${SHARED_BUFFER_BUILD_TESTS} )
+  enable_testing()
+  add_subdirectory ( test )
+endif ()
+
+# check to build example code
+if ( ${SHARED_BUFFER_BUILD_EXAMPLES} )
+  add_subdirectory ( example )
+endif ()
+
+# check to install
+if ( ${SHARED_BUFFER_INSTALL} )
+  set ( CPACK_RESOURCE_FILE_LICENSE ${CMAKE_CURRENT_SOURCE_DIR}/LICENSE.txt )
+  include ( CPack )
+endif ()
+
+# end of file
+

README.md

@@ -1,2 +1,62 @@
-# shared-buffer
-A reference counted character buffer class template
+# Shared Buffer, Header-Only C++ 20 Reference Counted Byte Buffer Classes
+
+#### Unit Test and Documentation Generation Workflow Status
+
+![GH Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/connectivecpp/shared-buffer/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/shared-buffer/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/shared-buffer/gen_docs.yml?branch=main&label=GH%20Actions%20generate%20docs)
+
+## Overview
+
+The `shared_buffer` classes are reference counted `std::byte` buffer classes useful for asynchronous networking. In particular, the Asio asynchronous networking library requires a buffer to be kept alive and valid until the outstanding IO operation (e.g. a network write) is completed. A straightforward and idiomatic way to achieve this is by using reference counted buffers.
+
+There are two classes - `const_shared_buffer` for outgoing buffers (which should not be modified), and `mutable_shared_buffer` for incoming buffers (mutable and expandable as data arrives).
+
+While internally all data is kept in `std::byte` buffers, convenience methods are provided for converting between traditional buffer types (such as `char *` or `unsigned char*` or similar).
+
+## Generated Documentation
+
+The generated Doxygen documentation for `shared_buffer` is [here](https://connectivecpp.github.io/shared-buffer/).
+
+## Dependencies
+
+The `shared_buffer` header file does 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
+
+`shared_buffer`  uses C++ 20 features, including 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 `SHARED_BUFFER_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.
+
+Specific version (or branch) specs for the Catch2 dependency is in `test/CMakeLists.txt`.
+
+## Build and Run Unit Tests
+
+To build and run the unit test program:
+
+First clone the `shared-buffer` repository, then create a build directory in parallel to the `shared-queue` directory (this is called "out of source" builds, which is recommended), then `cd` (change directory) into the build directory. The CMake commands:
+
+```
+cmake -D SHARED_BUFFER_BUILD_TESTS:BOOL=ON ../shared-buffer
+
+cmake --build .
+
+ctest
+```
+
+For additional test output, run the unit test individually, for example:
+
+```
+test/shared_buffer_test -s
+```
+
+The example can be built by adding `-D SHARED_BUFFER_BUILD_EXAMPLES:BOOL=ON` to the CMake configure / generate step.
+