doc

documentation/building.rst

@@ -3,22 +3,14 @@ Building from Source
 
 Begin be fetching all needed source. ::
 
-    git clone https://github.com/mdavidsaver/pvxs.git
+    git clone --recursive https://github.com/mdavidsaver/pvxs.git
     git clone --branch 7.0 https://github.com/epics-base/epics-base.git
-    # omit if installing libevent from RPM or DEB package
-    wget https://github.com/libevent/libevent/releases/download/release-2.1.11-stable/libevent-2.1.11-stable.tar.gz
 
 Prepare the PVXS source tree: ::
 
     cat <<EOF > pvxs/configure/RELEASE.local
     EPICS_BASE=\$(TOP)/../epics-base
     EOF
-    # omit if installing libevent from RPM or DEB package
-    cat <<EOF > pvxs/configure/CONFIG_SITE.local
-    USR_CPPFLAGS += -I$PWD/libevent-install/include
-    USR_LDFLAGS += -L$PWD/libevent-install/lib
-    USR_LDFLAGS += -Wl,-rpath,$PWD/libevent-install/lib
-    EOF
 
 Install or build libevent >=2.0
 
@@ -34,20 +26,13 @@ On Debian/Ubuntu. ::
 
     apt-get install libevent2-dev
 
-To build from source on a \*NIX host: ::
+To build from source (Requires `CMake <https://cmake.org/>`_): ::
 
-    tar -xzf libevent-2.1.11-stable.tar.gz
-    (cd libevent-2.1.11-stable \
-     && ./configure --prefix $PWD/../libevent-install \
-     && make install)
+    make -C pvxs/bundle libevent # implies .$(EPICS_HOST_ARCH)
 
-Alternately, building from source with CMake.
-On Windows this is possible with `CMake <https://cmake.org/>`_ and `Git Bash shell <https://git-scm.com/download/win>`_ installed. ::
+For additional archs: eg. ::
 
-    tar -xzf libevent-2.1.11-stable.tar.gz
-    (cd libevent-2.1.11-stable \
-     && cmake -DCMAKE_INSTALL_PREFIX:DIR=$PWD/../usr .. \
-     && cmake --build . --target install)
+    make -C pvxs/bundle libevent.linux-x86_64-debug
 
 Build Base and PVXS: ::
 
@@ -60,26 +45,9 @@ of PVXS, or building on a new host.  ::
     make -C pvxs runtests
 
 Cross-compiling libevent2
--------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
-libevent may be built with either autotools (aka. configure script) or CMake.
-On Linux cross compiling with autotools is likely easest, and is well documented elsewhere.
-The basic recipe is to add a target triple (eg. x86_64-w64-mingw32): ::
+The bundled libevent may be built for some cross compile targets.
+Currently only cross mingw. ::
 
-    ./configure --host=<target-toolchain-triple> ...
-
-It is then necessary to each build to a different prefix (eg. "$PWD/libevent-install" above)
-and configure these differently in "pvxs/configure/CONFIG_SITE.local".
-eg. with a mingw cross build. ::
-
-    tar -xzf libevent-2.1.11-stable.tar.gz
-    (cd libevent-2.1.11-stable && ./configure --prefix $PWD/../libevent-host && make install)
-    (cd libevent-2.1.11-stable && ./configure --host=--host=x86_64-w64-mingw32 --prefix $PWD/../libevent-mingw && make install)
-    cat <<EOF > pvxs/configure/CONFIG_SITE.local
-    USR_CPPFLAGS_linux-x86_64 += -I$PWD/libevent-host/include
-    USR_LDFLAGS_linux-x86_64 += -L$PWD/libevent-host/lib
-    USR_LDFLAGS_linux-x86_64 += -Wl,-rpath,$PWD/libevent-host/lib
-    USR_CPPFLAGS_windows-x64-mingw += -I$PWD/libevent-mingw32/include
-    USR_LDFLAGS_windows-x64-mingw += -L$PWD/libevent-mingw32/lib
-    USR_LDFLAGS_windows-x64-mingw += -Wl,-rpath,$PWD/libevent-mingw32/lib
-    EOF
+    make -C pvxs/bundle libevent.windows-x64-mingw

documentation/details.rst

@@ -0,0 +1,30 @@
+Notes
+=====
+
+Misc. notes on design and Implementation.
+
+* All Server and client Context instances listening on the same UDP port# within a process
+  will share a single UDP socket.
+
+* The UDP local multicast fanout aspect of the PVA protocol is not implemented.
+
+* Client UDP search retry follows a linear backoff starting from 1 second
+  and stepping to 30 seconds.  cf. bucketInterval and nBuckets in client.cpp.
+
+* To level UDP search traffic, search retry may delay a PV for an extra
+  bucket if the difference in the number of PVs in the desired and subsequent
+  buckets is too large.
+
+* Client Context::hurryUp() expires the search bucket timer immediately,
+  saving up to bucketInterval seconds.
+
+* Each Value refers points to a pair of FieldDesc and FieldStorage in arrays
+  of the same.  Value::operator[] steps around in these arrays.
+
+* There is a hidden StructTop which holds the FieldStorage array and holds
+  a shared_ptr to the FieldDesc array to join ownership of the two.
+
+* TCP connection buffering will read up to tcp_readahead (cf. conn.h) bytes
+  while waiting for a complete header.  After a header is received,
+  the larger of tcp_readahead or the message body length is buffered.
+

documentation/index.rst

@@ -26,6 +26,7 @@ Dependencies
    server
    util
    example
+   details
 
 
 Indices and tables