From a992176873c3f3cef93a38809ba06b8ae23d6adf Mon Sep 17 00:00:00 2001 From: LVancina <95012459+LVancina@users.noreply.github.com> Date: Wed, 24 Jan 2024 10:15:06 -0800 Subject: [PATCH] Documentation updates and pynorm example bug fixes (#82) * Added notes about waf execution in BUILD.TXT * Updated instructions for cloning and running make * Added more detailed instructions for win32 builds * Fixed typo on line 20 (capitalized 'f') that caused the command to fail * Generic editing and replaced dead URLs * Substituted setuptools package for the deprecated distutils in setup.py * Fixed typo in 'norm.exe' file path in Win32 build instructions * Fixed a bugs in normCast.py and normFileSend.py --------- Co-authored-by: Lucas --- BUILD.TXT | 20 ++++++++++++++++- README-PyNorm.txt | 2 +- doc/NormDeveloperGuide.xml | 39 ++++++++++++++++----------------- doc/NormUserGuide.xml | 22 +++++++++++++------ examples/python/normCast.py | 6 +++-- examples/python/normFileSend.py | 2 +- setup.py | 2 +- 7 files changed, 60 insertions(+), 33 deletions(-) diff --git a/BUILD.TXT b/BUILD.TXT index 3b3ebc2..4c6e360 100755 --- a/BUILD.TXT +++ b/BUILD.TXT @@ -6,11 +6,26 @@ To see a full list of options, run: ./waf -h +Note: if attempting to run waf as an executable as shown above results in a +message like this: + +/usr/bin/env: ‘python’: No such file or directory + +then try calling python directly: + +python waf + +or + +python3 waf + +For more background information about waf, visit the gitlab page at +https://gitlab.com/ita1024/./waf/ Configuring ----------- -To perform the configure checks, run: +To perform the configuration checks, run: ./waf configure @@ -51,6 +66,9 @@ To install, run: This will install the compiled library and headers to wherever your prefix was specified. (See configure flags) +This command may have to be run with root priviledges for certain prefix +directories depending on your system setup. + Uninstalling ------------ diff --git a/README-PyNorm.txt b/README-PyNorm.txt index 114b178..5e9160e 100755 --- a/README-PyNorm.txt +++ b/README-PyNorm.txt @@ -28,7 +28,7 @@ in similar places as your system's compiler. On UNIX systems, this is usually PATH environment variable. On Windows, PyNORM requires the "PyWin32" module, available at: - http://sf.net/projects/pywin32 + https://sourceforge.net/projects/pywin32 ------------- Installation diff --git a/doc/NormDeveloperGuide.xml b/doc/NormDeveloperGuide.xml index 6900095..4408de5 100755 --- a/doc/NormDeveloperGuide.xml +++ b/doc/NormDeveloperGuide.xml @@ -13,19 +13,19 @@ This document describes an application programming interface (API) - for the Nack-Oriented + for the Nack-Oriented Reliable Multicast (NORM) protocol implementation developed by the Protocol Engineering and Advance Networking (PROTEAN) Research Group of the - United States Naval Research + url="https://www.nrl.navy.mil/itd/ncs/">PROTEAN) Research Group of the + United States Naval Research Laboratory (NRL). The NORM protocol provides general purpose reliable data transport for applications wishing to use Internet Protocol (IP) Multicast services for group data delivery. NORM can also support unicast (point-to-point) data communication and may be used for such when deemed appropriate. The current NORM protocol specification is - given in the Internet Engineering Task + given in the Internet Engineering Task Force (IETF) RFC 3940. This + url="https://datatracker.ietf.org/doc/html/rfc5740">RFC 5740. This document is currently a reference guide to the NORM API of the NRL reference implementation. More tutorial material may be include in a future version of this document or a separate developer's tutorial may @@ -37,19 +37,19 @@ Background This document describes an application programming interface (API) - for the Nack-Oriented + for the Nack-Oriented Reliable Multicast (NORM) protocol implementation developed by the Protocol Engineering and Advance Networking (PROTEAN) Research Group of the - United States Naval Research + url="https://www.nrl.navy.mil/itd/ncs/">PROTEAN) Research Group of the + United States Naval Research Laboratory (NRL). The NORM protocol provides general purpose reliable data transport for applications wishing to use Internet Protocol (IP) Multicast services for group data delivery. NORM can also support unicast (point-to-point) data communication and may be used for such when deemed appropriate. The current NORM protocol specification is given in - the Internet Engineering Task + the Internet Engineering Task Force (IETF) RFC 5740. + url="https://datatracker.ietf.org/doc/html/rfc5740">RFC 5740. The NORM protocol is designed to provide end-to-end reliable transport of bulk data objects or streams over generic IP multicast @@ -134,7 +134,7 @@ may participate as senders and/or receivers within a NORM session. NORM senders transmit data to the session destination address (usually an IP multicast group) while receivers are notified of incoming data. The NORM - API provides and event notification scheme to notify the application of + API provides an event notification scheme to notify the application of significant sender and receiver events. There are also a number support functions provided for the application to control and monitor its participation within a NORM transport session. @@ -159,7 +159,7 @@ linkend="NormCreateInstance">NormCreateInstance()) as needed for applications with specific requirements for accessing and controlling participation in multiple NormSessions - from separate operating system multiple threads. Or, alternatively, a + from separate operating system threads. Or, alternatively, a single NormInstance could be used, with a "master thread" serving as an intermediary between the NormGetNextEvent() @@ -194,7 +194,7 @@ number of concurrently active senders, this may translate to significant memory allocation on receiver nodes. Currently, the API allows the application to control how much buffer space is allocated for each - active sender (NOTE: In the future, API functions may be provided limit + active sender (NOTE: In the future, API functions may be provided to limit the number of active senders monitored and/or provide the application with finer control over receive buffer allocation, perhaps on a per sender basis). @@ -227,7 +227,7 @@ Data Transmission The behavior of data transport operation is largely placed in - the control of the NORM sender(s). NORM senders controls their data + the control of the NORM sender(s). NORM senders control their data transmission rate, forward error correction (FEC) encoding settings, and parameters controlling feedback from the receiver group. Multiple senders may operate in a session, each with independent transmission @@ -253,7 +253,7 @@ be called before any calls to NormStartReceiver() are made. However, note that the cache directory may be changed even - during active NORM reception. In this case, the new specified + during active NORM reception. In this case, the newly specified directory path will be used for subsequently-received files. Any files received before a directory path change will remain in the previous cache location. Note that the The "makefiles" directory contains Unix Makefiles for various - platforms the "win32" and "wince" sub-directories there contain Microsoft + platforms. The "win32" and "wince" sub-directories there contain Microsoft Visual C++ (VC++) and Embedded VC++ project files for building the NORM implementation. Additionally, a "waf" (Python-based build tool) build option is supported that can be used to build and install the NORM library code on the supported platforms. Finally, Python and Java bindings to the - NORM API are included and "src/python" and "src/java" directories contain - the code for these and the "makefiles/java" directory contains Makefiles - to build the NORM Java JNI bindings. Note the "waf" tool can also be used - to build the Java and Python bindings. + NORM API are included in the "src/python" and "src/java" directories and the + "makefiles/java" directory contains Makefiles to build the NORM Java JNI bindings. + Note the "waf" tool can also be used to build the Java and Python bindings. Unix Platforms diff --git a/doc/NormUserGuide.xml b/doc/NormUserGuide.xml index cfb07fd..3e396b5 100755 --- a/doc/NormUserGuide.xml +++ b/doc/NormUserGuide.xml @@ -96,11 +96,13 @@ - Download and unpack the NORM source code tarball. + Download and unpack the NORM source code tarball or clone the github + repository using + git clone --recurse-submodules https://github.com/USNavalResearchLaboratory/norm.git - cd norm/unix + cd norm/makefiles @@ -118,7 +120,8 @@ - Download and unpack the NORM source code tarball + Download and unpack the NORM source code tarball or clone the + repository as described in the section above. @@ -128,7 +131,7 @@ - Open the "norm.sln" (VC++ .Net), + Inside the "norm/makefiles/win32" directory, open the "norm.sln" (VC++ .Net), "norm.dsw" (VC++ 6.0), or "norm.vcw" (Embedded VC++) workspace file. @@ -137,9 +140,14 @@ The "norm" project can be selected and built.  The "norm.exe" file will be found in - the "norm/win32/norm/Release" directory. + the "norm/Win32/norm/Release" directory. + The easiest way to run these builds is with Visual Studio. If you do not already have Visual Studio installed, then it can + be downloaded for free here. + When you launch Visual Studio, make sure to select "Visual C++" and open the "norm.sln" file. + This should load all of the project files and allow you to right-click on any of them in the Solution Explorer on the + left side and select "build". @@ -380,7 +388,7 @@ A minimal example norm sender command-line syntax is: - norm addr <addr/port> sendFile + norm addr <addr/port> sendfile <fileName> The corresponding minimal norm receiver @@ -1160,4 +1168,4 @@ use with norm - \ No newline at end of file + diff --git a/examples/python/normCast.py b/examples/python/normCast.py index 7dd61de..68ba319 100644 --- a/examples/python/normCast.py +++ b/examples/python/normCast.py @@ -301,14 +301,16 @@ class NormCaster(): self.is_running = False return - obj:Optional[pynorm.Object] = session.fileEnqueue(self.pendingSendFilePath, info= self.pendingSendFilePath.replace("\\","/").encode() ) + lastSlash = self.pendingSendFilePath.rfind('/') + filename = self.pendingSendFilePath[lastSlash+1:] + obj:Optional[pynorm.Object] = session.fileEnqueue(self.pendingSendFilePath, info= filename.encode() ) if obj: if self.opts.ack: session.setWatermark(obj,True) logging.info(f"add file:{self.pendingSendFilePath} {obj._object}") self.pendingSendFilePath = None # succeed enqued else: - logging.warning(f"fileEnqueue: {sendFilePath} failure!") + logging.warning(f"fileEnqueue: {self.pendingSendFilePath} failure!") def handle_norm_event(self, event:pynorm.Event): session:pynorm.Session = event.session diff --git a/examples/python/normFileSend.py b/examples/python/normFileSend.py index 49968f9..7f6c3d9 100755 --- a/examples/python/normFileSend.py +++ b/examples/python/normFileSend.py @@ -44,7 +44,7 @@ def main(argv): session.startSender(randint(0, 1000), 1024**2, 1400, 64, 16) print(('Sending file %s' % filename)) - session.fileEnqueue(filepath, filename) + session.fileEnqueue(filepath, info=filename.encode()) try: for event in instance: diff --git a/setup.py b/setup.py index 0684a18..556841e 100755 --- a/setup.py +++ b/setup.py @@ -1,6 +1,6 @@ # This Python script can be used to install the Python 'pynorm' package import platform -from distutils.core import setup, Extension +from setuptools import setup, Extension # Note to use 'pynorm", you will need to have the libnorm shared library # (libnorm.so or libnorm.dylib, etc) installed where your Python installation