DTNN-132 Clean up bplib prototype readme

README.md

@@ -1,14 +1,14 @@
 # bplib
 
-[1. Overview](#1-overview)
-[2. Build with CMake](#2-build-with-cmake)
-[3. Application Design](#3-application-design)
-[4. Application Programming Interface](#4-application-programming-interface)
-[5. Storage Service](#5-storage-service)
-
-[Note #1 - Bundle Protocol Version 6](doc/bpv6_notes.md)
-[Note #2 - Library Development Guidelines](doc/dev_notes.md)
-[Note #3 - Configuration Parameter Trades](doc/parm_notes.md)
+[1. Overview](#1-overview)  
+[2. Build with CMake](#2-build-with-cmake)  
+[3. Application Design](#3-application-design)  
+[4. Application Programming Interface](#4-application-programming-interface)  
+[5. Storage Service](#5-storage-service)  
+
+[Note #1 - Bundle Protocol Version 6](doc/bpv6_notes.md)  
+[Note #2 - Library Development Guidelines](doc/dev_notes.md)  
+[Note #3 - Configuration Parameter Trades](doc/parm_notes.md)  
 [Note #4 - Bundle Flow Analysis for Intermittent Communication](doc/perf_analysis_ic.md)
 
 ----------------------------------------------------------------------
@@ -39,62 +39,153 @@ library.
 
 #### Prerequisites
 
-1. The build requires the __cmake__ build system and a compiler toolchain (by default __gcc__).
+1. The build requires Ubuntu 22.04.4 LTS, the __cmake__ build system and a compiler toolchain (by default __gcc__).
+
 Additionally, the __pkg-config__ tool is used to manage the flags required for dependencies.
+
 These can typically be installed via the built-in package management system on most Linux
 distributions.
 
-On Debian/Ubuntu and derivatives:
+The required packages on Ubuntu 22.04 are: cmake, pkg-config, and build-essential.
+
+The versions used may change. The versions as of the last update of this document are:
+
+- cmake version 3.22.1
+- pkg-config 0.29.1
+- gcc  (Ubuntu 9.4.0-1ubuntu1~20.04.2) 9.4.0
+
+2. Install tinycbor if it is not already installed.  
+See https://github.com/intel/tinycbor.git.
+
+- tinycbor version 0.6.0
+
+#### Build bplib with cFS
+3. Create a subdirectory for building bplib. Run CMake to set up the build tree. Build bplib by running __make__ in the build subdirectory:
 
 ```sh
-    sudo apt-get install cmake pkg-config build-essential
+   git clone https://github.com/nasa/cFS cfs_bundle
+   cd ./cfs_bundle
+   git submodule init
+   git submodule update
+   git clone https://github.com/nasa/bp ./apps/bp
+   git clone https://github.com/nasa/bplib ./libs/bplib
 ```
 
-2. For BPv7 this uses the TinyCBOR library at https://github.com/intel/tinycbor.  As any
-distribution-packaged version may be outdated, it is recommended to compile this from source.
-As of this writing, the library uses a simple Makefile that will install into `/usr/local`.
-This installation prefix can be changed by editing the Makefile before building.  Otherwise,
-to install into the default location, steps are as follows:
+3. Setup OSAL.
 
-```sh
-    git clone https://github.com/intel/tinycbor
-    cd tinycbor
-    make
-    sudo make install
+Define the OSAL definitions for CMake.
+Run CMake for OSAL.
+Run Make for OSAL with the destination directory `./osal-staging`.
+
+```
+   cd ./cfs-bundle/osal
+   # cmake options from .github/actions/setup-osal/action.yml
+   CMAKE_OSAL_DEFS="-DCMAKE_INSTALL_PREFIX=/usr/local -DOSAL_SYSTEM_BSPTYPE=generic-linux "
+   # config-options:
+   CMAKE_OSAL_DEFS+="-DCMAKE_BUILD_TYPE=Release -DOSAL_OMIT_DEPRECATED=TRUE "
+   CMAKE_OSAL_DEFS+="-DENABLE_UNIT_TESTS=TRUE -DOSAL_CONFIG_DEBUG_PERMISSIVE_MODE=ON "
+   cmake $CMAKE_OSAL_DEFS -B ../osal-build
+   cd ../osal-build
+   make DESTDIR=../osal-staging install
 ```
 
-Note that "sudo" is only required for installation into a system directory.  If installing into a
-user-writable home directory, "sudo" is not necessary.
+4. Build the test runners
 
-3. Create a subdirectory for building bplib and run CMake to set up the build tree.
+Note that the possible build folders are one of <Debug/Release>-<OSAL/POSIX> for the build type and operating system layer respectively.
 
 ```sh
-   cd $HOME
-   mkdir build-bplib
-   cd build-bplib
-   cmake ../bplib
+   # Create the build folder based on Debug/Release and OSAL/POSIX
+   # MATRIX_BUILD_TYPE=[Debug|Release]
+   # MATRIX_OS_LAYER=[OSAL|POSIX]
+   # BPLIB_SOURCE=<path-to-cfs>/libs/bplib
+   # BPLIB_BUILD=./bplib-build-matrix-<MATRIX_BUILD_TYPE>-<MATRIX_OS_LAYER>
+   #   one of:
+   # BPLIB_BUILD=./bplib-build-matrix-Debug-OSAL
+   # BPLIB_BUILD=./bplib-build-matrix-Debug-POSIX
+   # BPLIB_BUILD=./bplib-build-matrix-Release-OSAL
+   # BPLIB_BUILD=./bplib-build-matrix-Release-POSIX
+
+   cmake \
+          -DCMAKE_BUILD_TYPE="${MATRIX_BUILD_TYPE}" \
+          -DBPLIB_OS_LAYER="${MATRIX_OS_LAYER}" \
+          -DCMAKE_PREFIX_PATH=/usr/local/lib/cmake \
+          -S "${BPLIB_SOURCE}" -B "${BPLIB_BUILD}"
+
+   # Build bplib
+   cd "${BPLIB_BUILD}"
+   make all
 ```
 
-#### Building
+5. Test bplib
 
-Build bplib by running __make__ in the build subdirectory:
+#### Example Test
+
+
+```
+   export NasaOsal_DIR=osal-staging/usr/local/lib/cmake
+   cd ./bplib-build-matrix-Debug-OSAL
+   common/ut-coverage/coverage-bplib_common-testrunner
+```
+
+#### Build bplib Stand Alone
+6. Create a subdirectory for building bplib.
 
 ```sh
-   cd $HOME/build-bplib
-   make
+   git clone https://github.com/nasa/bplib ./bplib
 ```
 
-#### Example Application
+7. Build the test runners
 
-For those that learn better through examples, an example application is provided in the `apps`
-directory.  This example program is not intended to be complete, but provides a quick way to
-see how to use the library.  After building and installing bplib on your system, the `bpcat`
-program provides a functionality similar to netcat for bplib.
+Note that the possible build folders are one of <Debug/Release>-<OSAL/POSIX> for the build type and operating system layer respectively.
 
 ```sh
-   cd apps
-   mkdir storage
-   ./bpcat
+   # Create the build folder based on Debug/Release and OSAL/POSIX
+   # MATRIX_BUILD_TYPE=[Debug|Release]
+   # MATRIX_OS_LAYER=[OSAL|POSIX]
+   # BPLIB_SOURCE=<path-to-cfs>/libs/bplib
+   # BPLIB_BUILD=./bplib-build-matrix-<MATRIX_BUILD_TYPE>-<MATRIX_OS_LAYER>
+   #   one of:
+   # BPLIB_BUILD=./bplib-build-matrix-Debug-OSAL
+   # BPLIB_BUILD=./bplib-build-matrix-Debug-POSIX
+   # BPLIB_BUILD=./bplib-build-matrix-Release-OSAL
+   # BPLIB_BUILD=./bplib-build-matrix-Release-POSIX
+
+   # Run cmake from the current directory with the CMake folder
+   # indicated by -S "$BPLIB_SOURCE}".
+
+   cmake \
+          -DCMAKE_BUILD_TYPE="${MATRIX_BUILD_TYPE}" \
+          -DBPLIB_OS_LAYER="${MATRIX_OS_LAYER}" \
+          -DCMAKE_PREFIX_PATH=/usr/local/lib/cmake \
+          -S "${BPLIB_SOURCE}" -B "${BPLIB_BUILD}"
+
+   # Build bplib
+   cd "${BPLIB_BUILD}"
+   make all
+```
+
+8. Test bplib stand alone
+
+The example program `bpcat` is available in the bplib stand alone build
+
+```
+$ ./bplib-build-matrix-Debug-POSIX/app/bpcat --help
+Usage: ./bplib-build-matrix-Debug-POSIX/app/bpcat [options]
+   -l/--local-addr=ipn://<node>.<service> local address to use
+   -r/--remote-addr=ipn://<node>.<service> remote address to use
+   -i/--input-file=<filename> read input from given file instead of stdin
+   -o/--output-file=<filename> write output to given file instead of stdout
+      --local-cla-uri=udp://<ip>:<port> Bind local CLA to given IP:port 
+      --remote-cla-uri=udp://<ip>:<port> Send bundles to remote CLA at given IP:port
+   -d/--delay=<msec> forced inter bundle send delay (20ms default)
+   -s/--adu-size=stream chunk (ADU) size to pass to bplib (default and max=15864 bytes)
+
+   Creates a local BP agent with local IPN address as specified.  All data
+   received from standard input is forwarded over BP bundles, and all data
+   received from bundles is forwarded to standard output.
+
+Example:
+   ./bplib-build-matrix-Debug-POSIX/app/bpcat -l ipn://101.1 -r ipn://201.1
 ```
 
 ----------------------------------------------------------------------

bplib-clean

@@ -0,0 +1,27 @@
+#!/bin/bash
+bplib-clean-err() {
+   echo "bplib-clean exited on error."
+   exit 1
+}
+trap bplib-clean-err ERR
+
+   cd $CFS_HOME
+
+   BPLIB_DELETE_LIST=( \
+      "bplib-build-matrix-Debug-OSAL" \
+      "bplib-build-matrix-Debug-POSIX" \
+      "bplib-build-matrix-Release-OSAL" \
+      "bplib-build-matrix-Release-POSIX" \
+   )
+
+   echo "In $(pwd)"
+   echo "Ready to delete:"
+   echo ${BPLIB_DELETE_LIST[@]}
+   read -p "Delete [y|N]?" choice
+   case "${choice}" in
+      y|Y ) \
+         (set -x; rm -rf ${BPLIB_DELETE_LIST[@]});;
+      * ) \
+         echo "bplib-clean canceled."
+    esac
+