INSTALL

### Read pbdZMQ vignettes "pbdZMQ-guide.pdf" first at 
### "https://cran.r-project.org/package=pbdZMQ".
###
### pbdZMQ can be installed with/without external ZeroMQ 4.2.2 library
### since pbdZMQ includes a minimum requirement of ZeroMQ 4.2.2 library.
###
### pbdZMQ is also tested mainly on Linux (XUbuntu-14.04.1), Windows 7, and
### Mac OSX 10.7 systems.
###
### Solaris needs ZeroMQ 4.0.7 library with GNU Make 4.1 (OpenCSW).
### See Section for Solaris in next for installation steps and read pbdZMQ

--- 'pbdZMQ' installation:
0. 'pkg-config' and system ZeroMQ library (libzmq, libzmq-dev) are requrired.

1. Default installation:

     > R CMD INSTALL pbdZMQ_*.*-*.tar.gz

--- 'pbdZMQ' installation with internal ZeroMQ library:

1. Enable internal ZeroMQ:
   This should work with most platforms.

     > R CMD INSTALL pbdZMQ_0.*-*.tar.gz \
       --configure-args="--enable-internal-zmq"

--- 'pbdZMQ' installation with external ZeroMQ library such as version 4.2.2:
0. Minimum steps for installing ZeroMQ 4.2.2 shared library

     > ./configure \
          --prefix=/usr/local/zmq \
          --enable-static=no \
          --enable-shared=yes \
          --with-poller=select \
          --without-documentation \
          --without-libsodium
     > make -j 4; make install

   or ZeroMQ 4.2.2 static library

     > ./configure \
          --prefix=/usr/local/zmq \
          --with-pic=yes \
          --enable-static=yes \
          --enable-shared=no \
          --with-poller=select \
          --without-documentation \
          --without-libsodium
     > make -j 4; make install

1. Steps for pbdZMQ with the external ZeroMQ shared library

     > R CMD INSTALL pbdZMQ_*.*-*.tar.gz \
       --configure-vars="ZMQ_INCLUDE='-I/usr/local/zmq/include' \
                         ZMQ_LDFLAGS='-L/usr/local/zmq/lib -lzmq'"

   or with the external ZeroMQ static library

     > R CMD INSTALL pbdZMQ_*.*-*.tar.gz \
       --configure-vars="ZMQ_INCLUDE='-I/usr/local/zmq/include' \
                         ZMQ_LDFLAGS='/usr/local/zmq/lib/libzmq.a'"

   provided the external library is installed at "/usr/local/zmq" where
   "include/" subdirectory contains "zmq.h" and "lib/" subdirectory contains
   the shared library such as "libzmq.so" or the static library such as
   "libzmq.a".

--- Testing:
   Suppose 'pbdZMQ' is installed correctly. I can run the next from one
   terminal.

     > Rscript -e "demo(hwserver,'pbdZMQ',ask=F,echo=F)" &
     > Rscript -e "demo(hwclient,'pbdZMQ',ask=F,echo=F)"

--- Installation with different polling system:
    By default 'select' method is used in 'pbdZMQ' for Linux, Windows, and
    Mac OSX. However, users may want to use 'autodetect' or try others for
    better polling. Currently, the options as given by ZeroMQ may be 'kqueue',
    'epoll', 'devpoll', 'poll', or 'select' depending on libraries and system.

     > R CMD INSTALL pbdZMQ_*.*-*.tar.gz \
       --configure-vars="ZMQ_POLLER='autodetect'"


### Section for Solaris
--- Install OpenCSW and 'ZeroMQ 4.0.7' library:
0. Make sure GNU tools are installed including gmake, gcc, g++, autoconf,
   automake, gtar, etc. Usually, OpenCSW hase them at
   "https://www.opencsw.org/get-it/packages/" and can be installed
   by "pkgutil". For example, "gcc4core" can be installed by

     > pkgadd -d https://get.opencsw.org/now
     > /opt/csw/bin/pkgutil -U
     > /opt/csw/bin/pkgutil -y -i gcc4core 
     > /usr/sbin/pkgchk -L CSWgcc4core # list files

1. Make sure gmake, gcc, g++, autoconf, automake are in the PATH and export
   it to environment. For example, I have

PATH=/opt/csw/gnu:/opt/csw/bin:/opt/csw/i386-pc-solaris2.10/bin:/usr/sbin:/usr/bin:/usr/openwin/bin:/usr/ucb
export PATH

   I also have a symbolic link "make" to "gmake" to avoid configuration
   problems. If not, use "ln -s" to make one.

2. Download 'zeromq-4.0.7.tar.gz' from "https://download.zeromq.org".

3. Untar, configure, make, and make install as next:

     > gtar zxvf zeromq-4.0.7.tar.gz
     > cd zeromq-4.0.7
     > ./configure --prefix=/work-my/local/zmq 
     > make
     > make install

   where I install the ZeroMQ library to "/work-my/local/zmq".

--- 'pbdZMQ' installation with external ZeroMQ library such as version 4.0.7:
1. Steps for pbdZMQ with the external ZeroMQ library.

     > R CMD INSTALL pbdZMQ_*.*-*.tar.gz \
       --configure-vars="ZMQ_INCLUDE='-I/work-my/local/zmq/include' \
                         ZMQ_LDFLAGS='-L/work-my/local/zmq/lib -lzmq'"

   provided the external library is installed at "/work-my/local/zmq" where
   "include/" subdirectory contains "zmq.h" and "lib/" subdirectory contains
   the shared library such as "libzmq.so".

--- Testing:
   Suppose 'pbdZMQ' is installed correctly. I can run the next from one
   terminal.

     > Rscript -e "demo(hwserver,'pbdZMQ',ask=F,echo=F)" &
     > Rscript -e "demo(hwclient,'pbdZMQ',ask=F,echo=F)"