norm

                    NORM SOURCE CODE RELEASE

/*********************************************************************
 *
 * AUTHORIZATION TO USE AND DISTRIBUTE
 * 
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that: 
 *
 * (1) source code distributions retain this paragraph in its entirety, 
 *  
 * (2) distributions including binary code include this paragraph in
 *     its entirety in the documentation or other materials provided 
 *     with the distribution.
 * 
 *      "This product includes software written and developed 
 *       by Code 5520 of the Naval Research Laboratory (NRL)." 
 *         
 *  The name of NRL, the name(s) of NRL  employee(s), or any entity
 *  of the United States Government may not be used to endorse or
 *  promote  products derived from this software, nor does the 
 *  inclusion of the NRL written and developed software  directly or
 *  indirectly suggest NRL or United States  Government endorsement
 *  of this product.
 * 
 * THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 *
 ********************************************************************/

This is the NRL NORM source code repository.

The Github "Discussions" feature is available here for comment and question in addition to the regular code issue reporting:

https://github.com/USNavalResearchLaboratory/norm/discussions

SOURCE CODE

The "norm" source Git repository includes "protolib" as a git submodule. You can add the "--recurse-submodules" to your git clone command to automate inclusion:

git clone --recurse-submodules https://github.com/USNavalResearchLaboratory/norm.git

The following items can be built from this source code release:

1. libnorm.a - static NORM library for Unix platforms, or

   Norm.lib - static NORM protocol library for Win32 platforms

(These libraries can be used by applications using the NORM API. The file "normApi.h" provides function prototypes for NORM API calls and the included "Norm Developer's Guide" provides a reference manual for NORM application development using this API. Additional tutorial material and API usage examples will be provided as additional documentation in the future)

2. norm (or norm.exe (WIN32) - command-line "demo" application built from "common/normApp.cpp"

(The included "Norm User's Guide" provides a rough overview of how to use this demo app. This demo application is useful for file transfers (and streaming on Unix))

3. normTest (or normTest.exe (WIN32)) - very simple test application

(The "normTest" application (see "common/normTest.cpp") is really just a simple playground for preliminary testing of the NORM API and does not do anything useful. But it does provide a very simple example of NORM API usage. More sophisticated (and better-documented) examples of NORM API usage will be provided in the future.

4. There is also an "examples" directory in the source code tree that contains some simplified examples of NORM API usage. The example set will be expanded as time progresses.

NRL also has started some apps built around NORM including:

A) A reliable multicast "chat" application (users can share files and images, too) with a GUI. Like IRC with no server needed.

B) An application for reliably "tunneling" real-time UDP packet streams (like RTP video or audio) using NORM's streaming capability.

NACK-Oriented Proxy (NORP)

NORM Proxy code is also included in the 'norp' directory. More info is available in the norp/doc directory, as well as the NORP website: https://www.nrl.navy.mil/itd/ncs/products/norp

Docker

A Dockerfile is provided to facilitate containerized NORM environment testing. Notable build arguments passed to docker build will influence how the image is created.

• platformName represents the base image name (defaults to ubuntu)
• platformVersion represents the tagged version for the base image (defaults to latest)
• version is a 1:1 mapping to this repo's tag (defaults to v1.5.9)
• configure is piped to ./waf configure (defaults to "")
• build is piped to ./waf (defaults to --targets=*)

Example usage:

CentOS7 build

docker build --build-arg platformName=centos \
  --build-arg platformVersion=7 \
  --build-arg="--build-java" \
  -t norm:centos-1.5.9 .

Running the data send and recv examples:

# Sender in one terminal
docker run -it --rm --name norm-send <norm:image> normDataSend
# Receiver in another terminal
docker run -it --rm --name norm-recv <norm:image> normDataRecv

OTHER FILES:

NormDeveloperGuide.pdf - PDF version of NORM Developer's Guide (nice for printing)

NormDeveloperGuide.html - HTML version of NORM Developer's Guide with Hyperlinked content (nice for browsing)

NormUserGuide.pdf - Guide to "norm" demo app usage

VERSION.TXT - NORM version history notes

README.md - this file

docker - directory containing docker container support

NOTES:

The NORM code depends upon the current "Protolib" release:

https://github.com/USNavalResearchLaboratory/protolib

It has been addded as a git submodule to the NORM git repository. So, to to build you will need to do the following steps to download the protolib code:

git clone --recurse-submodules https://github.com/USNavalResearchLaboratory/norm.git

Alternatively after a basic "git clone" you can do the folowing to pull in the protolib source:

cd norm git submodule update --init

To keep the 'protolib' submodule up to date, you will need to do the following:

cd norm/protolib git checkout master

This will enable you to issue 'git pull', etc to treat the 'protolib' sub-directory as its own (sub-) repository.