BIT-1430: Improve cross compilation support

* Add --toolchain= configure option

* Add --with-bifcl= configure option

* Change --with-binpac= configure option to mean "path to binpac
  executable"

* Add an example of how to use the above options for cross compiling
  Bro to the docs

CHANGES

@@ -1,4 +1,15 @@
 
+2.5-527 | 2018-04-27 11:01:03 -0500
+
+  * BIT-1430: Improve cross compilation support (Corelight)
+
+    * Add --toolchain= configure option
+
+    * Add --with-bifcl= configure option
+
+    * Change --with-binpac= configure option to mean "path to binpac
+      executable"
+
 2.5-526 | 2018-04-25 11:06:50 -0500
 
   * BIT-1914: comment out &check usages now that they emit warnings

NEWS

@@ -149,6 +149,9 @@ New Functionality
 Changed Functionality
 ---------------------
 
+- The --with-binpac= configure option has changed to mean "path
+  to the binpac executable" instead of "path to binpac installation root".
+
 - The MIME types used to identify X.509 certificates in SSL
   connections changed from "application/pkix-cert" to
   "application/x-x509-user-cert" for host certificates and

VERSION

@@ -1 +1 @@
-2.5-526
+2.5-527

cmake

@@ -1 +1 @@
-Subproject commit c40d8f9831b69259bfa930a64662d91cfdbf97bf
+Subproject commit 70fc7406f4baa87da9362c2b80ee6bbcdb242e0a

configure

@@ -27,6 +27,8 @@ Usage: $0 [OPTION]... [VAR=VALUE]...
     --generator=GENERATOR  CMake generator to use (see cmake --help)
     --ccache               use ccache to speed up recompilation (requires
                            ccache installation and CMake 3.10+)
+    --toolchain=PATH       path to a CMAKE_TOOLCHAIN_FILE
+                           (useful for cross-compiling)
 
   Installation Directories:
     --prefix=PREFIX        installation directory [/usr/local/bro]
@@ -62,7 +64,10 @@ Usage: $0 [OPTION]... [VAR=VALUE]...
     --with-openssl=PATH    path to OpenSSL install root
     --with-bind=PATH       path to BIND install root
     --with-pcap=PATH       path to libpcap install root
-    --with-binpac=PATH     path to BinPAC install root
+    --with-binpac=PATH     path to BinPAC executable
+                           (useful for cross-compiling)
+    --with-bifcl=PATH      path to Bro BIF compiler executable
+                           (useful for cross-compiling)
     --with-flex=PATH       path to flex executable
     --with-bison=PATH      path to bison executable
     --with-python=PATH     path to Python executable
@@ -174,6 +179,9 @@ while [ $# -ne 0 ]; do
         --ccache)
             append_cache_entry ENABLE_CCACHE         BOOL   true
             ;;
+        --toolchain=*)
+            append_cache_entry CMAKE_TOOLCHAIN_FILE  PATH   $optarg
+            ;;
         --prefix=*)
             prefix=$optarg
             append_cache_entry CMAKE_INSTALL_PREFIX PATH   $optarg
@@ -249,7 +257,10 @@ while [ $# -ne 0 ]; do
             append_cache_entry PCAP_ROOT_DIR PATH $optarg
             ;;
         --with-binpac=*)
-            append_cache_entry BinPAC_ROOT_DIR PATH $optarg
+            append_cache_entry BINPAC_EXE_PATH     PATH $optarg
+            ;;
+        --with-bifcl=*)
+            append_cache_entry BIFCL_EXE_PATH      PATH   $optarg
             ;;
         --with-flex=*)
             append_cache_entry FLEX_EXECUTABLE PATH $optarg

doc/install/cross-compiling.rst

@@ -0,0 +1,85 @@
+.. _crosstool-NG: https://crosstool-ng.github.io/
+.. _CMake toolchain: https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html
+
+===================
+Cross Compiling Bro
+===================
+
+.. contents::
+
+Prerequisites
+=============
+
+You need three things on the host system:
+
+1. The Bro source tree.
+2. A cross-compilation toolchain, such as one built via crosstool-NG_.
+3. Pre-built Bro dependencies from the target system.  This usually
+   includes libpcap, zlib, OpenSSL, and Python development headers
+   and libraries.
+
+Configuration and Compiling
+===========================
+
+You first need to compile a few build tools native to the host system
+for use during the later cross-compile build.  In the root of your
+Bro source tree:
+
+.. console::
+
+   ./configure --builddir=../bro-buildtools
+   ( cd ../bro-buildtools && make binpac bifcl )
+
+Next configure Bro to use your cross-compilation toolchain:
+
+.. console::
+
+   ./configure --toolchain=/home/jon/x-tools/RaspberryPi-toolchain.cmake --with-binpac=$(pwd)/../bro-buildtools/aux/binpac/src/binpac --with-bifcl=$(pwd)/../bro-buildtools/src/bifcl
+
+Here, the toolchain file a `CMake toolchain`_ file.  It might look
+something the following (using a Raspberry Pi as target system)::
+
+  # Operating System on which CMake is targeting.
+  set(CMAKE_SYSTEM_NAME Linux)
+
+  # The CMAKE_STAGING_PREFIX option may not work.
+  # Given that Bro is configured:
+  #
+  #   `./configure --prefix=<dir>`
+  #
+  # The options are:
+  #
+  #   (1) `make install` and then copy over the --prefix dir from host to
+  #       target system.
+  #
+  #   (2) `DESTDIR=<staging_dir> make install` and then copy over the
+  #       contents of that staging directory.
+
+  set(toolchain /home/jon/x-tools/arm-rpi-linux-gnueabihf)
+  set(CMAKE_C_COMPILER   ${toolchain}/bin/arm-rpi-linux-gnueabihf-gcc)
+  set(CMAKE_CXX_COMPILER ${toolchain}/bin/arm-rpi-linux-gnueabihf-g++)
+
+  # The cross-compiler/linker will use these paths to locate dependencies.
+  set(CMAKE_FIND_ROOT_PATH
+      /home/jon/x-tools/bro-rpi-deps
+      ${toolchain}/arm-rpi-linux-gnueabihf/sysroot
+  )
+
+  set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
+  set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
+  set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
+
+If that configuration succeeds you are ready to build:
+
+.. console::
+
+   make
+
+And if that works, install on your host system:
+
+.. console::
+
+   make install
+
+From there, you can copy/move the files from the installation prefix
+on the host system to the target system and start running Bro as usual.

doc/install/install.rst

@@ -214,6 +214,13 @@ all of the documentation for the latest Bro release is available on the
 Bro web site), there are instructions in ``doc/README`` in the source
 distribution.
 
+Cross Compiling
+---------------
+
+See :doc:`cross-compiling` for an example of how
+to cross compile Bro for a different target platform than the one on
+which you build.
+
 Configure the Run-Time Environment
 ==================================