doc

2020-03-12 21:22:24 -07:00
parent 8a16496776
commit eefd8f4aa2
5 changed files with 122 additions and 12 deletions
@@ -0,0 +1,85 @@
+Building from Source
+====================
+
+Begin be fetching all needed source. ::
+
+    git clone 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
+
+On RHEL7 and later. ::
+
+    yum install libevent2-dev
+
+On RHEL6 and earlier. ::
+
+    yum install libevent-dev
+
+On Debian/Ubuntu. ::
+
+    apt-get install libevent2-dev
+
+To build from source on a \*NIX host: ::
+
+    tar -xzf libevent-2.1.11-stable.tar.gz
+    (cd libevent-2.1.11-stable \
+     && ./configure --prefix $PWD/../libevent-install \
+     && make install)
+
+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. ::
+
+    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)
+
+Build Base and PVXS: ::
+
+    make -C epics-base
+    make -C pvxs
+
+It is recommended to run automatic unittests when building a new (to you) version
+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): ::
+
+    ./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
@@ -77,9 +77,16 @@ RPC

 `pvxs::client::Context::rpc` returns a
 `pvxs::client::RPCBuilder` to prepare an rpc() operation.
-rpc() differs from put() in that the call determines the type
-definition by providing a Value directly,
-so no builder callback is needed.
+There are two ways to prepare the arguments of an RPC operation.
+
+The recommended way is to use the one argument form of rpc()
+and zero or more calls to `pvxs::client::RPCBuilder::arg`
+to set argument names and values.
+These will be combined into a single argument structure
+conforming to the `pvxs::nt::NTURI` convention.
+
+Alternately, the two argument form of rpc() accepts are
+arbitrary Value which is passed to the server unaltered.

 .. doxygenclass:: pvxs::client::RPCBuilder
    :members:
@@ -13,13 +13,14 @@ CLI utilities acting as PVAccess protocol client and/or server.
 Dependencies

 * A C++11 compliant compiler (eg. GCC >= 4.9)
-* EPICS Base >=3.15.1
-* libevent >=2.0.1
+* `EPICS Base <https://epics-controls.org/resources-and-support/base/>`_ >=3.15.1
+* `libevent <http://libevent.org/>`_ >=2.0.1

 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
   :caption: Contents:

+   building
   value
   client
   server
@@ -22,7 +22,9 @@ time_t
 Commonly used sub-structure to represent a time

 **"secondsPastEpoch"**
-    Seconds since 1 Jan 1990 UTC.  This is 631152000 seconds after the POSIX epoch of 1970.
+    Seconds since POSIX epoch of 1 Jan 1970 UTC.
+    Note that the EPICS epoch is 631152000 seconds after the POSIX epoch.
+    (cf. POSIX_TIME_AT_EPICS_EPOCH in epicsTime.h from EPICS Base)

 **"nanoseconds"**
    Number of nanoseconds since the start of the second.
@@ -207,14 +207,18 @@ public:
    const Config& config() const;

    /** Request the present value of a PV
+     *
+     * Simple blocking
     *
     * @code
     * Context ctxt(...);
     * auto result = ctxt.get("pv:name")
     *                   .exec()
-     *                   .wait();
+     *                   ->wait();
     * @endcode
     *
+     * With completion callback
+     *
     * @code
     * Context ctxt(...);
     * auto op = ctxt.get("pv:name")
@@ -231,13 +235,17 @@ public:
    /** Request type information from PV.
     *  Results in a Value with no marked fields.
     *
+     * Simple blocking
+     *
     * @code
     * Context ctxt(...);
     * auto result = ctxt.info("pv:name")
     *                   .exec()
-     *                   .wait();
+     *                   ->wait();
     * @endcode
     *
+     * With completion callback
+     *
     * @code
     * Context ctxt(...);
     * auto op = ctxt.info("pv:name")
@@ -253,17 +261,18 @@ public:

    /** Request change/update of PV.
     *
-     * Assign certain values to certain fields.
+     * Assign certain values to certain fields and block for completion.
     *
     * @code
     * Context ctxt(...);
     * auto result = ctxt.put("pv:name")
     *                   .set("value", 42)
     *                   .exec()
-     *                   .wait();
+     *                   ->wait();
     * @endcode
     *
     * Alternately, and more generally, using a .build() callback
+     * and use .result() callback for completion notification.
     *
     * @code
     * Context ctxt(...);
@@ -293,15 +302,21 @@ public:
    RPCBuilder rpc(const std::string& pvname);

    /** Execute "stateless" remote procedure call operation.
+     *
+     * Simple blocking
     *
     * @code
     * Value arg = ...;
     * Context ctxt(...);
     * auto result = ctxt.rpc("pv:name", arg)
+     *                   .arg("blah", 5)
+     *                   .arg("other", "example")
     *                   .exec()
-     *                   .wait();
+     *                   ->wait();
     * @endcode
     *
+     * With completion callback
+     *
     * @code
     * Value arg = ...;
     * Context ctxt(...);