Document config-cross-recipe.sh helper script (#276)

Signed-off-by: Derek G Foster <[email protected]>

docs/scripts/config-cross-recipe.rst

@@ -0,0 +1,171 @@
+.. Copyright 2023 Intel Corporation
+   SPDX-License-Identifier: Apache 2.0
+
+======================
+config-cross-recipe.sh
+======================
+
+Helper script to configure CMake to cross-compile P4 Control Plane
+for the Arm Compute Complex (ACC).
+
+Build flow
+==========
+
+The ``config-cross-recipe.sh`` script is run after ``make-cross-ovs.sh``,
+to configure the remainder of the P4 Control Plane build.
+
+.. image:: config-cross-recipe-flow.png
+
+After running this script, you will need to issue a separate command
+to build and install the software. For example:
+
+.. code-block:: bash
+
+   cmake --build build -j8 --target install
+
+Syntax
+======
+
+.. code-block:: text
+
+  ./scripts/es2k/config-cross-recipe.sh \
+      [--help|-h]  \
+      [--dry-run|-n] \
+      [--build=BLDDIR | -B BLDDIR] \
+      [--deps=DEPS | -D DEPS] \
+      [--host=HOSTDEPS | -H HOSTDEPS] \
+      [--ovs=OVS | -O OVS] \
+      [--prefix=PREFIX | -P PREFIX] \
+      [--sde=SDE | -S SDE] \
+      [--toolchain=TOOLFILE | -T TOOLFILE ] \
+      [--no-krnlmon] \
+      [--no-ovs]
+
+Command-line parameters
+=======================
+
+General
+-------
+
+``--dry-run``, ``-n``
+  Displays the parameters that will be passed to CMake, and exits.
+
+``--help``, ``-h``
+  Displays usage information and exits.
+
+Paths
+-----
+
+``--build=BLDDIR``, ``-B BLDDIR``
+  Directory that CMake will use to perform the build.
+  Will be created if it does not exist.
+
+  Specifies the value of the ``-B`` CMake option.
+  Can be used to create separate build directories for native and
+  cross-compiled builds.
+  Defaults to ``build``.
+
+``--deps=DEPS``, ``-D DEPS`` *(see note)*
+  Directory in which the Stratum dependencies for the runtime system
+  are installed.
+
+  P4 Control Plane will be linked with these libraries.
+  Supplies the value of the ``DEPEND_INSTALL_DIR`` listfile variable.
+  Defaults to the value of the ``DEPEND_INSTALL`` environment variable,
+  if defined.
+  Otherwise, defaults to ``//opt/deps``.
+
+``--host=HOST``, ``-H HOST``
+  Directory in which the Stratum dependencies for the development
+  system are installed.
+
+  Used to compile Protobufs to C++ during cross-compilation.
+  Supplies the value of the ``HOST_DEPEND_DIR`` listfile variable.
+  Defaults to the value of the ``HOST_INSTALL`` environment variable,
+  if defined.
+  Otherwise, defaults to ``setup/hostdeps``.
+
+``--ovs=OVS``, ``-O OVS`` *(see note)*
+  Directory in which Open vSwitch is installed.
+
+  May be omitted if the ``--no-ovs`` option is specified.
+  Supplies the value of the ``OVS_INSTALL_DIR`` listfile variable for
+  the P4 Control Plane build.
+  May be the same as the ``prefix`` directory, in which case OVS and
+  P4 Control Plane will be installed to the same directory tree.
+  Defaults to the value of the ``OVS_INSTALL`` environment variable,
+  if defined.
+  Otherwise, defaults to ``//opt/ovs``.
+
+``--prefix=PREFIX``, ``-P PREFIX`` *(see note)*
+  Directory in which P4 Control Plane will be installed.
+  Will be created if it does not exist.
+
+  May be the same as the ``--ovs`` option, in which case OVS and
+  P4 Control Plane will be installed to the same directory tree.
+  Specifies the value of the ``CMAKE_INSTALL_PREFIX`` variable when
+  building P4 Control Plane.
+
+``--sde=SDE``, ``-S SDE`` *(see note)*
+  Directory in which the SDK for the Intel® IPU E2100 is installed.
+
+  Supplies the value of the ``SDE_INSTALL_DIR`` listfile variable.
+  Defaults to the value of the ``SDE_INSTALL`` environment variable,
+  if defined.
+  Otherwise, defaults to ``//opt/p4sde``.
+
+``--toolchain=FILE``, ``-T FILE``
+  Path to the CMake toolchain file.
+
+  Specifies the value of the ``CMAKE_TOOLCHAIN_FILE`` variable.
+  Defaults to the value of the ``CMAKE_TOOLCHAIN_FILE`` environment
+  variable.
+
+.. note::
+  ``//`` at the beginning of the directory path will be replaced with
+  the *sysroot* directory path.
+
+Options
+-------
+
+``--no-krnlmon``
+  Excludes the Kernel Monitor from the build.
+
+  Sets the ``WITH_KRNLMON`` listfile option to FALSE.
+
+``--no-ovs``
+  Excludes OVS from the build.
+
+  Sets the ``WITH_OVSP4RT`` listfile option to FALSE.
+
+Environment variables
+=====================
+
+``CMAKE_TOOLCHAIN_FILE``
+  Path to the CMake toolchain file to be used.
+  Specifies the value of the ``CMAKE_TOOLCHAIN_FILE`` variable.
+  May be overridden by ``--toolchain=TOOLFILE``.
+  Must be defined.
+
+``DEPEND_INSTALL``
+  Directory in which the Stratum dependencies for the runtime system
+  are installed.
+  Supplies the default value of the ``--deps`` option.
+
+``HOST_INSTALL``
+  Directory in which the Stratum dependencies for the development system
+  are installed.
+  Supplies the default value of the ``--host`` option.
+
+``OVS_INSTALL``
+  Directory in which Open vSwitch is installed.
+  Supplies the default value of the ``--ovs`` option.
+
+``SDE_INSTALL``
+  Directory in which the SDK for the IPU E2100 is installed.
+  Supplies the default value of the ``--sde`` option.
+
+``SDKTARGETSYSROOT``
+  Path to the system root (sysroot) directory for the ARM Compute Complex
+  (ACC) of the IPU E2100.
+  Must be defined.

docs/scripts/helper-scripts.rst

@@ -9,3 +9,4 @@ Helper Scripts
    :maxdepth: 1
 
    make-all
+   config-cross-recipe